APL標準コマンド


APL標準コマンド

共通プロパティ

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

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

type

文字列

必須

コマンドの型です。

description

文字列

""

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

delay

整数

0

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

screenLock

ブール値

false

trueの場合、操作タイマーを無効にします。

sequencer

文字列

""

このコマンドを実行するシーケンサーを指定します。

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,
}

sequencer

指定された場合、sequencerプロパティはこのコマンドを実行するシーケンサーの名前を示します。シーケンサーの選択ルールは次のとおりです(記載順)。

  1. シーケンサーが指定された場合、コマンドはそのシーケンサー上で通常モードで実行されます。
  2. それ以外の場合、コマンドが高速モードで実行されていれば、通常は高速モードで実行されます。
  3. それ以外の場合、コマンドがSequentialParallelのいずれかのコマンドのサブコマンドであれば、SequentialまたはParallelコマンドのシーケンサー上で通常モードで実行されます。
  4. それ以外の場合、コマンドは「MAIN」シーケンサー上で通常モードで実行されます。

コマンドシーケンサーの詳細については、コマンドのシーケンス実行を参照してください。

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プロパティのアニメーション化をサポートしています。from値はopacityに必須ではありませんが、transformには必ず指定してください。

カスタムのイージングカーブを定義するには、次のように記述します。

{
  "type": "AnimateItem",
  "easing": "path(0.25, 0.6, 0.5, 0.8, 0.75, 0.9)",
  "duration": 1000,
  "value": {
    "property": "opacity",
    "to": 1
  }
}

バインドされたプロパティをアニメーション化できます。以下の例では、Frameをviewportの中心の緑色のボックスとして表示しています。Frameは、コンポーネントのタップでバインドされた値SIDEをアニメーション化するアニメーションを定義します。アニメーションは、1秒かけてFrameのサイズと色をスムーズに変更します。

シミュレーターペインの緑色のボックスをクリックすると、アニメーションを確認できます。もう一度クリックすると、同じアニメーションが逆再生されます。


ベクターグラフィックに渡すパラメーターをアニメーション化することもできます。

以下の例では、細いストローク値で描写したボックスをベクターグラフィックとして定義しています。ベクターグラフィックをタップすると、ボックスが塗りつぶされるまで線の太さを広げるアニメーションが始まります。その後、アニメーションは元の形状に戻ります。

シミュレーターペインの青いボックスをクリックすると、アニメーションを確認できます。


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

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

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

プロパティ デフォルト 説明
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%未満の場合は、前のページに戻ります。

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

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

componentId

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

count

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

duration

次のページに進んだ後に待機する時間です。ページ間のアニメーション遷移は時間に含まれないため、コマンドの実行時間が全体的に長くなります。

時間は次のページに進んだ後に適用されるため、Pagerの最初のページには適用されません。ページングの開始を遅らせるには、標準コマンドのdelayプロパティを使用します。

ClearFocus

ClearFocusを使用するには、APL 1.1以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください

現在フォーカスされている実行可能なコンポーネントから、フォーカスを外します。フォーカスを当てたり解除したりできる実行可能なコンポーネントについては、focusedを参照してください。

一度にフォーカスできるコンポーネントは1つだけなので、ClearFocusは1つのコンポーネントにしか影響しません。

ClearFocusコマンドが実行されると、フォーカスを当てたコンポーネントからフォーカスを外し、そのコンポーネントのfocused状態をfalseに設定します。

ClearFocusコマンドには、通常のコマンドプロパティのほかにプロパティはありません。

たとえば、フォーカスを当てたコンポーネントからフォーカスを解除するには、次のように記述します。

{
  "type": "ClearFocus"
}

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

Finish

Finishを使用するには、APL 1.3以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください

現在のAPLドキュメントを閉じて終了します。finishコマンドには、共通のコマンドプロパティ以外のプロパティはありません。

finishコマンドを実行すると、APL内の他のすべての処理(実行中のコマンドを含む)を停止します。たとえば、SendEventとFinishの両方を1つのボタンの押下で使用する場合は、次の順序で記述する必要があります。

{
  "onPress": [
    {
      "type": "SendEvent",
      "arguments": [
        "now stopping"
      ]
    },
    {
      "type": "Finish"
    }
  ]
}

コマンドを逆の順序で記述すると、SendEventは実行されません。

finishコマンドは、通常モードと高速モードの両方で実行されます。

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

Reinflate

更新されたコンフィギュレーションプロパティで現在のドキュメントを再インフレートします。Alexaは、画面に最初にドキュメントを表示したときと同じプロセスに従って、ドキュメント全体を再構築します。Alexaは、新しいデバイスコンフィギュレーションに一致するenvironmentviewportの定数を使って、新しい更新されたデータバインディングコンテキストを作成します。

Reinflateコマンドに追加のプロパティはありません。

Reinflateコマンドを実行すると、ほかのコマンドも含め、APLのその他の処理がすべて停止します。たとえば、SendEventReinflateを同じハンドラーで実行したい場合、SendEventを最初に配置する必要があります。

以下の例では、UserEventリクエストをスキルに送信してからドキュメントを再インフレートしています。

{
  "onConfigChange": [
    {
      "type": "SendEvent",
      "sequencer": "ConfigSendEvent",
      "arguments": [
        "APLドキュメントの再インフレート"
      ]
    },
    {
      "type": "Reinflate"
    }
  ]
}

コマンドを逆の順序で記述すると、SendEventは実行されません。onConfigChangeハンドラーは高速モードで実行されるため、SendEventにはシーケンサーが必要です。

ドキュメントレベルおよびコンポーネントレベルのonMountコマンドは、ドキュメントの再インフレート後に実行されます。

Reinflateコマンドは通常モードと高速モードの両方で実行されます。

再インフレートを使用してタブレットをサポートする詳細については、サイズ変更が可能なタブレットなどのデバイスをサポートするを参照してください。

Scroll

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

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

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

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

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

  • 目的地に到達したとき。
  • スクロール可能なコンテンツの最後に到達したとき。
  • ユーザーが画面をタッチしたとき。
  • Alexaが新しいコマンドを送信したとき。新しいコマンドを開始すると、Scrollコマンドが終了し、スクロールが直ちに停止します。

使用可能なすべてのコンテンツをスムーズにスクロールするには、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);
  }

Select

Selectを使用するには、APL 1.3以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください

コマンドとデータの配列から1つのコマンドを選択します。Selectコマンドには、標準的なコマンドプロパティに加えて以下のプロパティがあります。

プロパティ デフォルト 説明
commands コマンドの配列 必須 選択する順番に並んだコマンドのリストです。
data 配列 [] コマンドに対してマップするデータのリストです。
otherwise コマンドの配列 [] commands配列からコマンドが選択されていない場合に実行するコマンドの配列です。

data配列が空の場合、Selectコマンドはcommands配列でwhentrueと評価された最初のコマンドを実行します。

次の例では、age7であると仮定します。コマンドは、3番目のコマンドに到達するまでcommands配列を反復処理します。このコマンドのwhenステートメントはtrueと評価されるため、SelectSetValueコマンドを実行して、指定されたtextプロパティの値を「子供」に更新します。

{
  "type": "Select",
  "commands": [
    {
      "when": "${age < 2}",
      "type": "SetValue",
      "property": "text",
      "value": "乳児",
      "componentId": "${textIdToUpdate}"
    },
    {
      "when": "${age < 5}",
      "type": "SetValue",
      "property": "text",
      "value": "幼児",
      "componentId": "${textIdToUpdate}"
    },
    {
      "when": "${age < 13}",
      "type": "SetValue",
      "property": "text",
      "value": "子ども",
      "componentId": "${textIdToUpdate}"
    },
    {
      "when": "${age < 18}",
      "type": "SetValue",
      "property": "text",
      "value": "ティーンエイジャー",
      "componentId": "${textIdToUpdate}"
    },
    {
      "type": "SetValue",
      "property": "text",
      "value": "大人",
      "componentId": "${textIdToUpdate}"
    }
  ]
}

data配列を指定すると、Selectコマンドは、data配列の項目ごとに、commands配列の各コマンドにtrueのwhen句が1つずつ含まれているかどうかを確認します。データバインディングコンテキストは、dataプロパティ、indexプロパティ、lengthプロパティをバインドすることにで拡張されます。Selectコマンドは、1つのコマンドを実行すると終了し、data配列に対する反復処理は継続しません。

次の例では、age17であると仮定します。このコマンドは、data配列を反復処理します。コマンドのwhenステートメントは、4番目の項目(17 < 18)で指定されるデータについてtrueと評価されるため、Selectはデータ配列の反復処理を停止して、SetValueコマンドを実行します。これにより、指定されたtextプロパティが「カテゴリーはティーンエイジャーです」に更新されます。

{
  "type": "Select",
  "commands": {
    "when": "${!data.until || age < data.until}",
    "type": "SetValue",
    "property": "text",
    "value": "カテゴリーは${data.category}です",
    "componentId": "${textIdToUpdate}"
  },
  "data": [
    {
      "until": 2,
      "category": "乳児"
    },
    {
      "until": 5,
      "category": "幼児"
    },
    {
      "until": 13,
      "category": "子ども"
    },
    {
      "until": 18,
      "category": "ティーンエイジャー"
    },
    {
      "category": "大人"
    }
  ]
}

複数のcommandsdata配列と組み合わせることができます。Selectは、引き続きcommands配列の1つのコマンドのみを実行します。次に例を示します。

{
  "type": "Select",
  "commands": [
    {
      "when": "${searchCategory == data.category && data.rating >= 8.0}",
      "type": "SetValue",
      "property": "text",
      "componentId": "${textIdToUpdate}",
      "value": "あなたのカテゴリーにぴったりの映画はこちら:<em>${data.title}</em>"
    },
    {
      "when": "${searchCategory == data.category}",
      "type": "SetValue",
      "property": "text",
      "componentId": "${textIdToUpdate}",
      "value": "あなたのカテゴリーに合う映画はこちら:<em>${data.title}</em>"
    }
  ],
  "data": "${movieData}"
}

次の例では、1番目に最も評価の高い映画が来るようにカテゴリーと評価で並び替えられた映画の配列にmovieDataがバインドされています。

{
  "movieData": [
    {"title":"アバター","category":"アドベンチャー","rating":7.8},
    {"title":"アラジン","category":"アドベンチャー","rating":7.1},
    {"title":"リメンバー・ミー","category":"アニメーション","rating":8.4},
    {"title":"トイ・ストーリー4","category":"アニメーション","rating":8},
    {"title":"ライオン・キング","category":"アニメーション","rating":7}
  ]
}

SearchCategoryが「アニメーション」の場合、Selectdata内の3番目の項目に達するまで反復処理します。この項目は、最初のwhenステートメントの両方の条件に一致します。最初のコマンドは、movieResultTextComponentコンポーネントのtextプロパティを実行して、「カテゴリーにぴったりの映画はこちら: リメンバー・ミー」に更新します。

SearchCategoryが「アドベンチャー」の場合、Selectdata内の最初の項目を選択します。これは、この項目が2番目のwhenステートメントの条件に一致するためです。2番目のコマンドは、movieResultTextComponenttextプロパティを実行して、「カテゴリーに合う映画はこちら: アバター」に更新します。

commands

コマンドの配列です。trueのwhen句を持つ配列の最初のコマンドが実行されます。

data

反復処理するデータの配列です。反復処理中に、データバインディングコンテキストは次のプロパティで拡張されます。

名前 説明
data データ配列のプロパティから割り当てられたデータです。
index 現在のデータ項目のゼロから始まるインデックスです。
length データ配列内のデータ項目の総数です。

これらのプロパティは、data配列プロパティに1つ以上の項目が含まれている場合にのみ設定されます。

otherwise

otherwiseコマンドは、commandsプロパティ内のいずれのコマンドも実行されない場合に実行されます。otherwiseコマンドでは、dataプロパティにアクセスできません。次に例を示します。

{
  "type": "Select",
  "commands": {
    "when": "${data.breed == breed}",
    "type": "SetValue",
    "property": "text",
    "componentId": "${textIdToUpdate}",
    "value": "飼い犬は${data.description}です"
  },
  "otherwise": {
    "type": "SetValue",
    "property": "text",
    "componentId": "${textIdToUpdate}",
    "value": "飼い犬の犬種を分類できません!"
  },
  "data": "${dogBreedData}"
}

dogBreedData配列の記述は以下のとおりです。

{
  "dogBreedData": [
    {
      "breed": "アーフェンピンシャー",
      "description": "忠実で好奇心があり、面白い"
    },
    {
      "breed": "バセットハウンド",
      "description": "垂れ耳で可愛らしい"
    },
    {
      "breed": "ビーグル",
      "description": "楽天的で陽気"
    }
  ]
}

上記の例では、「雑種」のbreedを渡すとotherwiseに割り当てられ、指定されたTextコンポーネントのテキストを「飼い犬の犬種を分類できません」に更新します。

otherwiseプロパティは、data配列のいずれも一致しない場合のフォールバック動作を提供します。

SendEvent

SendEventコマンドを使用して、イベントを生成してAlexaに送信します。SendEventコマンドは、スキルにAlexa.Presentation.APL.UserEventリクエストを送信します。UserEventには、コマンドをトリガーしたコンポーネントとイベントに関する情報が含まれています。

以下は、TouchWrapperonPressハンドラーでのSendEventコマンドの例です。

{
  "type": "TouchWrapper",
  "id": "idForTheTouchWrapper",
  "spacing": "@spacingSmall",
  "alignSelf": "center",
  "onPress": [
    {
      "type": "SendEvent",
      "arguments": [
        "textWasPressed",
        "このデータをスキルに送信する"
      ],
      "components": [
        "idForTheTextComponent"
      ]
    }
  ],
  "item": {
    "type": "Text",
    "id": "idForTheTextComponent",
    "color": "@colorAccent",
    "text": "クリックすると、スキルにUserEventが送信されます。"
  }
}

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

プロパティ デフォルト 説明
arguments オブジェクトの配列 [ ] UserEventリクエストでスキルに送信する引数データの配列です。
components 文字列の配列 [ ] コンポーネントIDの配列です。識別された各コンポーネントに関連付けられた値は、結果のUserEventリクエストに含まれます。

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

arguments

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

リクエストのargumentsプロパティのUserEventハンドラーで、このデータにアクセスします。

components

componentsプロパティはコンポーネントIDの配列です。これらの各コンポーネントのvalueは、UserEventリクエストに含まれます。これを使用して、フォームのコンテンツがサーバーに直接送信されるようにフォームを作成できます。

リクエストのcomponentsプロパティ内のコンポーネント値にアクセスします。

UserEvent

SendEventコマンドは、スキルにAlexa.Presentation.APL.UserEventリクエストを送信します。

たとえば、前述のTouchWrapperで定義されたSendEventは、次のようなUserEventリクエストを生成します。

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2020-01-20T22:28:44Z",
  "locale": "ja-JP",
  "arguments": [
    "textWasPressed",
    "このデータをスキルに送信する"
  ],
  "components": {
    "idForTheTextComponent": "クリックすると、スキルにUserEventが送信されます。"
  },
  "source": {
    "type": "TouchWrapper",
    "handler": "Press",
    "id": "idForTheTouchWrapper"
  },
  "token": "token-provided-with-RenderDocument"
}

このUserEventには、SendEventコマンドで定義された次の情報が含まれます。

  • argumentsプロパティには、SendEventコマンドのarguments配列に渡されるデータを含む配列が含まれます。この例では、このプロパティは静的文字列ですが、データバインディングを使用して動的情報を含めることができます。
  • sourceプロパティには、イベントをトリガーしたコンポーネントに関する詳細が含まれます。この例では、このプロパティはTouchWrapperです。
  • componentsプロパティには、ID「idForTheTextComponent」を持つコンポーネントのvalueが含まれます。これはTextコンポーネントであるため、UserEventに含まれる値はtextプロパティの値です。これは、SendEventが同じIDをcomponents配列に含めたためです。

UserEventリクエストの詳細は、UserEventリクエストを参照してください。

UserEventハンドラーの例については、UserEventリクエストを処理するを参照してください。

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つのコンポーネントのみがフォーカスされます。1つのコンポーネントにフォーカスを設定すると、他のコンポーネントのフォーカスが自動的に解除されます。

SetFocusは実行時に以下を実行します。

  1. ターゲットコンポーネントにフォーカスを当て、focused状態をtrueに設定します。
  2. 以前フォーカスを当てていたすべてのコンポーネントからフォーカスを外し、そのコンポーネントのfocused状態をfalseに設定します。

ターゲットコンポーネントが無効であるか、実行できない場合、またはinheritParentStateプロパティがtrueに設定されている場合、SetFocusコマンドは無視されます。

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

プロパティ デフォルト 説明
componentId 文字列 SELF フォーカスを当てるコンポーネントのIDです。

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

{
  "type": "SetFocus",
  "componentId": "myButton"
}

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

componentId

フォーカスを当てるコンポーネントのIDです。このプロパティが省略された場合、SetFocusコマンドを発行するコンポーネントが受け取り側となります。

コンポーネントにフォーカスを当てた状態でドキュメントを開くには、ドキュメントのonMountプロパティをSetFocusに設定します。

たとえば、ドキュメントのid myButtonを持つコンポーネントにフォーカスするには、次のように記述します。

{
  "onMount": {
    "type": "SetFocus",
    "componentId": "myButton"
  }
}

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%未満の場合は前のページに戻ります。onPageChangedコマンドは、ページが最終ページから変更された場合に停止時に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コマンドを使用して、checkeddisabledを変更できますが、推奨されていません。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

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

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

以下は、バインドされた値を更新する方法の例です。シミュレーターのテキストをクリックするたびに、数字が増えていくことを確認できます。ページを更新するか、Viewportのプロファイルを変更すると、カウンターがリセットされます。


上記の例では、TouchWrapperを押すたびに、表示されるテキストの数字が大きくなります。

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

componentId

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

property

変更されるプロパティの名前です。ビルトインのプロパティまたはバインディングを指定できます。

value

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

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

SpeakItem

SpeakItemコマンドは、画面の1つのコンポーネントのコンテンツを読み込みます。コンポーネントが表示されていない場合は、スクロールまたはページを移動して表示されます。

SpeakItemコマンドはコンポーネントのspeechプロパティで指定されたコンテンツを読み上げます。コンポーネントにspeechプロパティがない場合、SpeakItemコマンドはコンポーネントをスクロールして表示しますが、スピーチ音声は一切レンダリングしません。

コンポーネントのspeechプロパティをスピーチ音声に変換するtransformerの出力に設定します。たとえば、ssmlToSpeechtextToSpeechaplAudioToSpeechなどのトランスフォーマーです。

環境によっては、音声などのダイアログは使用できません。環境プロパティdisallowDialogを使って、デバイスとコンフィギュレーションが音声関連のコマンドをサポートしているかどうかを判断します。

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

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

以下は、1つのTextコンポーネントのコンテンツを読み上げ、テキストを画面に中央揃えするSpeakItemコマンドの例です。

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

SpeakItemコマンドは、コンポーネントのkaraoke状態を発話中にtrueに設定し、発話終了後にfalseに戻します。highlightModeプロパティはTextコンポーネントに適用されます。AlexaがTextコンポーネントを"highlightMode": "line"モードで読み上げるとき、テキストの各行は発話中にkaraoke状態に設定され、発話終了後にfalseに再設定されます。

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

  • SpeakItemコマンドはblockモードで発話中はコンテンツをスクロールしません。たとえば、コンポーネントがコンポーネントのスクロールContainerより大きい場合、スクロールした後でも見えないContainerからはみ出した部分は、隠れたままになります。
  • 円形画面ではコンポーネントを中央揃えにする必要があります。そうしない場合、表示されないコンテンツの部分が多くなってしまいます。
  • SpeakItemは、highlightModeblockの場合、発話中はテキストの個々の単語や行をハイライトしません。
  • 項目をスクロールして表示するのに使用するアルゴリズムは、スクロールするコンポーネントが1つのみであることを想定しています。入れ子構造のコンポーネントには対応していません。
  • speechプロパティのないコンポーネントもスクロールして表示しますが、スピーチ音声は一切レンダリングしません。
  • SpeakItemは、タブレットの向きを切り替えるなど、コンフィギュレーションの変更中には停止します。

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内にある項目のコンテンツを読み取ります。各項目は、Alexaが項目を読み上げる前にスクロール表示されます。各項目のspeechプロパティは再生する音声を定義します。項目にspeechプロパティが設定されていない場合、項目は音声なしでスクロール表示されます。

環境によっては、音声などのダイアログは使用できません。環境プロパティdisallowDialogを使って、デバイスとコンフィギュレーションが音声関連のコマンドをサポートしているかどうかを判断します。

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

プロパティ デフォルト 説明
align firstcenterlastvisible visible 項目の配置です。デフォルトはvisibleです。
componentId 文字列 SELF 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コマンドはfirstItemおよびlastItemのプロパティも読み上げることができます。コンポーネントにfirstItemが定義されている場合、firstItemのインデックスは0となり、itemsの子コンポーネントのインデックスは1から開始します。コンポーネントにfirstItemが定義されていない場合、itemsの子コンポーネントのインデックスは0から開始します。

以下の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);
  }
}


このページは役に立ちましたか?

最終更新日: 2022 年 08 月 12 日