APLドキュメント

APLドキュメント

APLドキュメントは、画面付きのデバイスに表示するテンプレートを定義するJSONオブジェクトです。APLドキュメントは構造とレイアウトを制御します。Alexa.Presentation.APL.RenderDocumentディレクティブを使用して、ドキュメントをデバイスに送信します。

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

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

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

リッチなAPLドキュメントには、取り込み対象のパッケージ、リソースの定義、スタイルの定義、ベクターグラフィックス、カスタムレイアウト、書き出しに関する情報、背景色が含まれている場合があります。

{
  "type": "APL",
  "version": "2022.1",
  "description": "APLドキュメントのサンプル",
  "background": "#C87F70",
  "import": [
    {
      "name": "sample-import",
      "source": "https://example.com/packages/fictitious-package-import-example",
      "version": "1.0"
    },
    {
      "name": "alexa-layouts",
      "version": "1.5.0"
    }
  ],
  "export": {
    "resources": [
      "CompanyBlue"
    ],
    "layouts": [
      {
        "name": "myBody",
        "description": "上下に並べて表示される2つのテキストブロック"
      }
    ]
  },
  "resources": [
    {
      "colors": {
        "CompanyBlue": "#0022f3"
      }
    }
  ],
  "styles": {
    "textBlockStyle": {
      "values": [
        {
          "fontSize": 24,
          "color": "@CompanyBlue"
        }
      ]
    }
  },
  "theme": "light",
  "graphics": {
    "AmazonPlayTrailer": {
      "type": "AVG",
      "version": "1.2",
      "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": [
      "myDocumentData"
    ],
    "item": {
      "type": "BodyTemplate3",
      "title": "${payload.myTitle}",
      "scrollItem": {
        "type": "myBody",
        "block1": "${myDocumentData.myTextBlock1}",
        "block2": "${myDocumentData.myTextBlock2}"
      }
    }
  }
}

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

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

プロパティ 型 必須 説明

background

色またはグラデーション

✕

標準の背景色を上書きします。

commands

コマンドのマップ

✕

コマンドの定義です。

description

文字列

✕

このドキュメントの任意の説明です。

environment

環境値のマップ

✕

ドキュメントをインフレートする前に適用するenvironmentのオーバーライドです。

export

書き出しのマップ

✕

外部パッケージまたはドキュメントで使用することを意図した要素の任意のリストです。

extensions

extensionsの配列

✕

ドキュメントがリクエストするAPL Extensionsの任意のリストです。

graphics

Alexa Vector Graphics（AVG）のマップ

✕

ベクターグラフィックスの定義です。

handleKeyDown

キーボードイベントハンドラーの配列

✕

ユーザーがキーボードのキーを押したときに実行するキーボードイベントハンドラーです。

handleKeyUp

キーボードイベントハンドラーの配列

✕

キーボードのキーが解放されたときに実行するキーボードイベントハンドラーです。

handleTick

Tickハンドラーの配列

✕

時間が経過すると呼び出されるティックハンドラーです。

import

インポートの配列

✕

外部APLパッケージの参照リストです。

layouts

レイアウトのマップ

✕

カスタムレイアウトです。

mainTemplate

APLレイアウト

〇

最初のレイアウトです。

onConfigChange

コマンド配列

✕

タブレットの向きが縦から横に変更されるなど、ドキュメントのコンフィギュレーションが変更されたときに実行するコマンドです。

onDisplayStateChange

コマンド配列

✕

表示状態が変化したときに実行するコマンドです。

onMount

コマンド配列

✕

このドキュメントが最初に表示されたときに実行するコマンドです。

resources

resources

✕

リソースの定義です。

settings

設定のマップ

✕

ドキュメント全体の設定です。

styles

スタイルの定義のマップ

✕

スタイルの定義です。

theme

文字列

✕

ドキュメント別のテーマです。

type

"APL"

◯

「APL」に設定する必要があります。

version

"2022.1"

〇

APL仕様のバージョンを表す文字列です。現在は"2022.1"です。

background

backgroundプロパティは、APLドキュメントの読み込み時に背景色を初期化する任意のプロパティで、色またはグラデーションに設定できます。背景を一貫して色またはグラデーションに設定することで、Alexaが複数のドキュメント間で切り替わっても、シームレスなユーザーエクスペリエンスを提供できます。

デバイスは、パッケージとリソースを読み込む前にプロパティを解析して解釈するため、backgroundプロパティでリソースを参照することはできません。データバインディング式は、初期状態のデータバインディングコンテキストのプロパティに制限されています。以下に、有効な背景の仕様の例を示します。

"background": "darkgreen"
"background": "rgb(10,255,10)"
"background": {
  "type": "linear",
  "colorRange": [ "darkgreen", "white" ],
  "inputRange": [ 0, 0.25 ],
  "angle": 90
}
"background": "${viewport.theme == 'dark' ? 'darkgreen' : 'lightgreen'}"

backgroundプロパティを指定しないと、デバイスではデフォルトの背景色が表示されます。backgroundプロパティが部分的に透明である場合、デバイスのデフォルトの背景色が透けて表示されます。

commands

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

environment

システムのデフォルト環境設定をオーバーライドします。データバインディングコンテキストのenvironmentプロパティを使って環境データにアクセスできます。

システムのデフォルト環境設定はほとんど編集できません。以下の表に、ドキュメントレベルのenvironmentプロパティでオーバーライド可能な設定をまとめています。

プロパティ 型 必須 説明

lang

文字列

✕

ドキュメントレベルの言語をBCP-47形式で設定します。

layoutDirection

LTR | RTL

✕

ドキュメントレベルのレイアウト方向を設定します。

parameters

パラメーター定義の配列

✕

データバインディングコンテキストに追加するオプションの名前付きパラメーターです。これを使って、environmentのプロパティをデータソースにバインドします。

environmentの値は、リソースが評価され、ドキュメントがインフレートされる前に計算されます。値は、限定されたデータバインディングコンテキストで評価されます。

environmentのプロパティにデータソースの値を設定するには、parametersプロパティのデータソースの名前を渡します。ドキュメントはparametersの各データソースをenvironmentの評価に使用した限定されたデータバインディングコンテキストに追加します。

次の例は、environment.layoutDirectionとenvironment.langをデータソースの値にバインドする方法を示しています。この例のデータソースは、MyDataです。

{
    "type": "APL",
    "version": "2022.1",
    "environment": {
        "parameters": [
            "MyData"
        ],
        "lang": "${MyData.dataLanguage}",
        "layoutDirection": "${MyData.dataLayoutDirection}"
    },
    "mainTemplate": {
        "parameters": [
            "MyData"
        ],
        "items": {
            "type": "Container",
            "direction": "row",
            "width": "100%",
            "height": "100%",
            "data": [
                "Language: ${environment.lang}",
                "Layout Direction: ${environment.layoutDirection}",
                "Text: ${MyData.textPhrase}"
            ],
            "item": {
                "type": "Text",
                "height": "100%",
                "text": "${data}",
                "spacing": "10dp"
            }
        }
    }
}

{
    "MyData": {
        "dataLanguage": "ja-JP",
        "dataLayoutDirection": "RTL",
        "textPhrase": "表示するテキスト"
    }
}

この例では、langとlayoutDirectionのenvironmentプロパティが"ja-JP"と"RTL"に設定されています。RTLレイアウト方向では、Containerが3つのテキスト項目を右から左に調整し、コンテナの右側に揃えます。

ドキュメントのenvironmentプロパティで利用できる限定されたデータバインディングコンテキストには、以下のプロパティが含まれます。

限定されたデータバインディングコンテキストには、現在の時刻と表示状態が含まれません。

データバインディングコンテキストのenvironmentプロパティは、システムが提供したlangおよびlayoutDirectionのデフォルト値を返します。

lang

ドキュメント全体のシステムデフォルト言語設定をオーバーライドします。このプロパティにより、TextおよびEditTextのコンポーネントに選択されるデフォルトフォントが決まります。

environment.langに"en-US"などのBCP-47文字列を設定します。指定しない場合、environment.langはデフォルトの空白文字列に設定されます。このプロパティを設定して正しいフォントが選択されるようにすることをお勧めします。必要に応じて個々のTextコンポーネントやEditTextコンポーネントのこのプロパティをオーバーライドできます。コンポーネントレベルのlangプロパティの詳細は、以下を参照してください。

ドキュメントロジックで、データバインディングコンテキストのenvironment.langプロパティを使ってドキュメントレベルのlang値にアクセスできます。

以下の例は、言語を"ja-JP"に設定し、Textコンポーネントが日本語バージョンの"Noto Sans CJK"フォントを使うようにしています。

{
    "type": "APL",
    "version": "2022.1",
    "environment": {
        "lang": "ja-JP"
    },
    "mainTemplate": {
        "item": {
            "type": "Text",
            "fontFamily": "Noto Sans CJK",
            "text": "こんにちは"
        }
    }
}

デバイスによっては、すべての言語固有のフォントがない場合もあります。可能な限り、対象デバイスでエクスペリエンスを常にテストしてください。

layoutDirection

ドキュメント全体のシステムデフォルトlayoutDirection値をオーバーライドします。このプロパティにより、mainTemplate配列のコンポーネントを配置する方向が決まります。次のいずれかに設定します。

  • LTR – コンポーネントを左から右の方向に配置します。
  • RTL– コンポーネントを右から左の方向に配置します。

必要に応じて、個々のコンポーネントのドキュメントレベルのlayoutDirectionをオーバーライドできます。コンポーネントレベルのlayoutDirectionプロパティの詳細については、layoutDirectionを参照してください。

指定しない場合、ドキュメントのデフォルトのlayoutDirectionはLTRです。

ドキュメントロジックで、データバインディングコンテキストのenvironment.layoutDirectionプロパティを使ってドキュメントレベルのlayoutDirection値にアクセスできます。

以下の例では、2つのテキストボックスを描画します。1つ目は右端に、2つ目は1つ目の左側に配置されます。

{
    "type": "APL",
    "version": "2022.1",
    "environment": {
        "layoutDirection": "RTL"
    },
    "mainTemplate": {
        "item": {
            "type": "Container",
            "width": "100%",
            "direction": "row",
            "items": [
                {
                    "type": "Text",
                    "text": "右揃え"
                },
                {
                    "type": "Text",
                    "text": "右揃えの左側に表示",
                    "spacing": "50dp"
                }
            ]
        }
    }
}

layoutDirectionがコンポーネントにどう影響を及ぼすかについて詳しくは、layoutDirectionを参照してください。

parameters

APLドキュメントで指定された名前付きデータソースのオプション配列を含みます。これらの名前付きデータソースは、environmentプロパティの評価に使用した限定されたデータバインディングコンテキストにバインドされます。

parametersを使って、environmentプロパティをデータソースのデータにバインドします。

parametersの項目は、mainTemplateプロパティで使用されるパラメーターと一致するか、そのサブセットである必要があります。

たとえば、以下の例では、environment.parametersをMyDataというデータソースに正しく設定しています。

{
    "type": "APL",
    "version": "2022.1",
    "environment": {
        "parameters": [
            "MyData"
        ],
        "lang": "${MyData.dataLanguage}",
        "layoutDirection": "${MyData.dataLayoutDirection}"
    },
    "mainTemplate": {
        "parameters": [
            "MyData",
            "AnotherDataSource"
        ],
        "items": []
    }
}

export

exportプロパティは、ドキュメント内で定義されているresources、graphics、layouts、stylesを識別します。これらのプロパティは、このドキュメントをパッケージとして読み込むほかのスキルでも使用できるようになります。exportプロパティはさまざまな情報を提供します。APLレンダリングエンジンは、パッケージに定義されているresources、graphics、layouts、stylesへのアクセスを制限しません。

exportプロパティを使用すると、共有する要素と、パッケージ内部にあって直接使用することを意図していない要素を特定できます。検証およびオーサリングツールでは、APL作成者が適切に構造化されたドキュメントを作成できるように、export情報を使用する必要があります。

exportプロパティは、次のキーを持つマップです。

プロパティ 型 デフォルト 説明
graphics 配列 [] graphicsの名前の配列です。
layouts 配列 [] layoutsの名前の配列です。
resources 配列 [] resourcesの名前の配列です。
styles 配列 [] stylesの名前の配列です。

これらの配列の各値は、次のプロパティを持つオブジェクトです。

プロパティ 型 デフォルト 説明
name 文字列 必須 要素の名前です。
description 文字列 "" 書き出された要素の任意の説明です。

値には説明を含めず、エンティティの名前を含む単一の文字列に短縮できます。

この例では、graphics、layouts、resources、stylesを含むexportプロパティを示します。

{
  "export": {
    "resources": [
      {
        "name": "CompanyRed",
        "description": "会社のロゴをレンダリングするためにストックされた色"
      },
      {
        "name": "CompanyBlue",
        "description": "赤以外の色を設定したいユーザー向け"
      },
      {
        "name": "CompanyGreen" // 説明省略済み
      },
      "CompanyGray" // 説明を 省略 すると、 単一 の 文字列 に 簡略化 でき ます
    ],
    "layouts": [
      {
        "name": "MediaControl",
        "description": "再生ボタンと一時停止ボタン付きのメディアコントローラー。"
      }
    ],
    "graphics": [
      "PlayButton",
      "PauseButton"
    ],
    "styles": [
      "PlayButtonStyle",
      "PauseButtonStyle"
    ]
  }
}

exportに記載するプロパティは、現在のドキュメントで定義する必要があります。

extensions

extensionsプロパティは、リクエストするAPL Extensionsを一覧表示します。ドキュメントとパッケージの両方でextensionをリクエストできます。extensionsプロパティで、リクエストされたextensionを名前とURIで一覧表示します。

この例では、3つのextensionを要求しています。ここに表示されている"remotebutton"および"fishfeeder"は架空のものです。

{
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    },
    {
      "name": "Button",
      "uri": "aplext:remotebutton:13"
    },
    {
      "name": "Fish",
      "uri": "aplext:fishfeeder:10"
    }
  ]
}

リクエストされる各Extensionは、次のキーを持つマップです。

プロパティ 型 デフォルト 説明
name 文字列 必須 Extensionのローカル名／名前空間です。
uri 文字列 必須 リクエストするExtensionのURIです。

nameプロパティは、APLドキュメントでExtensionを識別する方法を定義します。ドキュメントは、次の3つの場所でnameプロパティを使います。

  1. リクエストされ、指定されるすべてのExtensionsの名前とURIは、環境プロパティとして提供されます。ドキュメント内でこのプロパティを使って、特定のExtensionが利用可能かどうかを決定します。
  2. Extensionのnameは、Extensionイベントハンドラーを記述する際の名前として使用されます。これにより、ドキュメントはExtensionからイベントを受信し、それらのイベントに基づいて動作します。
  3. Extensionのnameは、Extensionのコマンドを実行する名前空間として使用されます。これにより、ドキュメントはExtensionにコマンドを送信します。
  4. Extensionのnameは、Extension固有のsettingsを取得するために使用されます。これにより、Extensionは必要に応じてロード時に自身の設定を行います。

ExtensionsのしくみとExtensionの操作方法については、APL Extensionsを参照してください。

利用可能なextensionは次のとおりです。

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
  }
}

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

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
  }
}

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

handleTick

時間が経過すると実行されるTickイベントハンドラーの配列です。

ティックイベントハンドラーに対して生成されたイベントは、次のような形式になります。

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

import

importプロパティは、名前付きAPLパッケージのリストを定義します。このドキュメント内のインポートされたパッケージで定義されているリソース、スタイル、およびレイアウトを使用できます。リストの各エントリーが次のプロパティを持つオブジェクトである、パッケージ参照の配列を指定します。

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

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

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

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

パッケージは、2つの方法のいずれかでダウンロードされます。

  • sourceプロパティを指定すると、ドキュメントは指定されたソースURLからパッケージをダウンロードします。
  • sourceプロパティを指定していない場合、ドキュメントは、パッケージ名とバージョンのプロパティを使用して、Alexaがサポートするパッケージの中央リポジトリからパッケージを取得します。Amazonが提供するパッケージのセットについては、APL向けAlexa Design Systemを参照してください。

デバイスランタイムソフトウェアは、パッケージをキャッシュします。デバイスは、2つのパッケージの名前とバージョンのプロパティが一致する場合、それらを同一であるとみなします（特定の異なるsourceプロパティを持っている場合も同様です）。パッケージの有効期限（TTL）は、ダウンロード中に受け取ったTTLによって決まります。

パッケージの開発やテストを行う際、パッケージを変更するたびに固有のプレリリースタグやビルドタグを割り当ててください。これにより、ランタイムはテスト中にキャッシュしたバージョンのパッケージを使うのではなく、新しいバージョンをリロードします。

Amazon S3などのサイトで独自のAPLパッケージをホストする場合、HTTPSエンドポイントでホストするすべてのAPLリソースに対してCross-Origin Resource Sharingが有効になっていることを確認してください。

name

パッケージ名は、[a-zA-Z][a-zA-Z0-9-]*の形式にします。

source

sourceプロパティが指定されている場合、パッケージのダウンロード元のURL場所を指定します。指定されていない場合、パッケージはAlexaがサポートする中央リポジトリから取得されます。Amazonが提供するパッケージのセットについては、APL向けAlexa Design Systemを参照してください。

パッケージソースURLには、httpではなくhttpsを使います。セキュリティ上の理由から、スキルのAPLドキュメントでhttp方式をサポートしているAlexaデバイスは多くありません。

version

パッケージのバージョンは、文法で指定されたセマンティックバージョニング規則に従う必要があります。

vers         ::= <<release>> <<prerelease>>? <<build>>?
release      ::= <<number>> "." <<number>> "." <<number>>
prerelease   ::= "-" <<identifier>> ( "." <<identifier>> )*
build        ::= "+" <<identifier>> ( "." <<identifier>> )*
identifier   ::= [a-zA-Z0-9-]+
number       ::= [0-9] | [1-9][0-9]+

有効なパッケージバージョンの例： 10.2.1、0.1.10-beta.3、0.9.7-alpha2.17+build.1002。

layouts

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

mainTemplate

mainTemplateプロパティは、ドキュメントが最初に画面に表示されたときにインフレートされるレイアウトです。ドキュメントを表示するには、AlexaにRenderDocumentディレクティブを送信します。

parameters配列は、ドキュメントをインフレートするRenderDocumentディレクティブで指定したデータソースにバインドするプロパティを定義します。

itemまたはitems配列は、表示するコンポーネントまたはレイアウトを定義します。mainTemplateは、1つの子のインフレーションアルゴリズムを使用して、表示する項目を選択します。そのため、配列に複数のコンポーネントが含まれている場合、ドキュメントは、whenがtrueに評価される最初のコンポーネントをインフレートします。複数のコンポーネントを表示するには、マルチ子コンポーネントにグループ化します。

onConfigChange

ドキュメントのコンフィギュレーションが変更されたときに実行するコマンドです。次のいずれかのプロパティが変更されると、onConfigChangeが呼び出されます。

onConfigChangeハンドラーに対して生成されたイベントは、次のような形式になります。

"event": {
  "source": {
    "type": "Document",
    "handler": "ConfigChange",
    "id": null,        // 値は報告されません
    "uid": null,       // 値は報告されません
    "value": null      // 値は報告されません
  },
  // Viewportプロパティ
  "height": INTEGER,         // 更新後のビューの高さ（DP）
  "width": INTEGER,          // 更新後のビューの幅（DP）
  "theme": STRING,           // 更新後のビューのテーマ
  "viewportMode": STRING,    // 更新後のviewportモード（"auto"、"hub"、"mobile"など）

  // コンフィギュレーションプロパティ
  "fontScale": NUMBER,       // 更新後のフォント拡大・縮小係数
  "screenMode": STRING,      // 更新後の画面モード（"normal"、"high-contrast"）
  "screenReader": BOOLEAN,   // スクリーンリーダーがオンの場合はTrue

  // 合成のプロパティ
  "sizeChanged": BOOLEAN,    // 幅や高さの値が変更された場合はTrue
  "rotated": BOOLEAN,        // 幅や高さの値が入れ替わった場合はTrue
}

イベントでは、7個の更新されたプロパティと2個の合成されたプロパティを利用できます。sizeChangedプロパティは、widthかheightの値が変更された場合にtrueとなるブール値です。rotateプロパティは、デバイスの向きの縦と横が切り替えられるなど、widthとheightの値が入れ替わった場合にtrueとなるブール値です。

コンフィギュレーションが変更された場合にドキュメントを再インフレートするには、Reinflateコマンドを実行します。

{
  "type": "APL",
  "version": "2022.1",
  "onConfigChange": {
    "type": "Reinflate"
  }
}

画面サイズが一定量変更された場合にドキュメントを再インフレートするには、コマンドにwhen文を追加し、イベントのプロパティを使って新しいサイズを決定します。以下の例では、画面サイズが25%以上変更された場合にドキュメントを再インフレートしています。

{
  "type": "APL",
  "version": "2022.1",
  "onConfigChange": {
    "type": "Reinflate",
    "when": "${Math.abs(viewport.width - event.width) > 0.25 * viewport.width || Math.abs(viewport.height - event.height > 0.25 * viewport.height)}"
  }
}

コンフィギュレーションが変更されたときにReinflateを実行するかどうかを選択できます。データバインディングコンテキストのviewportとenvironmentのプロパティは、ドキュメントのインフレート時に設定される定数値です。コンフィギュレーション変更時にドキュメントを再インフレートしない場合、これらのenvironmentとviewportのプロパティ値に実際のデバイスコンフィギュレーションが反映されません。

Reinflateを実行しないが、最新の環境プロパティを参照したい場合は、イベントから値を抽出し、バインドされた変数に格納します。

サイズ変更と再インフレートのオプションについて詳しくは、サイズ変更が可能なタブレットなどのデバイスをサポートするを参照してください。

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

onDisplayStateChange

ドキュメントの表示状態が変更されるたびに実行されるコマンドの配列です。ドキュメントの表示状態は、以下の表に記載された値のいずれかです。

名前 説明

hidden

ドキュメントは画面に表示されません。ドキュメントはティックイベントを生成せず、不規則な間隔でイベントを生成します。正しい動作をするドキュメントは、この状態に入るとすべてのアニメーションを停止します。

background

ドキュメントが画面上に表示されているか、大半がほかのコンテンツで隠されています。ドキュメントにシステムのメインのフォーカスがない状態です。ドキュメントはティックイベントを生成しますが、ドキュメントアニメーションは最小に制限されます。

foreground

ドキュメントは画面上および前面に表示されています。

非表示のドキュメントは最小限のシステムリソースを使用する必要があります。背景ドキュメントではアニメーションの使用を制限し、ユーザーのフォーカスが当たっていないと仮定します。

ハンドラーは、次の形式のイベントを生成します。

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

  "displayState": STRING     // 新しい表示状態（"hidden"、"background"、"foreground"のいずれか）
}

表示状態の変更イベントは、ドキュメントが最初にインフレートされたときには実行されません。グローバルのデータバインディングプロパティであるdisplayStateを使って、ドキュメントインフレート時の表示状態を判断します。

表示状態の変更イベントハンドラーは高速モードで実行されます。

onMount

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

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

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

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

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

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

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

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

resources

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

settings

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

プロパティ 型 必須 説明

idleTimeout

数値

<system>

無操作状態が続いたためにドキュメントを閉じるまでの時間です。

supportsResizing

ブール値

false

trueの場合、システムが画面のwidthとheightに対する変更を検出すると、APLランタイムはonConfigChangeハンドラーを呼び出します。

以下の例では、2分のデフォルトアイドルタイムアウトを設定しています。

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

settings内のプロパティには、データバインディングやAPLドキュメントではアクセスできません。settings内のプロパティは、APLドキュメントを表示するプロセスにコンフィギュレーション情報を提供します。

idleTimeout

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

supportsResizing

システムが、ユーザーがタブレットを回転させて向きを変更したなど、画面のwidthとheightに対する変更を検出したときに実行するアクションを判断します。supportsResizingをtrueに設定して以下の手順を行います。

  • 自動サイズ変更を有効にします。APLランタイムは、新しい画面サイズに合わせてレイアウトのサイズを変更します。
  • onConfigChangeハンドラーでコマンドを実行します。自動サイズ変更を使用する場合、このハンドラーを使ってコマンドを実行できます。このハンドラーを使って、Reinflateコマンドを実行することもできます。

サイズ変更と再インフレートのオプションについて詳しくは、サイズ変更が可能なタブレットなどのデバイスをサポートするを参照してください。

styles

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

theme

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

version

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

APLレンダリングエンジンがドキュメントのバージョンをサポートしていない場合、ドキュメントのレンダリングが拒否されます。レンダリングエンジンには下位互換性が必要です。「2022.1」のエンジンは、「1.9」以前のドキュメントもサポートします。

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

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

{
  "when": "${environment.aplVersion == '2022.1'}",
  "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をインフレートします。

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

最終更新日: 2022 年 08 月 12 日