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



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

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

プロパティ

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

デフォルト列は、プロパティのデフォルト値を示します。すべての必須プロパティを設定する必要があります。設定しないと、コンポーネントはインフレートされません。<none>の値は、プロパティにデフォルト値がないことを意味します。<none>の解釈はプロパティに依存します。たとえば、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には、標準アクション、カスタムアクションのいずれかを指定できます。

以下は、標準アクション（「activate」）を1つとカスタムアクション（「thumbsup」）を1つ定義する、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つ目のアクションは、1つ目のアクションが有効になっていない場合でも無視されます。

標準アクションは、標準イベントハンドラーに関連付けられた名前で予約されています。コマンド配列なしでアクションリストに標準アクションを指定した場合、アクションを呼び出すと指定されたイベントハンドラーが呼び出されます。次の表に、標準アクションを示します。

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

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

デフォルトイベントハンドラーを使用する標準アクションは、アクションがタッチ可能なコンポーネントに割り当てられているときに機能します。これらのアクションは、ほかのコンポーネントの種類には影響しません。

bind

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

bindのプロパティ

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

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の値が生データ内の要素とバインドされます。

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

checked

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

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

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

disabled

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

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

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

display

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

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

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

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

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

entity, entities

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

handleTick

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

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

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

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

heightおよびwidth

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

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

コンポーネントの高さなどのプロパティは、可能な限り相対ディメンションで指定するようにしてください。相対ディメンションでサイズを指定したコンポーネントは、異なる画面のサイズに応じて調整できます。ドキュメントがさまざまなデバイスで適切に表示されるかどうかの確認について詳しくは、以下を参照してください。

• レスポンシブ対応のAPLドキュメントを作成する
• Support Tablets and Other Devices that Can Change Size

id

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

inheritParentState

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

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プロパティを参照してください。

onCursorEnter

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

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

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

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

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

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イベントハンドラーは高速モードで実行されます。

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 – コンポーネントの上側にパディングを設定します。

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
}

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プロパティは、以下を参照してください。

• GridSequence
• Pager
• ScrollView
• Sequence
• Video

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

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

コンテンツをスピーチ音声に変換するトランスフォーマーが指定した不透明データです。以下のトランスフォーマーがサポートされています。

• ssmlToSpeech
• textToSpeech
• aplAudioToSpeech

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

style

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

transform

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

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

transformは、単一のプロパティとそれに関連付けられた値を持つオブジェクトです。変換は右から左に（Web規格に従って）適用されます。上記の例では、まずコンポーネントは右に10 dp移動され、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%" }
]

type

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

when

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

影に関する注意事項

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

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