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



コンポーネントは、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

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

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

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

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

"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の値を指定しない場合は、コンポーネントの元のサイズになります。

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の値はディメンション型であり、コンポーネントの周りに追加するスペースを指定します。APLでは、パディングと境界線を含めて要素の全幅と全高を計算します。それぞれのデフォルトは0です。パディングプロパティには、次の4つがあります。

• paddingBottom
• paddingLeft
• paddingRight
• paddingTop

shadowColor

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

shadowHorizontalOffset

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

shadowRadius

影のぼかしの半径です。

shadowVerticalOffset

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

speech

ssmlToSpeechまたはtextToSpeechトランスフォーマーで提供される不透明度。

その後で、データバインディング式を使用して、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の場合は、コンポーネントとすべての子コンポーネントが無視されます。

影に関する注意事項

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

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