pixijs-scene-text

PixiJSには5つのテキスト レンダリング クラスがあり、スタイリング、パフォーマンス、アニメーション間のさまざまなトレードオフをカバーしています。TextはフルCSSスタイル互換性のためにキャンバスにレンダリングします。BitmapTextは事前生成されたアトラスから読み込んで低コストの更新を実現します。HTMLTextはリッチマークアップのためSVGの<foreignObject>経由でHTMLフラグメントをレンダリングします。SplitTextとSplitBitmapTextは最初の2つのクラスをラップし、アニメーション用の文字ごと、単語ごと、行ごとのコンテナを公開します。

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タグ	非同期レンダリング（1フレームの遅延）、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 / アラビア語 / 絵文字の多いテキストが必要」 → 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を作成する前にアトラスを事前生成します。installなしでは、新しいfontFamilyで初めてBitmapTextを作成するとアトラスが遅延生成されます。
• MSDFフォント。 マルチチャネル符号付き距離フィールド フォントは任意のサイズで鮮明に保たれます。外部ツール（例：msdf-bmfont）で生成し、Assets.load('font.fnt')で読み込みます。カスタムビルドではimport 'pixi.js/text-bitmap'が必須です。

よくある間違い

[高] 毎フレーム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を使用してください。

[高] 位置指定コンストラクタ引数

間違い：

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

正解：

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

v8は(string, style)形式を削除しました。すべてのテキスト クラスはオプション オブジェクトを使用します。

[高] カスタムビルドでpixi.js/text-bitmapをインポートしていない

skipExtensionImports: trueまたはアグレッシブなツリーシェーキングの下では、import 'pixi.js/text-bitmap'を追加しない限り、Assets.load('font.fnt')は暗黙的に生データを返します。標準のimport { ... } from 'pixi.js'バンドルは拡張機能を含めています。

[中] テキスト インスタンスに子を追加する

すべてのテキスト クラスはallowChildren = falseを設定します。テキストを他のコンテンツとグループ化するにはContainerでラップしてください。

APIリファレンス

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