可視性変更イベントハンドラー

可視性変更イベントハンドラー

Alexa Presentation Language（APL）は、コンポーネントの可視性が変更されたときに可視性変更イベントを生成します。handleVisibilityChangeイベントハンドラーを使用すると、これらのイベントをキャプチャしてコマンドを実行できます。

可視性変更イベントが生成される変更の種類

可視性変更イベントがトリガーされる変更には、次の2種類があります。

  • コンポーネント全体のopacity（cumulativeOpacity）が変更された場合。たとえば、AnimateItemコマンドまたはSetValueコマンドでコンポーネントの不透明度を変更すると、コンポーネントのcumulativeOpacityが変更され、イベントが生成されます。
  • コンポーネントのバウンディングボックスの中で、親コンポーネント内に表示されている部分の割合（visibleRegionPercentage）が変更された場合。たとえば、Sequence内の子コンポーネントをスクロールして表示領域に入れると、子コンポーネントのvisibleRegionPercentageが変更され、イベントが生成されます。

可視性変更イベントハンドラー

コンポーネントの可視性の変更をキャプチャするハンドラーを定義できます。すべてのコンポーネントには、可視性変更ハンドラーの配列を受け取るhandleVisibilityChangeプロパティがあります。ハンドラーは、コンポーネントが最初にマウントされた後、visibleRegionPercentageまたはcumulativeOpacityが変更されたときに呼び出されます。

プロパティ 型 デフォルト スタイル設定 動的 説明

handleVisibilityChange

可視性変更ハンドラーの配列

[]

×

×

コンポーネントの可視性が変更されたときに呼び出される可視性ハンドラーです。

可視性変更ハンドラーは、以下の表のプロパティを持つオブジェクトです。

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

commands

コマンドの配列

必須

このハンドラーが呼び出された場合に実行するコマンドです。

description

文字列

—

オプションの説明です。

when

ブール値

true

trueの場合、このハンドラーが呼び出されます。

可視性変更ハンドラーの配列は並列に実行されます。各ハンドラーにはwhenプロパティがあります。ハンドラーは、以下の両方の条件が満たされた場合に実行されます。

  • ハンドラーのwhen句がtrueに評価された場合。
  • コンポーネントのvisibleRegionPercentageまたはcumulativeOpacityが変更された場合。

commands

この可視性変更ハンドラーが呼び出されたときに実行するコマンドの配列です。

生成されるイベントの形式は次のようになります。

{
  "event": {
    "source": {
      "type": "COMPONENT_TYPE",         // コンポーネントの型（"Pager"、"TouchWrapper"など）
      "handler": "VisibilityChange"
      ...                               // コンポーネントのソースのプロパティ
    },
    "visibleRegionPercentage": NUMBER, // コンポーネントの領域として定義されたディメンションに対する可視部分の割合（[0.0, 1.0]の範囲）
    "cumulativeOpacity": NUMBER        // コンポーネント全体の不透明度（[0.0, 1.0]の範囲）
  }
}

event.source.typeプロパティには、コンポーネントの名前（TouchWrapper、ScrollView、Sequenceなど）が設定されます。event.sourceのプロパティの詳細については、event.sourceを参照してください。

クコマンドは常に「高速モード」で実行されます。

when

trueの場合、可視性の変更時にこのハンドラーが呼び出されます。

visibleRegionPercentageの評価に関する制限

visibleRegionPercentageは、要素のバウンディングボックスの中で、親コンポーネント内に表示されている部分の割合を示します。この値の評価にあたっては、次の点は考慮されません。

  • visibleRegionPercentageでは、コンポーネントに適用される変換（移動、回転、拡大縮小）は考慮されません。コンポーネントまたは祖先コンポーネントに変換が適用されている場合は、可視性の計算を信頼しないでください。
  • visibleRegionPercentageでは、コンポーネントの上に子コンポーネントや絶対配置のコンポーネントが配置されて、コンポーネントが覆われる可能性は考慮されません。

パフォーマンスに関する考慮事項

過渡的な可視性の計算は、ドキュメント階層に応じて相対的にコストが高くなることがあります。このため、次の点を考慮に入れてください。

  • コンポーネントのhandleVisibilityChangeプロパティを使用するのは、どうしても必要な場合だけにしてください。
  • コンポーネントのcumulativeOpacityは、コンポーネントのopacity値と、コンポーネントの各祖先のopacityの積として計算されます。したがって、コンポーネントの祖先のいずれかの不透明度が変更されると、ハンドラーがトリガーされる可能性があります。この計算は、ターゲットコンポーネントが階層のルートに近いほど効率的になります。
  • whenプロパティを使用して、ハンドラーが必要でない場合は無効にしてください。

可視性変更イベントのタイミング

可視性変更ハンドラーは、ドキュメントオブジェクトモデルがコンポーネントの可視性を更新したときに実行されます。モデルの変更が画面に反映されるまでには若干の遅延時間があります。遅延の長さは、次のような複数の要因によって左右されます。

  • ドキュメントの複雑さ
  • オペレーティングシステムの負荷
  • グラフィック処理パイプラインの遅延

多くの場合、画面の更新は1つのグラフィックフレーム内（16ミリ秒）で行われますが、これは保証された動作ではありません。そのため、何らかのパフォーマンスを測定したり、正確な計算が必要なシステムを開発したりするときは、この潜在的な遅延時間を考慮に入れてください。

可視性変更ハンドラーの例

次の例では、ハンドラーを使用して、Sequenceの最後の項目の少なくとも50%が1秒間表示されたときにメッセージを表示します。

次の例では、Frameコンポーネントの不透明度を増減するボタンを表示します。Frameの可視性変更ハンドラーは、コンポーネントの現在の不透明度を表示するために使用される変数を更新し、ボタンを有効または無効にするタイミングを決定します。

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

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