APL標準コマンド



APL標準コマンド

関連トピック: APLコマンド

共通プロパティ

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

プロパティ 必須 説明
type 文字列 コマンドの型です。
description 文字列 このコマンドのオプションのドキュメントです。
delay 整数 このコマンドが実行されるまでの遅延時間(ミリ秒単位)です。負以外の値にする必要があります。デフォルトは0です。
when ブール値 条件式です。評価結果がfalseの場合、コマンドをスキップします。デフォルトはtrueです。

type

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

delay

delayはこのコマンドが実行される前に挿入されるミリ秒単位の時間です。delayは負以外の値にする必要があります。指定されない場合、delayのデフォルトは0です。delayはwhenプロパティがfalseになると、無視されます。delayは、コマンドがイベントハンドラー内から実行された場合には、無視されます。

when

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

Idleコマンド

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

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

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

Idleコマンドの型は「Idle」です。

Sequentialコマンド

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

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

プロパティ 必須 説明
commands コマンド配列 連続して実行する順番に並んだコマンドのリストです。
repeatCount 整数 デフォルトは0です。

commands

実行するコマンド配列です。コマンドは順番に実行され、各コマンドが終了しない限り次のコマンドは開始されません。Sequentialコマンドの遅延とシーケンスの最初のコマンドの遅延は、それぞれ加算されることに注意してください。

repeatCount

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

Parallelコマンド

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

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

プロパティ 必須 説明
commands コマンド配列 並行して実行する順序不同のコマンドのリストです。

commands

並行して実行する順序不同のコマンド配列です。すべてのコマンドの実行が終了すると、Parallelコマンドは終了します。Parallelコマンドの遅延と、各コマンドの遅延はそれぞれ加算されることに注意してください。

SendEventコマンド

SendEventコマンドを使用して、イベントを生成してAlexaに送信します。以下にSendEventコマンドの例を示します。

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

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

プロパティ 必須 説明
arguments 引数の配列 Alexaに渡す引数データの配列です。
components 文字列の配列 値データをAlexaから抽出したりAlexaに提供したりするコンポーネントの配列です。

arguments

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

components

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

SpeakItemコマンド

SpeakItemコマンドは画面の1つの項目のコンテンツを読み込みます。見えない場合、項目はスクロールされて表示されます。項目には音声プロパティを含める必要があります。

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

プロパティ 必須 説明
align first | last | \center | visible スクロール後の項目の配置です。デフォルトは「visible」です。
componentId 文字列 読み込むコンポーネントのIDです。
highlightMode line | block Karaokeの適用方法です。行ごとまたはブロック全体に適用します。デフォルトは「block」です。

たとえば次のように、1つのTextコンポーネントのコンテンツを読み込み、画面の中央に配置します。

  {
    "type": "SpeakItem",
    "componentId": "myJokeSetup",
    "highlightMode": "line",
    "align": "center"
  }

コンポーネントのkaraoke状態は、発話中にtrueに設定され、発話終了後にfalseに再設定されます。highlightModeはTextコンポーネントにのみ適用されます。Textコンポーネントが「line」のhighlightModeで読み込まれるとき、テキストの各行は発話中にkaraoke状態に設定され、発話終了後にfalseに再設定されます。

次の制限に注意してください。

  • SpeakItemコマンドは「block」モードで発話中はコンテンツをスクロールしません。たとえば、コンポーネントがコンポーネントのスクロールContainerより大きい場合、スクロールした後でも見えないContainerからはみ出した部分は、隠れたままになります。

  • 円形画面ではコンポーネントを中央揃えにする必要があります。そうしない場合、表示されないコンテンツの部分が多くなってしまいます。

  • SpeakItemは、発話中はテキストの個々の単語や行をハイライトしません。

  • 項目をスクロールして表示するのに使用するアルゴリズムは、1つのスクロールするコンポーネントのみを想定しています。入れ子構造のコンポーネントには対応していません。

  • スクロールスピードは定義されていませんので、デバイスによって異なります。

  • speechプロパティのないコンポーネントもスクロールして表示します。

SpeakItemコマンドが早く終了すると、視覚的な変更はすべて消去され、音声がすぐに停止されます。

align

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

アライメント 説明
first 項目の左上がスクロールContainerの左上に配置されます。
center 項目の中央がContainerの中央に配置されます。
last 項目の右下がスクロールContainerの右下に配置されます。
visible 項目全体を表示するのに必要な分だけ移動します。

componentId

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

highlightMode

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

Scrollコマンド

Scrollコマンドは、ScrollViewまたはSequenceをページ数だけ前または後にスクロールします。Scrollコマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

プロパティ 必須 説明
componentId 文字列 読み込むコンポーネントのIDです。
distance 数値 スクロールするページ数です。デフォルトは1です。

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

プロパティ 必須 説明
align first | last | \center | visible スクロール後の項目の配置です。デフォルトは「visible」です。
componentId 文字列 読み込むコンポーネントのIDです。
index 整数 表示する子の0から始まるインデックスです。

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

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

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

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

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

SetPageコマンド

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

プロパティ 必須 説明
componentId 文字列 読み込むコンポーネントのIDです。
position 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とは違います)。たとえば現在のページが3ページで、SetPageをposition=「relative」、value=-2で実行した場合、2ページは表示しないで3ページから1ページに移動します。

SetPageコマンドはあらゆるページを表示するように設定できます。Pagerコンポーネントで許可された移動方向は考慮されません。 ただし、ラップ動作はページ切り替えの計算に影響します。valueセクションを参照してください。

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の相対値は、値が範囲外の場合は無視されます。

AutoPageコマンド

AutoPageコマンドは、Pagerコンポーネントの連続するページを自動的に進めて表示させます。AutoPageコマンドは、リクエストされた時間最終ページを表示した後に終了します。AutoPageコマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

プロパティ 必須 説明
componentId 文字列 読み込むコンポーネントのIDです。
count 整数 表示するページ数です。デフォルトは全ページです。
duration 整数 ページ間で待機する時間です(ミリ秒単位)。デフォルトは0です。

たとえば、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

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