組み込みディレクティブ

ディレクティブは、式のレンダリング方法をカスタマイズすることでLitを拡張できる関数です。Litには、さまざまなレンダリングニーズに対応するための組み込みディレクティブが多数含まれています。

ディレクティブ概要

スタイリング

classMap

オブジェクトに基づいて、要素にクラスのリストを割り当てます。

styleMap

オブジェクトに基づいて、要素にスタイルプロパティのリストを設定します。

ループと条件

when

条件に基づいて、2つのテンプレートのいずれかをレンダリングします。

choose

キー値に基づいて、多数のテンプレートのいずれかをレンダリングします。

map

関数を使用して、イテラブルを変換します。

repeat

データ差分とDOMの安定性を実現するために、オプションのキー設定を使用して、イテラブルからDOMに値をレンダリングします。

join

イテラブルからの値を、結合子値と交互に配置します。

range

シーケンス内の数値のイテラブルを作成します。これは、特定の回数繰り返す場合に役立ちます。

ifDefined

値が定義されている場合は属性を設定し、未定義の場合は属性を削除します。

キャッシュと変更検出

cache

DOMを破棄するのではなく、テンプレートを変更するときにレンダリングされたDOMをキャッシュします。

keyed

レンダリング可能な値を一意のキーに関連付け、キーが変更された場合はDOMを強制的に再レンダリングします。

guard

依存関係のいずれかが変更された場合にのみ、テンプレートを再評価します。

live

属性またはプロパティが最後にレンダリングされた値ではなく、ライブDOMの値と異なる場合に設定します。

レンダリングされたDOMの参照

ref

テンプレートでレンダリングされた要素への参照を取得します。

特殊な値のレンダリング

templateContent

<template>要素の内容をレンダリングします。

unsafeHTML

文字列をテキストではなくHTMLとしてレンダリングします。

unsafeSVG

文字列をテキストではなくSVGとしてレンダリングします。

非同期レンダリング

until

1つ以上のPromiseが解決するまで、プレースホルダーコンテンツをレンダリングします。

asyncAppend

AsyncIterableからの値が生成されると、DOMに追加します。

asyncReplace

AsyncIterableから最新の値が生成されると、DOMにレンダリングします。

使用するものだけをバンドルしてください。 これらはLitパッケージの一部であるため、「組み込み」ディレクティブと呼ばれています。ただし、各ディレクティブは個別のモジュールであるため、アプリはインポートしたディレクティブのみをバンドルします。

独自のディレクティブを作成することもできます。詳細については、カスタムディレクティブを参照してください。

オブジェクトに基づいて、要素にクラスのリストを設定します。

インポート
シグネチャ
使用可能な場所

class 属性式(class属性内の唯一の式である必要があります)

classMapディレクティブは、element.classList APIを使用して、ユーザーから渡されたオブジェクトに基づいて、要素にクラスを効率的に追加および削除します。オブジェクト内の各キーはクラス名として扱われ、キーに関連付けられた値が真の場合、そのクラスが要素に追加されます。後続のレンダリングでは、偽またはオブジェクトに存在しなくなった以前に設定されたクラスは削除されます。

classMapclass属性内の唯一の式である必要がありますが、静的な値と組み合わせることができます

playgroundclassMapを詳しく調べてください。

オブジェクトに基づいて、要素にスタイルプロパティのリストを設定します。

インポート
シグネチャ
使用可能な場所

style 属性式(style属性内の唯一の式である必要があります)

styleMapディレクティブは、element.style APIを使用して、ユーザーから渡されたオブジェクトに基づいて、要素にインラインスタイルを効率的に追加および削除します。オブジェクト内の各キーはスタイルプロパティ名として扱われ、値はそのプロパティの値として扱われます。後続のレンダリングでは、未定義またはnullの以前に設定されたスタイルプロパティはすべて削除されます(nullに設定されます)。

ダッシュを含むCSSプロパティの場合、キャメルケースの同等のものを使用するか、プロパティ名を引用符で囲むことができます。たとえば、CSSプロパティfont-familyfontFamilyまたは'font-family'のいずれかとして記述できます。

--custom-colorなどのCSSカスタムプロパティを参照するには、プロパティ名全体を引用符で囲みます。

styleMapstyle属性内の唯一の式である必要がありますが、静的な値と組み合わせることができます

playgroundstyleMapを詳しく調べてください。

条件に基づいて、2つのテンプレートのいずれかをレンダリングします。

インポート
シグネチャ
使用可能な場所

任意

conditionがtrueの場合はtrueCase()の呼び出しの結果を返し、それ以外の場合はfalseCaseが定義されている場合はfalseCase()の呼び出しの結果を返します。

これは、elseなしでインライン条件を少しだけ記述しやすくする三項式の便利なラッパーです。

指定されたvalueをケースに一致させることに基づいて、ケースのリストからテンプレート関数を選択して評価します。

インポート
シグネチャ
使用可能な場所

任意

ケースは[caseValue, func]として構造化されています。valueは厳密な等価性によってcaseValueに一致します。最初のマッチが選択されます。ケースの値には、プリミティブ、オブジェクト、シンボルなど、任意の型を指定できます。

これはswitch文に似ていますが、式としてであり、フォールスルーはありません。

itemsの各値でf(value)を呼び出した結果を含むイテラブルを返します。

インポート
シグネチャ
使用可能な場所

任意

map()は、for/ofループの単純なラッパーであり、式でイテラブルを少し簡単に操作できるようにします。map()は常にその場で作成されたDOMを更新します。差分やDOMの移動は行いません。それが必要な場合は、repeatを参照してください。map()repeat()よりも小さく、高速であるため、差分やDOMの安定性が必要ない場合は、map()を優先してください。

データ差分とDOMの安定性を実現するために、オプションのキー設定を使用して、イテラブルからDOMに値をレンダリングします。

インポート
シグネチャ
使用可能な場所

子式

イテラブルから生成された一連の値(通常はTemplateResults)を繰り返し、イテラブルが変更されたときにこれらのアイテムを効率的に更新します。keyFnが指定されている場合、キーからDOMへの関連付けは、必要に応じて生成されたDOMを移動することで更新間で維持され、挿入と削除のために最小限の不要な作業を実行するため、一般的にrepeatを使用する最も効率的な方法です。

キー関数を使用していない場合は、map()の使用を検討する必要があります。

keyFnが提供されていない場合、repeatはアイテムから値への単純なマップと同様に動作し、DOMは潜在的に異なるアイテムに対して再利用されます。

repeatを使用する場合と標準のJavaScriptフロー制御を使用する場合の議論については、mapまたはrepeatを使用する場合を参照してください。

playgroundrepeatを詳しく調べてください。

itemsの値がjoinerの値と交互に配置されたイテラブルを返します。

インポート
シグネチャ
使用可能な場所

任意

startからend(排他的)までの整数で、stepずつ増分するイテラブルを返します。

インポート
シグネチャ
使用可能な場所

任意

値が定義されている場合は属性を設定し、未定義の場合は属性を削除します。

インポート
シグネチャ
使用可能な場所

属性式

AttributePartsの場合、値が定義されている場合は属性を設定し、値が未定義(undefinedまたはnull)の場合は属性を削除します。他の部分型の場合、このディレクティブはノーオペレーションです。

単一の属性値に複数の式が存在する場合、いずれかの式でifDefinedを使用し、undefined/nullと評価された場合、属性は削除されます。これは、URLの必要な部分が定義されていない場合に属性を設定すべきではない場合、404を防ぐためにURL属性を設定する場合に特に役立ちます。

playgroundifDefinedを詳しく調べてください。

DOMを破棄するのではなく、テンプレートを変更するときにレンダリングされたDOMをキャッシュします。このディレクティブを使用すると、大きなテンプレート間を頻繁に切り替える場合にレンダリングパフォーマンスを最適化できます。

インポート
シグネチャ
使用可能な場所

子式

cacheに渡された値が1つ以上のTemplateResultの間で変化する場合、特定のテンプレートのレンダリングされたDOMノードは、使用されていないときにキャッシュされます。テンプレートが変更されると、ディレクティブは新しい値に切り替える前に現在のDOMノードをキャッシュし、DOMノードを新しく作成するのではなく、以前にレンダリングされた値に切り替えるときにキャッシュから復元します。

Litがテンプレートを再レンダリングする場合、変更された部分のみを更新します。必要な以上のDOMを作成または削除することはありません。ただし、あるテンプレートから別のテンプレートに切り替える場合、Litは古いDOMを削除し、新しいDOMツリーをレンダリングします。

cache ディレクティブは、指定された式と入力テンプレートに対して生成された DOM をキャッシュします。上記の例では、summaryViewdetailView の両方のテンプレートの DOM をキャッシュしています。あるビューから別のビューに切り替えるとき、Lit は新しいビューのキャッシュされたバージョンを挿入し、最新のデータで更新します。これにより、これらのビューが頻繁に切り替えられる場合にレンダリングパフォーマンスを向上させることができます。

cache については、プレイグラウンドで詳しく調べてください。

レンダリング可能な値を一意のキーに関連付けます。キーが変更されると、値 (テンプレートなど) が同じであっても、前の DOM は削除および破棄されてから次の値がレンダリングされます。

インポート
シグネチャ
使用可能な場所

任意の式

keyed は、状態を持つ要素をレンダリングしていて、重要なデータが変更されたときに要素のすべての状態をクリアする必要がある場合に役立ちます。これは基本的に、Lit のデフォルトの DOM 再利用戦略をオプトアウトします。

keyed は、"enter" または "exit" アニメーションのために新しい要素を強制的に作成する必要がある場合、一部のアニメーションシナリオでも役立ちます。

不要な作業を防ぎ、レンダリングパフォーマンスを最適化するために、依存関係のいずれかが変更された場合にのみテンプレートを再評価します。

インポート
シグネチャ
使用可能な場所

任意の式

valueFn によって返される値をレンダリングし、依存関係のいずれかの識別子が変更された場合にのみ valueFn を再評価します。

ここで

  • dependencies は、変更を監視する値の配列です。
  • valueFn は、レンダリング可能な値を返す関数です。

guard は、データが更新されるまでコストのかかる処理を防ぐことで、イミュータブルなデータパターンで役立ちます。

この場合、コストのかかる calculateSHA 関数は、value プロパティが変更された場合にのみ実行されます。

guard については、プレイグラウンドで詳しく調べてください。

属性またはプロパティが最後にレンダリングされた値ではなく、ライブDOMの値と異なる場合に設定します。

インポート
シグネチャ
使用可能な場所

属性またはプロパティ式

値を更新するかどうかを判断するときに、Lit のデフォルトの動作である最後に設定された値に対するチェックではなく、ライブ DOM 値に対して式値をチェックします。

これは、DOM 値が Lit の外部から変更される可能性がある場合に役立ちます。たとえば、<input> 要素の value プロパティ、コンテンツ編集可能な要素のテキストを設定する式を使用する場合や、独自のプロパティまたは属性を変更するカスタム要素を使用する場合などです。

このような場合、DOM 値が変更されても、Lit 式を通じて設定された値が変更されていない場合、Lit は DOM 値を更新する必要があることを認識せず、そのままにします。これが望ましくない場合 (DOM 値をバインドされた値で上書きしたい場合) は、live() ディレクティブを使用します。

live() は、ライブ DOM 値に対して厳密な等価性チェックを実行し、新しい値がライブ値と等しい場合は何も実行しません。これは、式が型変換を引き起こす場合には live() を使用すべきではないことを意味します。属性式で live() を使用する場合は、文字列のみが渡されるようにするか、式がすべてのレンダリングで更新されるようにしてください。

live については、プレイグラウンドで詳しく調べてください。

<template>要素の内容をレンダリングします。

インポート
シグネチャ
使用可能な場所

子式

Lit テンプレートは JavaScript でエンコードされているため、動的にするための JavaScript 式を埋め込むことができます。Lit テンプレートに含める必要がある静的な HTML <template> がある場合は、templateContent ディレクティブを使用してテンプレートの内容をクローンし、Lit テンプレートに含めることができます。テンプレート要素参照がレンダリング間で変更されない限り、後続のレンダリングは何も行いません。

テンプレートの内容は開発者が管理する必要があり、信頼できない文字列を使用して作成してはならないことに注意してください。信頼できないコンテンツの例には、クエリ文字列パラメーターやユーザー入力からの値が含まれます。このディレクティブでレンダリングされた信頼できないテンプレートは、クロスサイトスクリプティング (XSS) の脆弱性につながる可能性があります。

templateContent については、プレイグラウンドで詳しく調べてください。

文字列をテキストではなくHTMLとしてレンダリングします。

インポート
シグネチャ
使用可能な場所

子式

Lit のテンプレート構文の重要な機能は、テンプレートリテラルから発生した文字列のみが HTML として解析されることです。テンプレートリテラルは信頼できるスクリプトファイルでのみ作成できるため、これは信頼できない HTML を挿入する XSS 攻撃に対する自然な保護として機能します。ただし、データベースからフェッチされた信頼できる HTML コンテンツなど、スクリプトファイルから発生していない HTML を Lit テンプレートでレンダリングする必要がある場合があります。unsafeHTML ディレクティブは、このような文字列を HTML として解析し、Lit テンプレートでレンダリングします。

unsafeHTML に渡される文字列は開発者が管理する必要があり、信頼できないコンテンツを含めてはならないことに注意してください。信頼できないコンテンツの例には、クエリ文字列パラメーターやユーザー入力からの値が含まれます。

このディレクティブでレンダリングされた信頼できないコンテンツは、クロスサイトスクリプティング (XSS)、CSS インジェクション、データ流出などの脆弱性につながる可能性があります。unsafeHTMLinnerHTML を使用して HTML 文字列を解析するため、セキュリティ上の影響は innerHTML と同じであり、MDN に記載されているとおりです。

unsafeHTML については、プレイグラウンドで詳しく調べてください。

文字列をテキストではなくSVGとしてレンダリングします。

インポート
シグネチャ
使用可能な場所

子式

unsafeHTML と同様に、データベースからフェッチされた信頼できる SVG コンテンツなど、スクリプトファイルから発生していない SVG コンテンツを Lit テンプレートでレンダリングする必要がある場合があります。unsafeSVG ディレクティブは、このような文字列を SVG として解析し、Lit テンプレートでレンダリングします。

unsafeSVG に渡される文字列は開発者が管理する必要があり、信頼できないコンテンツを含めてはならないことに注意してください。信頼できないコンテンツの例には、クエリ文字列パラメーターやユーザー入力からの値が含まれます。このディレクティブでレンダリングされた信頼できないコンテンツは、クロスサイトスクリプティング (XSS) の脆弱性につながる可能性があります。

unsafeSVG については、プレイグラウンドで詳しく調べてください。

DOM にレンダリングされた要素への参照を取得します。

インポート
シグネチャ
使用可能な場所

要素式

Lit でのほとんどの DOM 操作はテンプレートを使用して宣言的に実現できますが、高度な状況ではテンプレートにレンダリングされた要素への参照を取得し、命令的に操作する必要がある場合があります。これが役立つ可能性のある一般的な例としては、フォームコントロールにフォーカスを設定したり、コンテナー要素に対して命令的な DOM 操作ライブラリを呼び出したりする場合などがあります。

テンプレート内の要素に配置すると、ref ディレクティブはレンダリングされたときにその要素への参照を取得します。要素参照は、Ref オブジェクトを渡すか、コールバックを渡すかのいずれかの 2 つの方法で取得できます。

Ref オブジェクトは要素への参照のコンテナとして機能し、ref モジュールにある createRef ヘルパーメソッドを使用して作成できます。レンダリング後、Refvalue プロパティは要素に設定され、updated などのレンダリング後のライフサイクルでアクセスできます。

ref コールバックを ref ディレクティブに渡すこともできます。コールバックは、参照される要素が変更されるたびに呼び出されます。ref コールバックが別の要素の位置にレンダリングされた場合、または後続のレンダリングで削除された場合、最初に undefined で呼び出され、次いで (存在する場合) レンダーされた新しい要素で再度呼び出されます。LitElement では、コールバックはホスト要素にバインドされて自動的に呼び出されることに注意してください。

ref については、プレイグラウンドで詳しく調べてください。

1つ以上のPromiseが解決するまで、プレースホルダーコンテンツをレンダリングします。

インポート
シグネチャ
使用可能な場所

任意の式

Promise を含む一連の値を受け取ります。値は優先順位順にレンダリングされ、最初の引数が最も優先度が高く、最後の引数が最も優先度が低くなります。値が Promise の場合、解決されるまで、より優先度の低い値がレンダリングされます。

値の優先順位は、非同期データのプレースホルダーコンテンツを作成するために使用できます。たとえば、保留中のコンテンツを含む Promise を最初の (最も優先度の高い) 引数に、Promise ではないロードインジケーターテンプレートを 2 番目の (優先度の低い) 引数として使用できます。ロードインジケーターはすぐにレンダリングされ、Promise が解決されるとプライマリコンテンツがレンダリングされます。

until については、プレイグラウンドで詳しく調べてください。

AsyncIterableからの値が生成されると、DOMに追加します。

インポート
シグネチャ
使用可能な場所

子式

asyncAppend は、非同期イテラブルの値をレンダリングし、前の値の後に新しい値をそれぞれ追加します。非同期ジェネレーターも非同期イテラブルプロトコルを実装しているため、asyncAppend で使用できることに注意してください。

asyncAppend については、プレイグラウンドで詳しく調べてください。

AsyncIterableから最新の値が生成されると、DOMにレンダリングします。

インポート
シグネチャ
使用可能な場所

任意の式

asyncAppend と同様に、asyncReplace は、非同期イテラブルの値をレンダリングし、前の値を新しい値でそれぞれ置き換えます。

asyncReplace については、プレイグラウンドで詳しく調べてください。