APL標準コマンド(1.2)
- 共通プロパティ
- AnimateItemコマンド
- AutoPageコマンド
- Idleコマンド
- OpenURLコマンド
- Parallelコマンド
- Scrollコマンド
- ScrollToComponentコマンド
- ScrollToIndexコマンド
- SendEventコマンド
- Sequentialコマンド
- SetFocusコマンド
- ClearFocusコマンド
- SetPageコマンド
- SetStateコマンド
- SetValueコマンド
- SpeakItemコマンド
- SpeakListコマンド
- 関連トピック
関連トピック: APLコマンドの概要とAPLメディアコマンドも参照してください。
共通プロパティ
1つのコマンドはJSONオブジェクトとしてエンコードされます。すべてのコマンドには、以下のプロパティを含めることができます。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
|
文字列 | 必須 | コマンドの型です。 |
|
文字列 | "" | このコマンドのオプションのドキュメントです。 |
|
整数 | 0 | このコマンドが実行されるまでの遅延時間(ミリ秒単位)です。負以外の値にする必要があります。デフォルトは0です。 |
|
ブール値 |
|
条件式です。評価結果がfalse の場合、コマンドをスキップします。デフォルトはtrue です。 |
type
特定のコマンドを実行するように指定します。定義済みのプリミティブコマンドタイプやユーザー定義コマンドを使用することもできます。
delay
delay
の値は、このコマンドが実行される前に挿入されるミリ秒単位の時間です。delay
の値は正の整数で、指定されてない場合のデフォルト値は0です。when
プロパティがfalse
に解決された場合またはコマンドがイベントハンドラー内部で実行された場合、delay
の値は無視されます。
screenLock
trueの場合、このコマンドが実行されている間、操作タイマーは無効になります。screenLock=true
のコマンドの実行が終了すると、操作タイマーはゼロにリセットされます。
screenLockは、定義されたdelay
を含むコマンドの範囲全体に適用されます。たとえば、次のコマンドは画面ロックを30秒間保持します。
{
"type": "Idle",
"delay": 30000,
"screenLock": true,
}
when
when
がtrue
に設定されると、コマンドが実行されます。false
の場合、コマンドは無視されます。無視されたコマンドもscreenLock
プロパティを無視します。
AnimateItemコマンド
AnimateItem
を使用するには、APL 1.1以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。
単一コンポーネントの1つ以上のプロパティについて、固定の時間のアニメーションシークエンスを実行します。次に例を示します:
{
"type": "AnimateItem",
"easing": "ease-in-out",
"duration": 600,
"componentId": "myFlyingComponent",
"value": [
{
"property": "opacity",
"to": 1
},
{
"property": "transform",
"from": [
{
"translateX": 200
},
{
"rotate": 90
}
],
"to": [
{
"translateX": 0
},
{
"rotate": 0
}
]
}
]
}
コンポーネントでは、opacity
プロパティとtransform
プロパティのアニメーション化をサポートしています。opacityにはfrom
値を指定する必要はありませんが、transformsには指定する必要があります。
カスタムのイージングカーブを定義するには、次のように記述します。
{
"type": "AnimateItem",
"easing": "path(0.25, 0.6, 0.5, 0.8, 0.75, 0.9)",
"duration": 1000,
"value": {
"property": "opacity",
"to": 1
}
}
AnimateItem
には、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
componentId |
文字列 | SELF | コンポーネントのIDです。 |
duration |
整数 | 必須 | アニメーションの時間(ミリ秒)です。 |
easing |
linear、ease-inなど | linear | イージングカーブを指定します。 |
repeatCount |
整数 | 0 | リピート再生する回数です。 |
repeatMode |
restart、reverse | restart | アニメーションをリピート再生する方法です。 |
value |
アニメーション化するプロパティの配列 | 必須 | アニメーション化するプロパティの配列です。 |
高速モードでは、AnimateItem
コマンドはアニメーションが終了した状態にジャンプします。AnimateItem
コマンドの終了は、アニメーションが終了した状態にジャンプします。終了状態の計算方法については、repeatModeを参照してください。
componentId
コンポーネントのIDです。省略すると、AnimateItem
コマンドを発行するコンポーネントが使われます。
duration
アニメーション1回の経過時間(ミリ秒単位)です。repeatCount
プロパティが0より大きい値に設定されている場合、アニメーションの合計の時間は、その時間とリピート再生回数に1を足した値の積になります。たとえば、次のアニメーションの時間は合計10秒になります。
{
"type": "AnimateItem",
"duration": 1000,
"repeatCount": 9,
"repeatMode": "reverse",
"value": {
"property": "opacity",
"from": 0,
"to": 1
}
}
easing
イージングカーブでは、パラメーターの値が時間の経過とともにどのように変化するかを指定します。カーブは(0,0) から始まり(1,1)で終わる関数でなければなりません。イージングカーブの一般的な記述方法は、2つあります。
cubic-bezier(x1,y1,x2,y2)
: CSS規格に従って、始点(0,0)と終点(1,0)を持つ3次ベジェ曲線を定義します。パラメーター化された値の(x1, y1)と(x2, y2)は、曲線の内部制御点を定義します。通常、0から1の間となります。path(x1,y1,...,xN,yN)
: (0,0)から(1,1)までの区分線形関数です。x値は、昇順で0から1の間でなければなりません。y値は任意です。(0,0)と(1,1)の終了値は暗黙的に示されます。
以下のイージングカーブが事前定義されています。
名前 | デフォルト値 |
---|---|
linear | path() |
ease | cubic-bezier(0.25, 0.10, 0.25, 1.00) |
ease-in | cubic-bezier(0.42, 0.00, 1.00, 1.00) |
ease-out | cubic-bezier(0.00, 0.00, 0.58, 1.00) |
ease-in-out | cubic-bezier(0.42, 0.00, 0.58, 1.00) |
repeatCount
repeatCountは、コマンドが終了するまでにアニメーションをリピート再生する回数を定義します。デフォルトでは、repeatCountは0に設定されています。この場合、アニメーションは1回再生されて停止します。
repeatMode
repeateMode
は、アニメーションを毎回最初から最後まで再生するか、一回おきにアニメーションを先頭まで逆再生するかを定義します。次のリピートモードが定義されています。
名前 | 説明 |
---|---|
restart | アニメーションは、リピート再生されるたびに、元の値から始まります。 |
reverse | アニメーションは、毎回逆方向に再生されます。 |
アニメーションの終了状態は、repeatCount
とrepeatMode
の関数です。repeatMode
がreverseに設定され、repeatCount
が奇数の場合、アニメーションが終了した状態は開始状態と同じになります。上記以外の場合では、終了した状態はtoの値に割り当てられた「自然」な終了状態になります。
途中で終了したアニメーションは、常に終了した状態まで「ジャンプ」します。
value
アニメーション化するプロパティの配列です。配列の各要素は、次のような形式になります。
プロパティ | 型 | 必須 | 説明 |
---|---|---|---|
from |
数値 | ✕ | プロパティの開始値です。 |
property |
文字列 | ◯ | アニメーション化するプロパティの名前です。 |
to |
数値 | ◯ | プロパティの終了値です。 |
プロパティのアニメーションは、to/fromプロパティ、またはinputRange/outputRangeプロパティによって定義されます。「from」値を指定しない場合、プロパティの現在の値が使用されます。
transform
プロパティに関して、考慮しなければならない特殊なケースがあります。1つは、transform
プロパティはfromプロパティを暗黙的には定義しないということです。fromプロパティとtoプロパティの両方を設定する必要があります。
もう1つは、変換の間をスムーズに補間するには、fromリストとtoリストに、同じ順序で同じ一連の変換操作を指定する必要があるということです。次に例を示します:
"from": [ { "translateX": 30 }, { "rotate": 90 }],
"to": [ { "translateY": 30 }, { "rotate": 45 }]
上記は、各配列に移動とそれに続く回転が含まれているため、有効なfrom/to変換です。次の例に示すコードは動作しません。
"from": [ { "translateX": 30 }, { "scale": 1 }, { "rotate": 90 }],
"to": [ { "scale": 2 }, { "rotate": 45 }]
上記の例では、配列が一致していません。配列の長さが異なり、最初の要素も異なります。to配列の先頭に「ない」{ "translateX": 0 }
変換が、システムによって自動的に入力されると思われるかもしれませんが、APLランタイムの性能はそれほど高くなく、自動的に違いを見つけて修正することはできません。
AutoPageコマンド
AutoPage
コマンドは、Pagerコンポーネントの連続するページを自動的に進めて表示させます。AutoPage
コマンドは、リクエストされた時間内で最終ページを表示した後に終了します。
AutoPage
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
componentId | 文字列 | SELF | 移動する`Pager`のIDです。 |
count | 整数 | Pagerのすべてのページ | 表示するページ数です。 |
duration | 整数 | 0 |
次のページに進んだ後に待機する時間(単位:ミリ秒)です。 |
たとえば、 mySportsrPager
というPager
に自動的に移動するには、以下のように記述します。
{
"type": "AutoPage",
"componentId": "mySportsPager",
"duration": 1000,
"delay": 500
}
上記の例では、最初に500ミリ秒間一時停止( delay
プロパティ)します。その後、次のページに移動して1000ミリ秒間一時停止(duration
プロパティ)し、最後の一時停止が終了するまで、引き続きページ移動して一時停止します。たとえば、 mySportsPager
に3つのページがあり、最初にページ1が表示されている場合、 AutoPage
は次の処理を実行します。
- 起動を待機している間、ページ1を500ミリ秒間表示します。
- ページ2に移動し、1000ミリ秒間一時停止します。
- ページ3に移動し、1000ミリ秒間一時停止します。
この時点でコマンドは完了し、別のコマンドまたはイベントが変更されるまで、 Pager
はページ3を表示し続けます。
count
が正の数でない場合、AutoPage
コマンドを実行しても何も起きません。
終了すると、AutoPage
コマンドは以下のように動作します。
- AutoPageコマンドのシークエンスが50%以上完了している場合、ターゲットページを表示します。
- 50%未満の場合は、前のページに戻ります。
onPageChange
コマンドは、ページが変更された場合に新しいページで1回実行されます。
AutoPage
コマンドは、高速モードでは無視されます。
componentId
PagerコンポーネントのIDです。省略すると、AutoPage
コマンドを発行するコンポーネントが使われます。
count
表示するページ数です。指定しない場合、このデフォルトは残りのページ数となります。ラッピングには対応していません。値は最小値が0、最大値がpager.children.length - pager.currentIndex - 1の範囲に収まるように調整されます。
duration
次のページに進んだ後に待機する時間です。ページ間のアニメーション遷移は時間に含まれないため、コマンドの実行時間が全体的に長くなります。
時間は次のページに進んだ後に適用されるため、Pagerの最初のページには適用されません。ページングの開始を遅らせるには、標準コマンドの delay
プロパティを使用します。
Idleコマンド
Idle
コマンドを実行しても何も起きません。プレースホルダーとして使用するか、長い一連のコマンドに計算された遅延を挿入するために使用します。たとえば、次のコマンドを考えてみましょう。
{
"type": "Parallel",
"commands": [
{
"type": "Idle",
"delay": 3000
},
{
"type": "SpeakItem",
"componentId": "item7"
}
]
}
このコマンドシークエンスは「item7」を読み上げます。このIdle
コマンドの使用により、発話が早く終わる場合でも、コマンド全体が少なくとも3000ミリ秒続くことが保証されます。
Idle
コマンドのtype
はIdle
です。
idleコマンドは、高速モードでは無視されます。
OpenURLコマンド
OpenURL
を使用するには、APL 1.1以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。
URLを開きます。OpenURL
コマンドが成功すると、Webブラウザで指定されたURLやデバイスのその他のアプリが開きます。現在のデバイスで動作する適切なURLを指定する必要があります。OpenURL
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
source | 文字列 | 必須 | 開くURLです。 |
onFail | コマンドの配列 | [ ] | URLを開けなかった場合に実行するコマンドです。 |
たとえば、デバイスのブラウザでAmazonホームページを開くには、次のように記述します。
{
"type": "OpenURL",
"source": "https://www.amazon.co.jp",
"onFail": {
"type": "SetValue",
"componentId": "errorText",
"property": "text",
"value": "Amazon.co.jp (${event.source.value})を開けません"
}
}
すべてのデバイスでURLを開けるとは限りません。デバイスがURLを開くことをサポートしていない場合、コマンドは無視され、onFail
コマンドは実行されません。データバインディングコンテキストのallowOpenURL
の値を調べて、OpenURL
がデバイスでサポートされているかどうかを確認してください。
OpenURL
コマンドは、高速モードでは無視されます。
source
sourceプロパティは、ローカルデバイスでアプリを起動するのに適したURL/URIを表します。ローカルのWebブラウザでWebページを開くために、httpスキーマまたはhttpsスキーマを指定して使用することもできます。
onFail
onFailプロパティには、URLを開けない場合に実行する1つ以上のコマンドを格納します。onFailコマンドが制限時間内に実行される保証や、エンドユーザーに対してコマンドが成功しているように見えるという保証はありません。たとえば、空白のWebページやエラーのWebページが表示される可能性があります。ただし、APLランタイムは、3秒以内に失敗を報告するようにしなければなりません。onFailコマンドに対して生成されたイベントは、次のような形式になります。
"event": {
"source": {
"source": "OpenURL",
"handler": "Fail",
"value": NUMBER // プラットフォーム定義の数値エラー
}
}
onFailコマンドに渡されるevent.source.valueフィールドは、プラットフォーム定義の数値エラーコードに設定されます。上記の例にかかわらず、このエラーコードをユーザーに表示すべきではありませんが、SendEventコマンドを通じて、クラウドのスキルに不具合報告を送信するために使用できます。
Parallelコマンド
一連のコマンドを並列に実行します。Parallel
コマンドは、すべての子コマンドを同時に実行開始します。Parallel
コマンドは、すべての子コマンドが終了したときに実行完了と見なされます。Parallel
コマンドが早く終了すると、その時点で実行中のコマンドはすべて終了します。
Parallel
コマンドのtypeは、Parallel
です。Parallel
コマンドには、共通のコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
commands | コマンド配列 | 必須 | 並行して実行する順序不同のコマンドのリストです。 |
高速モードでは、parallelコマンドはすべてのサブコマンドを並列に実行しますが、遅延が発生することはありません(実質的な時間はゼロです)。
commands
並行して実行する順序不同のコマンド配列です。すべてのコマンドの実行が終了すると、 Parallel
コマンドは終了します。Parallel
コマンドに設定されるdelay
の値は、配列の各コマンドに設定されるdelay
の値に追加されます。次の例では、最初のSendEvent
コマンドが1500ミリ秒に実行され、2番目のSendEvent
コマンドが750ミリ秒に実行されます。つまり、2番目のSendEvent
コマンドは最初のコマンドよりも先に実行されます。
{
"type": "Parallel",
"delay": 500,
"commands": [
{
"type": "SendEvent",
"delay": 1000
},
{
"type": "SendEvent",
"delay": 250
}
]
}
Scrollコマンド
Scroll
コマンドは、ScrollViewまたはSequenceを一定のページ数だけ前または後にスクロールします。Scroll
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
componentId | 文字列 | SELF | 読み込むコンポーネントのIDです。 |
distance | 数値 | 1 | スクロールするページ数です。デフォルトは1です。 |
distanceにはスクロールするページ数を設定します。たとえば、次のようにリストを1ページだけ前にスクロールします。
{
"type": "Scroll",
"componentId": "myScrollingList",
"distance": 1
}
スクロールは次の場合に停止します。
- 目的地に到達したとき。
- スクロール可能なコンテンツの最後に到達したとき。
- ユーザーが画面をタッチしたとき。
- Alexaから新しいコマンドを受信したとき。終了により、スクロールはすぐに停止されます。
使用可能なすべてのコンテンツをスムーズにスクロールするには、distanceに大きな数を設定します。たとえば、次のようにリストの先頭にスムーズにスクロールバックします。
{
"type": "Scroll",
"componentId": "myScrollingList",
"distance": -10000
}
Scroll
コマンドは、高速モードでは無視されます。
componentId
ScrollViewまたはSequenceのIDです。省略すると、ScrollPage
コマンドを発行するコンポーネントが使われます。
distance
スクロールする距離です(ページ単位)。1「ページ」とは、ScrollView
またはSequence
の幅または高さから、適用されたパディングを除いたものです。負の数字は後方にスクロールします。distanceに0を設定するとスクロールしません。
たとえば、高さ400dpのScrollView
の上部と下部に50dpのパディングが設定されているとします。ScrollView
の「ページ」は300dpです。distanceに0.5を指定すると、ページの50%、つまり150dpだけ前にスクロールします。
適切なサフィックスを付けて、相対ディメンションまたは絶対ディメンションとして表すこともできます。「50%」、「33dp」、「25vh」などです。distanceに相対的な数値(「50%」など)を設定する場合は、単純な数値(この場合は「0.5」)を使用するのとまったく同じです。通常、APLドキュメントは、画面のサイズに合わせて記述されます。そのため、「100dp」などの絶対ディメンションよりも、「50%」や「0.5」といった相対ディメンションのスクロール指定を使用することをお勧めします。これにより、どのデバイスでも、ユーザーが目で追いやすい距離でコンテンツをスクロールできます。
ScrollToComponentコマンド
ScrollView
またはSequence
で前方または後方にスクロールして、特定のコンポーネントが表示されることを確認します。ScrollToComponent
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
align |
first 、center 、last 、visible |
visible |
スクロール後の項目の配置です。 |
componentId |
文字列 | SELF | コンポーネントのIDです。 |
たとえば、スクロールして特定の項目が表示されるようにするには、次のように記述します。
{
"type": "ScrollToComponent",
"componentId": "recipeSteps",
"align": "center"
}
ScrollToComponent
コマンドは、 componentId
の箇所またはその上にある、最初のSequence
またはScrollView
を探し、そこにスクロールします。
ユーザーが画面をタッチすると、スクロールは終了します。終了により、スクロールはすぐに停止されます。
ScrollToComponent
コマンドは、高速モードでは無視されます。
align
スクロール後かつ発話前の画面における項目の配置です。アライメントの列挙値には次のオプションがあります。
配置 | 説明 |
---|---|
first |
項目の左上がスクロールContainerの左上に配置されます。 |
center |
項目の中央がContainerの中央に配置されます。 |
last |
項目の右下がスクロールContainerの右下に配置されます。 |
visible |
項目全体を表示するのに必要な分だけ移動します。 |
componentId
コンポーネントのIDです。省略すると、ScrollToComponent
コマンドを発行するコンポーネントが使われます。
ScrollToIndexコマンド
ScrollViewまたはSequenceで前方または後方にスクロールして、特定の子コンポーネントが表示されることを確認します。ScrollToIndex
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
align |
first 、last 、center 、visible |
visible |
スクロール後の項目の配置です。 |
componentId |
文字列 | SELF | 読み込むコンポーネントのIDです。 |
index |
整数 | 必須 | 表示する子の0から始まるインデックスです。 |
たとえば、次のようにリストに表示されるレシピの5番目のステップにスクロールするには、index
を4に設定します。
{
"type": "ScrollToIndex",
"componentId": "recipeSteps",
"index": 4,
"align": "center"
}
componentId
は、Sequence
またはScrollView
コンポーネントである必要はありません。ScrollToIndex
コマンドは、componentId
の箇所またはその上にある、最初のSequence
またはScrollView
を探し、そこにスクロールします。
ユーザーが画面をタッチすると、スクロールは終了します。終了により、スクロールはすぐに停止されます。
ScrollToIndexコマンドは、高速モードでは無視されます。
align
スクロール後かつ発話前の画面における項目の配置です。アライメントの列挙値には次のオプションがあります。
配置 | 説明 |
---|---|
first | 項目の左上がスクロールContainerの左上に配置されます。 |
center | 項目の中央がContainerの中央に配置されます。 |
last | 項目の右下がスクロールContainerの右下に配置されます。 |
visible | 項目全体を表示するのに必要な分だけ移動します。 |
componentId
親ContainerのIDです。省略すると、ScrollToIndex
コマンドを発行するコンポーネントが使われます。
index
スクロールして表示するための、親Container内の子項目の0から始まるインデックスです。負の値は親Containerの最後から数えられます。たとえば、次のようにリスト内の最後から2番目の項目を表示します。
{
"type": "ScrollToIndex",
"index": -2,
}
表示する項目を見つけるためのアルゴリズムは、概ね以下のように説明できます。
let itemIndex = index < 0 ? index + children.length : index;
if (itemIndex >= 0 && itemIndex < children.length) {
let child = children[itemIndex];
scrollIntoView(child);
}
SendEventコマンド
SendEvent
コマンドを使用して、イベントを生成してAlexaに送信します。これにより、スキルに送信されるUserEvent
を生成します。
以下にSendEvent
コマンドの例を示します。
{
"type": "TouchWrapper",
"id": "buyButton",
"onPress": {
"type": "SendEvent",
"arguments": [
"彼が買いました"
]
},
"item": {
"type": "Text",
"text": "お買い物は今すぐ"
}
}
SendEvent
には、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
arguments | 引数の配列 | [ ] | Alexaに渡す引数データの配列です。 |
components | 文字列の配列 | [ ] | 値データをAlexaから抽出したりAlexaに提供したりするコンポーネントの配列です。 |
SendEvent
コマンドは、高速モードでは無視されます。
arguments
arguments
プロパティはAlexaに渡される配列です。配列の各要素には、実行時に適用されるデータバインディングが含まれます。これによって引数に${event.source.value}
など、イベント自体についてのデータを含めることができるため、このプロパティを使って、任意のデータをAlexaに送信します。
components
components
プロパティはコンポーネントIDの配列です。各コンポーネントのvalue
がイベントで出力されます。これによってスキル作成者は、フォームのコンテンツがサーバーに直接送信されるようにフォームを作成できます。
UserEvent
SendEvent
メッセージは、Alexa.Presentation.APL.UserEvent
リクエストでスキルに送信されます。
{
"type": "Alexa.Presentation.APL.UserEvent",
"requestId": "amzn1.echo-api.request.1",
"timestamp": "2019-06-29T01:14:24Z",
"locale": "ja-JP",
"arguments": [
"ARGUMENT1",
"ARGUMENT2"
],
"components": {
"ID1": "VALUE1",
"ID2": "VALUE2",
},
"source": {
"type": "TouchWrapper",
"handler": "onPress",
"id": "buyButton",
"value": false
},
"token": "token-provided-with-the-document"
}
Sequentialコマンド
Sequential
コマンドは、一連のコマンドを順番に実行します。前のコマンドが終了するのを待ってから、次のコマンドを実行します。Sequential
コマンドは、すべての子コマンドが終了すると完了します。
Sequential
コマンドのtype
はSequential
です。Sequential
コマンドには、共通のコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
catch |
コマンドの配列 | [] | このシークエンスが途中で終了した場合に実行する、順番に並んだコマンドのリストです。 |
commands |
コマンドの配列 | 必須 | 連続して実行する順番に並んだコマンドのリストです。 |
repeatCount |
整数 | 0 | これらのコマンドを追加で実行する回数です。 |
finally |
コマンドの配列 | [] | 通常のコマンドとcatchコマンドの後に実行する、順番に並んだコマンドのリストです。 |
- 通常モードでは、
commands
は順番に実行され、その後にfinally
コマンドが続きます。repeatCount
は通常のコマンドにのみ適用されます。 - 高速モードでは、
commands
は繰り返さずに順番に実行され、その後にfinally
コマンドが続きます。 - commandsのいずれかが早期に終了した場合(通常モード)、
catch
コマンドとfinally
コマンドは高速モードで実行されます。 - 通常モードでの実行中に
finally
コマンドのいずれかが終了した場合、残りのfinally
コマンドは高速モードで実行されます。
catch
catch
を使用するには、APL 1.1以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。
他のコマンドが実行されたことでsequentialコマンドが終了した場合、catchコマンドが実行されます。catchコマンドは「高速」モードで実行されます。すべてのdurationは無視され、各コマンドはdurationで指定した時間の最終値までジャンプします。catchコマンドは、 finally
コマンドの前に実行されます。
catch
コマンドは1回しか実行されません。repeatCount
プロパティは、catchコマンドには適用されません。
commands
実行するコマンド配列です。コマンドの配列は順番に実行され、各コマンドが終了しない限り次のコマンドは開始されません。Sequential
コマンドのdelay
値と、シークエンスdelay
値は累積で計算されます。たとえば、次の例では最初のSendEvent
コマンドは3000ミリ秒後に実行されます。
{
"type": "Sequential",
"delay": 1000,
"repeatCount": 2,
"commands": [
{
"type": "SendEvent",
"delay": 2000
},
{
"type": "SendEvent",
"delay": 2000
}
]
}
finally
finally
を使用するには、APL 1.1以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。
finallyコマンドは、通常のsequentialコマンドが終了した後、または早期終了によりcatchコマンドが実行された後に実行されます。(a)sequentialコマンド全体が高速モードで実行された場合、または(b)sequentialコマンドが早く終了した場合を除き、finallyコマンドは通常モードで実行されます。
finallyコマンドは1回しか実行されません。repeatCountプロパティは、finallyコマンドには適用されません。
repeatCount
この一連のコマンドを繰り返す回数です。デフォルトは0です。負の値は無視されます。
SetFocusコマンド
SetFocus
を使用するには、APL 1.1以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。
フォーカスされている実行可能なコンポーネントを変更します。フォーカスを当てたり解除したりできる実行可能なコンポーネントについては、focusedを参照してください。
一度に1つのコンポーネントのみに、フォーカスを当てることができます。コンポーネントにフォーカスを設定すると、他のコンポーネントのフォーカスが自動的に解除されます。
SetFocus
コマンドでは、実行時にターゲットのコンポーネントにフォーカスを当て、そのfocused
状態をtrueに設定します。さらに、以前フォーカスを当てていたコンポーネントからフォーカスを外し、そのコンポーネントのfocused
状態をfalseに設定します。
SetFocus
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
componentId | 文字列 | SELF | フォーカスを当てるコンポーネントのIDです。 |
たとえば、特定のコンポーネントにフォーカスするには、次のように記述します。
{
"type": "SetFocus",
"componentId": "myButton"
}
SetFocus
コマンドは遅延なしに高速モードで実行されます。
componentId
フォーカスを当てるコンポーネントのIDです。このプロパティが省略された場合、SetFocus
コマンドを発行するコンポーネントが受け取り側となります。
コンポーネントにフォーカスを当てた状態でドキュメントを開くには、ドキュメントのonMount
プロパティをSetFocus
に設定します。
たとえば、ドキュメントの特定のコンポーネントにフォーカスするには、次のように記述します。
{
"onMount": {
"type": "SetFocus",
"componentId": "myButton"
}
}
ClearFocusコマンド
ClearFocus
を使用するには、APL 1.1以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。
現在フォーカスされている実行可能なコンポーネントから、フォーカスを外します。フォーカスを当てたり解除したりできる実行可能なコンポーネントについては、focusedを参照してください。
一度にフォーカスできるコンポーネントは1つだけなので、ClearFocus
は1つのコンポーネントにしか影響しません。
ClearFocus
コマンドでは、実行時にフォーカスを当てたコンポーネントからフォーカスを外し、そのコンポーネントのfocused
状態をfalse
に設定します。
ClearFocus
コマンドには、通常のコマンドプロパティのほかにプロパティはありません。
たとえば、フォーカスを当てたコンポーネントからフォーカスを解除するには、次のように記述します。
{
"type": "ClearFocus"
}
ClearFocus
コマンドは遅延なしに高速モードで実行されます。
SetPageコマンド
SetPage
コマンドは、Pager
コンポーネントで表示されるページを変更します。SetPage
コマンドは、項目全体が表示されると終了します。SetPage
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
componentId |
文字列 | SELF | 読み込むコンポーネントのIDです。 |
position |
relative、absolute | absolute |
補正値はrelative かabsolute のいずれかです。デフォルトはabsolute です。 |
value |
整数 | 必須 | 移動距離です。絶対値または相対値で指定できます。 |
PagerにNページある場合、最初のインデックスは0
で、最後のインデックスはN-1
となります。相対位置は現在のページからのオフセットです。たとえば、1ページ先に進めるには次のようにします。
{
"type": "SetPage",
"componentId": "myWeatherPager",
"position": "relative",
"value": 1
}
絶対位置の場合、現在のページにインデックスが付けられます。負の絶対位置はリスト末尾からのオフセットです。たとえば、最後のページに移動するには次のようにします。
{
"type": "SetPage",
"componentId": "myWeatherPager",
"position": "absolute",
"value": -1
}
2ページ間で切り替える場合、間のページは表示されません(Sequence
とは違います)。たとえば、現在のページが13でSetPage
が"position"="relative","value": 2
で実行された場合、現在のページは範囲外となり、12ページ目を表示することなく11ページ目に移動します。
SetPage
コマンドはあらゆるページを表示するように設定できます。Pager
コンポーネントで許可された移動方向は考慮されません。ただし、ラップ動作はページ切り替えの計算に影響します。おおよそのアルゴリズムを参照してください。
SetPage
コマンドの終了時に、SetPage
コマンドシークエンスが50%以上完了していればターゲットページにジャンプし、50%未満の場合は前のページに戻ります。onPageChange
コマンドは、ページが最終ページから変更された場合に終了時に1回実行されます。
SetPage
コマンドは、高速モードでは無視されます。
componentId
PagerコンポーネントのIDです。省略すると、SetPage
コマンドを発行するコンポーネントが使われます。
position
position
がrelative
の場合、value
は現在のページから移動する相対的なページ数を指定します。position
がabsolute
の場合、value
は表示されるページの番号を絶対値で表します。
value
value
は、移動するページ数か、絶対値で表される移動先のページ番号のいずれかです。
最終位置と方向を計算するアルゴリズムは、おおよそ次の擬似コードとなります。
if (command.position == 'absolute') { // 絶対値の移動
let index = command.value < 0 ? pager.children.length + command.value : command.value;
index = Math.max(0, Math.min(pager.children.length - 1, index)); // 範囲を固定
// 最後のインデックスと移動の方向を返します。
if (index == pager.currentIndex)
return NO_MOVE
return (index, index < pager.currentIndex ? "LEFT" : "RIGHT");
}
else { // 相対値の移動
let index = pager.currentIndex + command.value;
// 相対値の移動が範囲外になり、ラッピングに対応していない場合、コマンドは無視されます
if (pager.navigation != "wrap" && (index < 0 || index >= pager.children.length))
return NO_MOVE;
// 適切にラップします
index = ((index % pager.children.length) + pager.children.length) % pager.children.length;
if (index == pager.currentIndex)
return NO_MOVE;
return (index, command.value < 0 ? "LEFT" : "RIGHT");
}
Pagerアニメーションは返された方向に動きます。
このアルゴリズムには、以下の特性があります。
-
絶対値は有効なページの範囲内に固定されます。directionは現在のページと相対的な方向になります。
-
ラッピングしているPagerの相対値は任意にラップします。directionはコマンドで与えられた値によって決まります。ラッピングでは方向は変更されません。
-
ラッピングしていないPagerの相対値は、値が範囲外の場合は無視されます。
SetStateコマンド
このコマンドは廃止予定であるため、状態を変更する目的での使用には適していません。
disabled
状態、checked
状態、focused
状態を変更するには、それぞれ、SetValue
、SetFocus
、ClearFocus
を使用します。詳細については、コンポーネントの状態を参照してください。
各コンポーネントには、スタイルを評価してコンポーネントを表示するための状態が与えられます。SetState
コマンドで、コンポーネントの状態設定を変更します。
SetState
コマンドを使用して、checkedとdisabled
を変更できますが、推奨されていません。SetValue
を使用して、checked
プロパティとdisabled
プロパティを変更してください。これにより、状態が更新されます。
focused
状態、karaoke
状態、karaokeTarget
状態、pressed
状態を直接設定することはできません。これらの状態を変更するには、SetFocus
コマンド、ClearFocus
コマンド、SpeakItem
コマンドのいずれかを使用します。
SetState
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
componentId | 文字列 | SELF | 値を設定する必要があるコンポーネントのIDです。 |
state | 文字列 | 必須 | 設定する状態の名前です。checked 、disabled 、focused のいずれかになります。 |
value | ブール値 | 必須 | 状態に設定する値です。 |
この例では、TouchWrapperの状態がcheckedに設定されます。
{
"type": "SetState",
"componentId": "myButton",
"state": "checked",
"value": true
}
componentId
状態が変更されるコンポーネントのIDです。このプロパティが省略された場合、SetStateコマンドを発行するコンポーネントが受け取り側となります。
state
変更する状態の名前です。現在のところ、checked
、disabled
、focused
に制限されています。
value
値はコマンドの実行時に評価されます。そのため、既存のコンポーネントのプロパティを活用できます。たとえば、このコマンドでは、現在のコンポーネントのchecked状態が切り替えられます。
{
"type": "SetState"
"state": "checked",
"value": "${!event.source.value}"
}
SetValueコマンド
コンポーネントのプロパティまたはバインディングを変更します。各コンポーネントには一連の動的なプロパティが定義されており、SetValue
を使用して変更できます。各コンポーネントでは、名前付きバインディングも使用できます。SetValue
を使用して変更できる動的なプロパティについては、各コンポーネントの仕様を参照してください。
SetState
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
componentId | 文字列 | SELF | 値を設定する必要があるコンポーネントのIDです。 |
property | 文字列 | 必須 | 設定するプロパティの名前です。 |
value | 文字列 | 必須 | プロパティに設定する値です。 |
この例では、ジョークのオチが表示されるよう値が設定されています。opacity
の値が1の場合、コンポーネントは完全に表示されるからです。
{
"type": "SetValue",
"componentId": "jokePunchline",
"property": "opacity",
"value": 1
}
SetValueコマンドでは、コンポーネントのプロパティの値またはコンポーネントのバインディングが変更されます。次のルールが適用されます。
- コンポーネントに、propertyで指定された名前を持つ動的なプロパティがある場合、そのプロパティが更新され、新しい値が設定されます。
- そうではなく、コンポーネントに、その名前を持つ
component_bind_property
プロパティがある場合、そのバインドされているプロパティが更新されます。 - バインドされているプロパティの値が変わると、そのプロパティに依存しているコンポーネントの動的なプロパティはすべて更新されます。
バインドしている値の更新の例を以下に示します。
{
"type": "TouchWrapper",
"bind": [
{
"name": "MyCounter",
"value": 0,
"type": "number"
}
],
"item": {
"type": "Text",
"text": "ボタンを押した回数は ${MyCounter} 回です"
},
"onPress": {
"type": "SetValue",
"property": "MyCounter",
"value": "${value + 1}"
}
}
上記の例では、TouchWrapper
を押すたびに、表示されるテキストの数字が大きくなります。
SetValueコマンドは、遅延なしに高速モードで実行されます。
componentId
値が変更されるコンポーネントのIDです。このプロパティが省略された場合、SetValue
コマンドを発行するコンポーネントが受け取り側となります。
property
変更されるプロパティの名前です。ビルトインのプロパティまたはバインディングを指定できます。
value
value
はコマンドの実行時に評価されます。そのため、既存のコンポーネントのプロパティを活用できます。この例では、SetValue
コマンドがターゲットコンポーネントのopacityを現在の値の50%に設定します。
{
"type": "SetValue"
"property": "opacity",
"value": "${event.target.opacity * 0.5}"
}
SpeakItemコマンド
SpeakItem
コマンドは、画面の1つの項目のコンテンツを読み込みます。見えない場合、項目はスクロールされて表示されます。項目にはspeech
プロパティを含めることをお勧めしますが、必須ではありません。どのタイプのコンポーネントも、SpeakItemの受け取り側になることができます。
SpeakItem
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
align |
first 、last 、center 、visible |
visible |
スクロール後の項目の配置です。デフォルトは「visible」です。 |
componentId |
文字列 | SELF | 読み込むコンポーネントのIDです。 |
highlightMode |
line 、block |
block | karaokeの適用方法です。行ごとまたはブロック全体に適用します。デフォルトは「block」です。 |
minimumDwellTime |
整数 | 0 | 項目をハイライトする最小時間(ミリ秒単位)です。 |
たとえば、次のように1つのTextコンポーネントのコンテンツを読み込み、画面の中央に配置します。
{
"type": "SpeakItem",
"componentId": "myJokeSetup",
"highlightMode": "line",
"align": "center"
}
コンポーネントのkaraoke
状態は、発話中にtrue
に設定され、発話終了後にfalse
に再設定されます。highlightMode
はTextコンポーネントにのみ適用されます。Text
コンポーネントが"highlightMode": "line"
モードで読み込まれるとき、テキストの各行は発話中にkaraoke
状態に設定され、発話終了後にfalse
に再設定されます。
次の制限に注意してください。
-
SpeakItem
コマンドはblock
モードで発話中はコンテンツをスクロールしません。たとえば、コンポーネントがコンポーネントのスクロールContainerより大きい場合、スクロールした後でも見えないContainerからはみ出した部分は、隠れたままになります。 -
円形画面ではコンポーネントを中央揃えにする必要があります。そうしない場合、表示されないコンテンツの部分が多くなってしまいます。
-
SpeakItem
は、highlightMode
がblock
の場合、発話中はテキストの個々の単語や行をハイライトしません。 -
項目をスクロールして表示するのに使用するアルゴリズムは、スクロールするコンポーネントが1つのみであることを想定しています。入れ子構造のコンポーネントには対応していません。
-
speech
プロパティのないコンポーネントもスクロールして表示します。
SpeakItem
コマンドが早く終了すると、視覚的な変更はすべて消去され、音声がすぐに停止されます。
SpeakItemコマンドは、高速モードでは無視されます。
align
スクロール後かつ発話前の画面における項目の配置です。アライメントの列挙値には次のオプションがあります。
配置 | 説明 |
---|---|
first | 項目の左上がスクロールContainerの左上に配置されます。 |
center | 項目の中央がContainerの中央に配置されます。 |
last | 項目の右下がスクロールContainerの右下に配置されます。 |
visible | 項目全体を表示するのに必要な分だけ移動します。 |
componentId
発話コンポーネントのIDです。省略すると、SpeakItemコマンドを発行するコンポーネントが使われます。
highlightMode
Text
コンポーネントのコンテンツをスタイル設定する方法を制御します。block
に設定すると、発話中にText
コンポーネント全体のkaraoke
状態の設定がtrueになります。highlightMode
を「line」に設定すると、Textコンポーネントの各行が個別に処理されます。各行は、align
プロパティに合わせてスクロールされ、個別にスタイル設定されます。
行ごとのKaraokeモードでは、スタイル設定の変更ができるのはcolorプロパティだけです。他のプロパティは無視されます。
Text
コンポーネント以外のコンポーネントがSpeakItem
の受け取り側となる場合、highlightMode
は無視されます。
minimumDwellTime
項目をハイライトする最低限の時間(ミリ秒単位)です。
SpeakListコマンド
共通Container内にある項目のコンテンツを読み取ります。各項目がスクロール表示され、その後に発話されます。各項目にはspeech
プロパティを含めることをお勧めしますが、必須ではありません。
SpeakList
コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。
プロパティ | 型 | デフォルト | 説明 |
---|---|---|---|
align |
first 、center 、last 、visible |
visible |
項目の配置です。デフォルトはvisible です。 |
componentId |
文字列 | SELF | [Sequence][apml-sequenceまたはContainer](またはその他のホスティングコンポーネント)のIDです。 |
count |
integer | 必須 | 読み取る子の数です。 |
minimumDwellTime |
number | 0 | 項目をハイライトするミリ秒単位の最小時間です。デフォルトは0です。 |
start |
integer | 必須 | 読み取りを開始する項目のインデックスです。 |
minimumDwellTime
を使用すると、タイトルの短い項目の読み上げが早くなりすぎないようにできます。たとえば、「ヴェノム」、「フェンス」、「ウィンストン・チャーチル/ ヒトラーから世界を救った男」といった映画のタイトルが並んでいる場合、最初の2つの項目では、休止時間がわずかに必要になります。
この例では、一覧のうち3つのコンポーネントが読み上げられ、それぞれが画面の中央に表示されます。
{
"type": "SpeakList",
"componentId": "movieList",
"start": 3,
"count": 3,
"minimumDwellTime": 700,
"align": "center"
}
コンポーネントのkaraoke
状態は各コンポーネントの発話中にtrue
に設定され、発話の終了後、false
に再設定されます。
以下のSpeakList
コマンドの特性に注意してください。
SpeakList
コマンドは発話中、コンテンツをスクロールしません。たとえば、コンポーネントがコンポーネントのスクロールContainerより大きい場合、スクロールした後でも見えないContainerからはみ出した部分は、隠れたままになります。- 円形画面ではコンポーネントを
center
揃えにする必要があります。そうしない場合、表示されないコンテンツの部分が多くなってしまいます。 SpeakList
は、発話中はテキストの個々の単語や行をハイライトしません。- スクロールして項目を表示するには、コンポーネント階層を上の方向に検索し、スクロール可能な最初の上位コンポーネントを見つけます。
- 項目をスクロールして表示するのに使用するアルゴリズムは、スクロールするコンポーネントが1つのみであることを想定しています。SpeakListは、入れ子構造のスクロールコンポーネントには対応していません。
- speechプロパティのないコンポーネントもスクロールして表示します。
- speechプロパティがなく、正の
minimumDwellTime
値があるコンポーネントは、その間はkaraokeに設定されます。 - speechプロパティがなく、正の
minimumDwellTime
値もないコンポーネントは、karaokeに設定されません。
SpeakList
コマンドは、高速モードでは無視されます。
align
スクロール後かつ発話前の画面における項目の配置です。アライメントの列挙値には次のオプションがあります。
配置 | 説明 |
---|---|
first |
項目の左上がスクロールContainerの左上に配置されます。 |
center |
項目の中央がContainerの中央に配置されます。 |
last |
項目の右下がスクロールContainerの右下に配置されます。 |
visible |
項目全体を表示するのに必要な分だけ移動します。 |
componentId
親コンポーネントのIDです。省略すると、SpeakList
コマンドを発行するコンポーネントが使われます。
count
発話する項目の数です。数が1に満たない場合、このコマンドは実行されず、スクロールも発話も行われません。数がContainerの残り項目数を超える場合、開始点から発話できる最大項目数に減らされます。
minimumDwellTime
項目をハイライト(karaoke
状態をtrue
に設定)するミリ秒単位の最小時間です。デフォルトは0です。
start
スクロールして表示し、発話するための、親Container内の最初の子項目の0から始まるインデックスです。負の値は親Containerの最後から数えられます。この例では、リストの最後の3つの項目が発話されます。
{
"type": "SpeakList",
"start": -3,
"count": 3
}
次のアルゴリズムは読み取りの実行方法を概算したものです。
let first = start < 0 ? start + children.length : start;
let last = Math.min(first + count, children.length – 1);
first = Math.max(0, first);
for (let index = first ; index <= last ; index++) {
let child = children[index];
scrollIntoView(child);
if (child.speech) {
child.setState("karaoke", true);
speakChildWithMinimumDwell(child, minimumDwellTime);
child.setState("karaoke", false);
}
else if (minimumDwellTime > 0) {
child.setState("karaoke", true);
waitForTimeout(minimumDwellTime);
child.setState("karaoke", false);
}
}