カスタム要素の使用 (ベータ)
この機能はベータサービスです。ベータサービスはお客様独自の裁量で試行するものとします。ベータ機能の使用には、「Agreements and Terms」に記載されたベータサービス規約が適用されます。
サードパーティ Web コンポーネントは customElements.define() を使用して作成できる Web コンポーネントであり、LWC アプリケーションで再利用できるカスタム要素になります。サードパーティ Web コンポーネントを使用していない限り、LWC でカスタム要素を使用する必要はありません。この記事の目的では、カスタム要素とサードパーティ Web コンポーネントは同じ意味になります。
Lightning Locker ではサードパーティ Web コンポーネントがサポートされていないため、Salesforce 組織で Lightning Web セキュリティ (LWS) が有効になっている必要があります。
カスタム要素では、次の条件に従う必要があります。
classでconstructor()を使用してカスタム要素を初期化します。- Shadow DOM または Light DOM を使用します。Shadow DOM については、LWS で closed モードのみがサポートされています。
customElements.define(name, constructor)を使用して、カスタム要素をCustomElementRegistryに登録します。nameはハイフンを含み、ページ内で一意である必要があります。
カスタム要素には、<template> タグを任意に使用することができます。<template> タグは document.createElement("template"); を使用して作成することができます。LWC の HTML テンプレートでは、<template> タグをネストすることはできません。
LWC では、カスタム要素はサードパーティ Web コンポーネントを使用する場合にのみ必要です。LWC にサードパーティ Web コンポーネントを実装する場合、そのコンポーネントのドキュメントで使用方法を確認することをお勧めします。
サードパーティの Web コンポーネントには、HTMLElement クラスを拡張したカスタム要素定義が含まれています。カスタム要素の定義では、要素の表示方法と、要素が追加または削除されたときの処理を記述します。
サードパーティ Web コンポーネントの動作は、connectedCallback() や disconnectedCallback() などのライフサイクルコールバック内に記述されています。
constructor()- カスタム要素が初期化されるときにコールされます。super()をコールする必要があり、シャドウの内容を設定するなど、表示前の処理を指定できます。connectedCallback()- カスタム要素が DOM に接続されるときに呼び出されます。disconnectedCallback()- カスタム要素が DOM から切断されたときに呼び出されます。observedAttributes()- 監視する属性の配列を返します。attributeChangedCallback()- 属性が追加、削除、変更されたときに呼び出されます。observeAttributes()で、監視する属性を指定します。adoptedCallback()- カスタム要素が新しいドキュメントに移動されると呼び出されます。
LWC では、カスタム要素はサードパーティ Web コンポーネントを使用する場合にのみ必要です。LWC にサードパーティ Web コンポーネントを実装する場合、そのコンポーネントのドキュメントで使用方法を確認することをお勧めします。
サードパーティ Web コンポーネントには、初期状態とデフォルト値を設定し、イベントリスナーを設定し、さらにシャドウルートを作成するコンストラクタが含まれています。
プロトタイプチェーンを確立するには、コンストラクタで super() をコールします。this.attachShadow() を使用してカスタム要素にシャドウルートを接続します。LWS ではモードを closed に設定する必要があります。「Lightning Web セキュリティと Lightning Locker の比較」を参照してください。
closed モードでは、shadowRoot プロパティは null を返すので、shadowRoot を使用して要素のシャドウルートにアクセスしたり操作したりすることはできません。closed モードでカスタム要素を作成する場合は、シャドウルートへの参照を shadow や __shadowRoot などの別の変数で保存します。
要素の内部 Shadow DOM 構造を作成するには、.innerHTML を使用してコンテンツを追加します。この例では、LWC コンポーネントのライフサイクルの外側でカスタム要素を定義しています。
カスタム要素の属性や子要素を操作するには、代わりに connectedCallback() または renderedCallback() を使用します。たとえば、要素を作成し、その要素に属性を設定する場合は、いずれかのライフサイクルコールバックまで遅延させ、属性が変更されたときに attributeChangedCallback() を使用してコールバックを定義します。詳細は、カスタム要素の仕様を参照してください。
LWC テンプレートでカスタム要素を使用するには、lwc:external 要素を使用します。
次の例は、カスタム要素の構造を示しています。この例では、押されたときに表示ラベルのカウンタを増分するボタンを作成しています。
LWC でカスタム要素を使用するには、lwc:external ディレクティブを使用してテンプレートに追加します。
コンポーネントは DOM で次のように表示されます。ボタンの表示ラベル ${this.count} はクリックされるたびに増分されます。
この例は前の例と似ていますが、カスタム要素の count 属性を監視し、属性が変更されたときに attributeChangedCallback() を使用してコールバックを定義します。
カスタム要素タグを LWC テンプレートに追加します。