APLコンポーネント



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

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

APLでは、コンポーネントとは、クライアントで表示されるプリミティブな視覚コンポーネントのことを指します。APLファイルを保存して別のAPLに読み込むことで新しいテンプレートの定義を追加することはできますが、新しく追加した下位レベルのコンポーネントを認識させてデバイス上のネイティブなユーザーインターフェースコントロールに変換するには、クライアントの更新が必要になります。

プロパティ

すべてのコンポーネントは、次のプロパティをサポートしています。列の意味について詳しくは、表の下を参照してください。

プロパティ 型 デフォルト スタイル設定 動的 説明 追加されたバージョン
accessibilityLabel 文字列 "" ✕ ✕ ユーザーがコンポーネントを選択したときに、この文字列が読み上げられます。 1.1
bind バインドの配列 [] ✕ ✕ データバインディングコンテキストに追加する式です。 1.0
description 文字列 "" ✕ ✕ このコンポーネントの任意の説明です。 1.0
checked ブール値 false ✕ ◯ trueの場合、このコンポーネントの状態はcheckedに設定されます。 1.1
disabled ブール値 false ✕ ◯ trueの場合、このコンポーネントはタッチまたはフォーカスに応答しません。 1.1
display 文字列（invisible、none、normal） normal ◯ ◯ コンポーネントが画面に表示されるかどうかを指定します。 1.1
entity （entities）エンティティの配列 [] ✕ ✕ Alexaでリファレンスの明確化に使用されるOpaqueデータです。 1.0
height ディメンション auto ✕ ✕ コンポーネントに指定する高さです。 1.0
id 文字列 "" ✕ ✕ ナビゲーションおよびイベントに使用する、コンポーネントの参照名です。 1.0
inheritParentState ブール値 false ✕ ✕ trueを指定した場合、親の状態が使用されます。 1.0
maxHeight ディメンション <none> ✕ ✕ このコンポーネントの高さの上限です。 1.0
maxWidth ディメンション <none> ✕ ✕ このコンポーネントの幅の上限です。 1.0
minHeight ディメンション 0 ✕ ✕ このコンポーネントの高さの下限です。 1.0
minWidth ディメンション 0 ✕ ✕ このコンポーネントの幅の下限です。 1.0
onMount コマンドの配列 [] ✕ ✕ コンポーネントが最初に表示されたときに実行されるコマンドです。 1.1
onCursorEnter コマンドの配列 [] ✕ ✕ カーソル（マウスポインター）がコンポーネントのアクティブな領域に入ったときに実行されるコマンドです。 1.2
onCursorExit コマンドの配列 [] ✕ ✕ カーソル（マウスポインター）がコンポーネントのアクティブな領域から出たときに実行されるコマンドです。 1.2
opacity 数値 1.0 ◯ ◯ このコンポーネントと子の不透明度です。 1.0
paddingBottom 絶対ディメンション 0 ✕ ✕ このコンポーネントの下側に追加するスペースです。 1.0
paddingLeft 絶対ディメンション 0 ✕ ✕ このコンポーネントの左側に追加するスペースです。 1.0
paddingRight 絶対ディメンション 0 ✕ ✕ このコンポーネントの右側に追加するスペースです。 1.0
paddingTop 絶対ディメンション 0 ✕ ✕ このコンポーネントの上側に追加するスペースです。 1.0
shadowColor 色 transparent ◯ ✕ 影の色です。 1.2
shadowHorizontalOffset 絶対ディメンション 0 ◯ ✕ 影の水平方向のオフセットです。 1.2
shadowRadius 絶対ディメンション 0 ◯ ✕ 影のぼかしの半径です。 1.2
shadowVerticalOffset 絶対ディメンション 0 ◯ ✕ 影の垂直方向のオフセットです。 1.2
speech 不透明 <none> ✕ ✕ オーディオ再生に関する変換済みの音声の情報です。 1.0
style スタイル "" ✕ ✕ 適用するスタイル（複数可）の名前です。 1.0
transform transformの配列 [] ✕ ◯ 変換の配列です。 1.1
type 文字列 必須 ✕ ✕ コンポーネントの型です。 1.0
when ブール値 true ✕ ✕ 評価結果がfalseの場合、このコンポーネントはインフレートされません。 1.0
width ディメンション auto ✕ ✕ このコンポーネントに指定する幅です。 1.0

デフォルト列は、プロパティのデフォルト値を示します。すべての必須プロパティを設定する必要があります。設定しないと、コンポーネントはインフレートされません。<none>の値は、プロパティにデフォルト値がないことを意味します。<none>の解釈はプロパティに依存します。たとえば、speechプロパティが設定されていないと、コンポーネントはSpeakItemコマンドを実行できません。maxHeightが設定されていないと、コンポーネントは任意の高さまで大きくなることができます。これは、maxHeightを非常に大きな数に設定することと同じです。

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

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

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

コンポーネントがイベントのターゲットである場合、以下の値がevent.targetに報告されます。

{
    "event": {
        "target": {
            "disabled": Boolean,
            "height": Number,   
            "id": ID,           
            "uid": UID,         
            "opacity": Number,  
            "width": Number     
        }
    }
}

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

accessibilityLabel

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

bind

コンポーネントのbindプロパティは、コンポーネントおよびその子のデータバインディングコンテキストを展開するためのものです。また、bindプロパティは、現在のコンテキストを展開するデータバインディングを順序付きで指定します。バインディングには順序があり、以前のバインディングの定義を、それ以降のバインディングで使用できます。

bindのプロパティ

バインディング配列の各バインディングオブジェクトには、次のプロパティを使用できます。

プロパティ 型 デフォルト 説明
name 文字列 必須 このバインディングで使用する名前です。有効な名前を設定する必要があります。
value 任意 必須 このバインディングに割り当てる値です。文字列の場合、データバインディングは文字列のコンテンツに対して行われます。
type 型 any プロパティの型です。

bindの評価

bindプロパティの評価は、whenプロパティとその他のプロパティとの間に行われます。バインディングは、配列の順序でデータバインディングコンテキストに追加されます。後続のバインディングでは先行するバインディングの結果を使用できます。次に例を示します：

{
  "type": "Text",
  "bind": [
    { "name": "FirstName", "value": "ジャスミン" },
    { "name": "LastName", "value": "スミス"},
    { "name": "Title", "value": "博士"},
    { "name": "FormalName", "value": "${LastName}${Title}" }
  ],
  "text": "${FirstName} さん、または ${FormalName} のどちらでお呼びしますか？"
}

この例では、FormalNameの内容は、それより前に定義されたTitleとLastNameの値によって決まります。最終的にこのテキストは、「ジャスミンさん、またはスミス博士のどちらでお呼びしますか？」となります。これは例として仮に作られたものであり、実際には、FirstName、LastName、Titleの値が生データ内の要素とバインドされます。

バインドされる値は、set_value_commandを使用して動的に変更できます。set_value_commandは、コンポーネントのプロパティを変更する場合にも使用されるため、コンポーネント固有のプロパティと競合することがないよう、バインドされるプロパティの名前は大文字で始めることをお勧めします。たとえば、「myCounter」ではなく、「MyCounter」や「"MY_COUNTER」のような名前にします。

checked

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

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

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

disabled

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

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

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

display

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

名前 説明
invisible コンポーネントは描画されませんが、スペースを占有します。タッチイベントには応答しません。
none コンポーネントを削除します。コンポーネントはレイアウトの一部ではなくなり、タッチに応答しません。
normal 通常どおりにコンポーネントを描画します。

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

次の表に示すように、コンテンツの表示と非表示はさまざまな方法で切り替えることができます。

表示 無効化 不透明度 表示の可否 スペース占有の有無 フォーカスの可否 タッチの可否 タッチおよびホバーのパススルー
normal false > 0 ◯ ◯ ◯ ◯ ✕
normal true > 0 ◯ ◯ ✕ ✕ ✕
normal false 0 ✕ ◯ ◯ ◯ ✕
normal true 0 ✕ ◯ ✕ ✕ ✕
invisible any any ✕ ◯ ✕ ✕ ◯
none any any ✕ ✕ ✕ ✕ ◯（ただし、スペースを占有しません）

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

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

entity

Opaque（不透明）のentityデータです。Alexaデバイスはentityデータをコンテキストとしてスキルに返します。

heightおよびwidth

width、height、minWidth、minHeight、maxWidth、maxHeightはすべてディメンション型のプロパティです。

最小幅および最小高のデフォルト値は0であり、コンポーネントは表示されない場合があります。最大幅および最大高のプロパティのデフォルト値はnoneであり、コンポーネントは自由に拡大縮小できます。widthおよびheightの値を指定しない場合は、コンポーネントの元のサイズになります。

id

コンポーネントのこのインスタンスに対して定義できる識別子です。階層表示で特定のコンポーネントを見つけられるようにするために使用します。他のidと同じ値を使用してもかまいませんが、一意の値を割り当てることをお勧めします。

inheritParentState

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

onMount

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

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

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

{
  "event": {
    "source": {
      "type": "nameOfComponent",
      "handler": "Mount",
      "id": "コンポーネントのID",
      "uid": "ランタイムで生成されたコンポーネントの固有ID",
      "value": null
    }
  }
}

イベントタイプのプロパティは、コンポーネントの名前に設定されます。たとえば、"Frame"、"Container"、"TouchWrapper"などです。

onCursorEnter

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

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

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

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

"event": {
  "source": {
    "source": NAME,    // コンポーネントの名前
    "handler": "CursorEnter",
    "id": ID,          // コンポーネントのID
    "uid": UID,          // ランタイムで生成されたコンポーネントの固有ID
    "value": Any,       // コンポーネントの標準的なsource値
  }
}

イベントのsourceプロパティにはコンポーネントの名前（「Image」、「TouchWrapper」、「Sequence」など）が設定されます。

onCursorExit

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

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

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

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

"event": {
  "source": {
    "source": NAME,    // コンポーネントの名前
    "handler": "CursorExit",
    "id": ID,          // コンポーネントのID
    "uid": UID,          // ランタイムで生成されたコンポーネントの固有ID
    "value": Any,       // コンポーネントの標準的なsource値
  }
}

イベントのsourceプロパティにはコンポーネントの名前（「Image」、「TouchWrapper」、「Sequence」など）が設定されます。

opacity

このコンポーネントと子コンポーネントの不透明度を一様に適用します。不透明度は0以上1以下の数値で指定します。この範囲を超える数値を指定した場合は、1に設定されます。実際に表示されるコンポーネントの不透明度は、この値に上位レベルの不透明度の値を掛けたものになります。たとえば、現在のコンポーネントの不透明度が0.5、親の不透明度が0.8の場合、実際に表示されるコンポーネントの不透明度は0.4になります。コンポーネントの不透明度を0に設定すると表示されなくなりますが、コンポーネント階層からは削除されません。

paddingBottom、paddingLeft、paddingRight、paddingTop

paddingの値はディメンション型であり、コンポーネントの周りに追加するスペースを指定します。APLでは、パディングと境界線を含めて要素の全幅と全高を計算します。それぞれのデフォルトは0です。

shadowColor

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

shadowHorizontalOffset

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

shadowRadius

影のぼかしの半径です。

shadowVerticalOffset

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

speech

speechには、Alexa ssmlToSpeechトランスフォーマーから取得するopaqueデータを指定します。これは、コンポーネントのコンテンツを読み上げるときに使用されるopaqueデータです。

ssmlToSpeechトランスフォーマーおよびtextToSpeechトランスフォーマーの詳細については、データソースとトランスフォーマーを参照してください。

style

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

transform

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

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

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

プロパティ グループ 型 デフォルト 説明
rotate 回転 数値 0.0 回転角度（度単位）です。正の角度で時計回りに回転します。
scale スケール 数値 1.0 X方向とY方向に均等に拡大縮小されます。
scaleX スケール 数値 1.0 X方向の倍率です（同じグループの場合は「scale」を上書きします）。
scaleY スケール 数値 1.0 Y方向の倍率です（同じグループの場合は「scale」を上書きします）。
skewX 傾斜 数値 1.0 X軸の傾斜角度（度単位）です。X軸は横線のままです。
skewY 傾斜 数値 1.0 Y軸の傾斜角度（度単位）です。Y軸は縦線のままです。
translateX 移動 ディメンション 0.0 オブジェクトを右方向に平行移動する距離です。
translateY 移動 ディメンション 0.0 オブジェクトを下方向に平行移動する距離です。

同じグループの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%" }
]

type

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

when

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

影に関する注意事項

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

コンポーネントの影は、標準的な描画の順番に従って描画されます。描画の順番が後のコンポーネントの影は、先に描画されたコンポーネントの上に表示されます。コンポーネントの影が重なったり、余分に切り取られたりすることがないように、コンポーネントの周りに十分なスペースを取っておくことをお勧めします。

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment