APL標準コマンド



APL標準コマンド

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

共通プロパティ

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

プロパティ デフォルト 説明

type

文字列 必須 コマンドの型です。

description

文字列 "" このコマンドのオプションのドキュメントです。

delay

整数 0 このコマンドが実行されるまでの遅延時間(ミリ秒単位)です。負以外の値にする必要があります。デフォルトは0です。

when

ブール値

true

条件式です。評価結果がfalseの場合、コマンドをスキップします。デフォルトはtrueです。

type

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

delay

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

screenLock

trueの場合、このコマンドが実行されている間、操作タイマーは無効になります。screenLock=trueのコマンドの実行が終了すると、操作タイマーはゼロにリセットされます。

screenLockは、定義されたdelayを含むコマンドの範囲全体に適用されます。たとえば、次のコマンドは画面ロックを30秒間保持します。

{
  "type": "Idle",
  "delay": 30000,
  "screenLock": true,
}

when

whentrueに設定されると、コマンドが実行されます。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つあります。

  1. cubic-bezier(x1,y1,x2,y2): CSS規格に従って、始点(0,0)と終点(1,0)を持つ3次ベジェ曲線を定義します。パラメーター化された値の(x1, y1)と(x2, y2)は、曲線の内部制御点を定義します。通常、0から1の間となります。
  2. 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 アニメーションは、毎回逆方向に再生されます。

アニメーションの終了状態は、repeatCountrepeatModeの関数です。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コマンドでは次の問題が発生することがわかっています。既知の問題の修正については、APLの既知の問題とバグを確認してください。

  • SpeakItemまたはSpeakListコマンドと一緒にAutoPageコマンドを使うことはAlexaデバイスでは可能ですが、開発者コンソールのAlexaシミュレーターではうまくいかない場合があります。

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コマンドのtypeIdleです。

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 firstcenterlastvisible 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 firstlastcentervisible 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": "en-US",
  "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コマンドのtypeSequentialです。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 補正値はrelativeabsoluteのいずれかです。デフォルトは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

positionrelativeの場合、valueは現在のページから移動する相対的なページ数を指定します。positionabsoluteの場合、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状態を変更するには、それぞれ、SetValueSetFocusClearFocusを使用します。詳細については、コンポーネントの状態を参照してください。

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

SetStateコマンドを使用して、checkedとdisabledを変更できますが、推奨されていません。SetValueを使用して、checkedプロパティとdisabledプロパティを変更してください。これにより、状態が更新されます。

focused状態、karaoke状態、karaokeTarget状態、pressed状態を直接設定することはできません。これらの状態を変更するには、SetFocusコマンド、ClearFocusコマンド、SpeakItemコマンドのいずれかを使用します。

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

プロパティ デフォルト 説明
componentId 文字列 SELF 値を設定する必要があるコンポーネントのIDです。
state 文字列 必須 設定する状態の名前です。checkeddisabledfocusedのいずれかになります。
value ブール値 必須 状態に設定する値です。

この例では、TouchWrapperの状態がcheckedに設定されます。

{
  "type": "SetState",
  "componentId": "myButton",
  "state": "checked",
  "value": true
}

componentId

状態が変更されるコンポーネントのIDです。このプロパティが省略された場合、SetStateコマンドを発行するコンポーネントが受け取り側となります。

state

変更する状態の名前です。現在のところ、checkeddisabledfocusedに制限されています。

value

値はコマンドの実行時に評価されます。そのため、既存のコンポーネントのプロパティを活用できます。たとえば、このコマンドでは、現在のコンポーネントのchecked状態が切り替えられます。

{
  "type": "SetState"
  "state": "checked",
  "value": "${!event.source.value}"
}

SetValueコマンド

SetValueコマンドはコンポーネントの動的プロパティを変更します。設定可能な値については、各コンポーネントの仕様を参照してください。SetValueを使用すると、指定したコンポーネントのプロパティは変化しますが、画面は再描画されません。コマンドの評価を参照してください。

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

プロパティ デフォルト 説明
componentId 文字列 SELF 値を設定する必要があるコンポーネントのIDです。
プロパティ 文字列 必須 設定するプロパティの名前です。
value 文字列 必須 プロパティに設定する値です。

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

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

SetValueコマンドを使用すると、コンポーネントごとにさまざまなプロパティの値を変更できます。変更可能な具体的なプロパティがコンポーネントごとに記載されています。

SetValueコマンドは遅延なしに高速モードで実行されます。

componentId

値が変更されるコンポーネントのIDです。このプロパティが省略された場合、SetValueコマンドを発行するコンポーネントが受け取り側となります。

プロパティ

変更されるプロパティの名前です。

value

valueはコマンドの実行時に評価されます。そのため、既存のコンポーネントのプロパティを活用できます。この例では、SetValueコマンドがターゲットコンポーネントのopacityを現在の値の50%に設定します。

{
  "type": "SetValue"
  "property": "opacity",
  "value": "${event.target.opacity * 0.5}"
}

SpeakItemコマンド

SpeakItemコマンドは画面の1つの項目のコンテンツを読み込みます。見えない場合、項目はスクロールされて表示されます。項目にはspeechプロパティを含めることをお勧めしますが、必須ではありません。どのタイプのコンポーネントも、SpeakItemの受け取り側になることができます。

SpeakItemコマンドには現在、問題が確認されています。既知の問題の修正については、APLの既知の問題とバグを参照してください。

  • SpeakItemコマンドに加え、PlayMediaまたはControlMediaコマンドがSequentialコマンドで使用された場合、ビデオ再生によって音声が中断されます。このバグが修正されると、2つのコマンドが順番に実行されます。
  • SpeakItemコマンドと一緒にAutoPageコマンドを使うことはAlexaデバイスでは可能ですが、開発者コンソールのAlexaシミュレーターではうまくいかない場合があります。

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

プロパティ デフォルト 説明
align firstlastcentervisible visible スクロール後の項目の配置です。デフォルトは「visible」です。
componentId 文字列 SELF 読み込むコンポーネントのIDです。
highlightMode lineblock block karaokeの適用方法です。行ごとまたはブロック全体に適用します。デフォルトは「block」です。
minimumDwellTime 整数 0 項目をハイライトする最小時間(ミリ秒単位)です。

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

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

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

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

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

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

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

  • 項目をスクロールして表示するのに使用するアルゴリズムは、スクロールするコンポーネントが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コマンドには現在、問題が確認されています。既知の問題の修正については、APLの既知の問題とバグを参照してください。

  • SpeakListコマンドに加え、PlayMediaまたはControlMediaコマンドがSequentialコマンドで使用された場合、ビデオ再生によって音声が中断されます。このバグが修正されると、2つのコマンドが順番に実行されます。
  • SpeakListコマンドと一緒にAutoPageコマンドを使うことはAlexaデバイスでは可能ですが、開発者コンソールのAlexaシミュレーターではうまくいかない場合があります。

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

プロパティ デフォルト 説明
align firstcenterlastvisible visible 項目の配置です。デフォルトはvisibleです。
componentId 文字列 SELF [Sequence][apml-sequenceまたはContainer](またはその他のホスティングコンポーネント)のIDです。
count 整数 必須 読み取る子の数です。
minimumDwellTime 数値 0 項目をハイライトするミリ秒単位の最小時間です。デフォルトは0です。
start 整数 必須 読み取りを開始する項目のインデックスです。

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