標準コマンド（キャラクターディスプレイ）

キャラクターディスプレイでは、Pagerを操作したり、コンポーネントプロパティの値を変更したりするために、ごく一部の標準コマンドがサポートされます。APLコマンドの全般的な動作の詳細については、APLコマンドを参照してください。

共通プロパティ
AutoPageコマンド
Idleコマンド
Parallelコマンド
Sequentialコマンド
SetPageコマンド
SetValueコマンド

共通プロパティ

1つのコマンドは1つのJSONオブジェクトとしてエンコードされます。すべてのAPL-Tコマンドには、次の共通プロパティがあります。

プロパティ	型	デフォルト	説明
type	文字列	必須	コマンドの型です。
description	文字列	""	（任意）このコマンドのドキュメントです。
delay	整数	0	このコマンドが実行されるまでの遅延時間（ミリ秒単位）です。負でない値にする必要があります。
screenLock	ブール値	false	trueの場合、`interaction_timer`を無効にします。
when	ブール値	true	条件式です。falseに評価される場合、コマンドはスキップされます。

type

実行する特定のコマンドを指定します。定義済みのプリミティブコマンドタイプのいずれかか、ユーザー定義コマンドを使用できます。

delay

delayは、このコマンドを実行する前に挿入する時間をミリ秒単位で指定します。delayは負でない値にする必要があります。指定しない場合、delayのデフォルトは0です。コマンドのwhenプロパティがfalseに解決された場合、delayは無視されます。コマンドがイベントハンドラーの内部から実行された場合も、delayは無視されます。

screenLock

screenLockプロパティは、APL-Tドキュメントのlifecycle_sectionに適用されます。trueの場合、このコマンドが実行されている間はinteraction_timerが無効になります。screenLock=trueのコマンドの実行が終了すると、interaction_timerは0にリセットされます。

screenLockはコマンドの範囲全体に適用され、delayが定義されている場合はその時間も対象になります。たとえば、次のコマンドは画面ロックを30秒間保留します。

{
  "type": "Idle",
  "delay": 30000,
  "screenLock": true
}

when

trueの場合、コマンドを実行します。falseの場合、コマンドを無視します。無視されたコマンドでは、screenLockも無視されます。

AutoPageコマンド

Pagerコンポーネントで、一連のページを自動的に進めて表示します。AutoPageコマンドは、リクエストされた時間だけ最終ページを表示した後に終了します。AutoPageコマンドには、標準のコマンドプロパティに加えて次のプロパティがあります。

プロパティ	型	デフォルト	説明
componentId	文字列	SELF	コンポーネントのIDです。
count	整数	<ALL>	表示するページ数です。デフォルトはすべてのページです。
duration	整数	0	ページ間で待機する時間です（ミリ秒単位）。

たとえば、スポーツページャーで自動的にページを進めるには、次のようにします。

{
  "type": "AutoPage",
  "componentId": "mySportsPager",
  "delay": 500,
  "duration": 1000
}

上記の例では、最初に500ミリ秒間一時停止します（delayプロパティ）。その後、次のページに進んで1000ミリ秒間一時停止し（durationプロパティ）、最後の一時停止が終了するまで、ページの変更と一時停止を続けます。この例のPagerに3ページが含まれているとすると、最初のページから開始した場合、AutoPageコマンドの動作は、500ミリ秒間一時停止、2ページ目を表示、1000ミリ秒間一時停止、3ページ目を表示、最後に1000ミリ秒間一時停止となります。

countが正の数でない場合、AutoPageコマンドを実行しても効果はありません。

AutoPageコマンドは、停止時に次の処理を行います。

AutoPageコマンドのシーケンスが50%以上完了している場合は、ターゲットページに移動します。
50%未満の場合は、前のページに戻ります。

ページが変更されると、onPageChangedコマンドが新しいページで1回実行されます。

AutoPageコマンドは、高速モードでは無視されます。

componentId

PagerコンポーネントのIDです。省略した場合、AutoPageコマンドを発行したコンポーネントが使用されます。

count

表示するページ数です。指定しない場合、デフォルトは残りのページ数になります。ラップ動作はサポートされません。値は[0, pager.children.length - pager.currentIndex - 1]の範囲に収まるように内部で調整されます。

duration

次のページに進んだ後に待機する時間です。ページ間のアニメーション遷移はこの時間に含まれないため、コマンド全体の実行時間はこれよりも長くなります。

Idleコマンド

Idleコマンドは何もしません。これはプレースホルダーとして使用するか、長い一連のコマンドに計算された遅延を挿入するために使用します。たとえば、次のコマンドを考えてみましょう。

{
  "type": "Sequential",
  "commands": [
    {
      "type": "SetValue",
      "componentId": "myText",
      "property": "text",
      "value": "こんにちは"
    },
    {
      "type": "Idle",
      "delay": 3000
    },
    {
      "type": "SetValue",
      "property": "myText",
      "value": "皆さん"
    }
  ]
}

このコマンド例は、idが「myText」のTextコンポーネントに「こんにちは」というテキストを3秒間表示してから、そのテキストを「皆さん」に切り替えます。

idleコマンドのtypeは「Idle」です。Idleコマンドには、共通のコマンドプロパティ以外のプロパティはありません。

Parallelコマンド

一連のコマンドを並列に実行します。Parallelコマンドは、すべての子コマンドを同時に実行開始します。Parallelコマンドは、すべての子コマンドが終了したときに実行完了と見なされます。Parallelコマンドが早期に停止すると、その時点で実行中のすべてのコマンドが停止します。

Parallelコマンドのtypeは「Parallel」です。Parallelコマンドには、共通のコマンドプロパティに加えて次のプロパティがあります。

プロパティ	型	デフォルト	説明
commands	コマンドの配列	必須	並行して実行する順序不同のコマンドのリストです。

高速モードでは、Parallelコマンドはすべてのサブコマンドを並列に実行しますが、遅延時間を無視します（実質的な時間は0になります）。

commands

並行して実行する順序不同のコマンドの配列です。すべてのコマンドの実行が終了すると、Parallelコマンドは終了します。Parallelコマンドのdelayと各コマンドのdelayは累算されることに注意してください。たとえば、次のようなコマンドがあるとします。

{
  "type": "Parallel",
  "delay": 500,
  "commands": [
    {
      "type": "SetValue",
      "delay": 1000
    },
    {
      "type": "SetValue",
      "delay": 250
    }
  ]
}

上記の例では、最初のSetValueは1500ミリ秒後に、2番目は750ミリ秒後（最初のSetValueよりも前）に実行されます。

Sequentialコマンド

Sequentialコマンドは、一連のコマンドを順番に実行します。前のコマンドが終了するのを待ってから、次のコマンドを実行します。Sequentialコマンドは、すべての子コマンドが終了すると完了します。

Sequentialコマンドのtypeは「Sequential」です。Sequentialコマンドには、共通のコマンドプロパティに加えて次のプロパティがあります。

プロパティ	型	デフォルト	説明
catch	コマンドの配列	[]	このシーケンスが早期に停止した場合に実行するコマンドの順序付きリストです。
commands	コマンドの配列	必須	順番に実行するコマンドの順序付きリストです。
finally	コマンドの配列	[]	通常のコマンドとcatchコマンドの後に実行するコマンドの順序付きリストです。
repeatCount	整数	0	これらのコマンドを追加で実行する回数です。

Sequentialコマンドは次のアルゴリズムで実行されます。

function runSequential(command, mode):
  if mode == "normal":
    for (i = 0 ; i <= repeatCount ; i++):
      for cmd in command.commands:
        run cmd
        wait for cmd to finish
        if cmd was stopped:
          return doCatch()
  elif mode == "fast":
    for cmd in commands:
      fastRun cmd

  return doFinally(mode)

function doCatch():
  for cmd in command.catch:
    fastRun cmd
  return doFinally("fast")

function doFinally(mode):
  for cmd in command.finally:
    if mode == "normal":
      run cmd
      wait for cmd to finish
      if cmd was stopped:  // 高速モードに切り替え
        mode = "fast"
    elif mode == "fast":
      fastRun cmd

このアルゴリズムには次のような特徴があります。

通常モードでは、commandsが順番に実行され、その後にfinallyコマンドが続きます。repeatCountは通常のコマンドにのみ適用されます。
高速モードでは、commandsが順番に実行された後、繰り返しは行われず、finallyコマンドが続きます。
commandsのいずれかが（通常モードで）早期に停止した場合、catchコマンドとfinallyコマンドは高速モードで実行されます。
通常モードでの実行中にfinallyコマンドのいずれかが停止した場合、残りのfinallyコマンドは高速モードで実行されます。

catch

catchコマンドは、ほかのコマンドが開始されたためにSequentialコマンドが停止した場合に実行されます。catchコマンドは「高速」モードで実行されます。つまり、すべての待機時間は無視され、各コマンドは最終的な値にジャンプします。catchコマンドは、finallyコマンドの前に実行されます。

catchコマンドが実行されるのは1回だけです。repeatCountプロパティは、catchコマンドには適用されません。

commands

実行するコマンドの配列です。コマンドは順番に実行され、各コマンドが終了しない限り次のコマンドは開始されません。Sequentialコマンドのdelayとシーケンスの最初のコマンドのdelayは累算されることに注意してください。たとえば、次のようなコマンドがあるとします。

{
  "type": "Sequential",
  "delay": 1000,
  "repeatCount": 2,
  "commands": [
    {
      "type": "SetValue",
      "delay": 2000
    },
    {
      "type": "SetValue",
      "delay": 2000
    }
  ]
}

上記の例では、最初のSetValueは3000ミリ秒後に実行されます。

finally

finallyコマンドは、Sequentialの通常のcommandsが終了した後か、Sequentialコマンドが早期に停止してcatchコマンドが実行された後に実行されます。（a）Sequentialコマンド全体が高速モードで実行された場合、または（b）Sequentialコマンドが早期に停止した場合を除き、finallyコマンドは通常モードで実行されます。

finallyコマンドが実行されるのは1回だけです。repeatCountプロパティは、finallyコマンドには適用されません。

repeatCount

この一連のコマンドを繰り返す回数です。デフォルトは0です。負の値は無視されます。

Sequentialコマンド全体に割り当てられた遅延時間は、開始時にのみ適用されることに注意してください。たとえば、前のセクションに示したサンプルのSequentialコマンドでは、最初のSetValueが3000ミリ秒後に実行され、2番目が5000ミリ秒後に実行され、再び最初のSetValueが7000ミリ秒後に実行されるという具合に続きます。

SetPageコマンド

Pagerコンポーネントに表示されているページを変更します。SetPageコマンドは、項目全体が表示されると終了します。SetPageコマンドには、標準のコマンドプロパティに加えて次のプロパティがあります。

プロパティ	型	デフォルト	説明
componentId	文字列	SELF	コンポーネントのIDです。
position	relative	absolute	値が相対オフセットか絶対オフセットかを示します。
value	整数	必須	移動距離です。絶対値または相対値で指定できます。

PagerにNページある場合、最初のページのインデックスは0で、最後のページのインデックスはN-1になります。相対位置の場合は、現在のページからのオフセットを示します。たとえば、1ページ先に進めるには次のようにします。

{
  "type": "SetPage",
  "componentId": "myWeatherPager",
  "position": "relative",
  "value": 1
}

絶対位置の場合は、現在のページのインデックスを設定します。負の絶対位置は、リストの末尾からのオフセットを示します。たとえば、最後のページに移動するには次のようにします。

{
  "type": "SetPage",
  "componentId": "myWeatherPager",
  "position": "absolute",
  "value": -1
}

2ページ間で切り替える場合、間のページは表示されません。たとえば、現在のページが3ページ目の場合、SetPageをposition="relative"、value=-2として実行すると、現在のページから1ページ目に遷移し、2ページ目は表示されません。

SetPageコマンドでは、表示するページを任意に設定できます。Pagerコンポーネントで許可されている移動方向は考慮されません。ただし、ラップ動作はページ切り替えの計算に影響します。valueのセクションを参照してください。

SetPageコマンドを停止すると、SetPageコマンドシーケンスが50%以上完了している場合はターゲットページにジャンプし、50%未満の場合は前のページに戻ります。最後に表示されていたページから変更された場合、コマンドの停止時にonPageChangedコマンドが1回実行されます。

SetPageコマンドは、高速モードでは無視されます。

componentId

PagerコンポーネントのIDです。省略した場合、SetPageコマンドを発行したコンポーネントが使用されます。

position

positionが「relative」の場合、valueは現在のページから移動する相対的なページ数を表します。positionが「absolute」の場合、valueは移動先のページ番号を絶対値で表します。

value

移動するページ数か、絶対値で表される移動先のページ番号のいずれかです。

最終的な位置と方向を計算するアルゴリズムは、大まかに次のようになります。

if (command.position == 'absolute') {  // 絶対値での移動
  let index = command.value < 0 ? pager.children.length + command.value : command.value;
  index = Math.max(0, Math.min(pager.children.length - 1, index));  // 範囲を固定

  // 最後のインデックスと移動の方向を返します。
  if (index == pager.currentIndex)
    return NO_MOVE

  return (index, index < pager.currentIndex ? "LEFT" : "RIGHT");
}
else {  // 相対値での移動
  let index = pager.currentIndex + command.value;

  // 相対値での移動先が範囲外になる場合、ラップ動作に対応していなければコマンドを無視します。
  if (pager.navigation != "wrap" && (index < 0 || index >= pager.children.length))
    return NO_MOVE;

  // 適切にラップします。
  index = ((index % pager.children.length) + pager.children.length) % pager.children.length;
  if (index == pager.currentIndex)
     return NO_MOVE;

  return (index, command.value < 0 ? "LEFT" : "RIGHT");
}

Pagerのアニメーションは、返された方向に動きます。

このアルゴリズムには次のような特徴があります。

絶対値は有効なページの範囲内に固定されます。directionは、現在のページを基準とした方向を表します。
ラップ動作に対応するPagerでは、相対値を使用すると任意にラップします。directionはコマンドで与えられた値によって決まります。ラップ動作で方向が変わることはありません。
ラップ動作に対応しないPagerでは、相対値が範囲外になる場合は無視されます。

SetValueコマンド

コンポーネントのプロパティまたはバインディングを変更します。各コンポーネントには、設定可能な動的プロパティのセットが定義されています。各コンポーネントで、名前付きバインディングが使用されることもあります。設定可能な値については、各コンポーネントの仕様を参照してください。

SetValueコマンドには、標準のコマンドプロパティに加えて次のプロパティがあります。

プロパティ	型	デフォルト	説明
componentId	文字列	SELF	値を設定するコンポーネントのIDです。
property	文字列	必須	設定するプロパティの名前です。
value	任意	必須	プロパティに設定する値です。

たとえば、ジョークのオチを表示するには次のようにします。

{
  "type": "SetValue",
  "componentId": "jokePunchline",
  "property": "text",
  "value": "向こう側に行くため。"
}

SetValueコマンドは、コンポーネントのプロパティの値またはコンポーネントのバインディングを変更します。次のルールが適用されます。

propertyで指定された名前を持つ動的プロパティがコンポーネントにある場合、そのプロパティが新しい値で更新されます。
それ以外の場合、指定された名前を持つbindプロパティがコンポーネントにあれば、そのバインドされたプロパティが更新されます。
バインドされたプロパティの値が変わると、そのプロパティに依存しているコンポーネントの動的プロパティがすべて更新されます。

以下は、バインドされた値を更新する例です。

{
  "type": "Container",
  "bind": [
    {
      "name": "MyCounter",
      "value": 0,
      "type": "number"
    }
  ],
  "item": {
    "type": "Text",
    "text": "Ct：${MyCounter}"
  },
  "onMount": {
    "type": "Sequential",
    "repeatCount": 10,
    "commands": [
      {
        "type": "SetValue",
        "delay": 500,
        "property": "MyCounter",
        "value": "${value + 1}"
      }
    ]
  }
}

上記の例では、カウントが10になるまで、500ミリ秒ごとにカウンターを1つずつ増やします。

SetValueコマンドは高速モードでも実行されますが、その場合は遅延時間は無視されます。

componentId

値を変更するコンポーネントのIDです。このプロパティを省略した場合、SetValueコマンドを発行したコンポーネントが対象になります。

property

変更するプロパティの名前です。ビルトインのプロパティまたはバインディングを指定できます。

value

valueはコマンドの実行時に評価されます。そのため、既存のコンポーネントのプロパティを活用できます。次に例を示します。

{
  "type": "SetValue",
  "property": "MyCounter",
  "value": "${value + 1}"
}

このコマンドは、コンテナーにバインドされたカウンターであるターゲットコンポーネントの値を1ずつ増やします。

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

フィードバックを送信

最終更新日: 2025 年 12 月 17 日