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

package/dist/plugin-renderer-text.esm.js

@@ -1,8 +1,8 @@
-import { TextStyle } from 'pixi.js';
-import { Component, resource, decorators, OBSERVER_TYPE } from '@eva/eva.js';
+import { Component, decorators, OBSERVER_TYPE, resource } from '@eva/eva.js';
 import { type } from '@eva/inspector-decorator';
+import { TextStyle, FillGradient, Color } from 'pixi.js';
 import { Renderer, RendererSystem } from '@eva/plugin-renderer';
-import { Text as Text$3 } from '@eva/renderer-adapter';
+import { HTMLText as HTMLText$1, Text as Text$3, BitmapText as BitmapText$1 } from '@eva/renderer-adapter';
 
 /*! *****************************************************************************
 Copyright (c) Microsoft Corporation. All rights reserved.
@@ -35,12 +35,104 @@ function __awaiter(thisArg, _arguments, P, generator) {
     });
 }
 
+/**
+ * 位图文本组件
+ *
+ * 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'
+ *   }
+ * }));
+ * ```
+ */
+class BitmapText extends Component {
+    constructor() {
+        super(...arguments);
+        this.text = '';
+        this.style = {};
+    }
+    init(obj) {
+        this.style = Object.assign({ fontSize: 24, fill: '#000000', fontFamily: 'Arial' }, obj === null || obj === void 0 ? void 0 : obj.style);
+        if (obj) {
+            this.text = obj.text;
+        }
+    }
+}
+BitmapText.componentName = 'BitmapText';
+__decorate([
+    type('string')
+], BitmapText.prototype, "text", void 0);
+
+/**
+ * 文本组件（基于 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 }));
+ * ```
+ */
 class Text$2 extends Component {
     constructor() {
         super(...arguments);
+        /** 文本内容 */
         this.text = '';
+        /** 文本样式配置 */
+        // @decorators.IDEProp 复杂编辑后续添加
         this.style = {};
     }
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.text - 文本内容
+     * @param obj.style - 文本样式
+     */
     init(obj) {
         const style = new TextStyle({
             fontSize: 20,
@@ -59,11 +151,104 @@ class Text$2 extends Component {
         }
     }
 }
+/** 组件名称 */
 Text$2.componentName = 'Text';
 __decorate([
     type('string')
 ], Text$2.prototype, "text", void 0);
 
+/**
+ * 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 }));
+ * ```
+ */
+class HTMLText extends Component {
+    constructor() {
+        super(...arguments);
+        /** 富文本内容（支持 HTML 标签） */
+        this.text = '';
+        /** 文本样式配置 */
+        this.style = {};
+        /** 纹理渲染配置 */
+        this.textureStyle = {};
+    }
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.text - 富文本内容
+     * @param obj.style - 文本样式
+     * @param obj.textureStyle - 纹理配置
+     */
+    init(obj) {
+        this.style = Object.assign({ fontSize: 24, fill: '#000000', fontFamily: 'Arial' }, obj === null || obj === void 0 ? void 0 : obj.style);
+        this.textureStyle = Object.assign({ scaleMode: 'linear', resolution: window.devicePixelRatio || 1 }, obj === null || obj === void 0 ? void 0 : obj.textureStyle);
+        if (obj) {
+            this.text = obj.text;
+        }
+    }
+}
+/** 组件名称 */
+HTMLText.componentName = 'HTMLText';
+__decorate([
+    type('string')
+], HTMLText.prototype, "text", void 0);
+
 let Text = class Text extends Renderer {
     constructor() {
         super(...arguments);
@@ -76,16 +261,21 @@ let Text = class Text extends Renderer {
     }
     componentChanged(changed) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (changed.componentName !== 'Text')
+            const isText = changed.componentName === 'Text';
+            const isHTMLText = changed.componentName === 'HTMLText';
+            const isBitmapText = changed.componentName === 'BitmapText';
+            if (!isText && !isHTMLText && !isBitmapText)
                 return;
             if (changed.type === OBSERVER_TYPE.ADD) {
-                const component = changed.component;
-                const text = new Text$3(component.text, component.style);
-                this.containerManager.getContainer(changed.gameObject.id).addChildAt(text, 0);
-                this.texts[changed.gameObject.id] = {
-                    text,
-                    component: changed.component,
-                };
+                if (isText) {
+                    yield this.addTextComponent(changed);
+                }
+                else if (isHTMLText) {
+                    yield this.addHTMLTextComponent(changed);
+                }
+                else {
+                    yield this.addBitmapTextComponent(changed);
+                }
                 this.setSize(changed);
             }
             else if (changed.type === OBSERVER_TYPE.REMOVE) {
@@ -95,55 +285,213 @@ let Text = class Text extends Renderer {
             }
             else {
                 this.change(changed);
+                // 如果样式改变且涉及字体，也需要等待字体资源加载
+                const component = changed.component;
+                if (changed.prop.prop[0] === 'style' && component.style && component.style.fontFamily) {
+                    const { text } = this.texts[changed.gameObject.id];
+                    yield this.waitForFontResource(text, changed, component.style.fontFamily);
+                }
                 this.setSize(changed);
             }
         });
     }
+    addTextComponent(changed) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const component = changed.component;
+            // 创建文本样式副本，先不设置 fontFamily
+            const styleWithoutFont = Object.assign({}, component.style);
+            const fontFamily = styleWithoutFont.fontFamily;
+            delete styleWithoutFont.fontFamily;
+            const initialText = fontFamily ? '' : component.text;
+            const text = new Text$3(initialText, styleWithoutFont);
+            this.containerManager.getContainer(changed.gameObject.id).addChildAt(text, 0);
+            this.texts[changed.gameObject.id] = {
+                text,
+                component,
+            };
+            // 如果指定了字体资源，等待资源加载完成后设置 fontFamily
+            if (fontFamily) {
+                yield this.waitForFontResource(text, changed, fontFamily);
+            }
+        });
+    }
+    addHTMLTextComponent(changed) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const component = changed.component;
+            // 创建样式副本，先不设置 fontFamily
+            const styleWithoutFont = Object.assign({}, component.style);
+            const fontFamily = styleWithoutFont.fontFamily;
+            delete styleWithoutFont.fontFamily;
+            const initialText = fontFamily ? '' : component.text;
+            const htmlText = new HTMLText$1(Object.assign({ text: initialText, style: styleWithoutFont }, (component.textureStyle && { textureStyle: component.textureStyle })));
+            this.containerManager.getContainer(changed.gameObject.id).addChildAt(htmlText, 0);
+            this.texts[changed.gameObject.id] = {
+                text: htmlText,
+                component,
+            };
+            // 如果指定了字体资源，等待资源加载完成后设置 fontFamily
+            if (fontFamily) {
+                yield this.waitForFontResource(htmlText, changed, fontFamily);
+            }
+        });
+    }
+    addBitmapTextComponent(changed) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const component = changed.component;
+            // 创建样式副本，先不设置 fontFamily
+            const styleWithoutFont = Object.assign({}, component.style);
+            const fontFamily = styleWithoutFont.fontFamily;
+            delete styleWithoutFont.fontFamily;
+            const initialText = fontFamily ? '' : component.text;
+            const bitmapText = new BitmapText$1(initialText, styleWithoutFont);
+            this.containerManager.getContainer(changed.gameObject.id).addChildAt(bitmapText, 0);
+            this.texts[changed.gameObject.id] = {
+                text: bitmapText,
+                component,
+            };
+            // 如果指定了字体资源，等待资源加载完成后设置 fontFamily
+            if (fontFamily) {
+                yield this.waitForFontResource(bitmapText, changed, fontFamily);
+            }
+        });
+    }
+    /**
+     * 等待字体资源加载完成并更新文本
+     */
+    waitForFontResource(text, changed, fontFamily) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!fontFamily) {
+                return;
+            }
+            try {
+                const fontName = Array.isArray(fontFamily) ? fontFamily[0] : fontFamily;
+                // 通过 resource 系统获取字体资源
+                const asyncId = this.increaseAsyncId(changed.gameObject.id);
+                yield resource.getResource(fontName);
+                // 验证异步操作是否仍然有效（防止组件已被移除）
+                if (!this.validateAsyncId(changed.gameObject.id, asyncId))
+                    return;
+                // 字体资源加载成功后，设置 fontFamily 并重新设置文本内容以触发重新渲染
+                const component = this.texts[changed.gameObject.id].component;
+                text.style.fontFamily = fontFamily;
+                text.text = component.text;
+                // 更新尺寸
+            }
+            catch (error) {
+                console.warn(`字体资源 ${fontFamily} 加载失败:`, error);
+            }
+        });
+    }
+    /**
+     * 将 Eva.js 的样式格式转换为 PixiJS v8 格式
+     */
+    processStyle(style) {
+        const processed = Object.assign({}, style);
+        // stroke + strokeThickness -> stroke: { color, width }
+        if (processed.strokeThickness) {
+            const color = processed.stroke;
+            processed.stroke = {
+                color,
+                width: processed.strokeThickness,
+            };
+            delete processed.strokeThickness;
+        }
+        // dropShadow* -> dropShadow: { color, distance, angle, alpha, blur }
+        if (processed.dropShadow) {
+            const dropShadowConfig = {};
+            if (processed.dropShadowColor != null) {
+                dropShadowConfig.color = processed.dropShadowColor;
+            }
+            if (processed.dropShadowDistance != null) {
+                dropShadowConfig.distance = processed.dropShadowDistance;
+            }
+            if (processed.dropShadowAngle != null) {
+                dropShadowConfig.angle = processed.dropShadowAngle;
+            }
+            if (processed.dropShadowAlpha != null) {
+                dropShadowConfig.alpha = processed.dropShadowAlpha;
+            }
+            if (processed.dropShadowBlur != null) {
+                dropShadowConfig.blur = processed.dropShadowBlur;
+            }
+            processed.dropShadow = dropShadowConfig;
+            delete processed.dropShadowColor;
+            delete processed.dropShadowDistance;
+            delete processed.dropShadowAngle;
+            delete processed.dropShadowAlpha;
+            delete processed.dropShadowBlur;
+        }
+        // fill 数组 -> 取第一个值 (deprecated)
+        if (Array.isArray(processed.fill)) {
+            processed.fill = processed.fill[0];
+        }
+        // fillGradientStops -> FillGradient 对象
+        if (Array.isArray(processed.fillGradientStops)) {
+            let fontSize;
+            if (processed.fontSize == null) {
+                fontSize = TextStyle.defaultTextStyle.fontSize;
+            }
+            else if (typeof processed.fontSize === 'string') {
+                fontSize = parseInt(processed.fontSize, 10);
+            }
+            else {
+                fontSize = processed.fontSize;
+            }
+            const gradientFill = new FillGradient(0, 0, 0, fontSize * 1.7);
+            const fills = processed.fillGradientStops.map((color) => Color.shared.setValue(color).toNumber());
+            fills.forEach((number, index) => {
+                const ratio = index / (fills.length - 1);
+                gradientFill.addColorStop(ratio, number);
+            });
+            processed.fill = { fill: gradientFill };
+            delete processed.fillGradientStops;
+        }
+        return processed;
+    }
     change(changed) {
         const { text, component } = this.texts[changed.gameObject.id];
+        const isHTMLText = changed.componentName === 'HTMLText';
         if (changed.prop.prop[0] === 'text') {
             text.text = component.text;
         }
         else if (changed.prop.prop[0] === 'style') {
-            Object.assign(text.style, changed.component.style);
-        }
-    }
-    asyncChangeTextStyle(text, textStyle) {
-        if (textStyle.fontFamily) {
-            const fontFamily = textStyle.fontFamily;
-            textStyle.fontFamily = '';
-            this.asyncUpdateFontFamily(text, fontFamily);
+            const processedStyle = this.processStyle(component.style);
+            Object.assign(text.style, processedStyle);
         }
-        Object.assign(text.style, textStyle);
-    }
-    asyncUpdateFontFamily(text, fontFamily) {
-        if (fontFamily) {
-            if (Array.isArray(fontFamily)) {
-                Promise.all(fontFamily.map(font => resource.getResource(font))).finally(() => {
-                    text.style.fontFamily = fontFamily;
-                });
-            }
-            else {
-                resource.getResource(fontFamily).finally(() => {
-                    text.style.fontFamily = fontFamily;
-                });
-            }
+        else if (changed.prop.prop[0] === 'textureStyle' && isHTMLText) {
+            // HTMLText 纹理样式变化需要重新创建
+            const htmlComponent = component;
+            const container = this.containerManager.getContainer(changed.gameObject.id);
+            const index = container.getChildIndex(text);
+            container.removeChild(text);
+            text.destroy({ children: true });
+            const newText = new HTMLText$1({
+                text: htmlComponent.text,
+                style: htmlComponent.style,
+                textureStyle: htmlComponent.textureStyle
+            });
+            container.addChildAt(newText, index);
+            this.texts[changed.gameObject.id].text = newText;
         }
     }
     setSize(changed) {
         const { transform } = changed.gameObject;
         if (!transform)
             return;
-        transform.size.width = this.texts[changed.gameObject.id].text.width;
-        transform.size.height = this.texts[changed.gameObject.id].text.height;
+        const { text } = this.texts[changed.gameObject.id];
+        const size = text.getSize();
+        transform.size.width = size.width;
+        transform.size.height = size.height;
     }
 };
 Text.systemName = 'Text';
 Text = __decorate([
     decorators.componentObserver({
         Text: ['text', { prop: ['style'], deep: true }],
+        HTMLText: ['text', { prop: ['style'], deep: true }, { prop: ['textureStyle'], deep: true }],
+        BitmapText: ['text', { prop: ['style'], deep: true }],
     })
 ], Text);
 var Text$1 = Text;
 
-export { Text$2 as Text, Text$1 as TextSystem };
+export { BitmapText, HTMLText, Text$2 as Text, Text$1 as TextSystem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/plugin-renderer-text",
-  "version": "2.0.1-beta.8",
+  "version": "2.0.1",
   "description": "@eva/plugin-renderer-text",
   "main": "index.js",
   "module": "dist/plugin-renderer-text.esm.js",
@@ -19,9 +19,9 @@
   "homepage": "https://eva.js.org",
   "dependencies": {
     "@eva/inspector-decorator": "^0.0.5",
-    "@eva/plugin-renderer": "2.0.1-beta.8",
-    "@eva/renderer-adapter": "2.0.1-beta.8",
-    "@eva/eva.js": "2.0.1-beta.8",
-    "pixi.js": "^8.8.1"
+    "@eva/plugin-renderer": "2.0.1",
+    "@eva/renderer-adapter": "2.0.1",
+    "@eva/eva.js": "2.0.1",
+    "pixi.js": "^8.17.0"
   }
 }