指令

一个渲染异步可迭代对象 [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://mdn.org.cn/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

一个抽象 Directive 基类，其 disconnected 方法将在包含该指令的 Part 由于重新渲染而被清除时调用，或者当用户在先前渲染的包含该指令的 Part 上调用 part.setConnected(false) 时调用（例如，当 LitElement 断开与 DOM 的连接时）。

导入

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

详情

如果随后在包含的 Part 上调用 part.setConnected(true)，则该指令的 reconnected 方法将在其下一个 update/render 回调之前调用。 在实现 disconnected 时，还应实现 reconnected 以与重新连接兼容。 请注意，更新可能在指令断开连接时发生。 因此，指令通常应在渲染/更新期间检查 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://mdn.org.cn/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

一个抽象 Directive 基类，其 disconnected 方法将在包含该指令的 Part 由于重新渲染而被清除时调用，或者当用户在先前渲染的包含该指令的 Part 上调用 part.setConnected(false) 时调用（例如，当 LitElement 断开与 DOM 的连接时）。

导入

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

详情

如果随后在包含的 Part 上调用 part.setConnected(true)，则该指令的 reconnected 方法将在其下一个 update/render 回调之前调用。 在实现 disconnected 时，还应实现 reconnected 以与重新连接兼容。 请注意，更新可能在指令断开连接时发生。 因此，指令通常应在渲染/更新期间检查 this.isConnected 标志以确定是否可以安全地订阅可能阻止垃圾回收的资源。

通过缓存 DOM 节点和模板生成的 TemplateInstances，实现多个模板之间快速切换。

导入

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

签名

cache(v): 指令结果<缓存指令>

参数

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

数组<[T, () => V]>

defaultCase?

() => V

详情

Cases 的结构为 [caseValue, func]。value 通过严格相等匹配 caseValue。选择第一个匹配项。Case 值可以是任何类型，包括基本类型、对象和符号。这类似于 switch 语句，但作为表达式，没有 fallthrough。

一个应用动态 CSS 类的指令。

导入

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

签名

classMap(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): 指令结果<保护指令>

参数

_value

unknown

f

() => 未知

模板函数

详情

值使用严格相等 (===) 与之前的值进行检查，因此检查不会检测对象或数组内部的嵌套属性变化。数组值使用严格相等检查每个项目与之前值在同一索引处的匹配情况。嵌套数组也仅通过严格相等进行检查。示例

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';

对于 AttributeParts，如果值已定义，则设置属性；如果值未定义，则删除属性。

导入

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

签名

ifDefined(value): 无 | 非空可空<T>

参数

value

T

详情

对于其他部分类型，此指令是无操作的。

返回一个可迭代对象，其中包含 items 中的值与 joiner 值交错。

导入

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

签名

join(items, joiner): 可迭代<I | J>

参数

items

undefined | 可迭代<I>

joiner

(index: 数字) => J

将可渲染值与唯一键关联。当键发生变化时，在渲染下一个值之前，会先移除并释放之前的 DOM，即使值（例如模板）相同。

导入

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

签名

keyed(k, v): 指令结果<键控>

参数

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): 指令结果<Live 指令>

参数

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<未知, void, 未知>

参数

items

未定义 | Iterable<T>

f

(value: T, index: 数字) => 未知

返回一个从 start 到 end（不包括 end）的整数可迭代对象，以 step 为增量。

导入

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

签名

range(end): Iterable<数字>

参数

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): 指令结果<Ref 指令>

参数

_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 基类，其 disconnected 方法将在包含该指令的 Part 由于重新渲染而被清除时调用，或者当用户在先前渲染的包含该指令的 Part 上调用 part.setConnected(false) 时调用（例如，当 LitElement 断开与 DOM 的连接时）。

导入

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

详情

如果随后在包含的 Part 上调用 part.setConnected(true)，则该指令的 reconnected 方法将在其下一个 update/render 回调之前调用。 在实现 disconnected 时，还应实现 reconnected 以与重新连接兼容。 请注意，更新可能在指令断开连接时发生。 因此，指令通常应在渲染/更新期间检查 this.isConnected 标志以确定是否可以安全地订阅可能阻止垃圾回收的资源。

导入

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

类型

一个重复从可迭代对象生成的系列值（通常是 TemplateResults）的指令，并在可迭代对象根据用户提供的与每个项目关联的 keys 发生变化时有效地更新这些项目。

导入

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

签名

repeat(items, keyFnOrTemplate, template?): 未知

参数

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 对象上设置。没有连字符的名称被认为是 camelCased 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。

将模板元素的内容呈现为 HTML。

导入

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

签名

templateContent(template): DirectiveResult<TemplateContentDirective>

参数

template

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 加载指示器模板作为第二个、优先级较低的参数。加载指示器将立即呈现，当 Promise 解析时，主要内容将呈现。示例

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

一个抽象 Directive 基类，其 disconnected 方法将在包含该指令的 Part 由于重新渲染而被清除时调用，或者当用户在先前渲染的包含该指令的 Part 上调用 part.setConnected(false) 时调用（例如，当 LitElement 断开与 DOM 的连接时）。

导入

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

详情

如果随后在包含的 Part 上调用 part.setConnected(true)，则该指令的 reconnected 方法将在其下一个 update/render 回调之前调用。 在实现 disconnected 时，还应实现 reconnected 以与重新连接兼容。 请注意，更新可能在指令断开连接时发生。 因此，指令通常应在渲染/更新期间检查 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 语句的情况下编写内联条件语句更加简洁。