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
高さ ディメンション 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
opacity 数値 1.0 このコンポーネントと子の不透明度です。 1.0
paddingBottom 絶対ディメンション 0 このコンポーネントの下側に追加するスペースです。 1.0
paddingLeft 絶対ディメンション 0 このコンポーネントの左側に追加するスペースです。 1.0
paddingRight 絶対ディメンション 0 このコンポーネントの右側に追加するスペースです。 1.0
paddingTop 絶対ディメンション 0 このコンポーネントの上側に追加するスペースです。 1.0
speech 不透明 <none> オーディオ再生に関する変換済みの音声の情報です。 1.0
style スタイル "" 適用するスタイル(複数可)の名前です。 1.0
transform 変換の配列 [] 変換の配列です。 1.1
type 文字列 必須 コンポーネントの型です。 1.0
when ブール値 true 評価結果がfalseの場合、このコンポーネントはインフレートされません。 1.0
ディメンション 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プロパティとその他のプロパティとの間に行われます。このため、when式で新しいバインディングを利用することはできませんが、このコンポーネントの他のプロパティではバインディングを利用できます。次に例を示します:

{
"type": "Text",
"bind": [
{ "name": "foo", "value": "27" },
{ "name": "bar", "value": "${foo + 23}" }
],
"text": "barの値は${bar}です"
}

上記の例では、foobarがデータバインディングコンテキストの引数になります。文字列と整数を足し算すると型は暗黙的に文字列に変換されるため、最終的なテキストは「barの値は2723です」になります。

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 ◯(ただし、スペースを占有しません)

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

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

entity

Opaqueのentityデータです。Alexaデバイスは実体データをコンテキストとしてスキルに返します。

heightおよびwidth

widthheightminWidthminHeightmaxWidthmaxHeightはすべてディメンション型のプロパティです。

最小幅および最小高のデフォルト値は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"などです。

opacity

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

paddingBottom、paddingLeft、paddingRight、paddingTop

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

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の場合は、コンポーネントとすべての子コンポーネントが無視されます。