RefreshView API の使用

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

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

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

LWC での更新ハンドラーメソッドの登録

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

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

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

Important

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

LWS が有効な組織の例

1import { LightningElement } from "lwc";
2import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
3export default class RefreshHandler extends LightningElement {
4  refreshHandlerID;
5  connectedCallback() {
6    this.refreshHandlerID = registerRefreshHandler(this, this.refreshHandler);
7  }
8  disconnectedCallback() {
9    unregisterRefreshHandler(this.refreshHandlerID);
10  }
11  refreshHandler() {
12    // example usage case for refresh participant
13    // fetch some data and report status once complete
14    let endPoint = "https://api.<your company>.com";
15    return new Promise((resolve) => {
16      fetch(endPoint, {
17        method: "GET",
18      });
19      resolve(true);
20    });
21  }
22}

Lightning Locker が有効な組織の例

1import { LightningElement } from "lwc";
2import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
3export default class RefreshHandler extends LightningElement {
4  refreshHandlerID;
5  connectedCallback() {
6    this.refreshHandlerID = registerRefreshHandler(
7      this.template.host,
8      this.refreshHandler.bind(this),
9    );
10  }
11  disconnectedCallback() {
12    unregisterRefreshHandler(this.refreshHandlerID);
13  }
14  refreshHandler() {
15    // example usage case for refresh participant
16    // fetch some data and report status once complete
17    let endPoint = "https://api.<your company>.com";
18    return new Promise((resolve) => {
19      fetch(endPoint, {
20        method: "GET",
21      });
22      resolve(true);
23    });
24  }
25}

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

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

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

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

RefreshEvent による更新の通知

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

1import { LightningElement } from "lwc";
2import { RefreshEvent } from "lightning/refresh";
3
4export default class RefreshButton extends LightningElement {
5  // signal a refresh programmatically
6  // or via a button click
7  beginRefresh() {
8    this.dispatchEvent(new RefreshEvent());
9  }
10}

RefreshEvent の受信の登録

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

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

Important

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

Note

LWS が有効な組織の例

1import { LightningElement } from "lwc";
2import {
3  registerRefreshContainer,
4  unregisterRefreshContainer,
5  REFRESH_ERROR,
6  REFRESH_COMPLETE,
7  REFRESH_COMPLETE_WITH_ERRORS,
8} from "lightning/refresh";
9
10export default class RefreshContainer extends LightningElement {
11  refreshContainerID;
12  connectedCallback() {
13    this.refreshContainerID = registerRefreshContainer(this, this.refreshContainer);
14  }
15  disconnectedCallback() {
16    unregisterRefreshContainer(this.refreshContainerID);
17  }
18  refreshContainer(refreshPromise) {
19    console.log("refreshing");
20    return refreshPromise.then((status) => {
21      if (status === REFRESH_COMPLETE) {
22        console.log("Done!");
23      } else if (status === REFRESH_COMPLETE_WITH_ERRORS) {
24        console.warn("Done, with issues refreshing some components");
25      } else if (status === REFRESH_ERROR) {
26        console.error("Major error with refresh.");
27      }
28    });
29  }
30}

Lightning Locker が有効な組織の例

1import { LightningElement } from "lwc";
2import {
3  registerRefreshContainer,
4  unregisterRefreshContainer,
5  REFRESH_ERROR,
6  REFRESH_COMPLETE,
7  REFRESH_COMPLETE_WITH_ERRORS,
8} from "lightning/refresh";
9
10export default class RefreshContainer extends LightningElement {
11  refreshContainerID;
12  connectedCallback() {
13    this.refreshContainerID = registerRefreshContainer(
14      this.template.host,
15      this.refreshContainer.bind(this),
16    );
17  }
18  disconnectedCallback() {
19    unregisterRefreshContainer(this.refreshContainerID);
20  }
21  refreshContainer(refreshPromise) {
22    console.log("refreshing");
23    return refreshPromise.then((status) => {
24      if (status === REFRESH_COMPLETE) {
25        console.log("Done!");
26      } else if (status === REFRESH_COMPLETE_WITH_ERRORS) {
27        console.warn("Done, with issues refreshing some components");
28      } else if (status === REFRESH_ERROR) {
29        console.error("Major error with refresh.");
30      }
31    });
32  }
33}

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

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

Note

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

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

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

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

関連トピック

RefreshStatus の定数

The Japanese Summer '24 guide is now live

日本語の Summer '24 ガイドが公開されました! 「Component Reference (コンポーネントリファレンス)」は、以前と同様にコンポーネントライブラリにあります。