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' が必要です。

よくある間違い

[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