指令

一個指令，用於渲染異步可迭代物件[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

一個抽象的 Directive 基底類別，當包含指令的 Part 因重新渲染而被清除時，或當使用者對先前渲染包含該指令的 Part 呼叫 part.setConnected(false) 時 (例如，當 LitElement 從 DOM 斷開連線時)，將會呼叫其 disconnected 方法。

匯入

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

詳細資訊

如果後續在包含的 Part 上呼叫 part.setConnected(true)，則會在下一個 update/render 回呼之前呼叫指令的 reconnected 方法。在實作 disconnected 時，也應該實作 reconnected 以與重新連線相容。請注意，在指令斷開連線時可能會發生更新。因此，指令通常應在 render/update 期間檢查 this.isConnected 標記，以判斷是否可以安全地訂閱可能會阻止垃圾回收的資源。

一個指令，用於渲染異步可迭代物件[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

一個抽象的 Directive 基底類別，當包含指令的 Part 因重新渲染而被清除時，或當使用者對先前渲染包含該指令的 Part 呼叫 part.setConnected(false) 時 (例如，當 LitElement 從 DOM 斷開連線時)，將會呼叫其 disconnected 方法。

匯入

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

詳細資訊

如果後續在包含的 Part 上呼叫 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

unknown

詳細資訊

範例

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 與一個 case 比對，從列表中選擇並評估一個範本函式。

匯入

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

簽名

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

參數

value

T

cases

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

defaultCase?

() => V

詳細資訊

Cases 的結構為 [caseValue, func]。value 會透過嚴格相等與 caseValue 比對。選擇第一個符合的項目。Case 的值可以是任何類型，包括基本類型、物件和符號。這與 switch 語句類似，但它是一個運算式，且沒有 fallthrough。

一個應用動態 CSS 類別的指令。

匯入

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

簽名

classMap(classInfo): DirectiveResult<ClassMapDirective>

參數

classInfo

ClassInfo

詳細資訊

這必須在 class 屬性中使用，且必須是屬性中使用的唯一部分。它會採用 classInfo 引數中的每個屬性，並在屬性值為真值時將屬性名稱新增至元素的 classList；如果屬性值為假值，則會從元素的 class 中移除屬性名稱。例如，如果 bar 的值為真值，則 {foo: 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

unknown

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

詳細資訊

對於其他 part 類型，此指令為無運算。

傳回一個可迭代物件，其中包含以 joiner 值交錯的 items 中的值。

匯入

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

unknown

v

unknown

詳細資訊

這對於強制重新轉譯具狀態的元件，或是使用預期新資料來產生新 HTML 元素的程式碼 (例如某些動畫技術) 很有用。

用於建立自訂指令的基底類別。使用者應擴展此類別，實作 render 和/或 update，然後將其子類別傳遞給 directive。

匯入

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

在決定是否更新值時，會檢查綁定值與即時 DOM 值，而不是先前綁定的值。

匯入

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

簽名

live(value): DirectiveResult<LiveDirective>

參數

value

unknown

詳細資訊

這在 DOM 值可能會從 lit-html 外部變更的情況下很有用，例如綁定到 <input> 元素的 value 屬性、可編輯內容元素的文字，或變更自身屬性或屬性的自訂元素。在這些情況下，如果 DOM 值變更，但透過 lit-html 綁定設定的值沒有變更，lit-html 將不知道要更新 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';

一個抽象的 Directive 基底類別，當包含指令的 Part 因重新渲染而被清除時，或當使用者對先前渲染包含該指令的 Part 呼叫 part.setConnected(false) 時 (例如，當 LitElement 從 DOM 斷開連線時)，將會呼叫其 disconnected 方法。

匯入

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

詳細資訊

如果後續在包含的 Part 上呼叫 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 接受兩個參數，即項目及其索引，並返回一個唯一的鍵值。

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

重要：如果提供 keyFn，則對於每次呼叫 repeat 中的所有項目，鍵必須是唯一的。當兩個或多個項目具有相同鍵時，行為是未定義的。如果未提供 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';

詳細資訊

鍵應為有效的 CSS 屬性名稱字串，例如 'background-color'，或為 CSSStyleDeclaration 的有效 JavaScript 駝峰式大小寫屬性名稱，例如 backgroundColor。

將 template 元素的内容呈現為 HTML。

匯入

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

簽名

templateContent(template): DirectiveResult<TemplateContentDirective>

參數

template

HTMLTemplateElement

詳細資訊

請注意，template 應由開發人員控制，而不是由使用者控制。使用此指令呈現使用者控制的 template 可能會導致跨網站指令碼漏洞。

用於建立自訂指令的基底類別。使用者應擴展此類別，實作 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 可以是第一個、最高優先級的參數，而非 Promise 的載入指示器範本可以用作第二個、較低優先級的參數。載入指示器會立即呈現，而主要內容會在 Promise 解析時呈現。範例

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

一個抽象的 Directive 基底類別，當包含指令的 Part 因重新渲染而被清除時，或當使用者對先前渲染包含該指令的 Part 呼叫 part.setConnected(false) 時 (例如，當 LitElement 從 DOM 斷開連線時)，將會呼叫其 disconnected 方法。

匯入

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

詳細資訊

如果後續在包含的 Part 上呼叫 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 的內聯條件式更為方便。