APLドキュメント（キャラクターディスプレイ）



ドキュメント（キャラクターディスプレイ）

APL-Tドキュメントは、構造が明確に定義されたJSONオブジェクトです。キャラクターディスプレイ付きデバイス（Echo Dot with clockなど）に表示するためのテンプレートを定義し、全体的な構造とレイアウトを制御します。ドキュメントをデバイスに送信するには、Alexa.Presentation.APLT.RenderDocumentディレクティブを使用します。

例

単純なAPL-Tドキュメントでは、1つのコンポーネントのみをインフレートできます。画面の左上隅に描画されます。

{
  "type": "APLT",
  "version": "1.0",
  "mainTemplate": {
    "items": [
      {
        "type": "Text",
        "text": "HI."
      }
    ]
  }
}

内容の多いAPL-Tドキュメントでは、複数のコンポーネントを入れ子にできます。

{
  "type": "APLT",
  "version": "1.0",
  "description": "これは少し複雑な例です",
  "layouts": {},
  "resources": [],
  "mainTemplate": {
    "items": [
      {
        "id": "myPager",
        "type": "Pager",
        "items": [
          {
            "type": "Text",
            "text": "P9: 1"
          },
          {
            "type": "Text",
            "text": "P9: 2"
          }
        ]
      }
    ]
  },
  "onMount": {
    "type": "AutoPage",
    "componentId": "myPager",
    "delay": 500,
    "count": 2,
    "duration": 500
  },
  "settings": {
    "idleTimeout": 10000
  }
}

構造

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

プロパティ 型 必須 説明
description 文字列 ✕ このドキュメントの任意の説明です。
layouts マップ ✕ カスタムレイアウトです（レイアウト）。
mainTemplate コンポーネントの配列 ◯ 最初のレイアウトです。
onMount コマンド配列 ✕ このドキュメントが最初に表示されたときに実行するコマンドです。
resources リソースの配列 ✕ リソースの定義です（リソース）。
settings マップ ✕ ドキュメント全体の設定です。
type "APLT" ◯ 「APLT」に設定する必要があります。
version "1.0" ◯ APL-T仕様のバージョンを表す文字列です。現在は「1.0」です。

mainTemplate

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

onMount

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

ドキュメントが画面に初めて表示される際に、次の一連のアクションが行われます。

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

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

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

settings

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

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

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

{
  "type": "APLT",
  "version": "1.0",
  "settings": {
    "idleTimeout": 120000
  }
}

idleTimeout

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

version

versionプロパティは、APL-Tドキュメントが使用するAPL-T仕様のバージョンを指定します。必要な機能を特定して正確にレンダリングするために、APL-Tレンダリングエンジンによって使用されます。APL-Tドキュメントの作成者は、versionプロパティを責任を持って正しく設定してください。

ドキュメントのバージョン番号がサポート対象外の場合、APL-Tレンダリングエンジンはそのドキュメントのレンダリングを拒否します。APL-Tレンダリングエンジンは、下位互換性を持つ予定です。具体的には、「1.1」をサポートするエンジンは、「1.0」ドキュメントもサポートする予定です。