APLバインド変数

APLバインド変数

Alexa Presentation Language（APL）のコンポーネント、レイアウト、Alexa Vector Graphics（AVG）はすべて、バインド変数をサポートしています。バインド変数とは、ドキュメントがコンポーネントとその子のデータバインディングコンテキストからアクセスできるローカル変数です。レイアウトでは、バインド変数はレイアウトのインフレート先のコンポーネントにアタッチされます。

コンポーネント、レイアウト、ベクターグラフィックのバインド変数を定義するには、bindプロパティを使用します。bindプロパティには、データバインディングコンテキストを展開するバインディングオブジェクトの順序付き配列を指定できます。

bindプロパティの評価

bindプロパティの評価は、コンポーネント、レイアウト、AVGで、whenプロパティの後、その他のプロパティの前に行われます。バインディングは配列順にデータバインディングコンテキストに追加されます。以下の例に示すように、後続のバインディングでは、その定義内の前のバインディングを使用できます。

{
  "type": "Text",
  "bind": [
    { "name": "FirstName", "value": "ジャスミン" },
    { "name": "LastName", "value": "スミス"},
    { "name": "Title", "value": "博士"},
    { "name": "FormalName", "value": "${LastName}${Title}" }
  ],
  "text": "${FirstName}さんと${FormalName}のどちらでお呼びしますか？"
}

この例では、FormalNameの内容は、それより前に定義されたTitleとLastNameの値によって決まります。最終的なテキストは、「ジャスミンさんとスミス博士のどちらでお呼びしますか？」となります。 この例は意図的に作り込まれたものです。実際には、FirstName、LastName、Titleの値は生データ内の要素にバインドするのが一般的です。

SetValueコマンドを使用すると、バインド値を動的に変更できます。

bindのオブジェクトのプロパティ

bind配列の各オブジェクトには、次のプロパティを使用できます。

プロパティ 型 デフォルト 説明

name

文字列

必須

このバインディングで使用する名前です。有効な名前を設定する必要があります。この名前は、データバインディング式で変数を参照するときに使用します。

value

任意

必須

このバインディングに割り当てる値です。valueが文字列の場合、データバインディングの評価は文字列の内容に対して行われます。

type

型

any

バインディングに格納する値の型です。
有効な値：any、boolean、string、number、dimention、color

onChange

コマンドの配列

[]

このバインディングの値が変更された場合に実行するコマンドです。AVGのbindプロパティでは使用できません。使用するには、APL 2024.1以降に更新する必要があります。

name

このバインディングで使用する名前です。名前は有効なデータバインディング識別子である必要があります。

type

このバインディングのデータ型です。デフォルトの型は「any」です。この場合、valueには任意の値を設定できます。型を指定すると、バインディングがその型に強制されます。

以下の例では、変数がbooleanで、23.4が0以外の数値であるため、Testの値はtrueになります。

{
  "name": "Test",
  "value": 23.4,
  "type": "boolean"
}

データバインディングで値をさまざまな型に強制する方法の詳細については、truthyと強制を参照してください。

value

バインディングに割り当てる値です。この値は、必要に応じて指定されたtypeに強制変換されます。この割り当ては、バインディングが最初に作成されたとき、およびバインディング内で使用される変数が変更されるたびに評価されます。

以下の例では、COUNTとSTRINGという2つのバインド変数を定義しています。

{
  "bind": [
    {
      "name": "COUNT",
      "value": 1
    },
    {
      "name": "STRING",
      "value": "カウントは${COUNT}です"
    }
  ]
}

SetValueコマンドなどでバインド値COUNTが変更されるたびに、バインド値STRINGも更新されます。

onChange

使用するには、APL 2024.1以降に更新する必要があります。

onChangeイベントハンドラーは、コンポーネントまたはレイアウトで、バインドされた値が変更されたときに実行されます。onChangeイベントハンドラーはAVG項目では使用できません。

onChangeハンドラーは高速モードで実行されます。生成されるイベントの形式は次のようになります。

{
  "event": {
    "source": {
      "type": "COMPONENT_TYPE",     // コンポーネントまたはAVG項目の型（Pager、TouchWrapperなど）
      "handler": "Change"
    },
    "current": "VALUE",             // バインディングの現在の値
    "previous": "VALUE"             // バインディングの前の値
  }
}

onChangeイベントハンドラーの一般的な用途は、Extensionによって提供されるライブデータの変更に対応することです。たとえば、FishFeederというExtensionでTankTemperatureという名前のライブデータオブジェクトが提供される場合、onChangeハンドラーを使用して水槽の最低温度と最高温度を追跡できます。

{
  "type": "Text",
  "bind": [
    {
      "name": "MIN_TEMP",
      "value": null
    },
    {
      "name": "MAX_TEMP",
      "value": null
    },
    {
      "name": "TEMP",
      "value": "${TankTemperature}",
      "onChange": [
        {
          "type": "SetValue",
          "property": "MIN_TEMP",
          "value": "${MIN_TEMP == null || TEMP < MIN_TEMP ? TEMP : MIN_TEMP}"
        },
        {
          "type": "SetValue",
          "property": "MAX_TEMP",
          "value": "${MAX_TEMP == null || TEMP > MAX_TEMP ? TEMP : MAX_TEMP}"
        }
      ]
    }
  ],
  "text": "現在の温度=${TEMP} 最低温度=${MIN_TEMP} 最高温度=${MAX_TEMP}"
}

Extensionのライブデータの詳細については、Extensionのライブデータを参照してください。

onChangeイベントハンドラーは再入可能ではありません。onChangeハンドラー内のコマンドによって、onChangeハンドラーをトリガーしたバインディングの値が変更されても、onChangeハンドラーが再度呼び出されることはありません。

以下は、バインド変数COUNTERを使用したTouchWrapperコンポーネントの例です。

{
  "type": "TouchWrapper",
  "bind": [
    {
      "name": "COUNTER",
      "value": 0,
      "onChange": {
        "type": "SetValue",
        "property": "COUNTER",
        "value": "${COUNTER+1}"
      }
    ]
  },
  "onPress": {
    "type": "SetValue",
    "property": "COUNTER",
    "value": 1
  }
}

TouchWrapperをタップするとCOUNTERが1に設定され、onChangeイベントハンドラーがトリガーされて、COUNTERが2に設定されます。この時点で、onChangeイベントハンドラーの内部から自身をトリガーすることはできないため、コマンドは停止します。

バインド変数の例

以下は、カウントを増減するボタンが付いたカウンターの例です。COUNTERというバインド変数でカウンターの現在の値を保持し、値が変わるたびにonChangeを使用してTextコンポーネントを更新します。onChangeハンドラーでは、カウンターの値が正、負、ゼロのいずれであるかに基づいてカウンターの色を変更するコマンドも実行します。

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

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