ディレクティブ

非同期イテラブル[1]のアイテムをレンダリングし、組み込みのイテラブルのサポートと同様に、以前の値の後ろに新しい値を追加するディレクティブ。このディレクティブは、子式でのみ使用できます。

インポート

import { asyncAppend } from 'lit/directives/async-append.js';

シグネチャ

asyncAppend(value, _mapper?): DirectiveResult<AsyncAppendDirective>

パラメータ

value

AsyncIterable<unknown>

非同期イテラブル

_mapper?

(v: unknown, index?: number) => unknown

詳細

非同期イテラブルは、[Symbol.asyncIterator]メソッドを持つオブジェクトであり、そのnext()メソッドはPromiseを返すイテレータを返します。新しい値が利用可能になると、Promiseが解決され、ディレクティブによって制御されるPartに値が追加されます。このディレクティブ以外の値がPartに設定されている場合、イテラブルはリッスンされなくなり、新しい値はPartに書き込まれません。[1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

ディレクティブを含む部分が再レンダリングの結果としてクリアされた場合、またはユーザーが以前にディレクティブを含むレンダリングされた部分でpart.setConnected(false)を呼び出した場合（例えば、LitElementがDOMから切断された場合）に、disconnectedメソッドが呼び出される抽象的なDirective基底クラスです。

インポート

import { AsyncAppendDirective } from 'lit/directives/async-append.js';

詳細

part.setConnected(true)が後で含まれる部分で呼び出された場合、ディレクティブの次のupdate/renderコールバックの前に、ディレクティブのreconnectedメソッドが呼び出されます。disconnectedを実装する場合、再接続と互換性を持たせるために、reconnectedも実装する必要があります。ディレクティブが切断されている間に更新が発生する可能性があることに注意してください。したがって、ディレクティブは通常、ガベージコレクションを妨げる可能性のあるリソースをサブスクライブすることが安全かどうかを判断するために、render/update中にthis.isConnectedフラグを確認する必要があります。

非同期イテラブル[1]のアイテムをレンダリングし、以前の値を新しい値で置き換え、一度に1つの値だけがレンダリングされるようにするディレクティブ。このディレクティブは、任意の式タイプで使用できます。

インポート

import { asyncReplace } from 'lit/directives/async-replace.js';

シグネチャ

asyncReplace(value, _mapper?): DirectiveResult<AsyncReplaceDirective>

パラメータ

value

AsyncIterable<unknown>

非同期イテラブル

_mapper?

Mapper<unknown>

詳細

非同期イテラブルは、[Symbol.asyncIterator]メソッドを持つオブジェクトであり、そのnext()メソッドはPromiseを返すイテレータを返します。新しい値が利用可能になると、Promiseが解決され、ディレクティブによって制御されるPartに値がレンダリングされます。このディレクティブ以外の値がPartに設定されている場合、イテラブルはリッスンされなくなり、新しい値はPartに書き込まれません。[1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

ディレクティブを含む部分が再レンダリングの結果としてクリアされた場合、またはユーザーが以前にディレクティブを含むレンダリングされた部分でpart.setConnected(false)を呼び出した場合（例えば、LitElementがDOMから切断された場合）に、disconnectedメソッドが呼び出される抽象的なDirective基底クラスです。

インポート

import { AsyncReplaceDirective } from 'lit/directives/async-replace.js';

詳細

part.setConnected(true)が後で含まれる部分で呼び出された場合、ディレクティブの次のupdate/renderコールバックの前に、ディレクティブのreconnectedメソッドが呼び出されます。disconnectedを実装する場合、再接続と互換性を持たせるために、reconnectedも実装する必要があります。ディレクティブが切断されている間に更新が発生する可能性があることに注意してください。したがって、ディレクティブは通常、ガベージコレクションを妨げる可能性のあるリソースをサブスクライブすることが安全かどうかを判断するために、render/update中にthis.isConnectedフラグを確認する必要があります。

テンプレートによって生成されたDOMノードとTemplateInstanceをキャッシュすることで、複数のテンプレート間を高速に切り替えることができます。

インポート

import { cache } from 'lit/directives/cache.js';

シグネチャ

cache(v): DirectiveResult<CacheDirective>

パラメータ

v

不明

詳細

例

let checked = false;
html`
  ${cache(checked ? html`input is checked` : html`input is not checked`)}
`

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { CacheDirective } from 'lit/directives/cache.js';

与えられたvalueをケースと一致させることで、リストからテンプレート関数を選択して評価します。

インポート

import { choose } from 'lit/directives/choose.js';

シグネチャ

choose(value, cases, defaultCase?): undefined | V

パラメータ

value

T

cases

Array<[T, () => V]>

defaultCase?

() => V

詳細

ケースは[caseValue, func]として構成されます。valueは厳密等価性によってcaseValueと照合されます。最初の一致が選択されます。ケースの値は、プリミティブ、オブジェクト、シンボルなど、任意の型にすることができます。これはswitch文に似ていますが、式として機能し、フォールスルーはありません。

動的なCSSクラスを適用するディレクティブ。

インポート

import { classMap } from 'lit/directives/class-map.js';

シグネチャ

classMap(classInfo): DirectiveResult<ClassMapDirective>

パラメータ

classInfo

ClassInfo

詳細

これはclass属性内で使用する必要があり、属性で使用される唯一の部分である必要があります。classInfo引数の各プロパティを受け取り、プロパティ値が真の場合はプロパティ名を要素のclassListに追加します。プロパティ値が偽の場合は、プロパティ名を要素のclassから削除します。たとえば、{foo: bar}は、barの値が真である場合にクラスfooを適用します。

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { ClassMapDirective } from 'lit/directives/class-map.js';

真偽値に対するクラス名のキーと値のセット。

インポート

import { ClassInfo } from 'lit/directives/class-map.js';

単一の値または値の配列が変更されるまで、テンプレート関数の再レンダリングを防ぎます。

インポート

import { guard } from 'lit/directives/guard.js';

シグネチャ

guard(_value, f): DirectiveResult<GuardDirective>

パラメータ

_value

不明

f

() => unknown

テンプレート関数

詳細

値は厳密等価性(===)で以前の値と照合されるため、オブジェクトまたは配列内のネストされたプロパティの変更は検出されません。配列の値は、各項目が同じインデックスの以前の値と厳密等価性で照合されます。ネストされた配列も厳密等価性によってのみチェックされます。例

html`
  <div>
    ${guard([user.id, company.id], () => html`...`)}
  </div>
`

この場合、テンプレートはuser.idまたはcompany.idのいずれかが変更された場合にのみ再レンダリングされます。 guard()は、データが更新されるまでコストのかかる作業を防ぐことで、イミュータブルなデータパターンで役立ちます。例

html`
  <div>
    ${guard([immutableItems], () => immutableItems.map(i => html`${i}`))}
  </div>
`

この場合、配列の参照が変更された場合にのみ、項目がマップされます。

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { GuardDirective } from 'lit/directives/guard.js';

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

インポート

import { ifDefined } from 'lit/directives/if-defined.js';

シグネチャ

ifDefined(value): nothing | NonNullable<T>

パラメータ

value

T

詳細

他のパート型の場合、このディレクティブはnoopです。

items内の値をjoinerの値でインタリーブしたイテラブルを返します。

インポート

import { join } from 'lit/directives/join.js';

シグネチャ

join(items, joiner): Iterable<I | J>

パラメータ

items

undefined | Iterable<I>

joiner

(index: number) => J

レンダリング可能な値を一意のキーに関連付けます。キーが変更されると、値（テンプレートなど）が同じ場合でも、次の値をレンダリングする前に、以前のDOMが削除および破棄されます。

インポート

import { keyed } from 'lit/directives/keyed.js';

シグネチャ

keyed(k, v): DirectiveResult<Keyed>

パラメータ

k

不明

v

不明

詳細

これは、ステートフルコンポーネントの再レンダリングを強制したり、新しいデータが新しいHTML要素を生成することを期待するコード（一部のアニメーション技術など）を操作したりする場合に役立ちます。

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { Keyed } from 'lit/directives/keyed.js';

値を更新するかどうかを判断する際に、以前にバインドされた値ではなく、ライブ DOM 値に対してバインディング値をチェックします。

インポート

import { live } from 'lit/directives/live.js';

シグネチャ

live(value): DirectiveResult<LiveDirective>

パラメータ

value

不明

詳細

これは、lit-html の外部から DOM 値が変更される可能性がある場合に役立ちます。たとえば、<input> 要素の value プロパティへのバインディング、コンテンツ編集可能な要素のテキスト、または独自のプロパティや属性を変更するカスタム要素などです。これらの場合、DOM 値が変更されても、lit-html バインディングで設定された値が変更されていない場合、lit-html は DOM 値を更新することを認識せず、そのまま放置します。これが望ましくない場合、つまり、DOM 値がどうであれバインドされた値で DOM 値を上書きしたい場合は、live() ディレクティブを使用してください。

html`<input .value=${live(x)}>`

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

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { LiveDirective } from 'lit/directives/live.js';

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

インポート

import { map } from 'lit/directives/map.js';

シグネチャ

map(items, f): Generator<unknown, void, unknown>

パラメータ

items

undefined | Iterable<T>

f

(value: T, index: number) => unknown

start から end (終端を含まない) までの整数を step ずつインクリメントしたイテラブルを返します。

インポート

import { range } from 'lit/directives/range.js';

シグネチャ

range(end): Iterable<number>

パラメータ

end

number

詳細

start が省略された場合、範囲は 0 から開始されます。step のデフォルトは 1 です。

要素への参照のコンテナである新しい Ref オブジェクトを作成します。

インポート

import { createRef } from 'lit/directives/ref.js';

シグネチャ

createRef(): Ref<T>

Ref オブジェクトの値を設定するか、バインドされている要素を使用して ref コールバックを呼び出します。

インポート

import { ref } from 'lit/directives/ref.js';

シグネチャ

ref(_ref): DirectiveResult<RefDirective>

パラメータ

_ref

RefOrCallback

詳細

Ref オブジェクトは、要素への参照のコンテナとして機能します。ref コールバックは、要素を唯一の引数として受け取る関数です。ref ディレクティブは、参照された要素が変更された場合、レンダリング中に Ref オブジェクトの値を設定するか、ref コールバックを呼び出します。注意: ref コールバックが後続のレンダリングで別の要素位置にレンダリングされたり削除されたりした場合、最初に undefined で呼び出され、次にレンダリングされた新しい要素 (存在する場合) で再度呼び出されます。

// Using Ref object
const inputRef = createRef();
render(html`<input ${ref(inputRef)}>`, container);
inputRef.value.focus();
// Using callback
const callback = (inputElement) => inputElement.focus();
render(html`<input ${ref(callback)}>`, container);

ref 値を保持するオブジェクト。

インポート

import { Ref } from 'lit/directives/ref.js';

ディレクティブを含む部分が再レンダリングの結果としてクリアされた場合、またはユーザーが以前にディレクティブを含むレンダリングされた部分でpart.setConnected(false)を呼び出した場合（例えば、LitElementがDOMから切断された場合）に、disconnectedメソッドが呼び出される抽象的なDirective基底クラスです。

インポート

import { RefDirective } from 'lit/directives/ref.js';

詳細

part.setConnected(true)が後で含まれる部分で呼び出された場合、ディレクティブの次のupdate/renderコールバックの前に、ディレクティブのreconnectedメソッドが呼び出されます。disconnectedを実装する場合、再接続と互換性を持たせるために、reconnectedも実装する必要があります。ディレクティブが切断されている間に更新が発生する可能性があることに注意してください。したがって、ディレクティブは通常、ガベージコレクションを妨げる可能性のあるリソースをサブスクライブすることが安全かどうかを判断するために、render/update中にthis.isConnectedフラグを確認する必要があります。

インポート

import { RefOrCallback } from 'lit/directives/ref.js';

型

イテラブルから生成された一連の値 (通常は TemplateResults) を繰り返し、各項目に関連付けられたユーザー指定の keys に基づいてイテラブルが変更されたときに、それらの項目を効率的に更新するディレクティブ。

インポート

import { repeat } from 'lit/directives/repeat.js';

シグネチャ

repeat(items, keyFnOrTemplate, template?): unknown

パラメータ

items

Iterable<T>

keyFnOrTemplate

KeyFn<T> | ItemTemplate<T>

template?

ItemTemplate<T>

詳細

keyFn が提供されている場合、厳密なキーから DOM へのマッピングが維持されることに注意してください。つまり、特定のキーの以前の DOM が必要に応じて新しい位置に移動され、DOM が異なるキーの値で再利用されることはありません (新しいキーには常に新しい DOM が作成されます)。これは、挿入と削除に必要な最小限の作業を実行するため、一般的に repeat を使用する最も効率的な方法です。keyFn は、項目とそのインデックスの 2 つのパラメーターを取り、一意のキー値を返します。

html`
  <ol>
    ${repeat(this.items, (item) => item.id, (item, index) => {
      return html`<li>${index}: ${item.name}</li>`;
    })}
  </ol>
`

重要: keyFn を提供する場合、キーは repeat の特定の呼び出しのすべての項目に対して一意である必要があります。2 つ以上の項目に同じキーがある場合の動作は定義されていません。keyFn が提供されていない場合、このディレクティブは項目を値にマッピングするのと同様の動作を行い、DOM は異なる可能性のある項目に対して再利用されます。

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { RepeatDirective } from 'lit/directives/repeat.js';

インポート

import { ItemTemplate } from 'lit/directives/repeat.js';

型

インポート

import { KeyFn } from 'lit/directives/repeat.js';

型

インポート

import { RepeatDirectiveFn } from 'lit/directives/repeat.js';

シグネチャ

RepeatDirectiveFn(items, keyFnOrTemplate, template?): unknown

パラメータ

items

Iterable<T>

keyFnOrTemplate

KeyFn<T> | ItemTemplate<T>

template?

ItemTemplate<T>

要素に CSS プロパティを適用するディレクティブ。

インポート

import { styleMap } from 'lit/directives/style-map.js';

シグネチャ

styleMap(styleInfo): DirectiveResult<StyleMapDirective>

パラメータ

styleInfo

Readonly<StyleInfo>

詳細

styleMap は style 属性でのみ使用でき、属性内の唯一の式である必要があります。 styleInfo オブジェクト内のプロパティ名を取得し、要素のインラインスタイルにプロパティを追加します。ダッシュ（-）付きのプロパティ名は、有効な CSS プロパティ名であると見なされ、setProperty() を使用して要素の style オブジェクトに設定されます。ダッシュのない名前は、キャメルケースの JavaScript プロパティ名であると見なされ、プロパティ代入を使用して要素の style オブジェクトに設定され、style オブジェクトが JavaScript スタイルの名前を CSS プロパティ名に変換できるようにします。たとえば、styleMap({backgroundColor: 'red', 'border-top': '5px', '--size': '0'}) は background-color、border-top、--size プロパティを設定します。

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { StyleMapDirective } from 'lit/directives/style-map.js';

CSS プロパティと値のキーと値のセット。

インポート

import { StyleInfo } from 'lit/directives/style-map.js';

詳細

キーは、'background-color' のような有効な CSS プロパティ名文字列か、backgroundColor のような CSSStyleDeclaration の有効な JavaScript キャメルケース プロパティ名である必要があります。

template 要素の内容を HTML としてレンダリングします。

インポート

import { templateContent } from 'lit/directives/template-content.js';

シグネチャ

templateContent(template): DirectiveResult<TemplateContentDirective>

パラメータ

テンプレート

HTMLTemplateElement

詳細

テンプレートは開発者が管理するものであり、ユーザーが管理するものではないことに注意してください。ユーザーが管理するテンプレートをこのディレクティブでレンダリングすると、クロスサイトスクリプティングの脆弱性につながる可能性があります。

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { TemplateContentDirective } from 'lit/directives/template-content.js';

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

インポート

import { unsafeHTML } from 'lit/directives/unsafe-html.js';

シグネチャ

unsafeHTML(value): DirectiveResult<UnsafeHTMLDirective>

パラメータ

value

undefined | null | string | noChange | nothing

詳細

値 undefined、null、および nothing は、すべてコンテンツがレンダリングされない（空の文字列）ことになります。これは、サニタイズまたはエスケープされていないユーザーが提供した入力で使用すると、クロスサイトスクリプティングの脆弱性につながる可能性があるため、安全ではありません。

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { UnsafeHTMLDirective } from 'lit/directives/unsafe-html.js';

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

インポート

import { unsafeSVG } from 'lit/directives/unsafe-svg.js';

シグネチャ

unsafeSVG(value): DirectiveResult<UnsafeSVGDirective>

パラメータ

value

undefined | null | string | noChange | nothing

詳細

値 undefined、null、および nothing は、すべてコンテンツがレンダリングされない（空の文字列）ことになります。これは、サニタイズまたはエスケープされていないユーザーが提供した入力で使用すると、クロスサイトスクリプティングの脆弱性につながる可能性があるため、安全ではありません。

カスタムディレクティブを作成するための基本クラスです。ユーザーはこのクラスを拡張し、renderやupdateを実装してから、サブクラスをdirectiveに渡す必要があります。

インポート

import { UnsafeSVGDirective } from 'lit/directives/unsafe-svg.js';

Promise を含む一連の値を Part にレンダリングします。

インポート

import { until } from 'lit/directives/until.js';

シグネチャ

until(values): DirectiveResult<UntilDirective>

パラメータ

values

Array<unknown>

詳細

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

const content = fetch('./content.txt').then(r => r.text());
html`${until(content, html`<span>Loading...</span>`)}`

ディレクティブを含む部分が再レンダリングの結果としてクリアされた場合、またはユーザーが以前にディレクティブを含むレンダリングされた部分でpart.setConnected(false)を呼び出した場合（例えば、LitElementがDOMから切断された場合）に、disconnectedメソッドが呼び出される抽象的なDirective基底クラスです。

インポート

import { UntilDirective } from 'lit/directives/until.js';

詳細

part.setConnected(true)が後で含まれる部分で呼び出された場合、ディレクティブの次のupdate/renderコールバックの前に、ディレクティブのreconnectedメソッドが呼び出されます。disconnectedを実装する場合、再接続と互換性を持たせるために、reconnectedも実装する必要があります。ディレクティブが切断されている間に更新が発生する可能性があることに注意してください。したがって、ディレクティブは通常、ガベージコレクションを妨げる可能性のあるリソースをサブスクライブすることが安全かどうかを判断するために、render/update中にthis.isConnectedフラグを確認する必要があります。

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

インポート

import { when } from 'lit/directives/when.js';

シグネチャ

when(condition, trueCase, falseCase?): T

パラメータ

condition

true

trueCase

() => T

falseCase?

() => F

詳細

これは、else なしでインライン条件を少しきれいに記述できる三項演算子の便利なラッパーです。