RefreshView API の使用
RefreshView API を使用するには、lightning/refresh
モジュールをインポートします。
lightning/refresh
モジュールは、また Aura の force:refreshView
に置き換えられ、以下を公開します。
- モジュールで更新を通知するために発行できる
RefreshEvent
イベント。 - ディスパッチされた更新イベントの受信と、更新処理の起動をコンポーネントで登録可能にする一連のメソッド。
- 更新処理の一環で呼び出すコールバックメソッドをコンポーネントで登録可能にする一連のメソッド。
RefreshComplete
、RefreshCompleteWithError
、RefreshError
などのステータス定義。
更新可能なビューに属するコンポーネントを更新処理に含めるには、登録する必要があります。
ビューの更新に含めるには、コンポーネントでハンドラーメソッドを登録します。コンポーネントの 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 が有効な組織の例
this
を registerRefreshContainer
に渡すと、RefreshEvent
の要素にイベントリスナーがバインドされます。登録した更新コンテナが RefreshEvent
を受信すると、更新ツリーで更新処理が開始されます。
RefreshEvent
は DOM のイベントバブルのルールに従うため、この処理を開始する更新コンテナは、通知元のコンポーネントに最も近い登録済み上位ノードになります。
登録済みコンテナのコールバック (この例では refreshContainer()
) は、コンテナが RefreshEvent
を受信すると呼び出されます。コールバックは、更新処理の開始時にパラメータとして Promise
を受け取ります。更新処理が終了すると、この Promise
は RefreshStatus
の値で解決されます。
更新関連の処理を管理するには、登録済みコンテナのコールバックメソッドを使用します。次に例を示します。
- 計測の開始/終了
- スピナーの表示
- エラー処理
- トースト
また、RefreshEvent
の例で示したように、disconnectedCallback()
で unregisterRefreshContainer()
メソッドを使用して、ビューコントローラの更新コンテナとしての登録を解除する必要があります。
関連トピック