APL標準コマンド（1.0）



（これはAPLの最新バージョンではありません。APLの最新バージョンの資料を参照するには、その他のバージョンオプションをクリックしてください）

• 共通プロパティ
• AutoPageコマンド
• Idleコマンド
• Parallelコマンド
• Scrollコマンド
• ScrollToIndexコマンド
• SendEventコマンド
• Sequentialコマンド
• SetPageコマンド
• SetStateコマンド
• SetValueコマンド
• SpeakItemコマンド
• SpeakListコマンド

関連トピック： APLコマンドの概要とAPLメディアコマンドも参照してください。

共通プロパティ

1つのコマンドはJSONオブジェクトとしてエンコードされます。すべてのコマンドには、以下のプロパティを含めることができます。

type

特定のコマンドを実行するように指定します。定義済みのプリミティブコマンドタイプやユーザー定義コマンドを使用することもできます。

delay

delayの値は、このコマンドが実行される前に挿入されるミリ秒単位の時間です。delayの値は正の整数で、指定されてない場合のデフォルト値は0です。whenプロパティがfalseに解決された場合またはコマンドがイベントハンドラー内部で実行された場合、delayの値は無視されます。

when

whenがtrueに設定されると、コマンドが実行されます。falseの場合、コマンドは無視されます。

AutoPageコマンド

AutoPageコマンドは、Pagerコンポーネントの連続するページを自動的に進めて表示させます。AutoPageコマンドは、リクエストされた時間内で最終ページを表示した後に終了します。

AutoPageコマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

たとえば、sports pagerで自動的に次ページを表示するには次のようにします。

  {
    "type": "AutoPage",
    "componentId": "mySportsPager",
    "duration": 1000
  }

countが正の数でない場合、AutoPage コマンドを実行しても何も起きません。

終了すると、AutoPageコマンドは以下のように動作します。

• AutoPageコマンドのシークエンスが50%以上完了している場合、ターゲットページを表示します。
• 50%未満の場合は、前のページに戻ります。

onPageChangeコマンドは、ページが変更された場合に新しいページで1回実行されます。

componentId

PagerコンポーネントのIDです。省略すると、AutoPageコマンドを発行するコンポーネントが使われます。

count

表示するページ数です。指定しない場合、このデフォルトは残りのページ数となります。ラッピングには対応していません。値は最小値が0、最大値がpager.children.length - pager.currentIndex - 1の範囲に収まるように調整されます。

duration

最初のページを含め、各ページを表示する待ち時間です。アニメーションによるページ間の移動は、すべて合計時間に加算されます。

Idleコマンド

Idleコマンドを実行しても何も起きません。これはプレースホルダーになっているか、長い一連のコマンドに計算された遅延を挿入するために使用されます。たとえば、次のコマンドを考えてみましょう。

  {
    "type": "Parallel",
    "commands": [
      {
        "type": "Idle",
        "delay": 3000
      },
      {
        "type": "SpeakItem",
        "componentId": "item7"
      }
    ]
  }

このコマンドシークエンスは「item7」を読み上げます。このIdleコマンドの使用により、発話が早く終わる場合でも、コマンド全体が少なくとも3000ミリ秒続くことが保証されます。

IdleコマンドのtypeはIdleです。

Parallelコマンド

一連のコマンドを並列に実行します。Parallelコマンドは、すべての子コマンドを同時に実行開始します。Parallelコマンドは、すべての子コマンドが終了したときに実行完了と見なされます。Parallelコマンドが早く終了すると、その時点で実行中のコマンドはすべて終了します。

Parallelコマンドのtypeは、Parallelです。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コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

distanceにはスクロールするページ数を設定します。たとえば、次のようにリストを1ページだけ前にスクロールします。

  {
    "type": "Scroll",
    "componentId": "myScrollingList",
    "distance": 1
  }

スクロールは次の場合に停止します。

• 目的地に到達したとき。
• スクロール可能なコンテンツの最後に到達したとき。
• ユーザーが画面をタッチしたとき。
• Alexaから新しいコマンドを受信したとき。終了によりすぐにスクロールが停止したとき。

使用可能なすべてのコンテンツをスムーズにスクロールするには、distanceに大きな数を設定します。たとえば、次のようにリストの先頭にスムーズにスクロールバックします。

  {
    "type": "Scroll",
    "componentId": "myScrollingList",
    "distance": -10000
  }

componentId

ScrollViewまたはSequenceのIDです。省略すると、ScrollPageコマンドを発行するコンポーネントが使われます。

distance

スクロールする距離です（ページ単位）。1「ページ」とは、ScrollViewまたはSequenceコンポーネントの幅または高さです。負の数字は後方にスクロールします。distanceに0を設定するとスクロールしません。

ScrollToIndexコマンド

ScrollViewまたはSequenceで前方または後方にスクロールして、特定の子コンポーネントが表示されることを確認します。ScrollToIndexコマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

たとえば、次のようにリストに表示されるレシピの5番目のステップにスクロールするには、indexを4に設定します。

  {
    "type": "ScrollToIndex",
    "componentId": "recipeSteps",
    "index": 4,
    "align": "center"
  }

componentIdは、SequenceまたはScrollViewコンポーネントである必要はありません。ScrollToIndexコマンドは、componentIdの箇所またはその上にある、最初のSequenceまたはScrollViewを探し、そこにスクロールします。

ユーザーが画面をタッチすると、スクロールは終了します。終了によりすぐにスクロールが停止したとき。

align

スクロール後かつ発話前の画面における項目の配置です。アライメントの列挙値には次のオプションがあります。

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に送信します。以下にSendEventコマンドの例を示します。

{
  "type": "TouchWrapper",
  "id": "buyButton",
  "onPress": {
    "type": "SendEvent",
    "arguments": [
      "彼が買いました"
    ]
  },
  "item": {
    "type": "Text",
    "text": "お買い物は今すぐ"
  }
}

SendEventには、標準的なコマンドプロパティに加えて以下のプロパティを設定します。

arguments

argumentsプロパティはAlexaに渡される配列です。配列の各要素には、実行時に適用されるデータバインディングが含まれます。これによって引数に${event.source.value}など、イベント自体についてのデータを含めることができるため、スキル開発者は任意のデータをAlexaに送ることができます。

components

componentsプロパティはコンポーネントIDの配列です。各コンポーネントのvalueがイベントで出力されます。これによってスキル作成者は、フォームのコンテンツがサーバーに直接送信されるようにフォームを作成できます。

UserEvent

SendEventメッセージはスキルに送信するTemplateRuntime.UserEventメッセージにパッケージされています。TemplateRuntime.UserEventメッセージは次のような形式です。

{
  "namespace": "TemplateRuntime",
  "name": "UserEvent",
  "payload": {
    "skillID": "XYZZY",
    "directiveID": "PDQBACH",
    "arguments": [
      ARGUMENT1,
      ARGUMENT2,
      :
    ],
    "components": {
      ID1: VALUE1,
      ID2: VALUE2,
      :
    },
    "source": {
      "type": "Button",
      "handler": "Press",
      "id": "buyButton",
      "value": false
    }
  }
}

APLランタイムは引数データをより大きなペイロード構造に渡します。その際に、イベントを作成したコンポーネントの種類に関するソース情報や呼び出したハンドラー、コンポーネントのIDも合わせて渡します。

Sequentialコマンド

Sequentialコマンドは、一連のコマンドを順番に実行します。前のコマンドが終了するのを待ってから、次のコマンドを実行します。Sequentialコマンドは、すべての子コマンドが終了すると完了します。Sequentialコマンドが早期に終了すると、現在実行中のコマンドは終了し、以降のコマンドは実行されません。

SequentialコマンドのtypeはSequentialです。Sequentialコマンドには、共通のコマンドプロパティに加えて以下のプロパティがあります。

commands

実行するコマンド配列です。コマンドの配列は順番に実行され、各コマンドが終了しない限り次のコマンドは開始されません。Sequentialコマンドのdelay値と、シークエンスdelay値は累積で計算されます。たとえば、次の例では最初のSendEventコマンドは3000ミリ秒後に実行されます。

{
  "type": "Sequential",
  "delay": 1000,
  "repeatCount": 2,
  "commands": [
    {
      "type": "SendEvent",
      "delay": 2000
    },
    {
      "type": "SendEvent",
      "delay": 2000
    }
  ]
}

repeatCount

この一連のコマンドを繰り返す回数です。デフォルトは0です。負の値は無視されます。

SetPageコマンド

SetPageコマンドは、Pagerコンポーネントで表示されるページを変更します。SetPageコマンドは、項目全体が表示されると終了します。SetPageコマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

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回実行されます。

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コマンド

各コンポーネントには、スタイルを評価してコンポーネントを表示するための状態が与えられます。SetStateコマンドで、コンポーネントの状態設定を変更します。

SetStateコマンドを利用し、checked、disabled、focusedという各種状態を変更できます。focused状態は設定できますが、消去できません。

karaoke状態とpressed状態は直接設定できませんが、SpeakItemコマンドを使用して変更できます。

SetStateコマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

この例では、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コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

この例では、ジョークのオチが表示されるよう値が設定されています。opacityの値が1の場合、コンポーネントは完全に表示されるからです。

{
  "type": "SetValue"
  "componentId": "jokePunchline",
  "property": "opacity",
  "value": 1
}

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コマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

たとえば、次のように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コマンドが早く終了すると、視覚的な変更はすべて消去され、音声がすぐに停止されます。

align

スクロール後かつ発話前の画面における項目の配置です。アライメントの列挙値には次のオプションがあります。

componentId

発話コンポーネントのIDです。省略すると、SpeakItemコマンドを発行するコンポーネントが使われます。

highlightMode

発話中にTextコンポーネントのコンテンツをスタイル設定する方法を制御します。「block」に設定すると、発話中にTextコンポーネント全体のkaraoke状態の設定がtrueになります。highlightModeを「line」に設定すると、Textコンポーネントの各行が個別に処理されます。各行は、alignプロパティに合わせてスクロールされ、個別にスタイル設定されます。行ごとのKaraokeモードでは、スタイル設定の変更ができるのはcolorプロパティだけです。他のプロパティは無視されます。

SpeakListコマンド

共通Container内にある項目のコンテンツを読み取ります。各項目がスクロール表示され、その後に発話されます。各項目にはspeechプロパティを含める必要があります。

SpeakListコマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

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に設定されません。

align

スクロール後かつ発話前の画面における項目の配置です。アライメントの列挙値には次のオプションがあります。

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);
  }
}