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.

警告

实验性：这些功能是新功能，可能会在未来版本中改进。

¥Experimental: These features are new and may evolve in future versions.

什么是 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高性能动态文本

适合：

¥Perfect for:

  • 逐字符或逐词动画

    ¥Per-character or per-word animations

  • 基于行的入口或出口效果

    ¥Line-based entrance or exit effects

  • 交互式文本元素

    ¥Interactive text elements

  • 复杂的动画排版

    ¥Complex animated typography

基本用法​

¥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右下角

示例：

¥Example:

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 相比，间距可能会略有不同。

¥⚠️ Character Spacing: Splitting text into individual objects removes browser or font kerning. Expect slight differences in spacing compared to standard 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:

  • 逐句段动画

    ¥Per-segment animations

  • 交互式或响应式文本效果

    ¥Interactive or responsive text effects

  • 复杂的布局

    ¥Complex layouts

此处 中概述的相同性能限制也适用于这些类。

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

API 参考​

¥API Reference