メインコンテンツまでスキップ

テキストエレメント

テキストエレメントは、フォントアセットを使って文字列を描画します。ラベル、タイトル、スコア、会話のセリフなど、キャンバス内のインターフェースにあるテキストはすべてテキストエレメントです。

Text

テキストの作成​

const title = new pc.Entity('title');
title.addComponent('element', {
    type: pc.ELEMENTTYPE_TEXT,
    fontAsset: font.id,
    text: 'Game Over',
    fontSize: 64,
    color: new pc.Color(1, 0.55, 0.2),
    anchor: [0.5, 0.5, 0.5, 0.5],
    pivot: [0.5, 0.5]
});
screen.addChild(title);

fontは読み込み済みのフォントアセットです。フォントアセットの使用を参照してください。

フォントにない文字はスペースとして描画され、エンジンはその文字を示す警告をログに出力します。フォントアセットを作成するときに、テキストに必要な文字をすべて含めてください。文字の選択を参照してください。

サイズ、間隔、配置​

プロパティ効果
fontSizeテキストの高さ（スクリーンの単位）。デフォルトは32
lineHeight隣り合う行のベースライン間の距離。fontSizeを指定し、lineHeightを指定せずに作成したテキストエレメントでは、行の高さがフォントサイズと同じになります。後からfontSizeを変更しても、lineHeightは変わりません
spacing文字間の距離に掛ける倍率。デフォルトは1
alignmentエレメント内でのテキストの位置。左下の0, 0から右上の1, 1までの値で指定します。デフォルトの0.5, 0.5では中央に配置されます

配置の効果が現れるのは、固定幅のラベルや、長さの異なる折り返し行のように、エレメントがテキストより大きい場合だけです。

サイズの調整、折り返し、行数の制限​

デフォルトでは、テキストエレメントのサイズはテキストに合わせて決まります。Auto WidthとAuto Heightにより、テキストが変わるたびに、エレメントの幅と高さがテキストの幅と高さに設定されます。エレメントに独自のサイズを与えるには、これらをオフにします。

Wrap Linesがオンで、エレメントに折り返しの基準となる幅がある場合、テキストは新しい行に折り返されます。幅があるのは、Auto Widthがオフの場合か、エレメントのアンカーが水平方向に分割されていて、アンカーの幅がエレメントに与えられている場合です。Auto Heightがオンなら、行が増えるにつれてエレメントの高さが増します。

// 400単位で折り返し、上端から下に向かって伸びる段落
paragraph.element.autoWidth = false;
paragraph.element.width = 400;
paragraph.element.wrapLines = true;
paragraph.element.pivot = new pc.Vec2(0.5, 1);

maxLinesは行数を制限します。制限を超えたテキストは切り捨てられず、最後の行でエレメントの端を越えて続くため、行数の制限は縮小して収める機能と組み合わせるか、はみ出した部分をマスクで切り取ってください。テキストのレイアウト後は、linesに、1行につき1つの文字列を持つ配列としてテキストが格納されます。

縮小して収める​

Auto Fit WidthとAuto Fit Heightは、Max Font SizeとMin Font Size（デフォルトは32と8）の範囲で、テキストがエレメントに収まるまでフォントを縮小します。収まるテキストは最大サイズで描画され、最小サイズでも収まらないテキストは最小サイズで描画されてはみ出します。行の高さもフォントと一緒に縮小されます。

自動フィットは、自動サイズがオフの軸でのみ機能します。Auto Fit WidthにはAuto Widthのオフが、Auto Fit HeightにはAuto Heightのオフが必要です。自動サイズがオンの場合は、代わりにエレメントがテキストに合わせて大きくなります。

// 名前を200 × 40のバッジに収まるように縮小する。必要なら12単位まで
badge.element.autoWidth = false;
badge.element.autoHeight = false;
badge.element.width = 200;
badge.element.height = 40;
badge.element.autoFitWidth = true;
badge.element.autoFitHeight = true;
badge.element.maxFontSize = 32;
badge.element.minFontSize = 12;
Text Auto Font Size

両端揃えのテキスト​

Justifyをオンにすると、折り返された行は、単語間の間隔を広げることでエレメントの幅いっぱいに引き伸ばされます。段落の最後の行と、改行で終わる行は両端揃えにならず、元の配置のままです。両端揃えには折り返しが必要なため、Wrap Linesもオンにしてください。justifyプロパティは、エンジン2.22から使用できます。

Text Justify

アウトラインとシャドウ​

プロパティ効果
outlineColorとoutlineThickness文字の周囲のアウトライン。太さは0（アウトラインなし）から1までです
shadowColorとshadowOffset文字の下に描かれるシャドウ。オフセットはpc.Vec2で、各値の範囲は-1から1です

アウトラインとシャドウはフォントのシェーダーで描画され、エディターとfont-toolsが作成するMSDFフォントアセットで機能します。

マークアップ​

Enable Markupをオンにすると（エンジンとReactではenableMarkup、Web Componentsではenable-markup）、テキスト内のタグでテキストの一部にスタイルを付けられます。

タグ効果
[color="#ff0000"]…[/color]6桁の16進コードで指定した色でテキストを描画します。そのテキストでは、エレメントの色の代わりにこの色が使われます
[outline color="#000000" thickness="0.5"]…[/outline]テキストにアウトラインを付けます
[shadow color="#000000" offset="0.5"]…[/shadow]シャドウを追加します。各軸を個別に設定するには、offsetXとoffsetYを使います
message.element.enableMarkup = true;
message.element.text = 'You found the [color="#ffcc00"]golden key[/color]!';

タグの開始ではない[は、\[と書きます。閉じられていないタグなど、マークアップにエラーがある場合は、タグも含めてテキスト全体が書かれたとおりに描画され、エンジンが警告をログに出力します。

Text Markup

テキストを徐々に表示する​

rangeStartとrangeEndは、テキストの一部を描画します。描画されるのは、rangeStartの文字から、rangeEndの文字の手前までです。これらを変更してもテキストのレイアウトはやり直されないため、タイプライター効果のコストはわずかです。textを変更すると範囲は新しいテキスト全体にリセットされるので、そこからテキストの長さがわかります。

dialog.element.text = 'It is dangerous to go alone.';

// テキストを変更すると範囲がリセットされるため、rangeEndはテキストの長さになる
const length = dialog.element.rangeEnd;
let shown = 0;
const handle = app.on('update', (dt) => {
    // 1秒あたり20文字を表示する
    shown = Math.min(shown + dt * 20, length);
    dialog.element.rangeEnd = Math.floor(shown);
    if (shown === length) handle.off();
});
Text Typewriter

実行時のテキストの変更​

textを設定すると、テキストのレイアウトがやり直され、メッシュが再構築されます。これは、エレメントの移動や色の変更よりもコストがかかります。タイマーやスコアのように、少数のラベルを毎フレーム更新するのは問題ありません。ラベルが多い場合は、値が変わったときだけテキストを設定してください。描画順とパフォーマンスを参照してください。

プレイヤーの言語でテキストを表示するには、エレメントにテキストの代わりにローカライズキーを指定します。ローカライズを参照してください。

右から左に書く言語と複雑な文字体系​

テキストエレメントは、1文字につき1つのグリフを左から右へ描画します。アラビア語やヘブライ語のように右から左に書く言語では、まず文字を並べ替える必要があり、アラビア語ではさらに文字の連結形も必要です。これを追加する方法については、言語ごとの注意点を参照してください。

関連情報​