Skip to main content

SplitText 和 SplitBitmapText

🌐 SplitText & SplitBitmapText

SplitText 和 SplitBitmapText 类允许你将字符串拆分成单独的行、单词和字符——每个作为自己的显示对象——从而实现丰富的逐段动画和高级文本布局效果。

🌐 The SplitText and SplitBitmapText classes let you break a string into individual lines, words, and characters—each as its own display object—unlocking rich, per-segment animations and advanced text layout effects.

这些类的工作方式就像常规的 Text 或 BitmapText 一样，但提供对文本每个部分的精细控制。

🌐 These classes work just like regular Text or BitmapText, but provide fine-grained control over every part of your text.

warning

实验性： 这些功能是新的，可能在未来版本中发展变化。

什么是 SplitText 和 SplitBitmapText？​

🌐 What Are SplitText & SplitBitmapText?

SplitText 和 SplitBitmapText 都扩展了 PixiJS 容器，为你的字符串的每一行、每一个单词和每一个字符生成嵌套的显示对象。

🌐 Both SplitText and SplitBitmapText extend PixiJS containers, generating nested display objects for each line, word, and character of your string.

区别在于底层文本渲染：

🌐 The difference is in the underlying text rendering:

类基类最适合
SplitTextText富样式文本
SplitBitmapTextBitmapText高性能动态文本

适合：

  • 逐字符或逐词动画
  • 基于行的进入或退出效果
  • 交互式文本元素
  • 复杂的动画排版

基本用法​

🌐 Basic Usage

SplitText 示例​

🌐 SplitText Example

import { SplitText } from 'pixi.js';

const text = new SplitText({
  text: 'Hello World',
  style: { fontSize: 32, fill: 0xffffff },

  // Optional: Anchor points (0-1 range)
  lineAnchor: 0.5, // Center lines
  wordAnchor: { x: 0, y: 0.5 }, // Left-center words
  charAnchor: { x: 0.5, y: 1 }, // Bottom-center characters
  autoSplit: true,
});

app.stage.addChild(text);

SplitBitmapText 示例​

🌐 SplitBitmapText Example

import { SplitBitmapText, BitmapFont } from 'pixi.js';

// Ensure your bitmap font is installed
BitmapFont.install({
  name: 'Game Font',
  style: { fontFamily: 'Arial', fontSize: 32 },
});

const text = new SplitBitmapText({
  text: 'High Performance',
  style: { fontFamily: 'Game Font', fontSize: 32 },
  autoSplit: true,
});

app.stage.addChild(text);

访问片段​

🌐 Accessing Segments

这两个类都提供了便捷的片段数组：

🌐 Both classes provide convenient segment arrays:

console.log(text.lines); // Array of line containers
console.log(text.words); // Array of word containers
console.log(text.chars); // Array of character display objects

每一行都包含一个单词，每个单词都包含一个字符。

🌐 Each line contains its words, and each word contains its characters.

锚点说明​

🌐 Anchor Points Explained

分段锚点控制旋转或缩放等变换的原点。

🌐 Segment anchors control the origin for transformations like rotation or scaling.

归一化范围：0（起始）到1（结束）

🌐 Normalized range: 0 (start) to 1 (end)

锚点含义
0,0左上角
0.5,0.5中心
1,1右下角

示例：

const text = new SplitText({
  text: 'Animate Me',
  lineAnchor: { x: 1, y: 0 }, // Top-right lines
  wordAnchor: 0.5, // Center words
  charAnchor: { x: 0, y: 1 }, // Bottom-left characters
});

动画示例（使用 GSAP）​

🌐 Animation Example (with GSAP)

import { gsap } from 'gsap';

const text = new SplitBitmapText({
  text: 'Split and Animate',
  style: { fontFamily: 'Game Font', fontSize: 48 },
});

app.stage.addChild(text);

// Animate characters one by one
text.chars.forEach((char, i) => {
  gsap.from(char, {
    alpha: 0,
    delay: i * 0.05,
  });
});

// Animate words with scaling
text.words.forEach((word, i) => {
  gsap.to(word.scale, {
    x: 1.2,
    y: 1.2,
    yoyo: true,
    repeat: -1,
    delay: i * 0.2,
  });
});

基于现有文本创建​

🌐 Creating from Existing Text

将现有文本对象转换为分段版本：

🌐 Convert existing text objects into segmented versions:

import { Text, SplitText, BitmapText, SplitBitmapText } from 'pixi.js';

const basicText = new Text({
  text: 'Standard Text',
  style: { fontSize: 32 },
});
const splitText = SplitText.from(basicText);

const bitmapText = new BitmapText({
  text: 'Bitmap Example',
  style: { fontFamily: 'Game Font', fontSize: 32 },
});
const splitBitmap = SplitBitmapText.from(bitmapText);

配置选项​

🌐 Configuration Options

两个类的共享选项：

🌐 Shared options for both classes:

选项描述默认值
text要渲染和拆分的字符串内容必填
style文本样式配置（根据文本类型而异）{}
autoSplit当文本或样式更改时自动更新段落true
lineAnchor行容器的锚点（number 或 {x, y}）0
wordAnchor单词容器的锚点（number 或 {x, y}）0
charAnchor字符对象的锚点（number 或 {x, y}）0

全局默认值​

🌐 Global Defaults

更改每个类的全局默认值：

🌐 Change global defaults for each class:

SplitText.defaultOptions = {
  lineAnchor: 0.5,
  wordAnchor: { x: 0, y: 0.5 },
  charAnchor: { x: 0.5, y: 1 },
};

SplitBitmapText.defaultOptions = {
  autoSplit: false,
};

限制​

🌐 Limitations

⚠️ 字符间距： 将文本拆分为单独的对象会移除浏览器或字体的字距调整。与标准 Text 相比，间距可能略有差异。

性能说明​

🌐 Performance Notes

拆分文本会创建额外的显示对象。对于简单的静态文本，使用常规的 Text 对象更高效。当你需要以下情况时使用 SplitText：

🌐 Splitting text creates additional display objects. For simple static text, a regular Text object is more efficient. Use SplitText when you need:

  • 逐句段动画
  • 交互式或响应式文本效果
  • 复杂的布局

这些类也适用此处列出的相同性能限制。

🌐 The same performance limitations outlined here apply for these classes as well.

API 参考​

🌐 API Reference