PixiJS v8 HTMLText 实战指南用 SVG foreignObject 在 WebGL 中渲染富文本 HTML/CSS【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijsHTMLText 是 PixiJS v8 提供的富文本渲染方案它借助 SVGforeignObject把一段 HTML 片段交给浏览器排版引擎绘制再将结果栅格化为 GPU 纹理从而让开发者获得完整的 HTML/CSS 盒模型排版能力。本文以 skills/pixijs-scene-text/references/html-text.md 为核心骨架结合 src/scene/text-html 目录下的真实源码与测试系统讲解 HTMLText 的构造选项、自定义标签、CSS 覆盖、自动换行、分辨率与 mipmap、异步渲染等全部要点并给出常见性能误区的正确解法。读完本文你将能在自己的 PixiJS 场景里正确创建、排版与优化富文本并清楚它相比 canvasText与BitmapText的取舍边界。什么是 HTMLText适用场景与工作原理HTMLText 通过 SVGforeignObject包裹一段 HTML 片段来完成文字渲染。它支持完整的 HTML/CSS 排版模型真正的b、i、br、div、换行、嵌套样式、emoji全部交给浏览器排版后栅格化到纹理上。凡是 canvasText无法表达的富格式、混合内容、内联自定义标签都可以交给 HTMLText。从源码看HTMLText 的整体数据流是text与style先被转换为 CSS见 textStyleToCSS.ts随后由 getSVGUrl.ts 拼装svgforeignObject.../foreignObject/svg并序列化为 URL再由 loadSVGImage.ts 加载为图片最终经 HTMLTextSystem.ts 上传为纹理交给 HTMLTextPipe.ts 批量渲染。这一整条链路是异步的——纹理要到创建后的下一帧才可用这一点会贯穿本文的多个注意事项。const rich new HTMLText({ text: bBold/b and iitalic/i text, style: { fontFamily: Arial, fontSize: 24, fill: 0x333333, wordWrap: true, wordWrapWidth: 400, }, }); app.stage.addChild(rich);需要特别说明的两点HTMLText 是叶子节点。所有文本类都设置了allowChildren falseHTMLText 不能挂子节点需要分组时应包一层Container参见 pixijs-scene-core-concepts 的 constructor-options。样式类是HTMLTextStyle它是TextStyle减去leading、textBaseline、trim、filters四个字段后的结果——这四个属性在 SVG 渲染路径下不受支持其余TextStyle属性全部可用。源码中的定义见 HTMLTextStyle.tsHTMLTextStyleOptions extends OmitTextStyleOptions, leading | textBaseline | trim | filters。版本提示v8 中所有文本类都只支持 options 对象构造器v7 的new HTMLText(string, style)位置参数形式已移除旧签名在源码中标记为deprecated见 HTMLText.ts。HTMLText 构造选项HTMLTextOptionsHTMLText继承基础TextOptions其 style 类型为HTMLTextStyle/HTMLTextStyleOptions并额外增加 HTML 专属字段。继承自基类的text、style、anchor、resolution、roundPixels行为与 canvasText一致详见 references/text.md此处仅列出 HTMLText 特有的新增项OptionTypeDefaultDescriptionstyleHTMLTextStyle \| HTMLTextStyleOptionsnew HTMLTextStyle()HTML 文本样式对象或选项。等于TextStyle减去leading、textBaseline、trim、filters并新增cssOverrides用于注入原始 CSS。textureStyleTextureStyle \| TextureStyleOptionsundefined生成纹理的缩放模式nearest或linearTextureStyle的其他字段一律被忽略advanced。autoGenerateMipmapsbooleanTextureSource.defaultOptions.autoGenerateMipmaps为文本纹理生成 mipmap缩小绘制时提升质量。所有基础文本选项text、anchor、resolution、roundPixels均继承自TextOptions所有Container选项position、scale、tint、label、filters、zIndex等同样有效。构造示例const minimal new HTMLText({ text: bHello/b }); const styled new HTMLText({ text: iStyled/i, style: { fontSize: 24, fill: 0xffffff }, anchor: 0.5, resolution: 2, autoGenerateMipmaps: true, textureStyle: { scaleMode: linear }, });源码实现中的几个关键细节值得注意textureStyle在构造函数里若传入的是普通 options 对象会被实例化为TextureStyle并调用warnIgnoredTextureStyle检查——只有scaleMode会被读取HTMLText.ts。autoGenerateMipmaps的默认值确实回退到TextureSource.defaultOptions.autoGenerateMipmapsHTMLText.ts。text赋值时会先做 HTML 清洗把br规范为br/、hr规范为hr/、nbsp;替换为#160;并移除未闭合的破损标签避免 SVG 序列化失败HTMLText.ts。因此直接写br也是安全的。textureStyle与autoGenerateMipmaps虽然也暴露为运行时实例属性但只在为新纹理生成时读取text、style 或 resolution 变化时仅调用onViewUpdate()不会重新生成纹理。源码中autoGenerateMipmaps的注释也明确提示修改后必须手动触发文本更新。核心实战模式用tagStyles实现自定义标签tagStyles把自定义或标准HTML 标签名映射为样式覆盖。嵌套继承是自动的warning嵌套在custom内部时会继承外层样式。标准标签如b、i、u、br按 HTML 语义正常工作。const message new HTMLText({ text: warningLow power/warning customPress any key/custom, style: { fontFamily: Arial, fontSize: 28, fill: 0xffffff, tagStyles: { warning: { fill: 0xff3333, fontWeight: bold }, custom: { fill: 0x66ccff, fontStyle: italic }, }, }, });从源码看tagStyles会被转换成真实的 CSS 选择器规则追加到样式表里tagStyleToCSS输出形如warning { color: #ff3333; font-weight: bold; }的规则见 textStyleToCSS.ts支持fill、stroke、dropShadow、fontSize、fontWeight、align、wordWrapWidth等属性的转换。需要注意canvasText的tagStyles只在有条目时才解析标签HTMLText 同理——HTMLText 本来就是真正的 HTML 解析这点比 canvasText更彻底。用addOverride注入原始 CSS对于TextStyle没有对应属性的 CSS 属性用addOverride注入原始 CSS。适合text-decoration、text-transform、超出TextStyle范围的letter-spacing以及任何在 SVGforeignObject内受支持的 CSS 属性。const styled new HTMLText({ text: Underlined shadowed text, style: { fontSize: 24, fill: 0xffffff }, }); styled.style.addOverride(text-decoration: underline); styled.style.addOverride(text-shadow: 2px 2px 4px rgba(0,0,0,0.5));源码层面cssOverrides是字符串数组addOverride会去重后追加并触发update()HTMLTextStyle.tsremoveOverride可反向移除同文件 L306-L315。在 textStyleToCSS.ts 中cssOverrides会被拼接到生成的 CSS 字符串末尾——因此它天然拥有最高优先级能覆盖所有内置样式。此外构造时也可通过style.cssOverrides数组一次性传入多条规则const richText new HTMLText({ text: div classtitleWelcome/div, style: { fontSize: 24, fill: #334455, cssOverrides: [ .title { font-size: 32px; color: red; }, .content { line-height: 1.5; } ], wordWrap: true, wordWrapWidth: 300, } });自动换行换行交给浏览器的 SVG 布局引擎处理因此它支持 CSS 换行的全部能力包括连字符断词hyphenation、两端对齐justification以及当字体和渲染 CSS 支持时的 RTL 文字。const wrapped new HTMLText({ text: A long paragraph of HTML text that should wrap automatically, style: { fontFamily: Arial, fontSize: 20, fill: 0xffffff, wordWrap: true, wordWrapWidth: 300, align: center, }, });对应源码wordWrap开启时生成max-width: {wordWrapWidth}pxbreakWords决定word-break: break-word还是normaltextStyleToCSS.tswhiteSpace: pre与wordWrap组合时会被改写为pre-wrap避免 pre 模式破坏自动换行同文件 L29。分辨率与 mipmap与 canvasText相同的模式resolution控制栅格化纹理的像素密度适合 Retina 屏autoGenerateMipmaps在文字被绘制得比原始尺寸更小时提升质量。const crisp new HTMLText({ text: Retina crisp, style: { fontSize: 32, fill: 0xffffff }, resolution: 2, autoGenerateMipmaps: true, });源码实现中纹理尺寸按(文本尺寸 padding * 2) * resolution计算并向上取整额外再加 2px 的uvSafeOffset防止 UV 出血HTMLTextSystem.tsSVG 根节点则通过transform: scale(resolution)放大getSVGUrl.ts。因此resolution直接决定纹理密度与清晰度。异步渲染纹理延迟一帧HTMLText 先渲染为 SVG blob再生成纹理。纹理在创建后一帧才可用。如果需要在显示前让文本就绪可以先把实例隐藏在下一帧再显示const htmlText new HTMLText({ text: Initial content, style: { fontSize: 24, fill: 0xffffff }, }); htmlText.visible false; app.stage.addChild(htmlText); app.ticker.addOnce(() { htmlText.visible true; });底层原因HTMLTextPipe._updateGpuText是 async 方法通过getTexturePromise异步构建纹理HTMLTextPipe.ts而HTMLTextSystem._buildTexturePromise中先要extractFontFamilies、getFontCss、measureHtmlText再loadSVGImage加载 SVG 图片全程是 Promise 链HTMLTextSystem.ts。测试代码里也专门提供了waitForPendingHTMLText工具来等待挂起的纹理生成HTMLText.test.ts。三个高频踩坑点[HIGH] 每帧更新 HTMLText 内容// 错误每帧触发 SVG 重渲染 栅格化 GPU 上传60fps 下开销过大 app.ticker.add(() { htmlText.text Score: ${score}; }); // 正确每帧变化的文本用 BitmapText仅重定位四边形无重栅格化 const bitmap new BitmapText({ text: Score: 0, style }); app.ticker.add(() { bitmap.text Score: ${score}; });每次HTMLText.text赋值都会重新渲染 SVG、栅格化并上传 GPU成本与 canvasText同级。任何每帧变化的文本都应该用BitmapText参考 references/bitmap-text.md。相关更新成本对比可参见 pixijs-scene-text SKILL 的对比表。[HIGH] 字体缺少 CORS 头如果 HTML 引用了跨域加载的 web 字体且对方没有返回 CORS 头SVGforeignObject会被污染栅格化失败或回退到默认字体。解决办法是让字体与页面同源或让服务器返回Access-Control-Allow-Origin。这正是 getSVGUrl.ts 用XMLSerializer序列化 SVG 并作为图片加载时所面临的浏览器安全限制。[MEDIUM] 期望创建帧就有尺寸// 错误text.width 此刻为 0测量是异步完成的 const text new HTMLText({ text: Hello, style }); text.x (app.screen.width - text.width) / 2; // 正确把布局计算推迟到下一帧 const text new HTMLText({ text: Hello, style }); app.ticker.addOnce(() { text.x (app.screen.width - text.width) / 2; });HTMLText 的测量是异步的。需要立即获得尺寸做布局时应把计算推迟到下一帧或者改用测量同步的 canvasText。测试也验证了text.width在初始状态下不包含paddingHTMLText.test.ts说明测量逻辑本身依赖异步排版结果。HTMLText 与其他文本类的选型在动手写代码前先明确 HTMLText 在 PixiJS v8 五类文本中的定位详见 pixijs-scene-text SKILL.md场景推荐类静态或低频更新的高质量样式标签Text分数、计时器、每帧变化的文本BitmapText需要b、i、br等混合格式HTMLText内联彩色标签如redWarning:/redText或HTMLText配合tagStyles逐字符动画短文本SplitText逐字符动画长文本/大量实例SplitBitmapTextCJK / 阿拉伯文 / emoji 密集文本Text或HTMLText自定义字体先Assets.load加载再设置style.fontFamily自定义字体在 HTMLText 中的用法与其他文本一致先通过Assets.load({ src: font.woff2, data: { family: MyFont } })加载data会转发给FontFace支持family、display、style、weights等字段再设置style.fontFamily。HTMLText 的字体处理链路会从文本与样式中提取字体族并生成内嵌的font-faceCSS见 extractFontFamilies.ts 与 getFontCss.ts。平台注意事项与性能边界从 HTMLText.ts 的文档注释与渲染管线实现可以确认以下事实渲染结果在不同浏览器间可能有细微差异——因为排版由各浏览器各自的引擎完成要求浏览器支持foreignObject性能与内存占用与 canvasText同级都走「重栅格化 GPU 上传」路径WebGPU 渲染器下由于 SVG 图片上传存在 CORS 问题系统会先把图片绘制到临时 canvas 再上传_createCanvas renderer.type RendererType.WEBGPU见 HTMLTextSystem.ts纹理生成通过TexturePool/BigPool复用池化资源同一样式键styleKey的多个 HTMLText 实例共享同一张纹理并做引用计数管理HTMLTextSystem.ts所以相同样式、不同内容的文本并不会各自重复生成纹理——纹理以text style组合为键。小结HTMLText 是 PixiJS v8 中「要 HTML/CSS 排版能力」时的首选完整的盒模型、真正的标签语义、自定义标签样式、任意 CSS 注入以及由浏览器提供的换行、连字与 RTL 支持。代价是异步渲染一帧延迟与和 canvasText同级的高更新成本。记住三条铁律每帧变化的文本用BitmapText需要立即测量的布局推迟一帧或用 canvasText跨域字体务必配置 CORS。更深入的学习资料HTMLText 样式与选项细节可阅读 pixijs-scene-text 技能文档 与 canvas 文本对照文档 references/text.md运行时渲染管线可继续阅读 HTMLText.ts、HTMLTextStyle.ts、HTMLTextSystem.ts 与 HTMLTextPipe.ts以及对应的测试 HTMLText.test.ts覆盖纹理清理、分辨率变化、上下文丢失恢复等边界行为。【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PixiJS v8 HTMLText 实战指南：用 SVG foreignObject 在 WebGL 中渲染富文本 HTML/CSS
PixiJS v8 HTMLText 实战指南用 SVG foreignObject 在 WebGL 中渲染富文本 HTML/CSS【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijsHTMLText 是 PixiJS v8 提供的富文本渲染方案它借助 SVGforeignObject把一段 HTML 片段交给浏览器排版引擎绘制再将结果栅格化为 GPU 纹理从而让开发者获得完整的 HTML/CSS 盒模型排版能力。本文以 skills/pixijs-scene-text/references/html-text.md 为核心骨架结合 src/scene/text-html 目录下的真实源码与测试系统讲解 HTMLText 的构造选项、自定义标签、CSS 覆盖、自动换行、分辨率与 mipmap、异步渲染等全部要点并给出常见性能误区的正确解法。读完本文你将能在自己的 PixiJS 场景里正确创建、排版与优化富文本并清楚它相比 canvasText与BitmapText的取舍边界。什么是 HTMLText适用场景与工作原理HTMLText 通过 SVGforeignObject包裹一段 HTML 片段来完成文字渲染。它支持完整的 HTML/CSS 排版模型真正的b、i、br、div、换行、嵌套样式、emoji全部交给浏览器排版后栅格化到纹理上。凡是 canvasText无法表达的富格式、混合内容、内联自定义标签都可以交给 HTMLText。从源码看HTMLText 的整体数据流是text与style先被转换为 CSS见 textStyleToCSS.ts随后由 getSVGUrl.ts 拼装svgforeignObject.../foreignObject/svg并序列化为 URL再由 loadSVGImage.ts 加载为图片最终经 HTMLTextSystem.ts 上传为纹理交给 HTMLTextPipe.ts 批量渲染。这一整条链路是异步的——纹理要到创建后的下一帧才可用这一点会贯穿本文的多个注意事项。const rich new HTMLText({ text: bBold/b and iitalic/i text, style: { fontFamily: Arial, fontSize: 24, fill: 0x333333, wordWrap: true, wordWrapWidth: 400, }, }); app.stage.addChild(rich);需要特别说明的两点HTMLText 是叶子节点。所有文本类都设置了allowChildren falseHTMLText 不能挂子节点需要分组时应包一层Container参见 pixijs-scene-core-concepts 的 constructor-options。样式类是HTMLTextStyle它是TextStyle减去leading、textBaseline、trim、filters四个字段后的结果——这四个属性在 SVG 渲染路径下不受支持其余TextStyle属性全部可用。源码中的定义见 HTMLTextStyle.tsHTMLTextStyleOptions extends OmitTextStyleOptions, leading | textBaseline | trim | filters。版本提示v8 中所有文本类都只支持 options 对象构造器v7 的new HTMLText(string, style)位置参数形式已移除旧签名在源码中标记为deprecated见 HTMLText.ts。HTMLText 构造选项HTMLTextOptionsHTMLText继承基础TextOptions其 style 类型为HTMLTextStyle/HTMLTextStyleOptions并额外增加 HTML 专属字段。继承自基类的text、style、anchor、resolution、roundPixels行为与 canvasText一致详见 references/text.md此处仅列出 HTMLText 特有的新增项OptionTypeDefaultDescriptionstyleHTMLTextStyle \| HTMLTextStyleOptionsnew HTMLTextStyle()HTML 文本样式对象或选项。等于TextStyle减去leading、textBaseline、trim、filters并新增cssOverrides用于注入原始 CSS。textureStyleTextureStyle \| TextureStyleOptionsundefined生成纹理的缩放模式nearest或linearTextureStyle的其他字段一律被忽略advanced。autoGenerateMipmapsbooleanTextureSource.defaultOptions.autoGenerateMipmaps为文本纹理生成 mipmap缩小绘制时提升质量。所有基础文本选项text、anchor、resolution、roundPixels均继承自TextOptions所有Container选项position、scale、tint、label、filters、zIndex等同样有效。构造示例const minimal new HTMLText({ text: bHello/b }); const styled new HTMLText({ text: iStyled/i, style: { fontSize: 24, fill: 0xffffff }, anchor: 0.5, resolution: 2, autoGenerateMipmaps: true, textureStyle: { scaleMode: linear }, });源码实现中的几个关键细节值得注意textureStyle在构造函数里若传入的是普通 options 对象会被实例化为TextureStyle并调用warnIgnoredTextureStyle检查——只有scaleMode会被读取HTMLText.ts。autoGenerateMipmaps的默认值确实回退到TextureSource.defaultOptions.autoGenerateMipmapsHTMLText.ts。text赋值时会先做 HTML 清洗把br规范为br/、hr规范为hr/、nbsp;替换为#160;并移除未闭合的破损标签避免 SVG 序列化失败HTMLText.ts。因此直接写br也是安全的。textureStyle与autoGenerateMipmaps虽然也暴露为运行时实例属性但只在为新纹理生成时读取text、style 或 resolution 变化时仅调用onViewUpdate()不会重新生成纹理。源码中autoGenerateMipmaps的注释也明确提示修改后必须手动触发文本更新。核心实战模式用tagStyles实现自定义标签tagStyles把自定义或标准HTML 标签名映射为样式覆盖。嵌套继承是自动的warning嵌套在custom内部时会继承外层样式。标准标签如b、i、u、br按 HTML 语义正常工作。const message new HTMLText({ text: warningLow power/warning customPress any key/custom, style: { fontFamily: Arial, fontSize: 28, fill: 0xffffff, tagStyles: { warning: { fill: 0xff3333, fontWeight: bold }, custom: { fill: 0x66ccff, fontStyle: italic }, }, }, });从源码看tagStyles会被转换成真实的 CSS 选择器规则追加到样式表里tagStyleToCSS输出形如warning { color: #ff3333; font-weight: bold; }的规则见 textStyleToCSS.ts支持fill、stroke、dropShadow、fontSize、fontWeight、align、wordWrapWidth等属性的转换。需要注意canvasText的tagStyles只在有条目时才解析标签HTMLText 同理——HTMLText 本来就是真正的 HTML 解析这点比 canvasText更彻底。用addOverride注入原始 CSS对于TextStyle没有对应属性的 CSS 属性用addOverride注入原始 CSS。适合text-decoration、text-transform、超出TextStyle范围的letter-spacing以及任何在 SVGforeignObject内受支持的 CSS 属性。const styled new HTMLText({ text: Underlined shadowed text, style: { fontSize: 24, fill: 0xffffff }, }); styled.style.addOverride(text-decoration: underline); styled.style.addOverride(text-shadow: 2px 2px 4px rgba(0,0,0,0.5));源码层面cssOverrides是字符串数组addOverride会去重后追加并触发update()HTMLTextStyle.tsremoveOverride可反向移除同文件 L306-L315。在 textStyleToCSS.ts 中cssOverrides会被拼接到生成的 CSS 字符串末尾——因此它天然拥有最高优先级能覆盖所有内置样式。此外构造时也可通过style.cssOverrides数组一次性传入多条规则const richText new HTMLText({ text: div classtitleWelcome/div, style: { fontSize: 24, fill: #334455, cssOverrides: [ .title { font-size: 32px; color: red; }, .content { line-height: 1.5; } ], wordWrap: true, wordWrapWidth: 300, } });自动换行换行交给浏览器的 SVG 布局引擎处理因此它支持 CSS 换行的全部能力包括连字符断词hyphenation、两端对齐justification以及当字体和渲染 CSS 支持时的 RTL 文字。const wrapped new HTMLText({ text: A long paragraph of HTML text that should wrap automatically, style: { fontFamily: Arial, fontSize: 20, fill: 0xffffff, wordWrap: true, wordWrapWidth: 300, align: center, }, });对应源码wordWrap开启时生成max-width: {wordWrapWidth}pxbreakWords决定word-break: break-word还是normaltextStyleToCSS.tswhiteSpace: pre与wordWrap组合时会被改写为pre-wrap避免 pre 模式破坏自动换行同文件 L29。分辨率与 mipmap与 canvasText相同的模式resolution控制栅格化纹理的像素密度适合 Retina 屏autoGenerateMipmaps在文字被绘制得比原始尺寸更小时提升质量。const crisp new HTMLText({ text: Retina crisp, style: { fontSize: 32, fill: 0xffffff }, resolution: 2, autoGenerateMipmaps: true, });源码实现中纹理尺寸按(文本尺寸 padding * 2) * resolution计算并向上取整额外再加 2px 的uvSafeOffset防止 UV 出血HTMLTextSystem.tsSVG 根节点则通过transform: scale(resolution)放大getSVGUrl.ts。因此resolution直接决定纹理密度与清晰度。异步渲染纹理延迟一帧HTMLText 先渲染为 SVG blob再生成纹理。纹理在创建后一帧才可用。如果需要在显示前让文本就绪可以先把实例隐藏在下一帧再显示const htmlText new HTMLText({ text: Initial content, style: { fontSize: 24, fill: 0xffffff }, }); htmlText.visible false; app.stage.addChild(htmlText); app.ticker.addOnce(() { htmlText.visible true; });底层原因HTMLTextPipe._updateGpuText是 async 方法通过getTexturePromise异步构建纹理HTMLTextPipe.ts而HTMLTextSystem._buildTexturePromise中先要extractFontFamilies、getFontCss、measureHtmlText再loadSVGImage加载 SVG 图片全程是 Promise 链HTMLTextSystem.ts。测试代码里也专门提供了waitForPendingHTMLText工具来等待挂起的纹理生成HTMLText.test.ts。三个高频踩坑点[HIGH] 每帧更新 HTMLText 内容// 错误每帧触发 SVG 重渲染 栅格化 GPU 上传60fps 下开销过大 app.ticker.add(() { htmlText.text Score: ${score}; }); // 正确每帧变化的文本用 BitmapText仅重定位四边形无重栅格化 const bitmap new BitmapText({ text: Score: 0, style }); app.ticker.add(() { bitmap.text Score: ${score}; });每次HTMLText.text赋值都会重新渲染 SVG、栅格化并上传 GPU成本与 canvasText同级。任何每帧变化的文本都应该用BitmapText参考 references/bitmap-text.md。相关更新成本对比可参见 pixijs-scene-text SKILL 的对比表。[HIGH] 字体缺少 CORS 头如果 HTML 引用了跨域加载的 web 字体且对方没有返回 CORS 头SVGforeignObject会被污染栅格化失败或回退到默认字体。解决办法是让字体与页面同源或让服务器返回Access-Control-Allow-Origin。这正是 getSVGUrl.ts 用XMLSerializer序列化 SVG 并作为图片加载时所面临的浏览器安全限制。[MEDIUM] 期望创建帧就有尺寸// 错误text.width 此刻为 0测量是异步完成的 const text new HTMLText({ text: Hello, style }); text.x (app.screen.width - text.width) / 2; // 正确把布局计算推迟到下一帧 const text new HTMLText({ text: Hello, style }); app.ticker.addOnce(() { text.x (app.screen.width - text.width) / 2; });HTMLText 的测量是异步的。需要立即获得尺寸做布局时应把计算推迟到下一帧或者改用测量同步的 canvasText。测试也验证了text.width在初始状态下不包含paddingHTMLText.test.ts说明测量逻辑本身依赖异步排版结果。HTMLText 与其他文本类的选型在动手写代码前先明确 HTMLText 在 PixiJS v8 五类文本中的定位详见 pixijs-scene-text SKILL.md场景推荐类静态或低频更新的高质量样式标签Text分数、计时器、每帧变化的文本BitmapText需要b、i、br等混合格式HTMLText内联彩色标签如redWarning:/redText或HTMLText配合tagStyles逐字符动画短文本SplitText逐字符动画长文本/大量实例SplitBitmapTextCJK / 阿拉伯文 / emoji 密集文本Text或HTMLText自定义字体先Assets.load加载再设置style.fontFamily自定义字体在 HTMLText 中的用法与其他文本一致先通过Assets.load({ src: font.woff2, data: { family: MyFont } })加载data会转发给FontFace支持family、display、style、weights等字段再设置style.fontFamily。HTMLText 的字体处理链路会从文本与样式中提取字体族并生成内嵌的font-faceCSS见 extractFontFamilies.ts 与 getFontCss.ts。平台注意事项与性能边界从 HTMLText.ts 的文档注释与渲染管线实现可以确认以下事实渲染结果在不同浏览器间可能有细微差异——因为排版由各浏览器各自的引擎完成要求浏览器支持foreignObject性能与内存占用与 canvasText同级都走「重栅格化 GPU 上传」路径WebGPU 渲染器下由于 SVG 图片上传存在 CORS 问题系统会先把图片绘制到临时 canvas 再上传_createCanvas renderer.type RendererType.WEBGPU见 HTMLTextSystem.ts纹理生成通过TexturePool/BigPool复用池化资源同一样式键styleKey的多个 HTMLText 实例共享同一张纹理并做引用计数管理HTMLTextSystem.ts所以相同样式、不同内容的文本并不会各自重复生成纹理——纹理以text style组合为键。小结HTMLText 是 PixiJS v8 中「要 HTML/CSS 排版能力」时的首选完整的盒模型、真正的标签语义、自定义标签样式、任意 CSS 注入以及由浏览器提供的换行、连字与 RTL 支持。代价是异步渲染一帧延迟与和 canvasText同级的高更新成本。记住三条铁律每帧变化的文本用BitmapText需要立即测量的布局推迟一帧或用 canvasText跨域字体务必配置 CORS。更深入的学习资料HTMLText 样式与选项细节可阅读 pixijs-scene-text 技能文档 与 canvas 文本对照文档 references/text.md运行时渲染管线可继续阅读 HTMLText.ts、HTMLTextStyle.ts、HTMLTextSystem.ts 与 HTMLTextPipe.ts以及对应的测试 HTMLText.test.ts覆盖纹理清理、分辨率变化、上下文丢失恢复等边界行为。【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考