@eva/plugin-renderer-text 2.0.1-beta.9 → 2.0.1

package/dist/plugin-renderer-text.d.ts

@@ -1,6 +1,8 @@
+import { BitmapText as BitmapText_2 } from '@eva/renderer-adapter';
 import { Component } from '@eva/eva.js';
 import { ComponentChanged } from '@eva/eva.js';
 import { ContainerManager } from '@eva/plugin-renderer';
+import { HTMLText as HTMLText_2 } from '@eva/renderer-adapter';
 import { Renderer } from '@eva/plugin-renderer';
 import { RendererManager } from '@eva/plugin-renderer';
 import { RendererSystem } from '@eva/plugin-renderer';
@@ -12,10 +14,228 @@ import { TextStyleFontWeight } from 'pixi.js';
 import { TextStyleTextBaseline } from 'pixi.js';
 import { TextStyleWhiteSpace } from 'pixi.js';
 
+/**
+ * 位图文本组件
+ *
+ * BitmapText 组件使用位图字体渲染文本，性能优于 Canvas 文本渲染。
+ * 适用于频繁更新的文本场景，如计分板、倒计时等。
+ *
+ * 支持两种字体模式：
+ * - 动态生成：指定 TextStyle，PixiJS 自动生成 bitmap font
+ * - 预加载字体：通过 BitmapFont.install() 预安装或从 .fnt 文件加载
+ *
+ * @example
+ * ```typescript
+ * const score = new GameObject('score');
+ * score.addComponent(new BitmapText({
+ *   text: 'Score: 0',
+ *   style: {
+ *     fontSize: 32,
+ *     fill: '#ffffff',
+ *     fontFamily: 'Arial'
+ *   }
+ * }));
+ * ```
+ */
+export declare class BitmapText extends Component<BitmapTextParams> {
+    static componentName: string;
+    text: string;
+    style: BitmapTextStyleOptions;
+    init(obj?: BitmapTextParams): void;
+}
+
+export declare interface BitmapTextParams {
+    text: string;
+    style?: BitmapTextStyleOptions;
+}
+
+declare interface BitmapTextStyleOptions {
+    fontFamily?: string | string[];
+    fontSize?: number | string;
+    fill?: string | number;
+    align?: 'left' | 'center' | 'right' | 'justify';
+    letterSpacing?: number;
+    padding?: number;
+    stroke?: string | number;
+    strokeThickness?: number;
+    fontWeight?: TextStyleFontWeight;
+    fontStyle?: TextStyleFontStyle;
+}
+
+/**
+ * HTML 富文本组件
+ *
+ * HTMLText 组件支持渲染带有 HTML 标签的富文本内容。
+ * 可以在文本中使用 HTML 标签（如 `<b>`, `<i>`, `<span>` 等）来实现丰富的文本样式，
+ * 适用于聊天对话、新闻内容、富文本显示等需要多样式文本的场景。
+ *
+ * 支持的 HTML 标签：
+ * - `<b>` - 粗体
+ * - `<i>` - 斜体
+ * - `<span style="color:#ff0000">` - 自定义样式
+ * - `<br>` - 换行
+ * 以及更多标准 HTML 文本标签
+ *
+ * @example
+ * ```typescript
+ * // 基础富文本
+ * const label = new GameObject('label');
+ * label.addComponent(new HTMLText({
+ *   text: '这是<b>粗体</b>和<i>斜体</i>文本',
+ *   style: {
+ *     fontSize: 24,
+ *     fill: '#000000',
+ *     fontFamily: 'Arial'
+ *   }
+ * }));
+ *
+ * // 带颜色的富文本
+ * label.addComponent(new HTMLText({
+ *   text: '欢迎 <span style="color:#ff0000">玩家123</span> 加入游戏！',
+ *   style: {
+ *     fontSize: 20,
+ *     wordWrap: true,
+ *     wordWrapWidth: 300
+ *   }
+ * }));
+ *
+ * // 自定义标签样式
+ * label.addComponent(new HTMLText({
+ *   text: '获得 <gold>100</gold> 金币',
+ *   style: {
+ *     fontSize: 18,
+ *     tagStyles: {
+ *       gold: {
+ *         fill: '#ffd700',
+ *         fontWeight: 'bold'
+ *       }
+ *     }
+ *   }
+ * }));
+ *
+ * // 高分辨率渲染（推荐使用 Render 组件的 resolution 属性）
+ * label.addComponent(new HTMLText({
+ *   text: '高清文本',
+ *   textureStyle: {
+ *     scaleMode: 'linear'
+ *   }
+ * }));
+ * label.addComponent(new Render({ resolution: 2 }));
+ * ```
+ */
+export declare class HTMLText extends Component<HTMLTextParams> {
+    /** 组件名称 */
+    static componentName: string;
+    /** 富文本内容（支持 HTML 标签） */
+    text: string;
+    /** 文本样式配置 */
+    style: HTMLTextParams['style'];
+    /** 纹理渲染配置 */
+    textureStyle: HTMLTextParams['textureStyle'];
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.text - 富文本内容
+     * @param obj.style - 文本样式
+     * @param obj.textureStyle - 纹理配置
+     */
+    init(obj?: HTMLTextParams): void;
+}
+
+export declare interface HTMLTextParams {
+    text: string;
+    style?: HTMLTextStyleOptions & {
+        cssOverrides?: string[];
+        wordWrap?: boolean;
+        wordWrapWidth?: number;
+        tagStyles?: Record<string, HTMLTextStyleOptions>;
+    };
+    textureStyle?: {
+        scaleMode?: 'linear' | 'nearest';
+        resolution?: number;
+    };
+}
+
+declare interface HTMLTextStyleOptions {
+    fontFamily?: string | string[];
+    fontSize?: number | string;
+    fill?: string | number;
+    align?: 'left' | 'center' | 'right' | 'justify';
+    breakWords?: boolean;
+    letterSpacing?: number;
+    lineHeight?: number;
+    padding?: number;
+    stroke?: string | number;
+    strokeThickness?: number;
+    dropShadow?: boolean;
+    dropShadowAlpha?: number;
+    dropShadowAngle?: number;
+    dropShadowBlur?: number;
+    dropShadowColor?: string | number;
+    dropShadowDistance?: number;
+    trim?: boolean;
+    fontWeight?: string;
+    fontStyle?: string;
+    fontVariant?: string;
+    textBaseline?: string;
+    whiteSpace?: string;
+}
+
+/**
+ * 文本组件（基于 PixiJS Text）
+ *
+ * Text 组件用于渲染文本内容，支持丰富的文本样式配置。
+ * 它基于 PixiJS 的 Text 实现，支持字体、颜色、描边、阴影、对齐等多种样式。
+ *
+ * 主要特性：
+ * - 支持多种字体和字号
+ * - 支持文本颜色、渐变填充
+ * - 支持描边和投影效果
+ * - 支持文本对齐和换行
+ *
+ * @example
+ * ```typescript
+ * // 基础文本
+ * const label = new GameObject('label');
+ * label.addComponent(new Text({
+ *   text: 'Hello EVA!',
+ *   style: {
+ *     fontSize: 32,
+ *     fill: 0xffffff
+ *   }
+ * }));
+ *
+ * // 带样式的文本
+ * label.addComponent(new Text({
+ *   text: '得分: 9999',
+ *   style: {
+ *     fontFamily: 'Arial',
+ *     fontSize: 48,
+ *     fontWeight: 'bold',
+ *     fill: ['#ff0000', '#ffff00'], // 渐变色
+ *     stroke: '#000000',
+ *     strokeThickness: 4,
+ *     dropShadow: true,
+ *     dropShadowDistance: 3
+ *   }
+ * }));
+ * // 如需高清渲染，使用 Render 组件的 resolution 属性
+ * label.addComponent(new Render({ resolution: 2 }));
+ * ```
+ */
 declare class Text_2 extends Component<TextParams> {
+    /** 组件名称 */
     static componentName: string;
+    /** 文本内容 */
     text: string;
+    /** 文本样式配置 */
     style: TextParams['style'];
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.text - 文本内容
+     * @param obj.style - 文本样式
+     */
     init(obj?: TextParams): void;
 }
 export { Text_2 as Text }
@@ -60,8 +280,8 @@ export declare class TextSystem extends Renderer {
     name: string;
     texts: {
         [propName: number]: {
-            text: Text_3;
-            component: Text_2;
+            text: Text_3 | HTMLText_2 | BitmapText_2;
+            component: Text_2 | HTMLText | BitmapText;
         };
     };
     renderSystem: RendererSystem;
@@ -69,9 +289,18 @@ export declare class TextSystem extends Renderer {
     containerManager: ContainerManager;
     init(): void;
     componentChanged(changed: ComponentChanged): Promise<void>;
+    private addTextComponent;
+    private addHTMLTextComponent;
+    private addBitmapTextComponent;
+    /**
+     * 等待字体资源加载完成并更新文本
+     */
+    private waitForFontResource;
+    /**
+     * 将 Eva.js 的样式格式转换为 PixiJS v8 格式
+     */
+    private processStyle;
     change(changed: ComponentChanged): void;
-    asyncChangeTextStyle(text: Text_3, textStyle: TextParams['style']): void;
-    asyncUpdateFontFamily(text: Text_3, fontFamily: string | string[] | undefined): void;
     setSize(changed: ComponentChanged): void;
 }