pixijs-scene-text

PixiJS 有 5 种文本渲染类，可在样式、性能和动画之间提供不同的权衡。Text 会渲染到画布，以完整保留 CSS 样式效果。BitmapText 从预生成的图集读取内容，更新开销低。HTMLText 通过 SVG <foreignObject> 渲染 HTML 片段，支持丰富标记。SplitText 和 SplitBitmapText 封装了前两种类，并提供字符、单词和行级容器，可用于动画。

假设你熟悉 pixijs-scene-core-concepts。所有文本类都是叶节点，不能有子节点。若要将多个文本实例组合在一起，请将它们放入 Container 中。

快速入门

const text = new Text({
  text: "Hello PixiJS",
  style: {
    fontFamily: "Arial",
    fontSize: 36,
    fill: 0xffffff,
    stroke: { color: 0x4a1850, width: 5 },
    dropShadow: { color: 0x000000, blur: 4, distance: 6 },
  },
});

text.anchor.set(0.5);
text.x = app.screen.width / 2;
text.y = 40;

app.stage.addChild(text);

所有文本类都使用选项对象构造函数；不支持 v7 中的 (string, style) 位置参数形式。

相关技能： pixijs-scene-core-concepts（叶节点、变换）、pixijs-assets（字体加载）、pixijs-performance（BitmapText 的权衡）、pixijs-color（用于填充和描边的 FillInput）、pixijs-scene-graphics（通过 FillInput 复用渐变和图案）。

变体

变体	适用场景	权衡	参考
Text	高质量的静态标签或不常更新的标签	更新开销大（画布重绘 + GPU 上传）	references/text.md
BitmapText	分数、计时器、游戏标签，以及每帧都会变化的内容	样式有限；字形图集固定；要实现清晰缩放需要 MSDF	references/bitmap-text.md
HTMLText	富文本、混合样式、真实 HTML 标签	异步渲染（延迟一帧）；更新开销与 Text 相近	references/html-text.md
SplitText	富样式文本的逐字符动画	每个字符都是一个完整的 Text；长字符串开销大	references/split-text.md
SplitBitmapText	长字符串或动态内容的逐字符动画	继承 BitmapText 的限制（字形图集；不使用 MSDF 时无法清晰缩放）	references/split-bitmap-text.md

如何选择

• “我需要一个带样式的静态标签” → Text。适用于标题、菜单、对话框和错误消息。参见 references/text.md。
• “我需要一个每帧更新的分数或计时器” → BitmapText。更新时只需重新定位四边形，无需重绘画布。参见 references/bitmap-text.md。
• “我需要使用 <b>、<i>、<br> 混合格式” → HTMLText。通过 SVG 进行真正的 HTML/CSS 渲染。参见 references/html-text.md。
• “我需要 <red>Warning:</red> 这样的行内彩色标签” → 使用带有 tagStyles 的 Text 或 HTMLText。两者都支持。
• “我需要单独为每个字符制作动画” → 短字符串使用 SplitText，长字符串或大量实例使用 SplitBitmapText。参见 references/split-text.md / references/split-bitmap-text.md。
• “我需要包含 CJK / 阿拉伯语 / 大量 emoji 的文本” → 使用 Text 或 HTMLText。BitmapText 无法处理，因为字形集对于单个图集来说过大。
• “我需要自定义字体” → 先通过 Assets.load({ src: 'font.woff2', data: { family: 'MyFont' } }) 加载字体，然后设置 style.fontFamily: 'MyFont'。适用于 Text 和 HTMLText。

更新成本对比

更新触发条件	Text	BitmapText	HTMLText	SplitText	SplitBitmapText
更改 .text	高	极低	高	极高（N 次文本重新渲染）	低（N 次四边形重新定位）
更改 .style	高	中	高	极高	中
移动（.x、.y）	无开销	无开销	无开销	无开销	无开销
旋转 / 缩放	无开销	无开销	无开销	无开销	无开销

“无开销”＝常规 Container 变换成本。“高”＝重新绘制画布并上传 GPU。“极低”＝仅重新定位四边形。每帧都会变化的字符串，仅在 BitmapText 或 SplitBitmapText 上更新。

快速了解

• 选项对象构造函数。 所有 v8 文本类都使用 new Text({ text, style, ... })。v7 的 (string, style) 形式已移除。
• tagStyles。 Text 和 HTMLText 支持通过 style.tagStyles 对标签进行单独样式设置。只有当 tagStyles 有条目时才会解析标签；否则 < 会被视为字面字符。
• BitmapFont.install。 在创建任何 BitmapText 之前预先生成图集。如果不安装，首个使用新 fontFamily 的 BitmapText 会延迟生成图集。
• MSDF 字体。 多通道有符号距离场字体在任何尺寸下都保持清晰。使用外部工具（例如 msdf-bmfont）生成，并通过 Assets.load('font.fnt') 加载。在自定义构建中需要 import 'pixi.js/text-bitmap'。

常见错误

[HIGH] 每帧更新 Text.text

错误：

app.ticker.add(() => {
  scoreText.text = `Score: ${score}`;
});

正确：

const scoreText = new BitmapText({ text: "Score: 0", style });
app.ticker.add(() => {
  scoreText.text = `Score: ${score}`;
});

每次更新 Text 都会重新栅格化整个字符串。对于任何每帧都会变化的值，请使用 BitmapText。

[HIGH] 使用位置参数构造函数

错误：

const text = new Text("Hello", { fontSize: 24 });

正确：

const text = new Text({ text: "Hello", style: { fontSize: 24 } });

v8 已移除 (string, style) 形式。所有文本类都使用选项对象。

[HIGH] 在自定义构建中未导入 pixi.js/text-bitmap

在 skipExtensionImports: true 或激进的摇树优化下，除非添加 import 'pixi.js/text-bitmap'，否则 Assets.load('font.fnt') 会静默返回原始数据。标准的 import { ... } from 'pixi.js' 包含此扩展。

[MEDIUM] 向文本实例添加子项

所有文本类都将 allowChildren = false。请用 Container 将文本与其他内容组合起来。

API 参考

• Text
• TextStyle
• BitmapText
• BitmapFont
• HTMLText
• HTMLTextStyle
• SplitText
• SplitBitmapText
• AbstractSplitText
• AbstractText