APL標準コマンド（1.2）



• 共通プロパティ
• AnimateItemコマンド
• AutoPageコマンド
• Idleコマンド
• OpenURLコマンド
• Parallelコマンド
• Scrollコマンド
• ScrollToComponentコマンド
• ScrollToIndexコマンド
• SendEventコマンド
• Sequentialコマンド
• SetFocusコマンド
• ClearFocusコマンド
• SetPageコマンド
• SetStateコマンド
• SetValueコマンド
• SpeakItemコマンド
• SpeakListコマンド
• 関連トピック

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

共通プロパティ

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

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

高速モードでは、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)の終了値は暗黙的に示されます。

以下のイージングカーブが事前定義されています。

repeatCount

repeatCountは、コマンドが終了するまでにアニメーションをリピート再生する回数を定義します。デフォルトでは、repeatCountは0に設定されています。この場合、アニメーションは1回再生されて停止します。

repeatMode

repeateModeは、アニメーションを毎回最初から最後まで再生するか、一回おきにアニメーションを先頭まで逆再生するかを定義します。次のリピートモードが定義されています。

アニメーションの終了状態は、repeatCountとrepeatModeの関数です。repeatModeがreverseに設定され、repeatCountが奇数の場合、アニメーションが終了した状態は開始状態と同じになります。上記以外の場合では、終了した状態はtoの値に割り当てられた「自然」な終了状態になります。

途中で終了したアニメーションは、常に終了した状態まで「ジャンプ」します。

value

アニメーション化するプロパティの配列です。配列の各要素は、次のような形式になります。

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

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

たとえば、デバイスのブラウザで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コマンドには、共通のコマンドプロパティに加えて以下のプロパティがあります。

高速モードでは、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
  }

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

たとえば、スクロールして特定の項目が表示されるようにするには、次のように記述します。

{
  "type": "ScrollToComponent",
  "componentId": "recipeSteps",
  "align": "center"
}

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

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

ScrollToComponentコマンドは、高速モードでは無視されます。

align

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

componentId

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

ScrollToIndexコマンド

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

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

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

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

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

ScrollToIndexコマンドは、高速モードでは無視されます。

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に送信します。これにより、スキルに送信されるUserEventを生成します。

以下にSendEventコマンドの例を示します。

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

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

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

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

たとえば、特定のコンポーネントにフォーカスするには、次のように記述します。

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

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

この例では、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コマンドでは、コンポーネントのプロパティの値またはコンポーネントのバインディングが変更されます。次のルールが適用されます。

1. コンポーネントに、propertyで指定された名前を持つ動的なプロパティがある場合、そのプロパティが更新され、新しい値が設定されます。
2. そうではなく、コンポーネントに、その名前を持つcomponent_bind_propertyプロパティがある場合、そのバインドされているプロパティが更新されます。
3. バインドされているプロパティの値が変わると、そのプロパティに依存しているコンポーネントの動的なプロパティはすべて更新されます。

バインドしている値の更新の例を以下に示します。

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

たとえば、次のように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

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

componentId

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

highlightMode

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

行ごとのKaraokeモードでは、スタイル設定の変更ができるのはcolorプロパティだけです。他のプロパティは無視されます。

Textコンポーネント以外のコンポーネントがSpeakItemの受け取り側となる場合、highlightModeは無視されます。

minimumDwellTime

項目をハイライトする最低限の時間（ミリ秒単位）です。

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

SpeakListコマンドは、高速モードでは無視されます。

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

関連トピック

• APLコマンドの概要
• メディアコマンド