RefreshView API の使用

RefreshView API を使用するには、lightning/refresh モジュールをインポートします。

lightning/refresh モジュールは、また Aura の force:refreshView に置き換えられ、以下を公開します。

  • モジュールで更新を通知するために発行できる RefreshEvent イベント。
  • ディスパッチされた更新イベントの受信と、更新処理の起動をコンポーネントで登録可能にする一連のメソッド。
  • 更新処理の一環で呼び出すコールバックメソッドをコンポーネントで登録可能にする一連のメソッド。
  • RefreshCompleteRefreshCompleteWithErrorRefreshError などのステータス定義。

更新可能なビューに属するコンポーネントを更新処理に含めるには、登録する必要があります。

ビューの更新に含めるには、コンポーネントでハンドラーメソッドを登録します。コンポーネントの connectedCallback() 内で registerRefreshHandler() メソッドを使用してハンドラーメソッドを登録します。

registerRefreshHandler() メソッドで渡されるパラメータは、組織で LWS を有効にしておらず、依然として Lightning Locker を使用してコンポーネントを実行している場合には、別の形式が必要になります。

コンテナが RefreshEvent を受け取ると、ハンドラーメソッドが呼び出されます。登録したコンテナは、登録済み更新ハンドラーの「更新ツリー」の構成要素となり、その順序は DOM をエミュレートします。次にコンテナは、更新ハンドラーを登録した参加コンポーネントのコールバック更新メソッドを呼び出します。

LWS が有効な組織の例

Lightning Locker が有効な組織の例

更新ツリーに登録された更新メソッドは、登録済みコンテナのノードから幅優先順に呼び出されます。この方法により、下位 (子) のハンドラーが呼び出される前に、上位 (親) のハンドラーが必ず解決されます。

登録済み更新ハンドラーのコールバックは、次の処理を実行する必要があります。

  • Boolean に解決される Promise を返します。
    • コンポーネントが更新の操作を完了し、このノードから更新ツリーを下って更新処理を継続できる場合は true
    • このノードの子要素へ更新処理を継続しない場合は false
  • 現在の状態に従って、必要な更新の参照操作を実行します。
  • 必要に応じて、データと状態を再度同期します。
  • 処理中に、スピナーやトーストなど、適切な UI を表示します。

また、前の例で示したように、disconnectedCallback() でコンポーネントのハンドラーメソッドの登録を解除する必要があります。

ビューの更新を開始するには、lightning/refresh で定義されている RefreshEvent イベントを起動します。このイベントは、コンテナに更新処理の開始を要求します。このイベントは、任意のコンポーネントから起動できます。

ユーザのビューの更新処理を開始するには、各コンテナ内のアプリケーションコントローラで RefreshEvent の受信を登録する必要があります。コンテナの connectedCallback() 内で registerRefreshContainer() メソッドを使用して、RefreshEvent の受信を登録します。

registerRefreshContainer() メソッドで渡されるパラメータは、組織で LWS を有効にしておらず、依然として Lightning Locker を使用してコンポーネントを実行している場合には、別の形式が必要になります。

コンポーネントを有効なページに追加する場合、RefreshEvent を受信するコンテナを作成する必要はありません。更新の範囲を指定する場合のみ、コンテナを追加します。

LWS が有効な組織の例

Lightning Locker が有効な組織の例

thisregisterRefreshContainer に渡すと、RefreshEvent の要素にイベントリスナーがバインドされます。登録した更新コンテナが RefreshEvent を受信すると、更新ツリーで更新処理が開始されます。

RefreshEvent は DOM のイベントバブルのルールに従うため、この処理を開始する更新コンテナは、通知元のコンポーネントに最も近い登録済み上位ノードになります。

登録済みコンテナのコールバック (この例では refreshContainer()) は、コンテナが RefreshEvent を受信すると呼び出されます。コールバックは、更新処理の開始時にパラメータとして Promise を受け取ります。更新処理が終了すると、この PromiseRefreshStatus の値で解決されます。

更新関連の処理を管理するには、登録済みコンテナのコールバックメソッドを使用します。次に例を示します。

  • 計測の開始/終了
  • スピナーの表示
  • エラー処理
  • トースト

また、RefreshEvent の例で示したように、disconnectedCallback()unregisterRefreshContainer() メソッドを使用して、ビューコントローラの更新コンテナとしての登録を解除する必要があります。

関連トピック