APLドキュメント



APLドキュメント

APLドキュメントは、構造が明確に定義されたJSONオブジェクトです。

APLドキュメントのサンプル

以下に、単一のTextコンポーネントをインフレートする単純なAPLドキュメントを示します。

{
  "type": "APL",
  "version": "1.0",
  "mainTemplate": {
    "item": {
      "type": "Text",
      "text": "ハローワールド"
    }
  }
}

インポート対象のパッケージ、リソースの定義、スタイルの定義、データソース、カスタムのレイアウトを含めることで、複雑なAPLドキュメントを作成できます。

{
  "type": "APL",
  "version": "1.0",
  "description": "これはBodyTemplate3の使用例です",
  "import": [
    {
      "name": "alexa-gui",
      "version": "1.0.3"
    }
  ],
  "resources": [
    {
      "colors": {
        "myBlue": "#0022f3"
      }
    }
  ],
  "styles": {
    "textBlockStyle": {
      "fontSize": 24,
      "color": "@myBlue"
    },
  },
  "layouts": {
    "myBody": {
      "parameters": ["block1", "block2"],
      "item": {
        "type": "Container",
        "direction": "column",
        "items": [
          {
            "type": "Text",
            "text": "${block1}",
            "style": "textBlockStyle"
          },
          {
            "type": "Text",
            "text": "${block2}",
            "style": "textBlockStyle"
          }
        ]
      }
    }
  },
  "mainTemplate": {
    "parameters": ["payload"],
    "item": {
      "type": "BodyTemplate3",       // alexa-gui定義済みです
      "title": "${payload.myTitle}",
      "scrollItem": {
        "type": "myBody",
        "block1": "${payload.myTextBlock1}",
        "block2": "${payload.myTextBlock2}"
      }
    }
  }
}

ドキュメントのプロパティ

最上位レベルのAPLドキュメントオブジェクトに含まれるプロパティは以下のとおりです。

プロパティ 必須 説明
description 文字列 このドキュメントの任意の説明です。
import インポートの配列 外部APLパッケージの参照リストです。
layouts レイアウトのマップ カスタマイズ可能な複雑なコンポーネントです。レイアウトを参照してください。
mainTemplate レイアウト ◯(上位レベルのドキュメント内) 最初のレイアウトです。
resources リソース リソースの定義です。リソースを参照してください。
styles スタイルのマップ スタイル定義のマップです。Stylesを参照してください。
type 文字列 「APL」に設定する必要があります。
version 文字列 APLの仕様のバージョンを表す文字列です。現在は「1.0」です。

mainTemplateプロパティは、最上位レベルのAPLドキュメントで必須です。このプロパティでは、画面に最初にインフレートおよび表示するレイアウトを定義します。mainTemplateプロパティは、最上位レベルのAPLドキュメントでのみ使用してください。インポート対象のパッケージでmainTemplateを使用しても、無視されます。

import

importプロパティでは、このドキュメントのテンプレートやリソースをインフレートするために必要な名前付きAPLパッケージの一覧を定義します。読み込むパッケージをパッケージ参照の一覧で指定します。この一覧の各エントリには、以下のプロパティを使用できます。

プロパティ 必須 説明
name 文字列 読み込むパッケージの名前です。
version 文字列 読み込むパッケージのバージョンです。
source URL パッケージのダウンロード元のURLを指定します。

以下は、内部alexa-guiパッケージと外部パッケージを使用する例です。


```json 
  "import": [
    {
      "name": "alexa-gui",
      "version": "1.0.3"
    },
    {
      "name": "my-own-package",
      "source": "https://www.example.com/my-custom-package.json"
    }	
  ]

APLパッケージはJSONファイルで、Amazon S3など、別のサイトでホスティングされる場合があります。HTTPSエンドポイントでホスティングされるすべてのAPL ResourcesでCross-Origin Resource Sharingがサポートされるようにしてください。

パッケージの読み込みにより、有向依存関係図が形成されます。リソース、スタイル、レイアウトの検索は、パッケージの読み込み順に従って深さ優先で行われます。たとえば、ドキュメントAがパッケージBとCに依存し、ドキュメントBとCがパッケージDに依存する場合、リソースの定義の検索順序はA、B、C、Dとなります。したがって、パッケージAは、B、C、Dで定義されたどのリソース、スタイル、レイアウトも上書きできます。依存関係のループが形成されないようにしてください。

パッケージは、2つのメカニズムのいずれかでダウンロードされます。sourceプロパティが指定されている場合、パッケージはその場所からダウンロードされます。sourceプロパティが指定されていない場合、パッケージは、パッケージ名とバージョンのプロパティを使用して、Alexaがサポートするパッケージの中央リポジトリから取得されます。パッケージは、デバイスランタイムソフトウェアによってキャッシュされます。2つのパッケージの名前とバージョンのプロパティが一致する場合、それらは同一であるとみなされます(特定の異なるsourceプロパティを持っている場合も同様です)。パッケージの有効期限(TTL)は、ダウンロード中に受け取ったTTLによって決まります。開発中のパッケージの場合は、ランタイムがパッケージを適切に再読み込みできるように、パッケージを変更するたびに固有のプレリリースタグやビルドタグを割り当てることをお勧めします。

layouts

layoutsプロパティでは、レイアウト定義に対してレイアウト名をマッピングします。APLレイアウトを参照してください。

mainTemplate

mainTemplateプロパティでは、定義済みのレイアウトを指定します。このレイアウトは、ドキュメントを初めて画面上にインスタンス化する場合にインフレートされます。

mainTemplateで定義したパラメーターは、ドキュメントをインフレートするディレクティブで指定したデータソースにバインドされます。

mainTemplateは、ドキュメントが最初に画面に表示されたときにインフレートされるレイアウトです。mainTemplateで定義したパラメーターは、APLドキュメントの表示を開始したRenderDocumentディレクティブで指定されたデータソースにバインドされます。RenderDocumentを参照してください。

resources

resourcesプロパティでは、リソースブロックの配列を指定します。

styles

stylesプロパティは、スタイル定義に対してスタイル名をマッピングするオブジェクトです。

APLドキュメントのインフレート

APLドキュメントは、次の手順に従って画面上のディスプレイにインフレートされます。

1.パッケージ処理キューにインポートパッケージの一覧を追加します。

2.処理キューのパッケージごとに次の処理が行われます。

  • 有向パッケージ依存関係グラフにこのパッケージを追加します。

  • パッケージが(a)デバイス上または(b)ディレクティブのpackagesプロパティ上で利用できるか確認します。パッケージがデバイス上にない場合は、importリストのsource値を使用して、指定されたURLからパッケージをダウンロードします。

  • パッケージのインポートリストをパッケージ処理キューに追加します。

3.viewportプロパティを使用して、最初のデータバインディングコンテキストを作成します。

4.デバイスのビルトインリソースを利用して、最初の名前付きリソースセットを作成します。

5.パッケージごとに、有向パッケージ依存関係グラフを深さ優先形式でトラバースします。

リソース配列内のリソースブロックごとに、次の処理が行われます。

現在のデータバインディングコンテキスト内にあるwhen句を評価します。when句の評価結果が偽の場合、そのブロックはスキップされます。when句の評価結果が真の場合は、次の処理が行われます。

  • ブール値マップ内の各ブール値を評価し、リソースに追加します。

  • 色マップ内の各色を評価し、リソースに追加します。

  • 数値マップ内の各数値を評価し、リソースに追加します。

  • 文字列マップ内の各文字列を評価し、リソースに追加します。

  • ディメンションマップ内の各ディメンションを評価し、リソースに追加します。

6.mainTemplate内のパラメーターごとに次の処理が行われます。

  • 名前が同じデータソースを特定します。

  • データバインディングコンテキストを更新して、データソースの値にこの名前を設定します。

7.標準のレイアウトインフレートロジックに従い、mainTemplateをインフレートします。