HTML テンプレートディレクティブ

ディレクティブとは、HTML テンプレートに動的な動作を追加する特別な属性のことです。ルート <template> タグ、ネストされた <template> タグ、または <p> タグなどの HTML 要素で特定のディレクティブを使用できます。一部のディレクティブは、異なるタグとの併用をサポートしています。

ルート <template> タグはコンポーネントの HTML テンプレートの最初の要素です。次のディレクティブがサポートされています。

DOM で表示されるように HTML コメントを維持します。たとえば、条件付きコメントを使うことで、特定のブラウザでのデザインやスタイルを改善できます。

lwc:preserve-comments が有効な場合、同階層の条件ディレクティブの間にコメントを配置できません。

Light DOM を使用してコンポーネントを表示します。これにより、サードパーティツールで querySelector などの標準ブラウザクエリ API を使用して DOM をトラバースできます。

コンポーネントのテンプレートには特定のディレクティブを使用してネストされた <template> タグを含めることができます。これらのネストされたタグでは、次のディレクティブのみがサポートされています。

配列を反復処理して、リストを表示します。for:each={array} は、ネストされたテンプレートや HTML 要素で使用できます。「リストの表示」を参照してください。

現在の項目にアクセスします。

currentItem プレースホルダは、モデルが現在の範囲に挿入する識別子です。

現在の項目のゼロから始まるインデックスにアクセスします。

index プレースホルダは、モデルが現在の範囲に挿入する新しい識別子です。

非推奨。if:true と if:false ディレクティブは、推奨されなくなりました。非推奨となり、今後削除される可能性があります。代わりに、lwc:if、lwc:elseif、lwc:else を使用します。

if:true|false={expression} は、テンプレートの DOM 要素を条件に応じて表示し、if:true と if:false のそれぞれで式を呼び出します。if:true と if:false ディレクティブをチェーニングする場合は、lwc:if、lwc:elseif、lwc:else などのディレクティブと同等の性能はなく、軽量でもありません。「条件に応じた DOM 要素の表示」を参照してください。

expression には、JavaScript 識別子 (例: person) またはオブジェクトからプロパティにアクセスするためのドット表記 (例: person.firstName) を指定できます。エンジンでは、計算式 (person[2].name['John']) は使用できません。expression の値を計算するには、JavaScript クラスで getter を使用します。

テンプレートの DOM 要素を条件に応じて表示します。lwc:if、lwc:elseif、lwc:else は、if:true と if:false のディレクティブより優先されます。

ネストされた <template> タグ、<div> タグ、その他 HTML 要素、および <c-custom-cmp> のようなカスタムコンポーネントタグでは、条件付きディレクティブを使用します。

lwc:elseif と lwc:else はどちらも、同階層の lwc:if または lwc:elseif のすぐ後ろに続ける必要があります。

lwc:if と lwc:elseif の両方で式を評価する必要があります。ただし、lwc:else には属性値を指定できません。

lwc:if および lwc:elseif に渡される式では、単純なドット表記がサポートされます。!condition、object?.property?.condition、sum % 2 === 1 など、複雑な式はサポートされていません。そのような式を計算するには、JavaScript クラスで getter を使用します。

lwc:elseif または lwc:else の前にテキストや他の要素を付加することはできません。タグ間の空白文字は、空白文字が条件付きディレクティブの同階層である場合、無視されます。たとえば lwc:if の後と lwc:else の前に <div> タグを含めることはできません。

コードコメントは、lwc:preserve-comments が有効ではない場合にのみ、条件ディレクティブの同階層に含めることができます。

偽値 (Falsy) をチェックするには、expression が true になるように否定演算子を付けて getter の戻り値に渡します。

配列の最初または最後の項目に特別な動作を適用して、リストを表示します。iterator:iteratorName={array} は、ネストされたテンプレートや HTML 要素で使用できます。「リストの表示」を参照してください。

iteratorName では、次のプロパティにアクセスします。

• value — リスト内の項目の値。このプロパティは、配列のプロパティにアクセスするために使用します。例: iteratorName.value.propertyName。
• index — リスト内の項目のインデックス。
• first — この項目がリスト内の最初の項目であるかどうかを示す Boolean 値。
• last — この項目がリスト内の最後の項目であるかどうかを示す Boolean 値。

親コンポーネント内の範囲設定されたスロットフラグメントを、子コンポーネント内の lwc:slot-bind ディレクティブとリンクします。子コンポーネントで Light DOM を使用する必要があります。

親コンポーネントの <template> 要素に lwc:slot-data を追加し、lwc:slot-data の値を文字列リテラルに設定します。

<template lwc:slot-data> 要素は、カスタム要素の直接の子でなければなりません。たとえば、<template lwc:slot-data> 要素はカスタム要素 <c-child> にネストされています。

lwc:slot-data の文字列リテラルと、対応する lwc:slot-bind によって使用される変数は、同じ名前を共有する必要はありません。

1 つの <template> 要素が持つことができるのは、lwc:slot-data の 1 つのインスタンスのみです。範囲設定されたスロットフラグメントは、1 つの子コンポーネントのみと結合します。

<slot> タグでは、次のディレクティブがサポートされています。

このディレクティブは、子コンポーネントの範囲設定されたスロットにデータを結合します。子コンポーネントで Light DOM を使用する必要があります。

子コンポーネントの <slot> 要素に lwc:slot-bind を追加し、lwc:slot-bind の値を変数名に設定します。

<slot lwc:slot-bind> 要素は、Light DOM 要素の HTML <template> でのみ使用できます。

1 つの <slot> 要素には 1 つの lwc:slot-bind のインスタンスのみを追加できます。範囲設定されたスロットは、1 つのデータソースにのみ結合できます。

<p> タグ、基本コンポーネント、独自のカスタムコンポーネントなどの HTML 要素で特定のディレクティブを使用できます。

前のセクションの lwc:if、lwc:elseif、lwc:else ディレクティブは、HTML タグや基本コンポーネント、独自のカスタムコンポーネントでの使用にも対応しています。

for:item={currentItem} および for:index={index} を使用して、配列を反復処理し、リストを表示します。また、前のセクションで説明したように、ネストされたテンプレートでの使用にも対応しています。

配列の最初または最後の項目に特別な動作を適用して、リストを表示します。また、前のセクションで説明したように、ネストされたテンプレートでの使用にも対応しています。

リスト内の各項目に一意の識別子を割り当てて表示パフォーマンスを向上させます。iterator:iteratorName={array} または for:each={{array}} で、このディレクティブを使用します。

key は、文字列または数字にする必要があります。オブジェクトにすることはできません。エンジンは、このキーを使用して、変更された項目を判別します。「リストの表示」を参照してください。

このディレクティブをネイティブ HTML 要素に追加すると、オーナーの JavaScript クラスから要素の appendChild() をコールして、スタイルを保持できます。

appendChild() へのコールで DOM を操作する場合、付加された要素にはスタイルは適用されません。Lightning Web コンポーネントをプログラミングするときは、JavaScript を使用して DOM を操作しないことをお勧めします。ただし、サードパーティの JavaScript ライブラリによっては、この手法が必要な場合があります。

サードパーティ Web コンポーネントやカスタム要素が、LWC テンプレートのネイティブ Web コンポーネントとして表示されるようにします。「サードパーティ Web コンポーネント (ベータ)」を参照してください。

ref は、セレクタなしで DOM 要素を見つけ、指定されたテンプレートに含まれる要素のみを照会します。

ref を使用するには、lwc:ref ディレクティブを要素に追加し、値を割り当てます。その参照をコールするには、this.refs を使用します。この例では、this.refs は実行時にディレクティブ lwc:ref="myDiv" を参照し、<div> にアクセスします。

Shadow DOM の this.template.querySelector() または Light DOM の this.querySelector() ではなく、this.refs を使用することをお勧めします。Shadow DOM のコンポーネントでは、this.refs は Shadow DOM 内の要素を参照します。Light DOM のコンポーネントでは、this.refs は Light DOM 内の要素を参照します。テンプレートに lwc:ref が定義されていない場合、this.refs は undefined を返します。

「コンポーネントが所有する要素へのアクセス」を参照してください。

プロパティを子コンポーネントに展開し、実行時にプロパティとしてバインドされたオブジェクトを要素で受け入れることができるようにします。コンポーネントの JavaScript でプロパティを定義します。

childProps をプロパティとして子コンポーネントに適用します。1 つの要素には 1 つの lwc:spread のインスタンスのみを設定できます。

「子コンポーネントのスプレッドプロパティ」を参照してください。

コンポーネントを動的にインスタンス化するには、<lwc:component> 管理要素をコンポーネントの HTML ファイルで lwc:is ディレクティブと共に使用します。

次に、<lwc:component> を使用する HTML テンプレートを示します。

詳細は、「コンポーネントの動的なインスタンス化」を参照してください。

関連トピック

• HTML テンプレートの使用
• サードパーティ JavaScript ライブラリの使用