APL基本コンポーネントのプロパティ

コンポーネントは、viewportに表示されるプリミティブな要素です。

Alexa Presentation Language（APL）のコンポーネントとは、クライアントでレンダリングされるプリミティブな視覚コンポーネントです。たとえば、Textコンポーネントは画面にテキストを表示します。すべてのAPLコンポーネントは、基本プロパティのセットを共有します。

プロパティ

すべてのコンポーネントは、次のプロパティをサポートしています。

「デフォルト」列は、プロパティのデフォルト値を示します。必須プロパティはすべて設定する必要があります。設定しない場合、コンポーネントはインフレートされません。デフォルト値のないプロパティは、「デフォルト」列にダッシュ（—）が表示されています。デフォルト値なしの解釈はプロパティによって異なります。たとえば、speechプロパティが設定されていない場合、SpeakItemコマンドを実行してもコンポーネントはテキストを読み上げません。maxHeightが設定されていない場合、コンポーネントは任意の高さに拡大される可能性があります。これは、maxHeightを大きい数値に設定した場合と同等です。

「スタイル設定」列は、スタイルから設定できるプロパティかどうかを示します。コンポーネントのプロパティに値を直接指定すると、スタイル定義の値はすべてオーバーライドされます。次の例では、myTextStyleの定義に関係なく、Textコンポーネントの不透明度は常に0.5に設定されます。

    {
      "type": "Text",
      "opacity": 0.5,
      "style": "myTextStyle"
    }

「動的」列は、SetValueコマンドを使用して動的に変更できるプロパティかどうかを示します。SetValueを使用して動的プロパティを設定すると、スタイル値はすべて上書きされます。動的プロパティの設定を解除するメカニズムはありません。

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

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

コンポーネント固有の値がevent.sourceとevent.targetに追加されます。

accessibilityLabel

アクセシビリティモードでスクリーンリーダーが使用する文字列です。

actions

障がいなどの理由でユーザーが操作できない場合は、支援技術を使ってプログラムで画面上のコンポーネントを操作できます。コンポーネントは、この技術で使う一連のアクションを定義します。actionsプロパティにはアクションオブジェクトのリストが含まれます。各アクションオブジェクトには、nameと、実行するcommandsのセットがあります。アクションのnameには、標準アクション、カスタムアクションのいずれかを指定できます。

以下は、1つの標準アクション（activate）と1つのカスタムアクション（thumbsup）を定義するTouchWrapperの例です。

{
  "type": "TouchWrapper",
  "actions": [
    {
      "name": "activate",
      "label": "ユーザーへの応答",
      "command": {
        "type": "SendEvent",
        "arguments": "Activated by action invocation"
      }
    },
    {
      "name": "thumbsup",
      "label": "いいね！します。",
      "command": {
        "type": "SetValue",
        "property": "Rating",
        "value": 1
      }
    }
  ]
}

actionsプロパティは、次の表に挙げたプロパティを持つオブジェクトの配列です。

labelプロパティには、アクションのローカライズされた説明を指定します。ラベルの例として、「アイテムを削除」や「返信」などがあります。

enabledプロパティにより、アクションを呼び出すことができるかどうかを決定します。無効のアクションもアクセシビリティシステムに表示される可能性がありますが、利用不可としてマークされます。

アクションリスト内の2つのアクションが同じnameプロパティを持つ場合、最初の1つが使用されます。2つ目のアクションは、最初のアクションが有効になっていない場合でも無視されます。

標準アクションは、標準イベントハンドラーに関連付けられた名前で予約されています。コマンド配列なしでアクションリストに標準アクションを指定した場合、アクションを呼び出すと指定されたイベントハンドラーが呼び出されます。標準アクションには、暗黙的と明示的の2種類があります。明示的なアクションを有効にするには、コンポーネントのactionsプロパティにアクションを指定する必要があります。暗黙的なアクションはデフォルトで有効になりますが、コマンドをオーバーライドすることができます。

次の表に、標準アクションを示します。

以下は、activateアクションを定義するTouchWrapperコンポーネントの例です。activateアクションにはコマンド配列がありません。このため、このアクションを呼び出すと、onPressプロパティで定義されたコマンドが呼び出されます。

{
  "type": "TouchWrapper",
  "onPress": {
    "type": "SendEvent",
    "arguments": "押されました。"
  },
  "actions": [
    {
      "name": "activate",
      "label": "サーバーへのメッセージ"
    }
  ]
}

タップジェスチャーと「押す」操作は非常に似ているため、「activate」アクションの結果としてonPressが呼び出されてもそのイベントハンドラーが指定されていない場合、onTapハンドラーがフォールバックとして実行されます。

以下の例では、「activate」アクションにコマンド配列がなく、onPressハンドラーが指定されていないため、「activate」アクションはonTapハンドラーを呼び出します。

{
  "type": "TouchWrapper",
  "gestures": [
    {
      "type": "Tap",
      "onTap": {
        "type": "SendEvent",
        "arguments": "これはactivateアクションで呼び出されます"
      }
    }
  ],
  "actions": [
    {
      "name": "activate",
      "label": "サーバーへのメッセージ"
    }
  ]
}

暗黙的な標準アクションは無効にすることができます。次の例では、Pagerのアクセシビリティスクロールを無効にします。

{ "type": "Pager", "actions": [ { "name": "scrollforward", "label": "アクセシビリティスクロール", "enabled": false } ] }

bind

コンポーネントのbindプロパティは、ローカルのバインド変数を使用して、コンポーネントとその子のデータバインディングコンテキストを拡張します。バインド変数の詳細については、APLバインド変数を参照してください。

checked

checkedプロパティは、コンポーネントがchecked状態かどうかを設定します。スタイルを定義する際にコンポーネントの状態として使用できます。

コンポーネントのchecked状態を変更するには、SetValueコマンドを使用します。

親のchecked状態を継承するには、子コンポーネントのinheritParentStateプロパティをtrueに設定します。

disabled

disabledプロパティは、コンポーネントがdisabled状態かどうかを設定します。スタイルを定義する際にコンポーネントの状態として使用できます。disabledがtrueの場合、コンポーネントはタッチイベントに応答しません。

コンポーネントのdisabled状態を変更するには、SetValueコマンドを使用します。

親のdisabled状態を継承するには、子コンポーネントのinheritParentStateプロパティをtrueに設定します。

display

コンポーネントのdisplayプロパティは、コンポーネントが画面に表示されるかどうかと、コンポーネントがレイアウトの計算にどのように影響するかを決定します。次の表に示す値のいずれかに設定します。

displayプロパティは、コンポーネントの作成時に使用されるデータバインディングコンテキスト、順序数、インデックスには影響しません。たとえば、3つの子を持つコンテナーがあり、最初の子がdisplay=noneに設定されているとしても、最初の子はindex=0でデータバインドされ、次の子はindex=1になります。

次の表は、コンテンツの表示と非表示を切り替えるさまざまな方法を示しています。

「フォーカスの可否」列はキーボードフォーカスを許可するかどうかを示します。「タッチの可否」列はタッチイベントに応答するかどうかを示します。displayがinvisibleまたはnoneの場合、タッチイベントはコンポーネントが存在しないものとして通過し、スタック順で次のコンポーネントによって処理されます。displayがnormalのコンポーネントはタッチイベントを通過させませんが、タッチイベントに応答するのはdisabledがfalseの場合だけです。

APL 2024.2以降では、pointerEventsプロパティにより、「タッチの可否」列と「タッチおよびホバーのパススルー」列に示されている動作がオーバーライドされる可能性があります。pointerEventsがnoneの場合、コンポーネントとその子はポインターイベントのターゲットになりません。イベントは、Zオーダー順で次に対象となるコンポーネントに渡されます。

display=invisibleのコンポーネントの子要素は描画されません。つまり、invisibleのコンポーネントがvisibleの子要素を持つことはありません。同様に、コンポーネントにdisplay=noneが指定されている場合、コンポーネントとそのすべての子要素は表示階層から削除され、画面上のスペースを占有しません。

entities、entity

Opaque（不透明）のentityデータです。Alexaデバイスはentityデータをコンテキストとしてスキルに返します。このプロパティを通じて、コンポーネントの目的に関する情報を提供してスキルコードで使用できます。

このプロパティにはオブジェクトの配列を設定します。各オブジェクトには、id、type、valueの各プロパティを指定できます。その他のプロパティは視覚コンテキストに含められません。

視覚コンテキストの詳細については、スキルリクエストのAPL視覚コンテキストを参照してください。

handleTick

時間が経過すると実行されるTickイベントハンドラーの配列です。

ティックイベントハンドラーに対して生成されたイベントは、次のような形式になります。

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // コンポーネントの型（Pager、TouchWrapperなど）       
    "handler": "Tick",
    ...                     // コンポーネントのソースプロパティ  
  }
}

event.source.typeプロパティには、コンポーネントの名前（TouchWrapper、ScrollViewなど）が設定されます。event.sourceの詳細についてはイベントソースを参照してください。

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

handleVisibilityChange

コンポーネントの可視領域または全体的な不透明度が変更されたときに実行する可視性変更ハンドラーの配列です。

コンポーネントの可視性変更ハンドラーは、コンポーネントのデータバインディングコンテキストで実行されます。

height

コンポーネントの最終的な高さを計算するために使用される値です。heightは、次の4つの方法のいずれかで設定できます。

• 絶対ディメンション - 100dp、25vh、24pxなどの値は、コンポーネントの高さを固定します。50.2のような数字だけの値は、dp値として解釈されます。したがって、50.2は"50.2dp"と同じです。絶対ディメンションの詳細については、絶対ディメンションを参照してください。
• 相対ディメンション - 25%などの値は、コンポーネントの高さを親コンポーネントの高さの割合として設定します。これを機能させるには、親コンポーネントでディメンションが定義されている必要があります。親コンポーネントのheightがautoの場合、子コンポーネントで相対的な高さを使用することは未定義の動作となり、0に設定されます。相対ディメンションの詳細については、相対ディメンションを参照してください。
• 自動ディメンション - autoを指定すると、子の高さにパディングを加えた高さがコンポーネントに適用されます。Frameの場合、この高さには境界線の高さも含まれます。
• ディメンション未設定 - コンポーネントのheightが指定されていない場合、高さはコンポーネントのデフォルトの高さに戻ります。デフォルトの高さについては、個別のコンポーネントのドキュメントを参照してください。

heightには、垂直方向のパディング、境界線、含まれているすべての子の高さの合計よりも小さい値を設定することができます。この場合、コンポーネントのコンテンツは最終的なコンポーネントの高さにクリップされます。

コンポーネントのheightは、可能な限り相対ディメンションで指定してください。相対ディメンションでサイズを指定したコンポーネントは、異なるサイズの画面に合わせて調整できます。ドキュメントがさまざまなデバイスで適切に表示されるようにする方法の詳細については、以下を参照してください。

• レスポンシブ対応のAPLドキュメントを作成する
• サイズ変更が可能なタブレットなどのデバイスをサポートする

id

コンポーネントのインスタンスに対して定義できる識別子です。idにより、視覚階層で特定のコンポーネントを見つけることができます。有効なidを表す正規表現は[_a-zA-Z][_a-zA-Z0-9]*です。ほかのidと同じ値を使用しても構いませんが、一意の値を割り当てることをお勧めします。内部的には、APLによって各コンポーネントに内部ID（uid）が割り当てられます。

次の例は、TextコンポーネントとImageコンポーネントを含むContainerを示しています。

{
  "type": "Container",
  "items": [
    {
      "type": "Text",
      "id": "myText"
    },
    {
      "type": "Image"
    }
  ]
}

Container、Text、Imageには、それぞれ:1001、:1002、:1003のような一意の内部ID値が割り当てられます。Alexaは、生成された内部uidと開発者が割り当てたid値の両方を視覚コンテキストにレポートします。

コンポーネントのidは、コマンドのターゲットとなるコンポーネントを指定するためにセレクター構文で使用できます。

inheritParentState

コンポーネントの状態を、コンポーネントの親の状態に置き換えます。コンポーネントの見た目を親の状態に合わせて変更する必要があるときに使用します。たとえば、ユーザーがTouchWrapperを押したときに、TouchWrapperの内側にあるTextコンポーネントの色を変更する場合を考えます。inheritParentStateをtrueに設定すると、TouchWrapperの状態が変わるたびにTextコンポーネントの状態も変更されます。

layoutDirection

コンポーネントがレンダリングされる方向を指定します。このプロパティを次のいずれかに設定します。

• inherit – デフォルトです。コンポーネントは、親からlayoutDirectionを継承します。コンポーネントがmainTemplateの直下にある場合、コンポーネントはドキュメントで指定されたlayoutDirectionを継承します。
• LTR – コンポーネントは左から右方向を使用します。
• RTL – コンポーネントは右から左方向を使用します。

コンポーネントのlayoutDirectionは、paddingStartプロパティとpaddingEndプロパティはpaddingLeftプロパティとpaddingRightプロパティをどのように上書きするかを決定します。

layoutDirectionプロパティによって、以下のコンポーネントの内部レイアウトが決まります。

• Container
• Text
• EditText
• タッチ可能なコンポーネント
• Pager
• Sequence
• GridSequence

layoutDirectionを設定するための推奨方法は、ドキュメントレベルのlayoutDirectionをデータソースの値に設定することです。レイアウトの特定のコンポーネントにドキュメント全体のlayoutDirectionとは異なる設定をする必要がある場合は、コンポーネントレベルのlayoutDirectionを使用します。

以下の例では、Container内に複数のテキストブロックを表示しています。すべてのテキストブロックがドキュメントのデフォルトのlayoutDirectionを使用していますが、1つだけ値をオーバーライドして別の値を使用しています。

この例では、データソースのexampleDataSource.responseLanguage.layoutDirectionを変更すると、画面に表示されるレイアウトが自動的に変更されます。スキルに送信されたリクエストで指定されたロケールを使用して、layoutDirectionとlangの値を特定し、これらの値をデータソースのAPLに渡します。

さまざまな言語をサポートし、リクエストのロケールを判定する方法の詳細については、多言語に対応するスキルを開発するを参照してください。

maxHeight

コンポーネントの最大の高さを制限するディメンションです。コンポーネントの高さがmaxHeightより大きくなることはありません。maxHeightプロパティは常に、minHeightプロパティと同じかそれ以上にする必要があります。maxHeightプロパティが指定されていない場合は、無限と見なされます。

maxWidth

コンポーネントの最大の幅を制限するディメンションです。コンポーネントの幅がmaxWidthより大きくなることはありません。maxWidthプロパティは常に、minWidthプロパティと同じかそれ以上にする必要があります。maxWidthプロパティが指定されていない場合は、無限と見なされます。

minHeight

コンポーネントの最小の高さを制限するディメンションです。コンポーネントの高さがminHeightより小さくなることはありません。minHeightプロパティは常に、maxHeightプロパティと同じかそれ以下にする必要があります。minHeightプロパティが指定されていない場合は、0と見なされます。

minWidth

コンポーネントの最小の幅を制限するディメンションです。コンポーネントの幅がminWidthより小さくなることはありません。minWidthプロパティは常に、maxWidthプロパティと同じかそれ以下にする必要があります。minWidthプロパティが指定されていない場合は、0と見なされます。

onCursorEnter

カーソルがコンポーネントのアクティブな領域に入ったときに実行するコマンドです。

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

disabled状態がtrueに設定されているコンポーネントは、カーソルイベントの変更に応答しないため、onCursorEnterイベントハンドラーに割り当てられたコマンドは実行されません。無効なコンポーネントの上にカーソルがある状態で、そのコンポーネントが有効になった場合、そのコンポーネントに対してonCursorEnterイベントが生成されます。

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

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // コンポーネントの型（Pager、TouchWrapperなど）       
    "handler": "CursorMove",
    ...                     // コンポーネントのソースプロパティ  
  },
  "component": {
    "x": Number,            // コンポーネントのmoveイベントのX位置（dp）        
    "y": Number,            // コンポーネントのmoveイベントのY位置（dp）        
    "width": Number,        // コンポーネントのdp単位での横幅     
    "height": Number,       // コンポーネントのdp単位での縦幅     
  }
}

event.source.typeプロパティには、コンポーネントの名前（TouchWrapper、ScrollViewなど）が設定されます。event.sourceの詳細についてはイベントソースを参照してください。

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

onCursorExit

カーソルがコンポーネントのアクティブな領域から出たときに実行するコマンドです。

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

disabled状態がtrueに設定されているコンポーネントは、カーソルイベントの変更に応答しないため、onCursorExitイベントハンドラーに割り当てられたコマンドは実行されません。無効なコンポーネントの上にカーソルがある状態で、そのコンポーネントが有効になった場合、そのコンポーネントに対してonCursorExitイベントが生成されます。

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

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // コンポーネントの型（Pager、TouchWrapperなど）       
    "handler": "CursorExit",
    ...                     // コンポーネントのソースプロパティ  
  }
}

event.source.typeプロパティには、コンポーネントの名前（TouchWrapper、ScrollViewなど）が設定されます。event.sourceの詳細についてはイベントソースを参照してください。

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

onCursorMove

カーソルがコンポーネントのアクティブな領域内を移動したときに実行するコマンドです。

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

disabled状態がtrueに設定されているコンポーネントは、カーソルイベントの変更に応答しないため、onCursorMoveイベントハンドラーに割り当てられたコマンドは実行されません。

移動イベントは、onCursorEnterイベントまたはonCursorExitイベントの実行時には実行されません。

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

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // コンポーネントの型（Pager、TouchWrapperなど）       
    "handler": "CursorMove",
    ...                     // コンポーネントのソースプロパティ  
  },
  "component": {
    "x": Number,            // コンポーネントのmoveイベントのX位置（dp）        
    "y": Number,            // コンポーネントのmoveイベントのY位置（dp）        
    "width": Number,        // コンポーネントのdp単位での横幅     
    "height": Number,       // コンポーネントのdp単位での縦幅     
  }
}

event.source.typeプロパティには、コンポーネントの名前（TouchWrapper、ScrollViewなど）が設定されます。event.sourceの詳細についてはイベントソースを参照してください。

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

onMount

コンポーネントが最初に表示されたときに実行されるコマンドです。マウントコマンドは、視覚的な画面切り替えを表示するために使用します。マウント時には、event.source.valueは未設定のままになります。

onMountコマンドは、ドキュメントの読み込み時にトリガーされます。コンポーネント自体が非表示である場合や画面に表示されていない場合でも、コンポーネントのonMountコマンドは実行されます。

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

"event": {
    "source": {
      "type": "COMPONENT_TYPE", // コンポーネントの型（Pager、TouchWrapperなど）       
      "handler": "Mount",
      ...                     // コンポーネントのソースプロパティ  
    }
  }

event.source.typeプロパティには、コンポーネントの名前（TouchWrapper、ScrollViewなど）が設定されます。event.sourceの詳細についてはイベントソースを参照してください。

onMountイベントハンドラーは、コンポーネントのデータバインディングコンテキストで通常モードで実行されます。コンポーネントレベルとドキュメントレベルのonMountハンドラーの相互作用については、ドキュメントのonMountプロパティを参照してください。

onLayout

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

このハンドラーは、コンポーネントが最初に表示されるとき（onMount）に呼び出され、その後、コンポーネントのレイアウトが変更されるたびに再び呼び出されます。

このハンドラーはレイアウトが計算された直後に呼び出されますが、イベントを受け取った時点では、新しいレイアウトはまだ画面に反映されていない可能性があります。これは特に、レイアウト（ディメンション）アニメーションが進行中の場合に当てはまります。

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

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

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // コンポーネントの型（Pager、TouchWrapperなど）
    "handler": "Layout",
    ...                      // コンポーネントのソースプロパティ
  },
  "width": NUMBER,     // レイアウト変更後のコンポーネントの幅
  "height": NUMBER,    // レイアウト変更後のコンポーネントの高さ
  "x": NUMBER,         // 親コンポーネント内でのコンポーネントのX座標
  "y": NUMBER          // 親コンポーネント内でのコンポーネントのY座標
}

次の例では、onLayoutを使用して水平方向のSequenceのサイズを変更し、異なるサイズの4つのTextコンポーネントが表示されるようにします。これらのコンポーネントは、それぞれwidthがautoに設定されています。TextコンポーネントのonLayoutハンドラーは、when条件を使用して、最初の4つの子項目についてコマンドを1回ずつ実行します。SetValueコマンドによってSequenceの幅を広げ、Text項目の表示に十分な大きさにします。

• APLドキュメント

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "mainTemplate": {
    "items": [
      {
        "type": "Container",
        "height": "100%",
        "width": "100%",
        "padding": "16dp",
        "bind": [
          {
            "name": "TotalItemsToShow",
            "value": ["最初の項目", "テキスト1", "3番目の項目", "T3", "テキスト4", "テキスト5", "テキスト6"]
          }
        ],
        "items": [
          {
            "type": "Sequence",
            "scrollDirection": "horizontal",
            "data": "${TotalItemsToShow}",
            "height": "auto",
            "width": 100,
            "maxWidth": "75%",
            "items": {
              "type": "Text",
              "width": "auto",
              "height": "auto",
              "text": "${data}",
              "spacing": 10,
              "onLayout": [
                {
                  "when": "${index <= 3}",
                  "type": "SetValue",
                  "componentId": ":parent()",
                  "property": "width",
                  "value": "${event.x + event.width}"
                }
              ]
            }
          },
          {
            "type": "Text",
            "id": "showResult",
            "text": "合計項目数：${TotalItemsToShow.length}（すべて表示するにはスクロール）"
          }
        ]
      }
    ]
  }
}

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

onSpeechMark

speechプロパティで指定されたオーディオにスピーチマークが見つかったときに実行するコマンドです。

スピーチマークの詳細については、スピーチマーク - Amazon Pollyを参照してください。

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

onSpeechMarkイベントは、コンポーネントのspeechプロパティにスピーチマークのあるオーディオが設定されている場合に、SpeakItemコマンドの実行中に発生します。

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

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // コンポーネントの型（Pager、TouchWrapperなど）
    "handler": "SpeechMark",
    ...                      // コンポーネントのソースプロパティ
  },
  "markType": MARK_TYPE,     // スピーチマークのタイプ
  "markTime": NUMBER,        // スピーチマークの開始時間（ミリ秒）
  "markValue": STRING
}

各スピーチマークにはタイプがあり、次の表に示す値のいずれかになります。

たとえば、SpeakItemコマンドが「right」という単語を読み上げたときにwordスピーチマークが生成された場合、次のイベントが生成されます。

"event": {
"source": {
    "type": "Text",
    "handler": "SpeechMark",
  },
  "markType": "word",
  "markTime": 3562,
  "markValue": "right"
}

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

以下の例は、SpeakItemを使用して短文を読み上げるAPLドキュメントを示しています。この文には向きを表す単語が含まれています。onSpeechMarkハンドラーは、文中の単語に対応する矢印のベクターグラフィックを表示するコマンドを実行します。たとえば、Alexaが「right」という単語を読み上げると矢印が右を指し、Alexaが「down」という単語を読み上げると下を指します。 この例では、onSpeechMarkハンドラーでwhenを使用して、「right」、「left」、「up」、「down」、「disappear」の各単語に応じてベクターグラフィックを更新します。

サンプルドキュメント： スピーチマークによるアニメーションと読み上げの同期  

{
  "type": "APL",
  "version": "2022.2",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.6.0"
    }
  ],
  "graphics": {
    "DirectionalArrow": {
      "description": "矢印を表示します。向きを変更するには、Directionパラメーターを設定します。",
      "type": "AVG",
      "version": "1.2",
      "parameters": [
        "Direction"
      ],
      "width": 100,
      "height": 100,
      "items": [
        {
          "type": "path",
          "description": "右",
          "strokeOpacity": "${Direction == 1 ? 1.0 : 0.0}",
          "pathData": "M0,50 100,50 50,0 100,50 50,100",
          "stroke": "#FF0000",
          "strokeWidth": 5
        },
        {
          "type": "path",
          "description": "下",
          "strokeOpacity": "${Direction == 2 ? 1.0 : 0.0}",
          "pathData": "M50,0 50,100 100,50 50,100 0,50",
          "stroke": "#4CAF50",
          "strokeWidth": 5
        },
        {
          "type": "path",
          "description": "左",
          "strokeOpacity": "${Direction == 3 ? 1.0 : 0.0}",
          "pathData": "M100,50 0,50 50,100 0,50 50,0",
          "stroke": "#FFEB3B",
          "strokeWidth": 5
        },
        {
          "type": "path",
          "description": "上",
          "strokeOpacity": "${Direction == 4 ? 1.0 : 0.0}",
          "pathData": "M50,100 50,0 0,50 50,0 100,50",
          "stroke": "#2196F3",
          "strokeWidth": 5
        }
      ]
    }
  },
  "mainTemplate": {
    "parameters": [
      "magicArrow"
    ],
    "items": [
      {
        "type": "Container",
        "items": [
          {
            "type": "AlexaHeader",
            "headerTitle": "${magicArrow.properties.headerTitle}"
          },
          {
            "type": "AlexaButton",
            "buttonText": "クリックして開始",
            "alignSelf": "center",
            "primaryAction": [
              {
                "type": "SpeakItem",
                "componentId": "magicArrowGraphic"
              }
            ]
          },
          {
            "type": "Text",
            "text": "${magicArrow.properties.directionPlainText}",
            "style": "textStyleBody",
            "textAlignVertical": "center",
            "maxLines": "${@viewportProfile == @hubRoundSmall ? 2 : '' }",
            "padding": [
              "@marginHorizontal",
              "@spacingSmall"
            ]
          },
          {
            "type": "VectorGraphic",
            "id": "magicArrowGraphic",
            "alignSelf": "center",
            "Direction": 0,
            "source": "DirectionalArrow",
            "speech": "${magicArrow.properties.directionSpeech}",
            "onSpeechMark": [
              {
                "when": "${event.markValue == 'right'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 1
              },
              {
                "when": "${event.markValue == 'down'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 2
              },
              {
                "when": "${event.markValue == 'left'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 3
              },
              {
                "when": "${event.markValue == 'up'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 4
              },
              {
                "when": "${event.markValue == 'disappear'}",
                "type": "SetValue",
                "property": "Direction",
                "value": 0
              }
            ]
          }
        ]
      }
    ]
  }
}

サンプルデータソース： スピーチマークによるアニメーションと読み上げの同期  

{
  "magicArrow": {
    "properties": {
      "headerTitle": "魔法の矢印",
      "narration": "<speak>これから、私の声に合わせて動く魔法の矢印を表示します。まず、矢印は左を指します。続いて、右を指します。それから下を指し、そして上も指します。最後に、矢印は消失します。</speak>"
    },
    "transformers": [
      {
        "transformer": "ssmlToSpeech",
        "inputPath": "narration",
        "outputName": "directionSpeech"
      },
      {
        "transformer": "ssmlToText",
        "inputPath": "narration",
        "outputName": "directionPlainText"
      }
    ]
  }
}

opacity

このコンポーネントとその子に不透明度（opacity）を一律に適用します。opacityは0以上1以下の数値です。この範囲を超える数値を指定した場合は、1に設定されます。実際に表示されるコンポーネントの不透明度は、opacity値に上位レベルの不透明度の値を掛けたものになります。

たとえば、現在のコンポーネントの不透明度が0.5で、親の不透明度が0.8の場合、実際に表示されるコンポーネントの不透明度は0.4になります。コンポーネントの不透明度を0に設定すると表示されなくなりますが、コンポーネント階層からは削除されません。

padding

paddingプロパティは、コンポーネントの周りにスペースを追加します。計算されたコンポーネントのwidthとheightにより、コンポーネントの外側の境界と切り抜かれる境界が定義されます。paddingに指定する値は、コンポーネントの外側の境界とコンテンツとの間のスペースを指定します。paddingプロパティには、負ではない絶対ディメンションの値を指定する必要があります。

paddingの値は、paddingプロパティで指定できます。コンポーネントの各辺には別々のプロパティを使用します。

• padding – コンポーネントの複数の辺に対してパディングを設定する値の配列を受け取ります。
• paddingBottom – コンポーネントの下側にパディングを設定します。
• paddingLeft – コンポーネントの左側にパディングを設定します。
• paddingRight – コンポーネントの右側にパディングを設定します。
• paddingTop – コンポーネントの上側にパディングを設定します。
• paddingStart – コンポーネントのlayoutDirectionに応じて、左または右のパディングを上書きするパディングです。詳細については、paddingStart, paddingEndを参照してください。
• paddingEnd – コンポーネントのlayoutDirectionに応じて、左または右のパディングを上書きするパディングです。詳細については、paddingStart, paddingEndを参照してください。

paddingプロパティは1～4個の値の配列です。左、上、右、下の順に指定します。この配列に指定する値が4つより少ない場合、paddingプロパティは以下の表に記載したルールに従って4つの要素の配列に拡張されます。

ほかの4つのpaddingプロパティは、特定の辺のpaddingに指定された値を上書きします。以下の例は、同じパディングを指定する3つの方法です。それぞれ、左と右に10、上に20、下に40のパディングが設定されます。

1つのpaddingプロパティで、左に10、上に20、右に10、下に40の値を指定します。

{
  "padding": [10,20,10,40]
}

1つのpaddingプロパティで、左と右に10、上と下に20の値を指定します。次に、paddingBottomプロパティで下の値を40に上書きします。

{
  "padding": [10,20],
  "paddingBottom": 40
}

1つのpaddingプロパティで、4辺すべてのパディングを10に指定する値を設定します。次に、paddingTopで上のパディング値を20に上書きします。次に、paddingBottomで下のパディング値を40に上書きします。

{
  "padding": 10,
  "paddingTop": 20,
  "paddingBottom": 40
}

paddingStart, paddingEnd

指定すると、paddingStartプロパティとpaddingEndプロパティによって paddingLeftプロパティとpaddingRightプロパティが上書きされます。上書きはlayoutDirectionプロパティに依存します。

たとえば、layoutDirectionがLTRの場合、次のコンポーネントでは左のパディングが15、右のパディングが20になります。layoutDirectionがRTLの場合、コンポーネントは右のパディングが15、左のパディングが20になります。

{
    "paddingLeft": 10,
    "paddingRight": 10,
    "paddingStart": 15,
    "paddingEnd": 20
}

preserve

Reinflateコマンドでドキュメントを再インフレートするときに保存する、動的なコンポーネントプロパティとバインドされたプロパティの配列です。Reinflateコマンドは、古いコンポーネントのidが新しいidと一致した場合にこれらのプロパティを保持します。コンポーネントにidがない場合、preserveに指定されたコンポーネントプロパティは保存されません。

以下の例では、TouchWrapperのchecked状態が保存されます。

{
  "type": "TouchWrapper",
  "id": "MyUniqueID",
  "preserve": ["checked"]
}

バインドされるプロパティも保存できます。以下の例では、Counterと呼ばれるバインドされるプロパティと、Counterを増分させるTouchWrapperを定義しています。preserve配列には、このバインドされるプロパティの名前が含まれています。このため、ドキュメントが再インフレートされるとCounterの値が保存されます。

{
  "type": "TouchWrapper",
  "id": "MyCounterButton",
  "bind": [
    {
      "name": "Counter",
      "value": 0
    }
  ],
  "preserve": [
    "Counter"
  ],
  "items": {
    "type": "Text",
    "text": "このボタンを${Counter}回押しました"
  },
  "onPress": [
    {
      "type": "SetValue",
      "property": "Counter",
      "value": "${Counter + 1}"
    }
  ]
}

コンポーネントの中には、動的なプロパティやバインドされるプロパティに加えて、コンポーネント固有のデータを保存するpreserveプロパティを持つものもあります（名前はコンポーネント固有）。たとえば、スクロールするコンポーネントにはスクロール位置を保存するpreserveプロパティが含まれます。次のコンポーネントのpreserveプロパティは、以下を参照してください。

• FlexSequence
• GridSequence
• Pager
• ScrollView
• Sequence
• Video

preserveプロパティは、新しいコンフィギュレーション値によって追加されたeventプロパティを使ってコンポーネントのデータバインディングコンテキストで評価されます。そうすることで、保存するプロパティを動的に選択できます。

pointerEvents

コンポーネントをポインターイベントのターゲットにできるかどうかを決定します。ポインターイベントには、タッチイベントやカーソルイベント（上、移動、下、キャンセル）、ジェスチャー、ホバーが含まれますが、これらに限定されません。

このプロパティには次の値を指定できます。

以下の例では、グラデーションを表示するVectorGraphicがSequenceの上に重ねて配置され、Sequenceの下部を覆っています。デフォルトの動作では、VectorGraphicがすべてのタッチイベントをキャプチャして通過させないため、Sequenceの下部をタッチしてドラッグしてもスクロールしません。pointerEventsをnoneに設定すると、ユーザーはSequenceのどの部分でもタッチしてドラッグし、コンテンツをスクロールできるようになります。

• APLドキュメント

{
  "type": "APL",
  "version": "2024.3",
  "theme": "dark",
  "background": "#232F3E",
  "mainTemplate": {
    "items": {
      "type": "Container",
      "height": 400,
      "width": 400,
      "alignItems": "center",
      "items": [
        {
          "type": "Sequence",
          "height": "100%",
          "width": "100%",
          "data": ["red", "blue", "green", "yellow", "gray", "purple"],
          "item": {
            "type": "Frame",
            "height": 125,
            "width": "100%",
            "background": "${data}"
          },
          "lastItem": [
            {
              "type": "Text",
              "text": "リストの終わり",
              "textAlign": "center",
              "textAlignVertical": "center",
              "height": 125
            }
          ]
        },
        {
          "type": "VectorGraphic",
          "id": "OverlayEffect",
          "position": "absolute",
          "height": 100,
          "width": 400,
          "top": 300,
          "source": "GradientOverlay",
          "pointerEvents": "none"
        }
      ]
    }
  },
  "graphics": {
    "GradientOverlay": {
      "type": "AVG",
      "version": "1.2",
      "width": 400,
      "height": 100,
      "resources": [
        {
          "gradients": {
            "linearGradient": {
              "inputRange": [
                0,
                0.8
              ],
              "colorRange": [
                "#ffffff00",
                "#000000ff"
              ],
              "type": "linear",
              "x2": 0,
              "y2": 1,
              "x1": 0,
              "y1": 0
            }
          }
        }
      ],
      "items": [
        {
          "type": "path",
          "pathData": "M0,0 L400,0 L400,100 L0,100 Z",
          "fill": "@linearGradient"
        }
      ]
    }
  }
}

role

roleは、コンポーネントの目的に関して、機械が読み取り可能な情報を提供します。一部の支援技術がこの情報を使用しています。たとえば、スクリーンリーダーは画面に表示されたコンポーネントを説明する際にroleを利用できます。

APLは、コンポーネント上で次のロールをサポートします。

• adjustable – コンポーネントは「調整」可能です（例：スライダーはadjustableです）。
• alert – ユーザーに提示する必要のある重要な情報を含む領域です。
• button – クリックまたは押下されたときに一般的なアクションをトリガーする入力です。linkロールと関連があります。
• checkbox – チェックやチェック解除、チェック状態の混在が可能なチェックボックスです。
• combobox – ユーザーが複数の選択肢から選択できるコンボボックスを表します。
• header – コンテンツセクションのヘッダーとして機能します（例：ナビゲーションバーのタイトルなど）。
• image – コンポーネントを画像として処理します。コンポーネントがボタンとしても機能する場合は、imagebuttonを使用します。
• imagebutton – ボタンとしても機能する画像コンポーネントです。
• keyboardkey – コンポーネントはキーボードのキーとして機能します。
• link – トリガーされると、ユーザーエージェントが新しいリソースやディスプレイに移動する入力です。
• list – listitemのリストを含む領域です。
• listitem – リスト内の個々の項目です。listitemの上位レベルにはlistが必要です。
• menu – コンポーネントは選択可能なメニューです。
• menubar – コンポーネントは複数のメニューのコンテナーです。
• menuitem – menu内の項目を表します。
• progressbar – コンポーネントはタスクの進捗状況を表します。
• radio – コンポーネントはラジオボタンとして機能します。
• radiogroup – コンポーネントにはradioボタンのグループが含まれます。
• scrollbar – 領域のスクロールを制御するスクロールバーを表します。
• search – 検索フィールドとしても処理されるテキストフィールドコンポーネントです。
• spinbutton – 選択肢のリストを開くボタンです。
• summary – アプリの初回起動時に、コンポーネントがアプリ内で現在どのような状態になっているかという情報を提供するために使用します。
• switch – チェック／チェック解除ではなく、オン／オフを切り替えることができるスイッチを表します。
• tab – タブを表します。tabの上位レベルにはtablistが必要です。
• tablist – tabコンポーネントのリストを含む領域です。
• text - コンポーネントは、変更できない静的なテキストとして扱われます。
• timer – 経過時間や残り時間を表すカウンターを表示する領域です。
• toolbar – ツールバー（アクションボタンやコンポーネントのコンテナー）を表すために使用します。

shadowColor

影の色です。通常は、ある程度の透明度がある色が使用されます。影の色には、全体のopacity（不透明度）も適用されます。

shadowHorizontalOffset

影の描画の水平方向のオフセットです。正の数では影が右に、負の数では影が左に移動します。

shadowRadius

影のぼかしの半径です。

shadowVerticalOffset

影の描画の垂直方向のオフセットです。正の数では影が下に、負の数では影が上に移動します。

speech

コンテンツをスピーチ音声に変換するトランスフォーマーから提供される不透明データです。speechプロパティで使用できるオーディオは、次のトランスフォーマーによって出力されます。

• ssmlToSpeech
• textToSpeech
• aplAudioToSpeech

データバインディング式を使用して、speechプロパティをトランスフォーマーの出力にバインドできます。その後、SpeakItemコマンドまたはSpeakListコマンドを使用して、Alexaでコンテンツを読み上げることができます。

style

コンポーネントのプロパティを設定するために使用する名前付きのスタイルです。

trackChanges

追跡するコンポーネントプロパティのリストです。追跡対象の状態またはプロパティへの各変更は、ドキュメントの視覚コンテキストに記録されてレポートされます。

たとえば、次の設定は、Videoコンポーネントの再生状態の変更を追跡するようにAPLに指示します。

{
  "type": "Video",
  "trackChanges": [ "playingState" ]
}

バインドされたプロパティの変更も追跡できます。次の例では、ボタンが押された回数を追跡します。

{
  "type": "TouchWrapper",
  "id": "MyCounterButton",
  "bind": {
    "name": "Counter",
    "value": 0
  },
  "trackChanges": [ "Counter" ],
  "items": {
    "type": "Text",
    "text": "このボタンを${Counter}回押しました"
  },
  "onPress": {
    "type": "SetValue",
    "property": "Counter",
    "value": "${Counter + 1}"
  }
}

コンポーネントによっては、動的プロパティやバインドされたプロパティのほかに、内部状態を表す特別なtrackChangesプロパティ名を持つものがあります。

• Video - 再生状態の変更を追跡する追加のtrackChangesプロパティ名があります。詳細については、VideoコンポーネントのtrackChangesプロパティを参照してください。

trackChangesプロパティは、コンポーネントのデータバインディングコンテキストで、新しい設定値が追加されたeventプロパティを使用して評価されます。これにより、追跡するプロパティを動的に選択できます。

変更がどのようにスキルにレポートされるかの詳細については、スキルリクエストのAPL視覚コンテキストを参照してください。

transform

変換配列は、コンポーネントに適用される変換値の配列です。次に例を示します：

"transform": [ { "rotate": 30 }, { "scaleX": 1.5 }, { "translateX": 10 }]

transformは、単一のプロパティとそれに関連付けられた値を持つオブジェクトです。変換は右から左に適用されます（ウェブ標準に従います）。上の例では、コンポーネントはまず右に10dp移動し、50%拡大された後、その中心の周りに30度回転されます。

変換配列の各要素は、次のいずれかになります。

同じグループのtransformプロパティは、単一のオブジェクトにまとめることができます。たとえば、以下は同等となります。

[ { "scaleX": 3.0, "scaleY": 2.0} ]
[ { "scale": 3.0, "scaleY": 2.0 } ]
[ { "scaleX": 3.0 }, { "scaleY": 2.0 } ]
[ { "scale": 2.0 }, { "scaleX": 1.5 } ]

変換は累積されます。最後の例では、X軸方向に1.5倍に拡大してから、両軸方向に2.0倍に拡大することで、最終的に{ "scaleX": 3.0, "scaleY": 2.0 }というスケーリングになります。

変換は、コンポーネントのデフォルトの境界を使用してドキュメントレイアウトが計算された後、コンポーネントに適用されます。その結果、変換後のコンポーネントとその子コンポーネント以外のコンポーネントのドキュメントフローには影響しません。

平行移動値では、絶対ディメンション（10pxや20dpなど）と相対ディメンション（30%など）の両方がサポートされます。相対ディメンションは、拡大縮小前のコンポーネントの幅と高さに基づいて計算されます。たとえば、コンポーネントを右下隅を中心に45度回転させるには、次のように入力します。

"transform": [
  { "translateX": "50%", "translateY": "50%" },
  { "rotate": 45 },
  { "translateX": "-50%", "translateY": "-50%" }
]

コンポーネントのデフォルトの境界は、transformプロパティで定義されている変換が適用される前のコンポーネントの境界です。

コンポーネントの変換された境界は、transformプロパティで定義された変換が適用された後のコンポーネントの境界です。

type

インフレートするコンポーネントを指定します。このセクションに記載したプリミティブコンポーネントのいずれか、または名前付きレイアウトを指定できます。

when

whenの式がtrueの場合、コンポーネントをインフレートします。falseの場合は、コンポーネントとすべての子コンポーネントが無視されます。

width

コンポーネントの最終的な幅を計算するために使用される値です。widthは、次の4つの方法のいずれかで設定できます。

• 絶対ディメンション - 100dp、25vh、24pxなどの値は、コンポーネントの幅を固定します。50.2のような数字だけの値は、dp値として解釈されます。したがって、50.2は"50.2dp"と同じです。絶対ディメンションの詳細については、絶対ディメンションを参照してください。
• 相対ディメンション - 25%などの値は、コンポーネントの幅を親コンポーネントの幅の割合として設定します。これを機能させるには、親コンポーネントでディメンションが定義されている必要があります。親コンポーネントのwidthがautoの場合、子コンポーネントで相対的な幅を使用することは未定義の動作となり、0に設定されます。相対ディメンションの詳細については、相対ディメンションを参照してください。
• 自動ディメンション - autoを指定すると、子の幅にパディングを加えた幅がコンポーネントに適用されます。Frameの場合、この幅には境界線の幅も含まれます。
• ディメンション未設定 - コンポーネントのwidthが指定されていない場合、幅はコンポーネントのデフォルトの幅に戻ります。デフォルトの幅については、個別のコンポーネントのドキュメントを参照してください。

widthには、水平方向のパディング、境界線、含まれているすべての子の幅の合計よりも小さい値を設定することができます。この場合、コンポーネントのコンテンツは最終的なコンポーネントの幅にクリップされます。

コンポーネントのwidthは、可能な限り相対ディメンションで指定してください。相対ディメンションでサイズを指定したコンポーネントは、異なるサイズの画面に合わせて調整できます。ドキュメントがさまざまなデバイスで適切に表示されるようにする方法の詳細については、以下を参照してください。

• レスポンシブ対応のAPLドキュメントを作成する
• サイズ変更が可能なタブレットなどのデバイスをサポートする

影に関する注意事項

テキストコンポーネントでは、テキストの形状に応じた影が生成されます。その他のすべての種類のコンポーネントでは、対象となるコンポーネントの変換された境界を囲む矩形の影が生成されます（パディングも含まれます）。コンポーネントの影は、親コンテナーに合わせて切り取られます。

コンポーネントの影は、標準的な描画の順番に従って描画されます。つまり、描画順が後のコンポーネントの影は、先に描画されたコンポーネントの上に表示されます。コンポーネントの影が重なったり、不要にクリップされたりしないように、コンポーネントの周りに十分なスペースを確保してください。

関連トピック

• APLコンポーネント
• アクション可能なコンポーネントのプロパティ
• タッチ可能なコンポーネントのプロパティ
• 複数子コンポーネントのプロパティ
• Alexaデザインガイド： Alexa Presentation Language

最終更新日: 2025 年 10 月 09 日