APL基本コンポーネントのプロパティ(1.4)
コンポーネントは、viewportに表示されるプリミティブな要素です。
APLでは、コンポーネントとは、クライアントで表示されるプリミティブな視覚コンポーネントのことを指します。たとえば、Text
コンポーネントは画面にテキストを表示します。すべての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 |
handleTick |
ティックハンドラーの配列。 | [] | ✕ | ✕ | 時間が経過すると呼び出されるティックハンドラーです。 | |
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の配列 | [] | ✕ | ◯ | (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.source
と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の値が生データ内の要素とバインドされます。
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 | ✕ | ✕ | ✕ | ✕ | ◯(ただし、スペースを占有しません) |
「フォーカスの可否」列はキーボードフォーカスを許可するかどうかを示します。「タッチの可否」列はタッチイベントに応答するかどうかを示します。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度回転されます。変換配列の各要素は、次のいずれかになります。
プロパティ | グループ | 型 | デフォルト | 説明 |
---|---|---|---|---|
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
の場合は、コンポーネントとすべての子コンポーネントが無視されます。
影に関する注意事項
テキストコンポーネントでは、テキストの形状に応じた影が生成されます。その他のすべての種類のコンポーネントでは、対象となるコンポーネントの境界を囲む矩形の影が生成されます(パディングも含まれます)。コンポーネントの影は、親コンテナーに合わせて切り取られます。
コンポーネントの影は、標準的な描画の順番に従って描画されます。描画の順番が後のコンポーネントの影は、先に描画されたコンポーネントの上に表示されます。コンポーネントの影が重なったり、余分に切り取られたりすることがないように、コンポーネントの周りに十分なスペースを取っておくことをお勧めします。