ImportPackageコマンド

ImportPackageコマンド

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

Alexa Presentation Language（APL）パッケージとその依存関係を現在のドキュメントにインポートし、パッケージがインポートされた後にコマンドを実行します。

プロパティ

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

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

accept

文字列

version

パッケージのacceptプロパティです。

name

文字列

必須

パッケージのnameプロパティです。

onFail

コマンドの配列

[]

パッケージの読み込みに失敗したときに実行するコマンドです。

onLoad

コマンドの配列

[]

パッケージが読み込まれたときに実行するコマンドです。

source

文字列

""

（オプション）パッケージのsourceプロパティです。

version

文字列

必須

パッケージのversionプロパティです。

accept、name、version、sourceの各プロパティの定義は、パッケージ参照で説明されています。

以下は、FishFeederというパッケージをインポートするコマンドの例です。

{
  "type": "ImportPackage",
  "name": "FishFeeder",
  "version": "1.2.0",
  "accept": ">=1.2 <2",
  "onLoad": [ <実行するコマンド> ],
  "onFail": [ <実行するコマンド> ]
}

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

onFail

パッケージまたは依存関係パッケージの読み込みに失敗した場合に実行するコマンドの配列です。パッケージの再読み込みは行われません。以前に読み込みに失敗したパッケージに対しては、即座にonFailイベントハンドラーが呼び出されます。

生成されるイベントの形式は次のようになります。

"event" {
  "source": {
    "type": COMPONENT_TYPE,  // コンポーネントの型（"TouchWrapper"など）
    "handler": "Fail",
    ...                      // コンポーネントのソースのプロパティ
  },
  "value": STRING,           // 読み込みに失敗したパッケージの名前、バージョン、URL
  "error": STRING,           // 失敗の理由
  "errorCode": NUMBER        // エラーの識別子
}

イベントで報告されるvalue、error、errorCodeは、デバッグの目的で提供されるものです。これらの値をユーザーに表示しないでください。

event.sourceのプロパティの詳細については、eventプロパティを参照してください。

onFailイベントハンドラーは高速モードで実行されます。

onLoad

パッケージとすべての依存関係パッケージが読み込まれたときに実行するコマンドの配列です。パッケージが既にドキュメントに読み込まれている場合は、このコマンドがすぐに実行されます。

生成されるイベントの形式は次のようになります。

"event": {
  "source": {
    "type": COMPONENT_TYPE,  // コンポーネントの型（"TouchWrapper"など）
    "handler": "Load",
    ...                      // コンポーネントのソースのプロパティ
  },
  "version": STRING,         // 読み込まれたパッケージのバージョン
}

versionプロパティは、読み込まれたパッケージのversionです。

event.sourceのプロパティの詳細については、eventプロパティを参照してください。

onLoadイベントハンドラーは高速モードで実行されます。

ImportPackageコマンドとドキュメントのimportプロパティ

インポートされたパッケージには、ドキュメントのimportプロパティが含まれていることがあります。これにより、追加で読み込むパッケージが特定されます。Alexaはパッケージを1回しか読み込みません。パッケージが既に読み込まれている場合、そのパッケージは無視されます。パッケージは、nameとversionタプルによって定義されます。したがって、次の2つのパッケージは同じではありません。

  • {"name": "A", "version": "1.1.0"}
  • {"name": "A", "version": "1.1.1"}（バージョン番号が異なる）

Aのバージョン1.1.0が読み込まれた後、バージョン1.1.1をリクエストすると、バージョン1.1.1が読み込まれてバージョン1.1.0をオーバーライドします。

パッケージが読み込まれ、内部で参照されているパッケージもすべて読み込まれると、コマンド、グラフィック、レイアウト、リソース、スタイルが処理され、コアドキュメントのコンテキストに追加されます。onLoadの コマンドは、この処理の後に実行されます。いずれかのパッケージの読み込みに失敗すると、onFailのコマンドが実行されます。

インポートされたパッケージから、次のプロパティが読み取られます。

  • type： APLであることが必要
  • version： サポートされているAPLバージョンであることが必要
  • commands
  • graphics
  • import
  • layouts
  • resources
  • styles

Reinflateコマンドでは、インポートされたパッケージは保存されません。ドキュメントは、以前にImportPackageコマンドで読み込まれたパッケージを含めずに再読み込みされます。

例

ImportPackageコマンドを使用すると、優先度の低いパッケージの読み込みを遅らせながら、それらのパッケージに依存する要素の表示にかかる時間を最小限に抑えることができます。

以下の例では、ドキュメントのonMountイベントハンドラーを使用して、バックグラウンドで「FishGraphics」パッケージの読み込みを開始します。ドキュメントは、後でユーザーがボタンを押したときに、ImportPackageを使用してFishGraphicsパッケージをインポートします。すると、onLoadイベントハンドラーがパッケージからグラフィックを表示します。FishGraphicsパッケージが既に読み込まれている場合は、onLoadイベントハンドラーが即座に実行されるため、SetValueコマンドはすぐにグラフィックを表示します。FishGraphicsの読み込みが完了していない場合は、パッケージの読み込み後にonLoadハンドラーが実行されます。このしくみにより、グラフィックの表示を試みる前に、パッケージが確実に使用可能になります。

{
  "type": "APL",
  "version": "2024.3",
  "onMount": {
    "type": "ImportPackage",
    "name": "FishGraphics",
    "version": "1.2.0",
    "accept": ">=1.2.0",
    "sequencer": "FishGraphicLoader"
  },
  "onPress": {
    "type": "ImportPackage",
    "name": "FishGraphics",
    "version": "1.2.0",
    "accept": ">=1.2.0",
    "onLoad": {
      "type": "SetValue",
      "componentId": "MY_FISH_GRAPHIC",
      "property": "source",
      "value": "HappyTunaGraphic"
    },
    "onFail": {
      "type": "SetValue",
      "componentId": "USER_MESSAGE",
      "property": "text",
      "value": "魚の画像を読み込むことができません"
    }
  }
}

もう1つの一般的な使用例が、項目のリストです。リストの項目をすぐに表示する必要がある場合に、実際の項目が読み込まれるまで項目のプレースホルダーを表示できます。以下の例では、リスト内に空のFrameコンポーネントを配置します。実際の表示項目は、パッケージが読み込まれた後にFrameにインフレートされます。

{
  "type": "APL",
  "version": "2024.3",
  "layouts": {
    "EnsureFishFeeder": {
      "parameters": [],
      "items": {
        "type": "Frame",
        "onMount": {
          "type": "ImportPackage",
          "sequencer": "DelayedLoader_${event.source.uid}",
          "name": "FishFeeder",
          "version": "1.2.0",
          "onLoad": {
            "type": "InsertItem",
            "item": {
              "type": "FishFeederLayout",
              "numberOfFish": "${data.fish_count}",
              "tankSize": "${data.tank_size}"
            }
          }
        }
      }
    }
  },
  "mainTemplate": {
    "items": {
      "type": "Container",
      "item": {
        "type": "EnsureFishFeeder"
      },
      "data": [
        {
          "fish_count": 12,
          "tank_size": "SMALL"
        },
        {
          "fish_count": 18,
          "tank_size": "MEDIUM"
        },
        {
          "fish_count": 87,
          "tank_size": "LARGE"
        }
      ]
    }
  }
}

以下の例は、挿入するオブジェクトを検査し、それがパッケージに依存しているかどうかを判断する汎用パッケージローダーを示しています。

{
  "type": "APL",
  "version": "2024.3",
  "layouts": {
    "PackageWrapper": {
      "parameters": [
        "DATA"
      ],
      "items": [
        {
          "when": "${DATA.PACKAGE_NAME}",
          "type": "Frame",
          "onMount": {
            "type": "ImportPackage",
            "sequencer": "DelayedLoader_${event.source.uid}",
            "name": "${DATA.PACKAGE_NAME}",
            "version": "${DATA.PACKAGE_VERSION}",
            "onLoad": {
              "type": "InsertItem",
              "item": "${DATA}"
            }
          }
        },
        "${DATA}"
      ]
    }
  },
  "mainTemplate": {
    "items": {
      "type": "Container",
      "item": {
        "type": "PackageWrapper",
        "DATA": "${data}"
      },
      "data": [
        {
          "PACKAGE_NAME": "FishFeeder",
          "PACKAGE_VERSION": "1.2.0",
          "type": "FishFeederLayout",
          "numberOfFish": 12,
          "tankSize": "SMALL"
        },
        {
          "type": "Text",
          "text": "これは水槽ではありません"
        }
      ]
    }
  }
}

この例では、PackageWrapperレイアウトにより、PACKAGE_NAMEプロパティが定義されているかどうかを確認します。定義されている場合はパッケージ名として扱い、Frameを作成して、リクエストされたパッケージをonMountイベントハンドラーで読み込んだ後、その項目をコンポーネントとして挿入します。PACKAGE_NAMEプロパティが定義されていない場合は、その項目をラッパーに含めます。

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

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