LWC でのサードパーティ Web コンポーネントの使用 (Beta)

LWC アプリケーションでサードパーティ Web コンポーネントを使用します。サードパーティ Web コンポーネントは、LWC テンプレートのネイティブ Web コンポーネントとして表示されます。サードパーティ Web コンポーネントは、iframe または lwc:dom="manual" を使用することで LWC テンプレートファイル内で使用できますが、LWC テンプレート内で lwc:external を使用してサードパーティ Web コンポーネントをネイティブ Web コンポーネントとして表示することをお勧めします。

サードパーティ Web コンポーネントには、さまざまな JavaScript フレームワークや、純粋な標準 JS で記述されたフレームワークを使用できます。MDN Web コンポーネントは、LWC フレームワークで使用できるサードパーティ Web コンポーネントの例です。同様に、webcomponents.org は、カスタム要素と Shadow DOM 標準に基づいた Web コンポーネントのコレクションを提供しています。

サードパーティの JavaScript ライブラリを使用している場合は、「サードパーティ JavaScript ライブラリの使用」を参照してください。

サードパーティ Web コンポーネントを使用する前に、AppExchange でサードパーティ LWC アプリケーションまたはコンポーネントを確認し、必要な機能を備えた管理パッケージをインストールすることをお勧めします。または、基本コンポーネントで要件が満たされるかどうかを確認してください。

LWC 以外のサードパーティ Web コンポーネントを使用するには、次のいずれかの方法に従います。

• ファイルを静的リソースとしてアップロードし、lightning/platformResourceLoader モジュールの loadScript メソッドを使用してコンポーネントを読み込みます。1 つの静的リソースにつき 5 MB までアップロードできます。組織では、最大 250 MB の静的リソースを使用できます。
• .js-meta.xml 設定ファイルを使用して、サードパーティ Web コンポーネントを LWC モジュールとして追加します。コンポーネントの JavaScript ファイルの最大ファイルサイズは 128 KB です。

このベータリリースには、いくつかの既知の問題があります。

• Shadow DOM を使用するサードパーティ Web コンポーネントでは、attachShadow({ mode: "closed" }); の closed シャドウルートのみがサポートされます。サードパーティ Web コンポーネントが open モードを使用している場合は、コンポーネントが LWS に準拠するようにソースを更新してください。または、Shadow DOM を使用しないサードパーティ Web コンポーネントを使用します。「Light DOM」を参照してください。
• loadScript は現在 ECMAScript モジュール (ESM) をサポートしていません。たとえば、<script type="module"> はサポートされていません。サードパーティの Web コンポーネントをインポートするには、IIFE (Immediately-Invoked Function Expression: 即時実行関数式) や UMD (Universal Module Definition: ユニバーサルモジュール定義) などの従来形式のカスタム要素を含むバンドルされた JavaScript ファイルを使用します。
• npm やその他の連動関係を持つサードパーティ Web コンポーネント、またはコンパイルとバンドルを必要とするサードパーティ Web コンポーネントはサポートされていません。LWC では現在、npm からのインポートはサポートされていません。
• ID で要素を参照するサードパーティ Web コンポーネントは、Shadow DOM ではサポートされていません。たとえば、コンポーネントが document.getElementById('some-id') を使用する場合、LWC はグローバル HTML ドキュメントにアクセスできません。可能な限りテンプレート参照を使用してください。
• エクスペリエンスビルダーサイトでは現在、LWS が有効な場合、サードパーティ Web コンポーネントがサポートされていません。
• Lightning Web Security では現在、extends オプションを使用したカスタマイズされた組み込み要素がサポートされていません。また、Safari などの WebKit ベースのブラウザでもカスタマイズされた組み込み要素はサポートされていません。HTMLElement を拡張するクラスでできることについて詳しく知りたい場合は、HTML 仕様の「Custom Elements (カスタム要素)」を参照してください。

サードパーティ Web コンポーネントを使用する場合は、次のガイドラインに従ってください。

• サードパーティ Web コンポーネントにデータを渡すには、属性、プロパティ、または lwc:spread ディレクティブを使用します。Web コンポーネントにデータを渡すとき、LWC ではデフォルトでデータが属性として設定されます。プロパティは存在する場合にのみ設定されます。
• Lightning Web コンポーネントのスロットにマークアップを渡すのと同じようにして、サードパーティ Web コンポーネントのスロットにマークアップを渡します。合成 Shadow のスロットは、サードパーティ Web コンポーネントではサポートされていません。
• LWC テンプレートではルート <template> タグのみがサポートされています。サードパーティーコンポーネントで <template> タグをネストする必要がある場合は、代わりに JavaScript ファイルで document.createElement('template') を使用してください。
• LWC テンプレートでの宣言によるイベントのバインドには、小文字のイベント名のみを使用できます。サードパーティ Web コンポーネントでイベント名に小文字以外の文字やハイフンを使用している場合は、addEventListener() を使用してプラグラムによってイベントリスナーを追加してください。
• observedAttributes() や attributeChangedCallback() を使用して、サードパーティ Web コンポーネントを表示した場合には、その後に属性の変更を監視します。
• lwc:external では動的なコンポーネントの作成がサポートされていません。カスタム要素は、Lightning Web コンポーネントやネイティブ HTML 要素と同様に表示されます。

詳細は、「カスタム要素にデータを渡す (ベータ)」を参照してください。

この例のサードパーティ Web コンポーネントは、lightning-relative-date-time 基本コンポーネントに似ています。サードパーティ Web コンポーネントを使用する前に、基本コンポーネントが要件を満たしているかどうかを確認してください。

この例では、IIFE として利用可能な time-elements JavaScript ファイルを使用しています。

time-elements は、local-time、relative-time、time-ago、time-until などの Web コンポーネントを提供しています。

これらの Web コンポーネントを使用するには、事前に組織で JavaScript ファイルを静的リソースとしてアップロードしておきます。この例では、静的リソースの名前は timeElements になっています。

loadScript 関数を使用して lightning/platformResourceLoader から静的リソースをインポートします。

この例では、MDN の popup-info コンポーネントを使用します。このコンポーネントを LWC モジュールとして追加するには、force-app/main/default/lwc フォルダに Lightning Web コンポーネントを作成します。名前は popupInfo という名前にしましょう。

テンプレートで、popup-info 要素に lwc:external ディレクティブを含めます。

JavaScript ファイルで、closed モードのシャドウルートを作成します。この例では、trailheadLogo 静的リソースを使用し、popup-info が接続されています。また、"img/default.png" 画像パスを {$logo} に置き換えています。これは静的リソースとしてアップロードされたロゴを参照します。

関連トピック

• Lightning Web セキュリティに関する FAQ
• Salesforce 開発者ブログ: What ISV Partners Need to Know About Lightning Web Security (ISV パートナーが知っておくべき Lightning Web セキュリティのポイント)
• MDN Web Docs: Using shadow DOM (Shadow DOM の使用)