APL Text

APL Text

Textコンポーネントは、1行または複数行のテキストを表示します。

プロパティ

Textコンポーネントには、基本コンポーネントのプロパティに加えて次のプロパティがあります。列の意味を参照する。

プロパティ 型 デフォルト スタイル設定 動的 説明

color

色

テーマによって異なります

◯

◯

テキストの色です。

fontFamily

文字列

sans-serif

◯

◯

フォントファミリーです（「Amazon Ember Display」など）。

fontSize

負でない絶対ディメンション

40dp

◯

◯

テキストのサイズです。

fontStyle

normal、italic

normal

◯

◯

表示するフォントスタイルです。

fontWeight

normal、bold、100、200、300、400、500、600、700、800、900

normal

◯

◯

表示するフォントの太さです。

lang

文字列

""

◯

◯

テキストの言語です。設定した場合、APLはテキストの表示用にfontFamilyの言語固有のバージョンを探します。

letterSpacing

絶対ディメンション

0

◯

◯

文字間に追加するスペースです。

lineHeight

数値（パーセンテージ）

125%

◯

◯

行の高さの乗数です。

maxLines

負でない数値

0

◯

◯

表示するテキストの最大行数です。テキスト全体を表示できない場合は、テキストが切り詰められ、省略記号が追加されます。

onTextLayout

コマンドの配列

[]

×

×

テキストレイアウトが変更されたときに実行するコマンドです。

text

文字列

""

×

◯

このテキストボックスに表示するマークアップです。この値がnullまたは空の文字列""に設定されている場合、コンテンツは表示されません。

textAlign

auto、left、right、center、start、end

auto

◯

◯

段落内でのテキストの配置です。

textAlignVertical

auto、top、bottom、center

auto

◯

◯

テキストの垂直方向の配置です。

これらのプロパティのほとんどには、現在のテキストスタイルによってデフォルト値が指定されます。スタイルの説明については、リソースを参照してください。

Textコンポーネントは、ScrollView内に配置されない限りスクロールしません。

Textがイベントのソースまたはターゲットである場合は、以下の値がevent.sourceまたはevent.targetに報告されます。

{
  // Text固有の値
  "type": "Text",
  "text": String,      // 表示されるテキスト
  "color": Color,      // テキストの色

  // 一般的なコンポーネントの値
  "bind": Map,         // コンポーネントのデータバインディングコンテキストへのアクセス
  "checked": Boolean,  // チェック状態
  "disabled": Boolean, // 無効化の状態
  "focused": Boolean,  // フォーカス状態
  "height": Number,    // コンポーネントのdp単位の高さ（パディングを含む）
  "id": ID,            // コンポーネントのID
  "opacity": Number,   // コンポーネントの不透明度[0～1]
  "pressed": Boolean,  // 押下状態
  "uid": UID,          // ランタイムで生成されたコンポーネントの一意のID
  "width": Number      // コンポーネントのdp単位の幅（パディングを含む）
}

layoutDirectionコンポーネントプロパティ

コンポーネントのlayoutDirectionプロパティは、Textコンポーネントがテキストを整列するときにtextAlignプロパティをどのように解釈するかを決定します。

heightおよびwidthコンポーネントプロパティ

コンポーネントプロパティのheightとwidthは、Textコンポーネントのバウンディングボックスのサイズを制御します。バウンディングボックスが小さすぎてテキストを表示できない場合、デバイスはテキストを切り詰め、テキスト全体は表示されないことを示す省略記号を表示します。

コンポーネントのheightプロパティとwidthプロパティの詳細については、APL基本コンポーネントのプロパティを参照してください。

テキストのバウンディングボックスの詳細と例については、Textコンポーネントのバウンディングボックスを理解するを参照してください。

color

テキストの色です。テーマがライトの場合、デフォルトは#1E2222です。テーマがダークの場合、デフォルトは#FAFAFAです。

fontFamily

表示されるテキストのフォントを指定します。fontFamilyプロパティには、単一のフォント名か、コンマ区切りのフォント名のリストを含む文字列を指定できます。APLランタイムは、このリストを検索して、デバイスにインストールされている最初の名前付きフォントを見つけます。有効なフォントが見つからない場合は、デフォルトのsans-serifフォントが使用されます。

フォント名にはスペースを使用できます。APLでは、次の2種類のフォント名がサポートされています。

  • インストールされているフォントの固有名（「amazon-ember」、「times」、「times new roman」など）
  • 一般名（「serif」または「sans-serif」）

Alexaデバイスでは、特定のフォントセットの存在は保証されません。fontFamilyリストの最後には「serif」または「sans-serif」を指定して、有効なフォントを確実に利用できるようにしてください。

{
"type": "Text",
"fontFamily", "times new roman, times, georgia, serif"
}

多くのAlexaデバイスでは、「sans-serif」のデフォルトは「Amazon Ember Display」、「serif」のデフォルトは「Bookerly」です。アジアの一部のマーケットでは、これらのデフォルトは「Noto Sans CJK」になります。

alexa-stylesパッケージで利用可能なフォントスタイルの詳細については、フォントファミリーを参照してください。

fontSize

フォントのサイズです。通常はdpで表します。デフォルトは40dpです。

fontStyle

フォントのスタイルです。normalまたはitalicを指定できます。デフォルトはnormalです。

fontWeight

表示されるテキストのフォントの太さです。デフォルトはnormalです。normalとboldがランタイムに割り当てられています。100から900までの整数値はフォントの太さのバリエーションに対応し、数字が大きいほど太くなります。ほとんどのフォントは、これほど多くのバリエーションはサポートしていません。たとえば、Amazon Ember Displayには5種類の太さ（Thin、Light、Regular、Medium、Bold）があり、それぞれ100、300、500、700、900が割り当てられています。

fontWeightは、整数や文字列ではなく、列挙値のセットを表すことに注意してください。たとえば、750という値は無効であり、フォントの太さは700～800の間には設定されません。

fontWeightのリソースを作成する場合は、stringリソースを使用します。次の例では、リソースブロックでmyMidFontWeightとmyLightFontWeightというfontWeightのリソースを2つ作成します。

{
  "resources": [
    {
      "strings": {
        "myMidFontWeight": "500",
        "myLightFontWeight": "100"
      }
    }
  ]
}

lang

テキストの言語です。設定した場合、APLはテキストの表示用にfontFamilyの言語固有のバージョンを探します。

有効なフォントが見つからない場合、APLはこのプロパティを無視し、指定されたfontFamilyを使用します。

langプロパティにはBCP-47文字列（"ja-JP"など）を設定します。

次の例では、NotoSans-CJKフォントの日本語スタイルバージョンを使用してTextコンポーネントを表示します。

{
    "type": "APL",
    "version": "2024.3",
    "mainTemplate": {
        "item": {
            "type": "Text",
            "lang": "ja-JP",
            "fontFamily": "Noto Sans CJK"
        }
    }
}

注： Alexaデバイスには、特定の言語のフォントがインストールされていない場合があります。さまざまなデバイスでエクスペリエンスをテストして、正常に動作することを確認してください。

letterSpacing

文字間に追加するスペースです。デフォルトは0です。

lineHeight

行の高さの乗数です。デフォルトは125%です。

フォントの行送りは、fontSizeにlineHeightを掛けたものになります。たとえば、320dpiのディスプレイで、fontSizeが100dp、lineHeightが120%に設定されている場合、フォントサイズは200ピクセル、行送りは240ピクセルになります。lineHeightを100%未満に設定すると、文字が重なることがあります。

maxLines

表示するテキストの最大行数です。デフォルトは0で、制限がないことを表します。正の整数に設定すると、テキストが指定行数でクリッピングされ、テキストが切り詰められたことを示す省略記号が挿入されます。

onTextLayout

コンポーネントのテキストのレイアウト計算が変更されたときに実行するコマンドです。

Textコンポーネントが固定サイズの場合、この計算はコンポーネントのディメンションに影響しないため、ハンドラーはコンポーネントのレイアウトが完了した後に実行されます。Textコンポーネントのサイズがautoに設定されている場合、ハンドラーはレイアウト中に実行されます。

ハンドラーに定義されたコマンドでは、テキストプロパティを変更することができます。このシナリオでは、最終的な結果のテキストのみがレンダリングされます。

event.source.valueは、コンポーネントの標準のソース値に設定されます。event.sourceのプロパティの詳細については、イベントソースを参照してください。

生成されるイベントの形式は次のようになります。

"event": {
  "source": {
    "type": "Text",
    "handler": "TextLayout",
    ...                      // コンポーネントのソースのプロパティ
  },
  "laidOutText": STRING,  // 表示用に実際にレイアウトされる、クリッピングされたテキスト。省略記号を含みます。
  "isTruncated": BOOLEAN, // リクエストされたバインディングボックスにテキストが収まらず、切り詰められた場合はtrue。
  "textHeight": NUMBER,   // dp単位で測定されたテキストの高さ。
  "textWidth": NUMBER     // dp単位で測定されたテキストの幅。
}

次の例では、onTextLayoutイベントハンドラーでSetValueコマンドを使用して、TextコンポーネントのfontSizeを小さくします。このコマンドは、現在のフォントサイズが10より大きく、テキストが切り詰められている場合に実行されます。コマンドによってfontSizeが縮小されると、テキストのレイアウトが変わるため、もう一度onTextLayoutハンドラーが呼び出されます。この処理は、テキストが切り詰められなくなるか、フォントサイズが10以下になるまで続行されます。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "longTextContent"
    ],
    "items": [
      {
        "type": "Container",
        "height": "100%",
        "width": "100%",
        "padding": 16,
        "bind": [
          {
            "name": "FontSize",
            "value": 40
          },
          {
            "name": "TextToShow",
            "value": </span>"${longTextContent.reallyLongText}"<//span>
          }
        ],
        "items": [
          {
            "type": "Text",
            "text": "現在のfontSize：${FontSize}、文字数：${String.length(TextToShow)}<br>---"
          },
          {
            "type": "Text",
            "text": "${TextToShow}",
            "width": "100%",
            "height": "auto",
            "maxHeight": "50%",
            "fontSize": "${FontSize}",
            "onTextLayout": [
              {
                "when": "${event.isTruncated && event.source.bind.FontSize > 10}",
                "type": "SetValue",
                "property": "FontSize",
                "value": "${event.source.bind.FontSize - 10}"
              }
            ]
          }
        ]
      }
    ]
  }
}

クリップボードにコピーされました。

{
  "longTextContent": {
    "reallyLongText": "これは長いテキストブロックです。<code>Text</code>コンポーネントの<code>maxHeight</code>プロパティは、コンポーネントの高さを親<code>Container</code>の50% に制限します。この長いテキストは、切り詰めずに全体を収めることはできないため、<code>onTextLayout</code> コマンドの<code>when</code>条件はtrueに評価されます。<code>SetValue</code>コマンドはフォントを10単位縮小します。これにより、コンポーネントの再レイアウトがトリガーされます。<br><br>このレイアウト変更の結果、<code>onTextLayout</code>が再びトリガーされ、テキストがまだ切り詰められる場合は、もう一度フォントサイズを10単位縮小します。このプロセスは、<code>onTextLayout</code>ハンドラーの<code>when</code>条件が<code>false</code>に評価されるまで繰り返されます。<code>when</code>条件により、フォントサイズは10未満にならないことが保証されます。<br><br>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.Urna porttitor rhoncus dolor purus non enim.Porta nibh venenatis cras sed felis eget.Mauris pellentesque pulvinar pellentesque habitant morbi tristique senectus et netus.Dignissim convallis aenean et tortor.Purus semper eget duis at tellus at urna condimentum.Eros donec ac odio tempor orci dapibus ultrices in.Faucibus ornare suspendisse sed nisi lacus sed viverra.Sit amet mattis vulputate enim nulla aliquet porttitor lacus luctus.Egestas erat imperdiet sed euismod nisi porta.A condimentum vitae sapien pellentesque.Facilisi nullam vehicula ipsum a arcu cursus.Donec et odio pellentesque diam volutpat commodo.Enim tortor at auctor urna nunc.",
    "longText": "これは長いテキストブロックです。<code>Text</code>コンポーネントの<code>maxHeight</code>プロパティは、コンポーネントの高さを親<code>Container</code>の50% に制限します。この長いテキストは、切り詰めずに全体を収めることはできないため、<code>onTextLayout</code> コマンドの<code>when</code>条件はtrueに評価されます。<code>SetValue</code>コマンドはフォントを10単位縮小します。これにより、コンポーネントの再レイアウトがトリガーされます。<br><br>このレイアウト変更の結果、<code>onTextLayout</code>が再びトリガーされ、テキストがまだ切り詰められる場合は、もう一度フォントサイズを10単位縮小します。このプロセスは、<code>onTextLayout</code>ハンドラーの<code>when</code>条件が<code>false</code>に評価されるまで繰り返されます。<code>when</code>条件により、フォントサイズは10未満にならないことが保証されます。",
    "shortText": "これは短いテキストブロックです。Viewportにはテキスト全体が切り詰められずに表示されるため、40ポイントのフォントサイズを使用します。"
  }
}

onTextLayoutイベントハンドラーは、コンポーネントのデータバインディングコンテキストで高速モードで実行されます。

text

テキストブロックに表示するテキスト文字列です。空の文字列に設定すると、テキストは表示されません。nullに設定すると、空の文字列（""）と同じ結果になります。

テキストブロックでは、簡単なマークアップがサポートされます。サポートされるタグは次のとおりです。

タグ 説明 例 表示

<br>

改行を挿入します。改行は繰り返すことができます。

行1<br>行2

行1
行2

<strong>、<b>

タグ間のテキストを太字にします（太さ700）。

<b>大型</b>犬は人懐っこい。

大型犬は人懐っこい。

<em>、<i>

タグ間のテキストを斜体にします。

宿題の<em>エマ</em>を読む。

宿題のエマを読む。

<strike>

タグ間のテキストに取り消し線を引きます。

このドキュメントは<strike>良い</strike>とても良い。

このドキュメントは良いとても良い。

<u>

タグ間のテキストに下線を引きます。

そのチョコレート、<u>大好きでした</u>。

そのチョコレート、大好きでした。

<tt>、<code>

タグ間のテキストを等幅で表示します。

<code>main</code>関数がエントリポイントです。

main関数がエントリポイントです。

<sup>、<sub>

タグ間のテキストを上付きまたは下付きの文字として表示します。

H<sub>2</sub>Oの化学式についてはギブソン<sup>1</sup>を参照のこと。

H2Oの化学式についてはギブソン1を参照のこと。

<nobr>

テキストを自動的に複数行に折り返さないようにします。

<nobr>Dr. A. Ramaswamy</nobr>を途中で折り返さず、全体を1つの単語として扱います。
Dr.
A. Ramaswamyを途中で折り返さず、全体を1つの単語として扱います。

<span>

インライン書式を適用する範囲を定義します。spanでサポートされるアトリビュートを参照してください。

これは<span color="red">赤</span>です。

これは赤です。

<li>

リスト項目を定義します。詳細については、リストレイアウトを参照してください。

買い物リスト：<li>バナナ</li><li>にんじん</li>

買い物リスト：

  • バナナ
  • にんじん

マークアップ要素は入れ子にできます。マークアップの入れ子が不適切な場合の動作は未定義です。たとえば、次のコードは<b>と<u>の要素が正しく入れ子になっていないため、正しくレンダリングされません。

<b>昔、<u>小さな犬</b>がバッタを食べて具合が悪くなりました</u>。

以下は、テキストマークアップの使用例を示しています。

テキスト内のマークアップ文字は、文字実体参照で置き換える必要があります。

実体 文字 説明

&amp;

&

アンパサンド

&lt;

<

小なり記号

&gt;

>

大なり記号

&#nn;

10進数のUnicodeコードポイント

「nn」は有効な整数

&#xnn;

16進数のUnicodeコードポイント

「nn」は有効な16進数

数値実体参照は10進数と16進数で表記できます。たとえば、©は&#169;または&#xa9;と表記できます。

spanでサポートされるアトリビュート

<span>タグでは、次の表に示す名前付きアトリビュートがサポートされます。

アトリビュート 説明 例 表示

color

タグ間のテキストの色です。

任意の色にすることができます。リソースを使用して色を指定できます。

inheritに設定すると、テキストのcolorプロパティがタグ間の色として設定されます。

これは<span color="red">赤</span>です。

これは赤です。

fontSize

タグ間のテキストのフォントサイズです。負でない絶対ディメンションの配列にする必要があります。ディメンションはリソースを使用して設定できます。

inheritに設定すると、テキストのfontSizeがタグ間のフォントサイズとして設定されます。

これは<span fontSize="48dp"\>大きいフォント</span\>です。

これは大きいフォントです。

リストレイアウト

APLは、箇条書きリストのレイアウトをサポートしています。<li>タグでマークされた一連のテキストブロックは、箇条書きリストとしてレンダリングされます。現在サポートされているのはフラットな箇条書きリストだけで、<li>タグを入れ子にしてもフラット化されます。

たとえば、"買い物リスト：<li>じゃがいも（マッシュ用、あればユーコンゴールド、なければラセットでもよい）</li><li>バナナ<li>にんじん</li></li>パスタも忘れずに。"という文字列は、次のようにレンダリングされます。

買い物リスト：

  • じゃがいも（マッシュ用、あればユーコンゴールド、なければラセットでもよい）
  • バナナ
  • にんじん

パスタも忘れずに。

リストレイアウトでは、マーカーとしてUnicodeシンボルU+2022（行頭文字•）が使用されます。パディングおよびマーカーの間隔は、現在のフォントの空白の幅と同じになります。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "height": "100%",
        "width": "100%",
        "padding": 20,
        "items": [
          {
            "type": "Text",
            "text": "買い物リスト：<li>じゃがいも（マッシュ用、あればユーコンゴールド、なければラセットでもよい）</li><li>バナナ<li>にんじん</li></li>パスタも忘れずに。"
          }
        ]
      }
    ]
  }
}

textAlign

テキスト行の水平方向の配置を制御します。次のいずれかに設定します。

  • auto（デフォルト）
  • left
  • center
  • right
  • start
  • end

auto、start、endのプロパティはすべて、コンポーネントに指定されたlayoutDirectionに基づいてテキストを配置します。

プロパティ 左から右（"LTR"） 右から左（"RTL"）

auto

テキストを左揃えにします。

テキストを右揃えにします。

start

テキストを左揃えにします。

テキストを右揃えにします。

end

テキストを右揃えにします。

テキストを左揃えにします。

次の例では、textAlignのさまざまなオプションと、このプロパティに設定できる値を順番に切り替えるボタンを表示します。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "id": "mainContainer",
        "height": "100%",
        "width": "100%",
        "bind": [
          {
            "name": "TextAlignSetting",
            "description": "textAlignプロパティの値を格納する変数です。ほかのコンポーネント／コマンドからアクセスできるようにバインド変数を使用します。",
            "value": "auto"
          },
          {
            "name": "TAValues",
            "description": "textAlignプロパティに設定できる値です。",
            "value": ["auto","center","right","left","end","start"]
          },
          {
            "name": "TACurrentIndex",
            "description": "選択されているtextAlign設定のTAValues配列内でのインデックスを計算します。",
            "value": "${Array.indexOf(TAValues,TextAlignSetting)}"
          },
          {
            "name": "TANextValue",
            "description": "選択されている設定のインデックスを使用して、配列内の次の設定を特定します。配列の最後に達したら、リスト内の最初の項目（auto）にリセットします。",
            "value": "${TACurrentIndex < TAValues.length-1 ? TAValues[TACurrentIndex+1] : TAValues[0]}"
          }
        ],
        "items": [
          {
            "type": "AlexaHeader",
            "headerTitle": "textAlignプロパティの例"
          },
          {
            "type": "Text",
            "id": "myText",
            "height": "50%",
            "shrink": 1,
            "text": "これが変更対象のテキストです。<br><code>textAlign</code>プロパティは現在<b><code>${TextAlignSetting}</code></b>に設定されています。",
            "paddingStart": "@marginHorizontal",
            "paddingEnd": "@marginHorizontal",
            "textAlign": "${TextAlignSetting}"
          },
          {
            "type": "AlexaButton",
            "buttonText": "textAlignを${TANextValue}に変更",
            "alignSelf": "center",
            "primaryAction": [
              {
                "type": "SetValue",
                "property": "TextAlignSetting",
                "value": "${TANextValue}"
              }
            ]
          }
        ]
      }
    ]
  }
}

textAlignVertical

テキストボックス内のテキストの配置を指定します。テキストボックスの高さがテキストコンテンツよりも高い場合に使用されます。次のいずれかに設定します。

  • auto（デフォルト）
  • top
  • center
  • bottom

デフォルトはautoで、デフォルトのフォントの配置が使用されます。英語の場合、デフォルトのフォントの配置はtopと同じです。

サンプルテキスト

次の例は、指定されたtextを緑色で表示するTextコンポーネントを示しています。この例では、maxLinesプロパティで条件式を使用して、円形の小型デバイスではテキストを切り詰め、大きいデバイスではテキスト全体を表示します。

このページは役に立ちましたか？

最終更新日: 2025 年 11 月 26 日