APLドキュメント（1.2）

APLドキュメント

APLドキュメントとは、構造が明確に定義されたJSONオブジェクトのことです。ドキュメントは、画面のあるデバイスに表示するためのテンプレートを定義し、全体的な構造とレイアウトを制御します。Alexa.Presentation.APL.RenderDocumentディレクティブを使用して、ドキュメントをデバイスに送信します。

APLドキュメントのサンプル
ドキュメントのプロパティ
APLドキュメントのインフレート

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

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

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

複雑なAPLドキュメントには、取り込み対象のパッケージ、リソースの定義、スタイルの定義、ベクターグラフィックス、カスタムレイアウトが含まれています。

{
  "type": "APL",
  "version": "1.2",
  "import": [
    {
      "name": "sample-import",
      "source": "https://example.com/packages/fictitious-package-import-example"
    },
    {
      "name": "alexa-layouts",
      "version": "1.1.0"
    }
  ],
  "resources": [
    {
      "colors": {
        "CompanyBlue": "#0022f3"
      }
    }
  ],
  "styles": {
    "textBlockStyle": {
      "values": [
        {
          "fontSize": 24,
          "color": "@CompanyBlue"
        }
      ]
    }
  },
  "theme": "light",
  "graphics": {
    "AmazonPlayTrailer": {
      "type": "AVG",
      "version": "1.0",
      "parameters": [
        {
          "name": "fillColor",
          "type": "color",
          "default": "black"
        }
      ],
      "width": 48,
      "height": 48,
      "items": {
        "type": "path",
        "pathData": "M24,2C11.869,2,2,11.869,2,24s9.869,22,22,22s22-9.869,22-22S36.131,2,24,2z M24,44C12.972,44,4,35.028,4,24 C4,12.972,12.972,4,24,4s20,8.972,20,20C44,35.028,35.028,44,24,44z M19,34.799V13.201c0-1.004,1.041-1.563,1.829-0.937 l13.53,10.799c0.604,0.479,0.573,1.394-0.031,1.874L20.845,35.736C20.057,36.362,19,35.804,19,34.799z",
        "fillColor": "${fillColor}"
      }
    }
  },
  "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",
      "title": "${payload.myTitle}",
      "scrollItem": {
        "type": "myBody",
        "block1": "${payload.myTextBlock1}",
        "block2": "${payload.myTextBlock2}"
      }
    }
  }
}

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

APLドキュメントには、次の最上位プロパティがあります。

プロパティ	型	必須	説明
`commands`	コマンドのマップ	✕	コマンドの定義です。
`description`	文字列	✕	このドキュメントの任意の説明です。
`graphics`	AVGのマップ	✕	ベクターグラフィックスの定義です。
`handleKeyDown`	キーボードイベントハンドラーの配列	✕	キーボードのキーが押下されたときに実行されるキーボードイベントハンドラーのリストです。
`handleKeyUp`	キーボードイベントハンドラーの配列	✕	キーボードのキーが解放されたときに実行されるキーボードイベントハンドラーのリストです。
`import`	インポートの配列	✕	外部APLパッケージの参照リストです。
`layouts`	レイアウトのマップ	✕	カスタムレイアウトです。
`mainTemplate`	レイアウト	◯	最初のレイアウトです。
`onMount`	コマンドの配列	✕	このドキュメントが最初に表示されたときに実行するコマンドです。
`resources`	リソース	✕	リソースの定義
`settings`	設定のマップ	✕	ドキュメント全体の設定です。
`styles`	スタイルの定義のマップ	✕	スタイルの定義です。
`theme`	文字列	✕	ドキュメント別のテーマです。
`type`	"APL"	◯	「APL」に設定する必要があります。
`version`	"1.2"	◯	APLの仕様のバージョンを表す文字列です。最新バージョンは「1.2」です。

commands

commandsプロパティは、コマンド名とユーザー定義コマンドの定義をマッピングするオブジェクトです。

graphics

graphicsプロパティは、ドキュメント内から参照できる、名前付きのベクターグラフィックスのコレクションを定義します。ベクターグラフィックスの形式について詳しくは、Alexa Vector Graphics形式を参照してください。

handleKeyDown

キーボードのキーが押下されたとき、またはキーがオートリピートされたときに実行されるキーボードイベントハンドラーの配列です。keyDownイベントは、可能な場合には必ず生成されます。たとえば、Shiftキーが押下されるとkeyDownイベントが発生します。

生成されるイベントの形式は次のとおりです。

"event": {
  "source": {
   "type": "Document",
    "handler": "KeyDown",
    "id": null,        // 値は報告されません
    "uid": null,       // 値は報告されません
    "value": null      // 値は報告されません
  },
  "keyboard": {
    "altKey":   Boolean
    "code":     String,
    "ctrlKey":  Boolean,
    "key":      String,
    "metaKey":  Boolean,
    "repeat":   Boolean,
    "shiftKey": Boolean
  }
}

キーボードプロパティの詳細については、キーボードイベントのドキュメントを参照してください。

handleKeyUp

キーボードのキーが解放されたときに実行されるキーボードイベントハンドラーの配列です。keyUpイベントは、文字入力時だけでなく、可能な場合には必ず生成されます。たとえば、キーボードのShiftキーが解放されるとkeyUpイベントが生成されます。

生成されるイベントの形式は次のとおりです。

"event": {
  "source": {
   "type": "Document",
    "handler": "KeyUp",
    "id": null,        // 値は報告されません
    "uid": null,       // 値は報告されません
    "value": null      // 値は報告されません
  },
  "keyboard": {
    "altKey":   Boolean
    "code":     String,
    "ctrlKey":  Boolean,
    "key":      String,
    "metaKey":  Boolean,
    "repeat":   Boolean,
    "shiftKey": Boolean
  }
}

キーボードプロパティの詳細については、キーボードイベントのドキュメントを参照してください。

import

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

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

以下は、APL向けAlexaデザインシステムで提供されているalexa-layoutsパッケージと外部パッケージを使用した例です。

  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.1.0"
    },
    {
      "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プロパティは、ドキュメントが最初に画面に表示されたときにインフレートされるレイアウトです。ドキュメントを表示するには、AlexaにRenderDocumentディレクティブを送信します。

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

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

onMount

このドキュメントが画面上で最初に表示されたときに実行するコマンドです。コンポーネントのonMountコマンドが実行された後に、このコマンドが実行されます。

デバイスの画面上で最初にドキュメントが表示された際に、次の一連のアクションが行われます。

すべてのコンポーネントのonMountコマンドを並行して実行します。
ドキュメントのonMountコマンドを実行します。

効率よく実行するために、これらのコマンドは、次のメタコマンドにまとめられています。

{
  "type": "Sequential",
  "commands": [
    {
      "type": "Parallel",
      "commands": "<COMPONENT_ON_MOUNT_COMMANDS>"
    }
  ],
  "finally": "<DOCUMENT_ON_MOUNT_COMMAND>"
}

この構造体が設定されている理由は、コンポーネントのonMountコマンドが実行されている間に、ドキュメントに対してタッチイベントまたは外部コマンドが発行される可能性があるためです。コンポーネントのonMountコマンドが実行されている間にイベントが発生した場合、これらのコマンドは終了し、ドキュメントのonMountコマンドが高速モードで実行されます。ドキュメントのonMountコマンドの実行中にイベントが発生した場合、そのコマンドは終了します。

生成されるイベントの形式は次のとおりです。

"event": {
  "source": {
    "type": "Document",
    "handler": "Mount",
    "id": null,        // 値は報告されません
    "uid": null,       // 値は報告されません
    "value": null      // 値は報告されません
  }
}

resources

resourcesプロパティでは、リソースブロックの配列を指定します。Resourcesを参照してください。

settings

settingsプロパティは、ドキュメント全体のプロパティを定義するキーと値のペアのマップを保持します。次のプロパティが定義されています。

プロパティ	型	デフォルト	説明
idleTimeout	数値	<system>	無操作状態が続いたためにドキュメントを閉じるまでの時間です。

たとえば、デフォルトのアイドルタイムアウトを2分間に設定するには、次のように指定します。

{
  "type": "APL",
  "version": "1.2",
  "settings": {
    "idleTimeout": 120000
  }
}

settingsプロパティに格納されている情報には、データバインディングやAPLドキュメントではアクセスできません。これらは、APLドキュメントを表示するプロセスに構成情報を提供するだけです。

APLを使用するデバイスやランタイムでは、カスタムのデバイスまたはランタイム固有の設定を追加できます。グローバルなsettingsプロパティが新たに追加されても競合が発生しないように、カスタムのデバイスまたはランタイム固有のsettingsプロパティの名前は、先頭をハイフンまたは大文字にすることをお勧めします。たとえば、「-idleTimeoutWhenDark」や「IdleTimeoutWhenDark」のようにします。

idleTimeout

無操作状態が続いたためにドキュメントを閉じる前に、ドキュメントを画面に表示したままにする推奨時間（ミリ秒単位）です。この値は推奨値であり、動作を保証するものではありません。特定のデバイスでは、アイドルタイムアウト値が無視されたり、制限されたりすることがあります。

styles

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

theme

theme値が指定されている場合、この値によってデータバインディングコンテキストのviewport.themeプロパティが上書きされます。Viewportオブジェクトのthemeを参照してください。

version

versionプロパティは、APLドキュメントが使用するAPLのバージョンを指定します。必要な機能を特定して、正確にレンダリングするために、APLレンダリングエンジンによって使用されます。

ドキュメントのバージョン番号がサポートされていない場合、APLレンダリングエンジンはそのドキュメントのレンダリングを拒否します。一般に、レンダリングエンジンは下位互換性があると考えられています。つまり、「1.2」エンジンでは「1.0」ドキュメントもサポートすると見なされます。

APL仕様の現在のバージョンは「1.2」です。古いバージョン番号（「1.0」など）のドキュメントで、「1.1」以降の仕様の新しい機能（AnimateItemコマンドなど）を使用しようとした場合、レンダリング動作は保証されません。この場合、レンダリングエンジンは「1.0」の機能を提供する義務がありますが、それより新しいバージョンの機能は無視できます。

新しい機能を使いつつ古いバージョンのAPLを搭載したデバイスに対応するドキュメントを作成するには、environment.aplVersionプロパティを使用して、新しい機能を条件付きブロックでラップします。

{
  "when": "${environment.aplVersion == '1.2'}",
  "type": "VectorGraphic",
  "source": "sample-vector-graphic",
  "position": "absolute",
  "fillColor": "yellow",
  "top": "3vh",
  "left": "3vw"
}

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

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

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

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

有向パッケージ依存関係グラフにこのパッケージを追加します。
パッケージが（a）デバイス上または（b）ディレクティブのpackagesプロパティ上で利用できるか確認します。パッケージがデバイス上にない場合は、importリストのsource値を使用して、指定されたURLからパッケージをダウンロードします。
パッケージのインポートリストをパッケージ処理キューに追加します。

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

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

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

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

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

ブール値マップ内の各ブール値を評価し、リソースに追加します。
色マップ内の各色を評価し、リソースに追加します。
数値マップ内の各数値を評価し、リソースに追加します。
文字列マップ内の各文字列を評価し、リソースに追加します。
ディメンションマップ内の各ディメンションを評価し、リソースに追加します。

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

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

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