ReactiveElement

当属性改变时，同步属性值。

参数

name

string

_old

null | string

value

null | string

详情

具体来说，当设置属性时，会设置相应的属性。你应该很少需要实现这个回调。如果覆盖了此方法，则必须调用super.attributeChangedCallback(name, _old, value)。有关 attributeChangedCallback 的更多信息，请参阅 MDN 上的使用生命周期回调。

返回与注册属性相对应的属性列表。

注册 ReactiveController 以参与元素的响应式更新周期。元素在生命周期回调期间自动调用任何已注册的控制器。

参数

controller

ReactiveController

详情

如果元素在调用 addController() 时已连接，则控制器的 hostConnected() 回调将立即被调用。

从元素中移除 ReactiveController。

参数

controller

ReactiveController

为该类禁用给定的警告类别。

详情

此方法仅存在于开发版本中，因此应使用以下保护措施访问它

// Disable for all ReactiveElement subclasses
ReactiveElement.disableWarning?.('migration');
// Disable for only MyElement and subclasses
MyElement.disableWarning?.('migration');

读取或设置该类所有启用的警告类别。

详情

此属性仅在开发版本中使用。

为该类启用给定的警告类别。

详情

此方法仅存在于开发版本中，因此应使用以下保护措施访问它

// Enable for all ReactiveElement subclasses
ReactiveElement.enableWarning?.('migration');
// Enable for only MyElement and subclasses
MyElement.enableWarning?.('migration');

在首次连接时，创建元素的 renderRoot，设置元素样式，并启用更新。

允许在扩展中使用super.disconnectedCallback()，同时保留在将来断开连接时进行非破坏性功能添加的可能性。

向类添加一个初始化函数，该函数在实例构造期间调用。

参数

initializer

Initializer

详情

这对于针对 ReactiveElement 子类运行的代码（如装饰器）很有用，这些代码需要为每个实例执行工作，例如设置 ReactiveController。

const myDecorator = (target: typeof ReactiveElement, key: string) => {
  target.addInitializer((instance: ReactiveElement) => {
    // This is run during construction of the element
    new MyController(instance);
  });
}

装饰一个字段将导致每个实例运行一个添加控制器的初始化程序

class MyElement extends LitElement {
  @myDecorator foo;
}

初始化程序按构造函数存储。向子类添加初始化程序不会将其添加到超类中。由于初始化程序在构造函数中运行，因此初始化程序将按类层次结构的顺序运行，从超类开始，一直到实例的类。

为注册的属性创建属性访问器，设置元素样式，并确保所有超类也被最终确定。如果元素已最终确定，则返回 true。

将类标记为已完成创建属性。

如果元素原型上不存在属性访问器，则创建它，并使用给定的选项存储属性的PropertyDeclaration。属性设置器调用属性的 hasChanged 属性选项或使用严格的标识检查来确定是否请求更新。

参数

name

PropertyKey

options?

PropertyDeclaration<unknown, unknown>

详情

此方法可以被覆盖以自定义属性；但是，在这样做时，重要的是要调用 super.createProperty 以确保属性被正确设置。此方法在内部调用 getPropertyDescriptor 来获取要安装的描述符。要自定义属性在获取或设置时的行为，请覆盖 getPropertyDescriptor。要自定义属性的选项，请按照以下方式实现 createProperty

static createProperty(name, options) {
  options = Object.assign(options, {myOption: true});
  super.createProperty(name, options);
}

所有元素属性的记忆列表，包括任何超类属性。在用户子类最终确定类时，延迟创建。

返回要在给定名称的属性上定义的属性描述符。如果未返回描述符，则该属性将不会成为访问器。例如，

参数

name

PropertyKey

key

string | symbol

options

PropertyDeclaration<unknown, unknown>

详情

class MyElement extends LitElement {
  static getPropertyDescriptor(name, key, options) {
    const defaultDescriptor =
        super.getPropertyDescriptor(name, key, options);
    const setter = defaultDescriptor.set;
    return {
      get: defaultDescriptor.get,
      set(value) {
        setter.call(this, value);
        // custom action.
      },
      configurable: true,
      enumerable: true
    }
  }
}

返回与给定属性关联的属性选项。这些选项通过 properties 对象或 @property 装饰器使用 PropertyDeclaration 定义，并在 createProperty(...) 中注册。

参数

name

PropertyKey

详情

注意，此方法应被视为“最终”方法，不应被覆盖。要自定义给定属性的选项，请覆盖 createProperty。

用户提供的对象，将属性名称映射到包含配置反应式属性选项的 PropertyDeclaration 对象。当设置反应式属性时，元素将更新并渲染。

详情

默认情况下，属性是公共字段，因此应将其视为主要由元素用户设置，无论是通过属性还是属性本身。通常，元素更改的属性应该是私有或受保护的字段，并且应该使用 state: true 选项。标记为 state 的属性不会从相应的属性中反映出来。但是，有时元素代码确实需要设置公共属性。这通常仅应在响应用户交互时完成，并且应触发一个事件来通知用户；例如，复选框在被点击时设置其 checked 属性并触发 changed 事件。对于非基本类型（对象或数组）属性，通常不应执行修改公共属性的操作。在其他情况下，当元素需要管理状态时，应使用带有 state: true 选项的私有属性。在需要时，可以使用公共属性初始化状态属性以促进复杂的交互。

返回元素应该渲染到的节点，并默认创建并返回一个开放的 shadowRoot。实现以自定义元素的 DOM 渲染位置。例如，要渲染到元素的 childNodes 中，请返回 this。

元素 DOM 应该渲染到的节点或 ShadowRoot。默认为开放的 shadowRoot。

调用 attachShadow 时使用的选项。设置此属性以自定义 shadowRoot 的选项；例如，要创建一个封闭的 shadowRoot：{mode: 'closed'}。

详情

注意，这些选项在 createRenderRoot 中使用。如果此方法是自定义的，则应尽可能尊重选项。

所有元素样式的记忆列表。在用户子类最终确定类时，延迟创建。

接受用户通过 static styles 属性提供的样式，并返回要应用于元素的样式数组。覆盖此方法以集成到样式管理系统中。

参数

styles?

CSSResultGroup

详情

样式是去重的，保留列表中的最后一个实例。这是一个性能优化，可以避免重复的样式，尤其是在通过子类化进行组合时。保留最后一个项目是为了尝试保留级联顺序，并假设最后添加的样式覆盖以前的样式最为重要。

要应用于元素的样式数组。样式应使用 css 标签函数、可构造样式表或从本机 CSS 模块脚本导入来定义。

详情

关于内容安全策略的说明：当浏览器不支持采用的样式表时，元素样式将使用 <style> 标签实现。要将此类 <style> 标签与 style-src CSP 指令一起使用，style-src 值必须包含 'unsafe-inline' 或 nonce-<base64-value>，其中 <base64-value> 被服务器生成的 nonce 替换。要提供一个 nonce 以在生成的 <style> 元素上使用，请在加载应用程序代码之前，将 window.litNonce 设置为页面 HTML 中的服务器生成的 nonce。

<script>
  // Generated and unique per request:
  window.litNonce = 'a1b2c3d4';
</script>

注意，此方法应被视为最终方法，不应被覆盖。它在元素实例上被一个触发第一个更新的函数覆盖。

参数

_requestedUpdate

boolean

当元素首次更新时调用。实现以在更新后对元素执行一次性操作。

参数

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

具有旧值的已更改属性的映射

详情

firstUpdated() {
  this.renderRoot.getElementById('my-text-area').focus();
}

在此方法内部设置属性将触发元素在此更新周期完成后再次更新。

updateComplete 承诺的覆盖点。

详情

由于 TypeScript 的一个限制，直接覆盖 updateComplete getter 不安全，这意味着当目标语言为 ES5 时，无法调用超类 getter（例如 super.updateComplete.then(...)）（https://github.com/microsoft/TypeScript/issues/338）。应改为覆盖此方法。例如

class MyElement extends LitElement {
  override async getUpdateComplete() {
    const result = await super.getUpdateComplete();
    await this._myChild.updateComplete;
    return result;
  }
}

在第一次更新后设置为 true。元素代码不能假设 renderRoot 在元素 hasUpdated 之前存在。

如果由于调用 requestUpdate() 而存在挂起的更新，则为真。应仅读取。

执行元素更新。注意，如果在更新期间抛出异常，firstUpdated 和 updated 不会被调用。

详情

调用 performUpdate() 以立即处理挂起的更新。通常不需要这样做，但在您需要同步更新的罕见情况下可以这样做。注意：为了确保 performUpdate() 同步完成挂起的更新，它不应该被覆盖。在 LitElement 2.x 中，建议覆盖 performUpdate() 来定制更新调度。现在您应该覆盖 scheduleUpdate()。为了与 LitElement 2.x 向后兼容，通过 performUpdate() 调度更新仍然有效，但将使同步处理更新的 performUpdate() 调用变得困难。

请求异步处理的更新。当元素应基于一些状态进行更新时，应调用此方法，该状态不是由设置响应式属性触发的。在这种情况下，不要传递任何参数。当手动实现属性 setter 时，也应调用此方法。在这种情况下，传递属性 name 和 oldValue 以确保遵守任何配置的属性选项。

参数

name?

PropertyKey

请求属性的名称

oldValue?

unknown

请求属性的旧值

options?

PropertyDeclaration<unknown, unknown>

要使用的属性选项，而不是之前配置的选项

调度元素更新。您可以通过返回一个 Promise 来覆盖此方法，从而更改更新的时序。更新将等待返回的 Promise，您应解决 Promise 以允许更新继续。如果覆盖了此方法，则必须调用 super.scheduleUpdate()。

详情

例如，要调度更新以便在下一帧之前发生

override protected async scheduleUpdate(): Promise<unknown> {
  await new Promise((resolve) => requestAnimationFrame(() => resolve()));
  super.scheduleUpdate();
}

控制元素请求更新时是否应调用 update()。默认情况下，此方法始终返回 true，但这可以自定义以控制何时更新。

参数

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

具有旧值的已更改属性的映射

更新元素。此方法将属性值反映到属性。它可以被覆盖以渲染和保持更新的元素 DOM。在此方法中设置属性将不会触发另一个更新。

参数

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

具有旧值的已更改属性的映射

返回一个 Promise，该 Promise 在元素完成更新时解析。Promise 值是一个布尔值，如果元素在没有触发另一个更新的情况下完成了更新，则为 true。如果 Promise 结果为 false，则在 updated() 中设置了属性。如果 Promise 被拒绝，则在更新期间抛出了异常。

详情

要等待其他异步工作，请覆盖 getUpdateComplete 方法。例如，有时在履行此 Promise 之前等待已渲染的元素很有用。为此，首先等待 super.getUpdateComplete()，然后等待任何后续状态。

每当元素更新时调用。实施以通过 DOM API 执行更新后的任务，例如，将焦点放在元素上。

参数

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

具有旧值的已更改属性的映射

详情

在此方法内部设置属性将触发元素在此更新周期完成后再次更新。

在 update() 之前调用，以计算更新过程中需要的值。

参数

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

详情

实施 willUpdate 来计算依赖于其他属性并在更新过程的其余部分中使用的属性值。

willUpdate(changedProperties) {
  // only need to check changed properties for an expensive computation.
  if (changedProperties.has('firstName') || changedProperties.has('lastName')) {
    this.sha = computeSHA(`${this.firstName} ${this.lastName}`);
  }
}
render() {
  return html`SHA: ${this.sha}`;
}

调用以将属性值转换为属性值。

参数

value

null | string

type?

TypeHint

调用以将属性值转换为属性值。

参数

value

Type

type?

TypeHint

详情

它返回 unknown 而不是 string，以与 https://github.com/WICG/trusted-types（以及类似的努力）兼容。

指示属性如何以及是否成为观察到的属性。如果值为 false，则不会将属性添加到 observedAttributes。如果为 true 或不存在，则观察小写属性名（例如 fooBar 变成 foobar）。如果为字符串，则观察字符串值（例如 attribute: 'foo-bar'）。

指示如何将属性转换为属性或从属性转换为属性。如果此值为函数，则它用于将属性值转换为属性值。如果它是一个对象，它可以包含 fromAttribute 和 toAttribute 的键。如果没有提供 toAttribute 函数并且 reflect 设置为 true，则属性值将直接设置为属性。如果没有提供，则使用默认的 converter；它支持 Boolean、String、Number、Object 和 Array。注意，当属性发生更改并且 converter 用于更新属性时，属性永远不会再次因为属性更改而更新，反之亦然。

指示是否将为该属性创建访问器。默认情况下，将为该属性生成一个访问器，该访问器在设置时请求更新。如果此标志为 true，则不会创建访问器，并且用户有责任调用 this.requestUpdate(propertyName, oldValue) 以在属性更改时请求更新。

指示属性是否应该反映到属性。如果为 true，则在设置属性时，将使用根据 attribute 属性选项的规则确定的属性名和使用 converter 属性选项的规则转换的属性值来设置属性。

当设置为 true 时，表示属性是内部私有状态。用户不应设置该属性。当使用 TypeScript 时，此属性应标记为 private 或 protected，并且在命名中使用前导 _ 也是一种常见的做法。该属性不会添加到 observedAttributes。

指示属性的类型。这仅用作 converter 的提示，以确定如何将属性转换为属性或从属性转换为属性。

一个函数，指示当设置属性时是否应将其视为已更改。该函数应接收 newValue 和 oldValue，如果应请求更新，则返回 true。

参数

value

Type

oldValue

Type