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

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

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

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

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

たとえば、以下の例ではAnimateItemコマンドを呼び出すslideInFromRightというコマンドを作成しています。

{
  "commands": {
    "slideInFromRight": {
      "parameters": [
        "distance"
      ],
      "command": {
        "type": "AnimateItem",
        "easing": "ease-in-out",
        "duration": 300,
        "values": [
          {
            "property": "opacity",
            "from": 0,
            "to": 1
          },
          {
            "property": "transformX",
            "from": "${distance}",
            "to": 0
          }
        ]
      }
    }
  }
}

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

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

上記の例では、distanceパラメーターがtranslateXプロパティアニメーションの20vwにバインドされます。コマンドの時間は500ミリ秒になります（時間として渡された値「500」は、内部の300ミリ秒のdurationを上書きします）。

コマンドの定義

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

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

commands

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

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"など）。推奨はできませんが、型の強制やデフォルト値が不要な場合に、コマンド定義を簡潔にすることができます。

コマンドのインフレート

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

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

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

    "commands": {
      "customPressHandler": {
        "description": "checkedの場合に現在のコンポーネントを非表示にして、イベントを起動します。"
        "parameters": [
          "onChecked",
          {
            "type": "number",
            "name": "opacity",
            "default": 0.5
          }
        ],
        "commands": [
          {
            "type": "SetValue",
            "property": "opacity",
            "value": "${opacity}"
          },
          {
            "type": "Sequential",
            "when": "${event.target.value}",
            "commands": [
              "${onChecked}"
            ]
          }
        ]
      }
    }

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

{
  "onPress": {
    "type": "customPressHandler",
    "onChecked": {
      "type": "SendEvent",
      "arguments": [
        "checkedに設定されました。"
      ]
    },
    "delay": 500
  }
}

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

[
  {
    "type": "SetValue",
    "property": "opacity",
    "value": 0.5,
    "delay": 500
  },
  {
    "type": "Sequential",
    "when": "${event.target.value}",
    "delay": 500,
    "commands": [
      {
        "type": "SendEvent",
        "arguments": [
          "checkedに設定されました。"
        ]
      }
    ]
  }
]

以下に注意してください。

  • 元の呼び出しでは、delay値として「500」を渡しました。customPressHandler定義にはパラメーターとしてdelayが含まれていないため、delay値はカスタムコマンドの各コマンドに渡されました。
  • 元の呼び出しではopacity値を渡しませんでしたが、opacityはcustomPressHandlerのパラメーターとして定義されています。そのため、データバインディングコンテキストは、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"}などの行を入力して、ソフトスタッガーを使用した冒頭アニメーションをコンポーネントに追加できます。

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