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



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

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

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

プロパティ

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

プロパティ デフォルト スタイル設定 動的 説明 追加されたバージョン
accessibilityLabel 文字列 "" ユーザーがコンポーネントを選択したときに、この文字列が読み上げられます。 1.1
action, actions アクションの配列 [] 複雑なタッチ操作に相当するプログラムです。  
bind バインドの配列 [] データバインディングコンテキストに追加する式です。 1.0
description 文字列 "" このコンポーネントの任意の説明です。 1.0
checked ブール値 false trueの場合、このコンポーネントの状態はcheckedに設定されます。 1.1
disabled ブール値 false trueの場合、このコンポーネントはタッチまたはフォーカスに応答しません。 1.1
display 文字列(invisiblenonenormal normal コンポーネントが画面に表示されるかどうかを指定します。 1.1
entity, entities エンティティの配列 [] Alexaでリファレンスの明確化に使用されるOpaqueデータです。 1.0
handleTick Tickハンドラーの配列 [] 時間が経過すると呼び出されるティックハンドラーです。  
height 正のディメンション auto コンポーネントに指定する高さです。 1.0
id 文字列 "" ナビゲーションおよびイベントに使用する、コンポーネントの参照名です。 1.0
inheritParentState ブール値 false trueを指定した場合、親の状態が使用されます。 1.0
layoutDirection 文字列LTRRTLinheritに設定。 "inherit" コンポーネントがレンダリングされる方向。このプロパティは、左から右、または右から左に記述する言語に設定します。 1.7
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
padding 負でない絶対ディメンションの配列 [] コンポーネントの両側に追加するスペースです。 1.6
paddingBottom 負でない絶対ディメンション 0 このコンポーネントの下側に追加するスペースです。 1.0
paddingEnd 負でない絶対ディメンション <none> このコンポーネントの終点に追加するスペースです。終点は、コンポーネントのlayoutDirectionに応じて、コンポーネントの左側または右側になります。 1.7
paddingLeft 負でない絶対ディメンション 0 このコンポーネントの左側に追加するスペースです。 1.0
paddingRight 負でない絶対ディメンション 0 このコンポーネントの右側に追加するスペースです。 1.0
paddingStart 負でない絶対ディメンション <none> このコンポーネントの始点エッジに追加するスペースです。始点は、コンポーネントのlayoutDirectionに応じて、コンポーネントの左側または右側になります。 1.7
paddingTop 負でない絶対ディメンション 0 このコンポーネントの上側に追加するスペースです。 1.0
preserve 文字列の配列 [] Reinflateコマンドでドキュメントを再インフレートする際に保存するプロパティです。 1.6
role 文字列 "" コンポーネントの役割または目的です。  
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の配列 [] (transformations)変換の配列です。 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.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.sourceevent.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プロパティは、次の表に挙げたプロパティを持つオブジェクトの配列です。

名前 デフォルト 説明
command, commands コマンド配列 [] このアクションがトリガーされたら実行するコマンドの配列です。
enabled ブール値 true trueの場合、ユーザーはこのアクションを呼び出すことができます。
label 文字列 必須 ユーザーに提示する、このアクションのローカライズした説明です。
name 文字列 必須 実行するアクションの名前です。

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

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

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

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

名前 デフォルトイベントハンドラー 説明
activate onPress 1回押して放す操作に相当します。
doubletap onDoublePress コンポーネントのダブルタップに相当します。
longpress onLongPress コンポーネントの長押しに相当します。
swipeaway onSwipeDone コンポーネントのスワイプジェスチャーに相当します。

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

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

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

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

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の内容が、それより前に定義されたTitleLastNameの値によって決まります。最終的にこのテキストは、「ジャスミンさん、またはスミス博士のどちらでお呼びしますか?」となります。これは例として仮に作られたものであり、実際には、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プロパティは、画面に表示されるかどうかや、レイアウトの計算に与える影響を決定します。次のいずれかの値に設定します。

名前 説明
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, entities

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

handleTick

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

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

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

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

heightおよびwidth

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

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

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

id

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

inheritParentState

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

layoutDirection

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

  • inherit – (デフォルト)。コンポーネントは、親からlayoutDirectionを継承します。
  • LTR – コンポーネントは左から右方向を使用します。
  • RTL – コンポーネントは右から左方向を使用します。

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

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

layoutDirectionを設定するための推奨方法は、データバインディングを使用し、データソースの方向を設定することです。ドキュメント内の最上位のContainerコンポーネントにlayoutDirectionを設定し、子コンポーネントがその設定を継承するようにします。必要に応じて、Containerbindプロパティを使用して、Containerの子プロパティで参照する変数を作成します。

次の例では、データバインドとbindプロパティを使用して、最上位のContainerコンポーネントのlayoutDirectionをデータソースの値に設定します。Containerの2番目の子コンポーネントは、3項演算子を使用して、layoutDirectionの値に基づいて、resoucesで定義されている適切な左向きまたは右向きの矢印を選択します。

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

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

onMount

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

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

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

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

event.source.typeプロパティには、コンポーネントの名前(TouchWrapperScrollViewなど)が設定されます。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プロパティには、コンポーネントの名前(TouchWrapperScrollViewなど)が設定されます。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プロパティには、コンポーネントの名前(TouchWrapperScrollViewなど)が設定されます。event.sourceの詳細についてはイベントソースを参照してください。

onCursorExitイベントハンドラーは高速モードで実行されます。

opacity

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

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

padding

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

コンポーネントのレイアウトモデル。widthとheightのプロパティによりコンポーネントの境界を指定します。paddingプロパティは、境界内にコンポーネントの表示されるコンテンツを挿入します。
コンポーネントのレイアウトモデル。widthとheightのプロパティによりコンポーネントの境界を指定します。paddingプロパティは、境界内にコンポーネントの表示されるコンテンツを挿入します。

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

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

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

配列のマッピング 説明

[X][X,X,X,X]に拡張

X値を4辺すべてに割り当てます。

[X,Y][X,Y,X,Y]に拡張

X値を左と右に割り当てます。Y値を上と下に割り当てます。

[X,Y,Z][X,Y,Z,Y]に拡張

X値を左に割り当てます。Y値を上と下に割り当てます。Z値を右に割り当てます。

ほかの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プロパティに依存します。

プロパティ 左から右("LTR") 右から左("RTL")

paddingStart

paddingLeftを上書き

paddingRightを上書き

paddingEnd

paddingRightを上書き

paddingLeftを上書き

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

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

preserve

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

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

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

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

role

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

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

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

shadowColor

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

shadowHorizontalOffset

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

shadowRadius

影のぼかしの半径です。

shadowVerticalOffset

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

speech

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

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

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%" }
]

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

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

type

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

when

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

影に関する注意事項

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

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