InsertItemコマンド

InsertItemコマンド

InsertItemにはAPL 2023.3以降が必要です。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。

インフレートされたAlexa Presentation Language（APL）ドキュメントに項目を追加します。成功すると、構造の変更を反映するようにドキュメントのレイアウトが調整されます。

同様の結果は、1つの子のみのインフレートとwhenプロパティを使用することでも達成できます。ただし、この手法を使用するには、APLドキュメントを作成する時点でインフレートするレイアウトを知っている必要があります。ドキュメントの作成時にレイアウトや子コンポーネントの存在がわからない場合は、InsertItemコマンドを使用します。

プロパティ

InsertItemコマンドには、共通のコマンドプロパティに加えて、以下の表に示すプロパティがあります。typeプロパティはInsertItemに設定します。

コマンドを実行するために値が必要なプロパティの場合、以下の表の「デフォルト」列に「必須」と表示されています。それ以外の場合はデフォルト値が表示されますが、デフォルト値がないこともあります。

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

at

整数

MAX_INT

既存の子項目の配列内で、この項目を挿入する位置を指定します。設定しない場合、コマンドは指定された親コンポーネントの子項目の末尾に項目を追加します。

componentId

Selector

:source

親コンポーネントのIDです。このコマンドは、指定されたコンポーネントの子として項目を挿入します。

item、items

オブジェクトの配列

[]

挿入するコンポーネントまたはレイアウトです。

at

既存の子項目の配列内で、itemを挿入する位置を指定します。負のインデックスは配列の定義に従います。指定しない場合、コマンドは指定された親コンポーネントの子項目の末尾に項目を追加します。

配列の範囲外エラーを防ぐために、次のルールにより、atの値は配列のサイズ内に制限されます。

  • atの値が配列の長さよりも大きい場合、InsertItemは新しい項目を配列の末尾に追加します。
  • atの値が小さすぎて挿入位置が負になる場合、InsertItemは配列の先頭に項目を挿入します。

親コンポーネントの子項目の配列には、親コンポーネントの子コンポーネントであるすべてのインフレートされたコンポーネントが含まれています。たとえば、複数子コンポーネントの場合、子項目の配列には以下が含まれます。

  • firstItem（定義されている場合）
  • item配列のすべての項目
  • lastItem（定義されている場合）

したがって、atを0に設定すると、コマンドは定義されたfirstItemの前に挿入項目を配置します。項目を末尾に追加すると、コマンドは定義されたlastItemの後に項目を配置します。

componentId

新しい項目の挿入先となるコンポーネントまたはレイアウトを特定するセレクターです。セレクターが既存のコンポーネントに解決されない場合、InsertItemコマンドは何も実行しません。

item、items

挿入するコンポーネントまたはレイアウトです。配列に複数の項目が含まれている場合、whenプロパティで選択された最初の項目が使用されます。詳細については、1つの子のみのインフレートを参照してください。

挿入された項目は、ほかのコンポーネントと同様にドキュメントのデータバインディング構文にアクセスでき、APLドキュメントで宣言されている拡張機能も参照できます。拡張機能の詳細については、APL拡張機能を参照してください。

InsertItemが効果を持たない状況

以下のシナリオでは、インフレートされたドキュメントに対してInsertItemコマンドは効果を持ちません。

  1. 挿入された項目が何もレンダリングしない場合。たとえば、挿入された項目にwhenが含まれていて、それがfalseに評価される場合です。APLの形式が誤っている場合も、挿入された項目がレンダリングされない状況になる可能性があります。
  2. コマンドが、子コンポーネントをサポートしない親コンポーネント（VectorGraphicなど）をターゲットにしている場合。

  3. コマンドが、単一の子をサポートする親コンポーネント（Frameなど）をターゲットにしている場合。

  4. ターゲットコンポーネントは複数子コンポーネントでも、データ配列のインフレートが使用されている場合。

InsertItemとレイアウトの調整

次のドキュメントでは、単一のTextコンポーネントを含むContainerを定義しています。ContainerのIDはmainで、TextコンポーネントのIDはhelloです。

{
  "type": "APL",
  "version": "2023.3",
  "mainTemplate": {
    "items": [
      {
        "type": "Container",
        "id": "main",
        "items": [
          {
            "type": "Text",
            "id": "hello"
            "text": "ハローワールド",
            "textAlign": "center",
            "textAlignVertical": "center",
            "grow": 1
          }
        ]
      }
    ]
  }
}
単一のTextコンポーネントを持つドキュメントのインフレート結果を表すワイヤーフレーム

次のInsertItemコマンドは、このContainerの末尾にTextコンポーネントを追加します。

{
  "commands": [
    {
      "type": "InsertItem",
      "componentId": "main",
      "item": {
        "type": "Text",
        "id": "bye",
        "grow": 1,
        "text": "さようなら",
        "textAlign": "center",
        "textAlignVertical": "center"
      }
    }
  ]
}

レイアウトは、追加のTextコンポーネントが収まるように調整されます。growプロパティにより、元のhelloコンポーネントの高さは半分に縮小されます。

新しいTextコンポーネントが挿入された後のドキュメントを表すワイヤーフレーム

InsertItemの例

複数子コンポーネントに挿入する

以下の例では、Frameコンポーネントを含むレイアウトを使用して、2つのコンポーネントの周囲に境界線を表示します。この例は、ドキュメントがインフレートされてから5秒後にInsertItemコマンドを実行して、TextFrameレイアウトの2つ目のインスタンスを挿入します。ページを更新してドキュメントを再インフレートし、InsertItemによる更新を確認してください。

この例は、ContainerのonChildrenChangedハンドラーでSendEventを使用することで、InsertItemコマンドの後に以下のUserEventリクエストをスキルに送信します。

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2023-10-20T18:26:45Z",
  "locale": "en-US",
  "arguments": [
    {
      "uid": ":1003",
      "index": 1,
      "action": "insert"
    }
  ],
  "components": {},
  "source": {
    "type": "Container",
    "handler": "ChildrenChanged",
    "id": "main"
  },
  "token": "/insertItemBasicFrameToken"
}

SendEventを検査するには、この例をスキルでテストしてください。

単一子コンポーネントに挿入する

以下の例では、InsertItemを使用して、TouchWrapperのタップ時にそのコンポーネントに項目を挿入します。TouchWrapperは1つの子しか保持できないため、この例では、まずRemoveItemを実行してhelloレイアウトを削除し、次にInsertItemを使用してbyeレイアウトを挿入します。

onChildrenChangedハンドラーはTouchWrapperなどの単一子コンポーネントでは利用できないため、この例には含まれていません。

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

最終更新日: 2025 年 12 月 04 日