pixijs-scene-text

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PixiJS has five text-rendering classes that cover different trade-offs between styling, performance, and animation.

Text

renders to a canvas for full CSS-style fidelity.

BitmapText

reads from a pre-generated atlas for cheap updates.

HTMLText

renders an HTML fragment via SVG

<foreignObject>

for rich markup.

SplitText

and

SplitBitmapText

wrap the first two classes and expose per-character, per-word, and per-line containers for animation.

Assumes familiarity with

pixijs-scene-core-concepts

. All text classes are leaf nodes; they cannot have children. Wrap multiple text instances in a

Container

to group them.

PixiJS 拥有五个文本渲染类，在样式、性能和动画之间做出了不同的权衡。

Text

渲染到画布以实现完整的CSS级样式保真度。

BitmapText

从预先生成的图集中读取数据，实现低开销的更新。

HTMLText

通过SVG

<foreignObject>

渲染HTML片段，支持丰富的标记。

SplitText

和

SplitBitmapText

封装前两个类，暴露逐字符、逐词和逐行的容器以支持动画。

假设你已熟悉

pixijs-scene-core-concepts

。所有文本类都是叶子节点；它们不能拥有子元素。若要将多个文本实例分组，请将它们包裹在

Container

中。

Quick Start

快速开始

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);

All text classes use options-object constructors; positional

(string, style)

from v7 is not supported.

Related skills:

pixijs-scene-core-concepts

(leaves, transforms),

pixijs-assets

(font loading),

pixijs-performance

(BitmapText tradeoffs),

pixijs-color

(

FillInput

for fill/stroke),

pixijs-scene-graphics

(gradients and patterns reused via

FillInput

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

复用渐变和图案）。

Variants

变体对比

Variant	Use when	Trade-offs	Reference
`Text`	High-quality static or infrequent-update labels	Expensive to update (canvas re-draw + GPU upload)	references/text.md
`BitmapText`	Scores, timers, gameplay labels, anything that changes every frame	Limited styling; fixed glyph atlas; requires MSDF for crisp scaling	references/bitmap-text.md
`HTMLText`	Rich formatted text, mixed styles, real HTML tags	Async rendering (one frame delay); similar update cost to `Text`	references/html-text.md
`SplitText`	Per-character animation with rich styling	Each char is a full `Text` ; expensive for long strings	references/split-text.md
`SplitBitmapText`	Per-character animation on long strings or dynamic content	Inherits BitmapText limitations (glyph atlas, no MSDF-free crispness)	references/split-bitmap-text.md

变体类型	使用场景	优缺点对比	参考文档
`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

When to use what

场景选型指南

"I need a styled static label" →
```
Text
```
. Use for titles, menus, dialog, error messages. See
```
references/text.md
```
.
"I need a score or timer that updates every frame" →
```
BitmapText
```
. Updates only reposition quads; no canvas re-draw. See
```
references/bitmap-text.md
```
.
"I need mixed formatting with

,

,
 
" →
```
HTMLText
```
. Real HTML/CSS rendering via SVG. See
```
references/html-text.md
```
.
"I need inline colored tags like
<red>Warning:</red>
" →
```
Text
```
or
```
HTMLText
```
with
```
tagStyles
```
. Both support it.
"I need to animate each character individually" →
```
SplitText
```
for short strings,
```
SplitBitmapText
```
for long strings or many instances. See
```
references/split-text.md
```
/
```
references/split-bitmap-text.md
```
.
"I need CJK / Arabic / emoji-heavy text" →
```
Text
```
or
```
HTMLText
```
.
```
BitmapText
```
fails because the glyph set is too large for a single atlas.

"I need a custom font" → Load via

Assets.load({ src: 'font.woff2', data: { family: 'MyFont' } })

first, then set

style.fontFamily: 'MyFont'

. Works for

Text

and

HTMLText

"我需要一个带样式的静态标签" → 使用
```
Text
```
。适用于标题、菜单、对话框、错误提示。详见
```
references/text.md
```
。
"我需要逐帧更新的分数或计时器" → 使用
```
BitmapText
```
。仅重新定位四边形；无需画布重绘。详见
```
references/bitmap-text.md
```
。
"我需要

、

、
 
这类混合格式" → 使用
```
HTMLText
```
。通过SVG实现真实HTML/CSS渲染。详见
```
references/html-text.md
```
。
"我需要
<red>警告:</red>
这类内联彩色标签" → 使用带
```
tagStyles
```
的
```
Text
```
或
```
HTMLText
```
。两者均支持该功能。
"我需要为每个字符单独设置动画" → 短字符串用
```
SplitText
```
，长字符串或多实例用
```
SplitBitmapText
```
。详见
```
references/split-text.md
```
/
```
references/split-bitmap-text.md
```
。
"我需要显示CJK/阿拉伯语/大量表情符号文本" → 使用
```
Text
```
或
```
HTMLText
```
。
```
BitmapText
```
因字形集过大无法放入单个图集而失效。

"我需要自定义字体" → 先通过

Assets.load({ src: 'font.woff2', data: { family: 'MyFont' } })

加载，再设置

style.fontFamily: 'MyFont'

。此方法适用于

Text

和

HTMLText

。

Update cost comparison

更新开销对比

Update trigger	Text	BitmapText	HTMLText	SplitText	SplitBitmapText
Changing `.text`	High	Very low	High	Very high (N text re-renders)	Low (N quad repositions)
Changing `.style`	High	Medium	High	Very high	Medium
Moving ( `.x` , `.y` )	Free	Free	Free	Free	Free
Rotating / scaling	Free	Free	Free	Free	Free

"Free" = normal Container transform cost. "High" = new canvas draw + GPU upload. "Very low" = quad reposition only. Update strings that change per-frame only on

BitmapText

SplitBitmapText

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

"无额外开销" = 常规Container变换开销。"高开销" = 新画布绘制 + GPU上传。"极低开销" = 仅四边形重定位。仅在

BitmapText

或

SplitBitmapText

上更新逐帧变化的字符串。

Quick concepts

核心概念速览

Options-object constructors. Every v8 text class uses
```
new Text({ text, style, ... })
```
. The v7
```
(string, style)
```
form is removed.
tagStyles
.
```
Text
```
and
```
HTMLText
```
support per-tag styling via
```
style.tagStyles
```
. Tags are only parsed when
```
tagStyles
```
has entries; otherwise
```
<
```
is treated literally.
BitmapFont.install
. Pre-generates an atlas before you create any
```
BitmapText
```
. Without install, the first
```
BitmapText
```
with a new
```
fontFamily
```
generates the atlas lazily.
MSDF fonts. Multi-channel Signed Distance Field fonts stay sharp at any size. Generate with external tools (e.g., msdf-bmfont), load via
```
Assets.load('font.fnt')
```
. Requires
```
import 'pixi.js/text-bitmap'
```
in custom builds.

选项对象构造函数：v8版本的所有文本类均使用
```
new Text({ text, style, ... })
```
形式。v7版本的
```
(string, style)
```
形式已被移除。
tagStyles
：
```
Text
```
和
```
HTMLText
```
支持通过
```
style.tagStyles
```
实现按标签设置样式。仅当
```
tagStyles
```
有配置项时才会解析标签；否则
```
<
```
会被视为字面量。
BitmapFont.install
：在创建任何
```
BitmapText
```
之前预先生成图集。若不执行install操作，首次使用新
```
fontFamily
```
创建
```
BitmapText
```
时会延迟生成图集。
MSDF字体：多通道有符号距离场字体在任何尺寸下都能保持清晰。需通过外部工具（如msdf-bmfont）生成，再通过
```
Assets.load('font.fnt')
```
加载。自定义构建中需引入
```
import 'pixi.js/text-bitmap'
```
。

Common Mistakes

常见错误

[HIGH] Updating

Text.text

every frame

[高风险] 逐帧更新

Text.text

Wrong:

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

Correct:

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

Every

Text

update re-rasterizes the whole string. Use

BitmapText

for any value that changes per-frame.

错误示例：

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] Positional constructor args

[高风险] 使用位置参数构造函数

Wrong:

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

Correct:

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

v8 removed the

(string, style)

form. All text classes use options objects.

错误示例：

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

正确示例：

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

v8版本已移除

(string, style)

形式。所有文本类均使用选项对象。

[HIGH] Not importing

pixi.js/text-bitmap

in custom builds

[高风险] 自定义构建中未引入

pixi.js/text-bitmap

Under

skipExtensionImports: true

or aggressive tree-shaking,

Assets.load('font.fnt')

silently returns raw data unless you add

import 'pixi.js/text-bitmap'

. The standard

import { ... } from 'pixi.js'

bundle includes the extension.

当开启

skipExtensionImports: true

或激进摇树优化时，

Assets.load('font.fnt')

会静默返回原始数据，除非你添加

import 'pixi.js/text-bitmap'

。标准的

import { ... } from 'pixi.js'

包已包含该扩展。

[MEDIUM] Adding children to a text instance

[中风险] 向文本实例添加子元素

Every text class sets

allowChildren = false

. Wrap in a

Container

to group text with other content.

所有文本类都设置了

allowChildren = false

。若要将文本与其他内容分组，请将其包裹在

Container

中。

pixijs-scene-text

Original

Translation

Quick Start

快速开始

Variants

变体对比

When to use what

场景选型指南

Update cost comparison

更新开销对比

Quick concepts

核心概念速览

Common Mistakes

常见错误

[HIGH] Updating
`Text.text`
every frame

[高风险] 逐帧更新
`Text.text`

[HIGH] Positional constructor args

[高风险] 使用位置参数构造函数

[HIGH] Not importing
`pixi.js/text-bitmap`
in custom builds

[高风险] 自定义构建中未引入
`pixi.js/text-bitmap`

[MEDIUM] Adding children to a text instance

[中风险] 向文本实例添加子元素

API Reference

API参考

pixijs-scene-text

Original

Translation

Quick Start

快速开始

Variants

变体对比

When to use what

场景选型指南

Update cost comparison

更新开销对比

Quick concepts

核心概念速览

Common Mistakes

常见错误

[HIGH] Updating Text.text every frame

[高风险] 逐帧更新Text.text

[HIGH] Positional constructor args

[高风险] 使用位置参数构造函数

[HIGH] Not importing pixi.js/text-bitmap in custom builds

[高风险] 自定义构建中未引入pixi.js/text-bitmap

[MEDIUM] Adding children to a text instance

[中风险] 向文本实例添加子元素

API Reference

API参考

[HIGH] Updating
`Text.text`
every frame

[高风险] 逐帧更新
`Text.text`

[HIGH] Not importing
`pixi.js/text-bitmap`
in custom builds

[高风险] 自定义构建中未引入
`pixi.js/text-bitmap`