APLのユーザー定義コマンド

APLのユーザー定義コマンド

Alexa Presentation Language（APL）ドキュメントまたはパッケージでは、カスタムコマンドを定義できます。

ユーザー定義コマンドの概要

APLドキュメントには、一連のコマンドを定義するcommandsプロパティがあります。ユーザー定義コマンドでは、ほかのAPL標準コマンドを呼び出すことができます。

次の例では、AnimateItemコマンドを呼び出すslideInFromRightというコマンドを作成します。

{
  "commands": {
    "slideInFromRight": {
      "parameters": [
        "distance",
        {
          "name": "duration",
          "type": "number",
          "default": 300
        }
      ],
      "command": {
        "type": "AnimateItem",
        "easing": "ease-in-out",
        "duration": "${duration}",
        "value": [
          {
            "property": "opacity",
            "from": 0,
            "to": 1
          },
          {
            "property": "transform",
            "from": {
              "translateX": "${distance}"
            },
            "to": {
              "translateX": 0
            }
          }
        ]
      }
    }
  }
}

パラメーター化されたコマンドを使用するには、次のようにコマンド名を型として渡します。

{
  "type": "TouchWrapper"
  "onPress": {
    "type": "slideInFromRight",
    "duration": 1000,
    "distance": "20vw"
  }
}

この例では、translateXプロパティアニメーションでdistanceパラメーターが20vwにバインドされます。コマンドの再生時間は1000ミリ秒になります。これは、durationパラメーターに渡された値の1000が、コマンドに定義されているデフォルト値の300をオーバーライドするためです。

このコマンドにはdurationのデフォルト値が定義されているため、durationパラメーターを指定せずにコマンドを呼び出すこともできます。その場合は、300ミリ秒のアニメーションが代わりに表示されます。一方、distanceパラメーターにはデフォルト値がありません。distanceを指定せずにコマンドを呼び出すと、アニメーションのtransform.translateXプロパティはデフォルトで0になるため、0から0へ「スライド」アニメーションとなり、コンポーネントは移動しません。

コマンドの定義

ドキュメント内のcommandプロパティでは、コマンド名をコマンドの定義にマッピングします。コマンドの定義には、次のプロパティが含まれます。

プロパティ 型 必須 説明
parameters パラメーター定義の配列 × （任意）データバインディングコンテキストに追加する名前付きのパラメーターです。
command、commands コマンドの配列 ◯ 実行するコマンドの配列です。
description 文字列 × このコマンドの説明です。

commands

commandsプロパティは、実行するコマンドの暗黙的な順次ブロックです。コマンドの配列では、単一のコマンドからコマンドの配列への自動変換や、パラメーターから配列への置換など、配列を使ったデータバインディングの標準的なルールがサポートされます。

parameters

parametersは、引数として渡すことができる名前付きの値です。各パラメーターは、以下のプロパティを持つオブジェクトです。

プロパティ 型 必須 説明
default 任意 × このパラメーターが指定されない場合に適用するデフォルト値です。デフォルトは空です。
description 文字列 × ユーザー提供のこのパラメーターの説明です。
name 文字列 ◯ パラメーターの名前です。
type any、array、boolean、color、dimension、integer、map、number、object、string × パラメーターの型です。デフォルトはanyです。

パラメーター名は、大文字または小文字の英字で始まり、スペースを含まない一意の名前（[a-zA-Z][a-zA-Z0-9]*）にする必要があります。

手間を省くため、パラメーターオブジェクトの代わりにパラメーター名を使用できます（{ "name": "title", ... }の代わりに"title"など）。これは推奨されませんが、型の強制やデフォルト値が不要な場合に、コマンド定義を簡潔にすることができます。

コマンドのインフレート

コマンドは、次のアルゴリズムに従ってインフレートされます。

  • parametersの各項目が評価され、データバインディングコンテキストに追加されます。
  • command配列が評価されます。
  • オブジェクトに割り当てられているプロパティのうち、名前付きパラメーターと一致しないものは、プロパティとして各コマンドに渡されます。

たとえば、次のcustomPressHandlerの定義を見てみましょう。

    "commands": {
      "customPressHandler": {
        "description": "チェックされた状態の場合、現在のコンポーネントを非表示にしてイベントを発生させます。"
        "parameters": [
          "onChecked",
          {
            "type": "number",
            "name": "opacity",
            "default": 0.5
          }
        ],
        "commands": [
          {
            "type": "SetValue",
            "property": "opacity",
            "value": "${opacity}"
          },
          {
            "type": "Sequential",
            "when": "${event.target.checked}",
            "commands": [
              "${onChecked}"
            ]
          }
        ]
      }
    }

このカスタムコマンドが次のように呼び出されたとします。

{
  "onPress": {
    "type": "customPressHandler",
    "onChecked": {
      "type": "SendEvent",
      "arguments": ["チェックされました"]
    },
    "delay": 500
  }
}

onPressハンドラーが呼び出されたとき、インフレートされたコマンドは次のようになります。

[
  {
    "type": "SetValue",
    "property": "opacity",
    "value": 0.5,
    "delay": 500
  },
  {
    "type": "Sequential",
    "when": "${event.target.checked}",
    "delay": 500,
    "commands": [
      {
        "type": "SendEvent",
        "arguments": ["チェックされました"]
      }
    ]
  }
]

次の点に注意してください。

  • 元の呼び出しでは、delayの値として500が渡されています。customPressHandlerの定義にはパラメーターとしてdelayが含まれていないため、delayの値はカスタムコマンドの各コマンドに渡されます。
  • 元の呼び出しではopacity値は渡されていませんが、customPressHandlerにはパラメーターとしてopacityが定義されています。そのため、データバインディングコンテキストはopacityのデフォルト値（この例では0.5）で拡張されます。この値は、SetValueコマンドの${opacity}の展開に使用されます。

入れ子になったユーザーコマンドの展開

他のユーザーコマンドを参照するユーザーコマンドを定義できます。次に例を示します。

{
  "SoftStagger": {
    "description": "オブジェクトを左または右からスライド表示するソフトスタッガーです",
    "parameters": [
      "delay",
      "duration",
      "distance"
    ],
    "commands": [
      {
        "type": "SetValue",
        "property": "opacity",
        "value": 0
      },
      {
        "type": "AnimateItem",
        "values": [
          {
            "property": "opacity",
            "to": 1
          },
          {
            "property": "translateX",
            "from": "${distance}",
            "to": 0
          }
        ],
        "delay": "${delay}",
        "duration": "${duration}",
        "easing": "ease-out"
      }
    ]
  }
}

SoftStaggerコマンドをそのまま使用して、delay、duration、distanceのパラメーターを渡すことができます。利便性のために、SoftStaggerを使用して標準的なバリエーションを定義することもできます。

{
  "SoftStagger1": {
    "commands": {
      "type": "SoftStagger",
      "delay": 0,
      "duration": 666,
      "distance": 40
    }
  },
  "SoftStagger2": {
    "commands": {
      "type": "SoftStagger",
      "delay": 50,
      "duration": 666,
      "distance": 40
    }
  }
}

次に、onMount:{"type": "SoftStagger2"}のような行を使用して、コンポーネントにソフトスタッガーによる開始アニメーションを追加できます。

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

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