APLドキュメント

Note: Sign in to the developer console to build or publish your skill.

APLドキュメント

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

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

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

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

リッチなAPLドキュメントには、インポートされるパッケージ、リソース定義、スタイル定義、ベクターグラフィックス、カスタムレイアウト、エクスポート情報、背景色が含まれていることがあります。

{
  "type": "APL",
  "version": "2024.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.7.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`	環境値のマップ	×	ドキュメントのインフレート前に環境に適用するオーバーライドです。
`export`	エクスポートのマップ	×	（任意）外部のパッケージまたはドキュメントで使用することを想定した要素のリストです。
`extensions`	Extensionの配列	×	（任意）ドキュメントでリクエストするAPL Extensionのリストです。
`graphics`	Alexa Vector Graphics（AVG）のマップ	×	ベクターグラフィックスの定義です。
`handleKeyDown`	キーボードイベントハンドラーの配列	×	ユーザーがキーボードのキーを押したときに実行するキーボードイベントハンドラーです。
`handleKeyUp`	キーボードイベントハンドラーの配列	×	キーボードのキーが解放されたときに実行するキーボードイベントハンドラーです。
`handleTick`	ティックハンドラーの配列	×	時間の経過に伴って呼び出されるティックハンドラーです。
`import`	インポートの配列	×	外部APLパッケージの参照のリストです。
`layouts`	レイアウトのマップ	×	カスタムのレイアウトです。
`mainTemplate`	レイアウト	◯	最初のレイアウトです。
`onConfigChange`	コマンドの配列	×	ドキュメントの設定が変更されたときに実行するコマンドです。たとえば、タブレットの向きが縦から横に変更されたときに呼び出されます。
`onDisplayStateChange`	コマンドの配列	×	表示状態が変更されたときに実行するコマンドです。
`onMount`	コマンドの配列	×	このドキュメントが最初に表示されたときに実行するコマンドです。
`resources`	リソース	×	リソースの定義です。
`settings`	設定のマップ	×	ドキュメント全体の設定です。
`styles`	スタイルの定義のマップ	×	スタイルの定義です。
`theme`	文字列	×	ドキュメント固有のテーマです。
`type`	"APL"	◯	「APL」に設定する必要があります。
`version`	"2024.1"	◯	APL仕様のバージョンを表す文字列です。現在は"2024.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": "2024.1",
    "environment": {
        "parameters": [
            "MyData"
        ],
        "lang": "${MyData.dataLanguage}",
        "layoutDirection": "${MyData.dataLayoutDirection}"
    },
    "mainTemplate": {
        "parameters": [
            "MyData"
        ],
        "items": {
            "type": "Container",
            "direction": "row",
            "width": "100%",
            "height": "100%",
            "data": [
                "言語：${environment.lang}",
                "レイアウト方向：${environment.layoutDirection}",
                "テキスト：${MyData.textPhrase}"
            ],
            "item": {
                "type": "Text",
                "height": "100%",
                "text": "${data}",
                "spacing": "10dp"
            }
        }
    }
}

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

この例では、environmentのlangプロパティとlayoutDirectionプロパティが「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": "2024.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つ目の左側に配置されます。

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

parameters

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

parametersを使用すると、environmentのプロパティをデータソースのデータにバインドできます。

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

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

{
    "type": "APL",
    "version": "2024.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プロパティにより、共有を想定している要素と、外部からの直接使用を想定していないパッケージの内部的な要素を特定することができます。検証およびオーサリングツールでは、export情報を使用して、APL作成者が適切な構造のドキュメントを作成できるように支援します。

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

プロパティ	型	デフォルト	説明
graphics	配列	[]	`graphics`の名前の配列です。
layouts	配列	[]	`layouts`の名前の配列です。
リソース	配列	[]	`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 Extensionのリストを指定します。ドキュメントとパッケージの両方でExtensionをリクエストできます。extensionsプロパティには、リクエストするExtensionを名前とURIで指定します。

次の例では、3つのExtensionをリクエストします。この例に示されているremotebuttonとfishfeederは架空のExtensionです。

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

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

プロパティ	型	デフォルト	説明
`name`	文字列	必須	Extensionのローカル名／名前空間です。
`uri`	文字列	必須	リクエストするExtensionのURIです。
`required`	ブール値	false	`true`の場合、Extensionを登録できなければドキュメントはレンダリングに失敗します。

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

リクエストして提供されたすべてのExtensionの名前とURIは、environmentのプロパティとして公開されます。特定のExtensionが利用可能かどうかを判断するには、ドキュメント内でこのプロパティを使用します。
Extensionのnameは、Extensionイベントハンドラーを記述するときの名前空間として使用されます。これにより、ドキュメントでExtensionからイベントを受け取り、それらのイベントに応じて処理を実行できます。
Extensionのnameは、Extensionのコマンドを実行する名前空間として使用されます。これにより、ドキュメントからExtensionにコマンドを送信できます。
Extensionのnameは、Extension固有のsettingsから設定を取得するために使用されます。これにより、Extensionは必要に応じて、読み込み時に自身の設定を行うことができます。

オプションのrequiredプロパティをtrueに設定すると、リクエストしたExtensionが存在し、Extensionの登録メッセージに応答しない限り、ドキュメントをレンダリングすることはできなくなります。

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

利用できるExtensionの一覧については、利用可能な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プロパティの詳細については、キーボードイベントのドキュメントを参照してください。

ドキュメントのkeyDownハンドラーは、ドキュメントのデータバインディングコンテキストで実行されます。

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

ドキュメントのkeyUpハンドラーは、ドキュメントのデータバインディングコンテキストで実行されます。

handleTick

時間の経過に伴って実行されるティックイベントハンドラーの配列です。

ティックイベントハンドラーに対して生成されるイベントの形式は次のとおりです。

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

ドキュメントのティックハンドラーは、ドキュメントのデータバインディングコンテキストで実行されます。

import

importプロパティは、名前付きAPLインポートのリストを定義します。インポートされたパッケージに定義されているリソース、スタイル、レイアウト、その他の項目を、このドキュメント内で使用できます。詳細については、パッケージのインポートリストを参照してください。

layouts

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

mainTemplate

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

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

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

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
}

sizeChangedプロパティは、widthまたはheightの値が変更されたときにtrueを返すブール値です。rotateプロパティは、デバイスの向きの縦と横が切り替えられた場合など、widthとheightの値が入れ替わったときにtrueを返すブール値です。

いずれかの設定が変更されたときにドキュメントを再インフレートするには、Reinflateコマンドを実行します。

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

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

{
  "type": "APL",
  "version": "2024.3",
  "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コマンドが実行された後に実行されます。

デバイスで最初に画面にドキュメントが表示されると、次の一連の処理が行われます。

すべてのコンポーネントの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      // 値は報告されません
  }
}

onMountイベントハンドラーは、ドキュメントのデータバインディングコンテキストで実行されます。

リソース

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

settings

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

プロパティ	型	必須	説明
`idleTimeout`	数値	<システム>	無操作状態が続いたためにドキュメントを閉じるまでの時間です。
`pseudoLocalization`	オブジェクト	`{}`	擬似ローカライゼーション関連の設定を指定します。
`supportsResizing`	ブール値	false	trueの場合、システムが画面の`width`と`height`に対する変更を検出すると、APLランタイムは`onConfigChange`ハンドラーを呼び出します。

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

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

settingsプロパティ内のプロパティには、データバインディングやAPLドキュメントからアクセスすることはできません。settingsプロパティは、APLドキュメントを表示するプロセスに設定情報を提供するものです。

idleTimeout

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

pseudoLocalization

pseudoLocalizationプロパティは、ドキュメントで「擬似ローカライゼーション」モードを有効にします。このモードを使用すると、さまざまな言語にローカライズしたときにUI要素がどのように表示されるかをテストできます。

pseudoLocalizationは、文字列を実際に翻訳した場合に必要となるスペースを模倣する擬似翻訳です。たとえば、「Hello World」という文字列の疑似ロケールバージョンは「[Ħḗḗŀŀǿǿ Ẇǿǿřŀḓ]」になります。結果の文字列はまだ判読可能ですが、元の文字列よりも多くのスペースと高さを占有します。これを使用して、テキストがほかの言語に翻訳されたときに発生する可能性のある、切り詰めやオーバーフローなどのUIレイアウトの問題を特定できます。

このpseudoLocalizationプロパティは、次の表に示すプロパティを持つオブジェクトです。

プロパティ	型	デフォルト	説明
`enabled`	ブール値	`false`	`true`の場合、ランタイムはドキュメント内のすべてのテキストに擬似ローカライゼーションを適用します。
`expansionPercentage`	数値	30	テキスト文字列を伸長するときに使用する長さのパーセンテージを指定します。0～100の値に設定します。

疑似ローカライゼーションを有効にすると、APLドキュメント内のすべてのテキストが疑似ロケールバージョンに変換されます。この変換には、発音区別符号・開始マーカー・終了マーカーの追加、母音の複製による文字列の伸長、パディングの使用が含まれます。

コンテンツを翻訳すると、テキストの長さが大きく変わる可能性があります。たとえば、英語からドイツ語に翻訳するとテキストは最大35%伸長します。ヘブライ語、ポーランド語、フィンランド語、ポルトガル語などのほかの言語でも、一般に25～40%の大幅な伸長が見られる可能性があります。デフォルトでは、疑似ローカライゼーションはテキストを30%伸長します。伸長率を調整するには、expansionPercentageプロパティを使用します。

次の例では、テキストを40%伸長します。

"settings": {
  "pseudoLocalization": {
      "enabled": true,
      "expansionPercentage": 40
   }
}

supportsResizing

ユーザーがタブレットを回転させて向きを変更した場合など、画面のwidthとheightに対する変更をシステムが検出したときに実行するアクションを決定します。次の動作を有効にするには、supportsResizingをtrueに設定します。

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

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

styles

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

theme

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

version

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

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

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

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

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

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

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

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

2. 処理キューのパッケージごとに、次の処理を行います。

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

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

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

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

resources配列内のリソースブロックごとに、次の処理を行います。

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

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

6. mainTemplate内のパラメーターごとに、次の処理を行います。

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

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

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

フィードバックを送信

最終更新日: 2025 年 11 月 04 日