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ドキュメントには、次の最上位プロパティがあります。
| プロパティ | 型 | 必須 | 説明 |
|---|---|---|---|
|
|
✕ |
標準の背景色を上書きします。 | |
|
|
コマンドのマップ |
✕ |
コマンドの定義です。 |
|
|
文字列 |
✕ |
このドキュメントの任意の説明です。 |
|
|
環境値のマップ |
✕ |
ドキュメントをインフレートする前に適用するenvironmentのオーバーライドです。 |
|
|
書き出しのマップ |
✕ |
外部パッケージまたはドキュメントで使用することを意図した要素の任意のリストです。 |
|
|
extensionsの配列 |
✕ |
ドキュメントがリクエストするAPL Extensionsの任意のリストです。 |
|
|
✕ |
ベクターグラフィックスの定義です。 | |
|
|
✕ |
ユーザーがキーボードのキーを押したときに実行するキーボードイベントハンドラーです。 | |
|
|
✕ |
キーボードのキーが解放されたときに実行するキーボードイベントハンドラーです。 | |
|
|
Tickハンドラーの配列 |
✕ |
時間が経過すると呼び出されるティックハンドラーです。 |
|
|
インポートの配列 |
✕ |
外部APLパッケージの参照リストです。 |
|
|
レイアウトのマップ |
✕ |
カスタムレイアウトです。 |
|
|
APLレイアウト |
〇 |
最初のレイアウトです。 |
|
|
コマンド配列 |
✕ |
タブレットの向きが縦から横に変更されるなど、ドキュメントのコンフィギュレーションが変更されたときに実行するコマンドです。 |
|
|
コマンド配列 |
✕ |
表示状態が変化したときに実行するコマンドです。 |
|
|
コマンド配列 |
✕ |
このドキュメントが最初に表示されたときに実行するコマンドです。 |
|
|
✕ |
リソースの定義です。 | |
|
|
設定のマップ |
✕ |
ドキュメント全体の設定です。 |
|
|
スタイルの定義のマップ |
✕ |
スタイルの定義です。 |
|
|
文字列 |
✕ |
ドキュメント別のテーマです。 |
|
|
"APL" |
◯ |
「APL」に設定する必要があります。 |
|
|
"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プロパティでオーバーライド可能な設定をまとめています。
| プロパティ | 型 | 必須 | 説明 |
|---|---|---|---|
|
|
文字列 |
✕ |
ドキュメントレベルの言語をBCP-47形式で設定します。 |
|
|
|
✕ |
ドキュメントレベルのレイアウト方向を設定します。 |
|
|
パラメーター定義の配列 |
✕ |
データバインディングコンテキストに追加するオプションの名前付きパラメーターです。これを使って、 |
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プロパティを使います。
- リクエストされ、指定されるすべてのExtensionsの名前とURIは、環境プロパティとして提供されます。ドキュメント内でこのプロパティを使って、特定のExtensionが利用可能かどうかを決定します。
- Extensionの
nameは、Extensionイベントハンドラーを記述する際の名前として使用されます。これにより、ドキュメントはExtensionからイベントを受信し、それらのイベントに基づいて動作します。 - Extensionの
nameは、Extensionのコマンドを実行する名前空間として使用されます。これにより、ドキュメントはExtensionにコマンドを送信します。 - 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が呼び出されます。
viewport.heightviewport.widthviewport.themeviewport.modeenvironment.disallowVideoenvironment.fontScaleenvironment.screenModeenvironment.screenReader
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
ドキュメントの表示状態が変更されるたびに実行されるコマンドの配列です。ドキュメントの表示状態は、以下の表に記載された値のいずれかです。
| 名前 | 説明 |
|---|---|
|
|
ドキュメントは画面に表示されません。ドキュメントはティックイベントを生成せず、不規則な間隔でイベントを生成します。正しい動作をするドキュメントは、この状態に入るとすべてのアニメーションを停止します。 |
|
|
ドキュメントが画面上に表示されているか、大半がほかのコンテンツで隠されています。ドキュメントにシステムのメインのフォーカスがない状態です。ドキュメントはティックイベントを生成しますが、ドキュメントアニメーションは最小に制限されます。 |
|
|
ドキュメントは画面上および前面に表示されています。 |
非表示のドキュメントは最小限のシステムリソースを使用する必要があります。背景ドキュメントではアニメーションの使用を制限し、ユーザーのフォーカスが当たっていないと仮定します。
ハンドラーは、次の形式のイベントを生成します。
"event": {
"source": {
"type": "Document",
"handler": "DisplayStateChange",
"id": null, // 値は報告されません
"uid": null, // 値は報告されません
"value": null // 値は報告されません
},
"displayState": STRING // 新しい表示状態（"hidden"、"background"、"foreground"のいずれか）
}
表示状態の変更イベントは、ドキュメントが最初にインフレートされたときには実行されません。グローバルのデータバインディングプロパティであるdisplayStateを使って、ドキュメントインフレート時の表示状態を判断します。
表示状態の変更イベントハンドラーは高速モードで実行されます。
onMount
このドキュメントが画面上で最初に表示されたときに実行するコマンドです。コンポーネントのonMountコマンドが実行された後に、このコマンドが実行されます。
デバイスの画面上で最初にドキュメントが表示された際に、次の一連のアクションが行われます。
- すべてのコンポーネントの
onMountコマンドを並行して実行します。 - ドキュメントの
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プロパティは、ドキュメント全体のプロパティを定義するキーと値のペアのマップを保持します。次のプロパティが定義されています。
| プロパティ | 型 | 必須 | 説明 |
|---|---|---|---|
|
|
数値 |
<system> |
無操作状態が続いたためにドキュメントを閉じるまでの時間です。 |
|
|
ブール値 |
false |
trueの場合、システムが画面の |
以下の例では、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 日