APLのユーザー定義コマンド
APLドキュメントまたはパッケージでカスタムコマンドを定義できます。
user commands
を使用するには、APL 1.1以降が必要です。これよりも古いバージョンの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"}
などの行を入力して、ソフトスタッガーを使用した冒頭アニメーションをコンポーネントに追加できます。