CustomElementRegistry: define() 方法

语法

define(name, constructor)
define(name, constructor, options)

参数

name

新自定义元素的名称。必须是有效的自定义元素名称。

constructor

新自定义元素的构造函数。

options 可选

用于控制元素定义的配置对象。目前支持一种选项

extends

指定要扩展的内置元素的名称的字符串。用于创建定制的内置元素。

返回值

无（undefined）。

异常

NotSupportedError DOMException

在以下情况下抛出

• CustomElementRegistry 已包含同名或同构造函数的条目（或已以其他方式定义）。
• 指定了 extends 选项，并且它是一个有效的自定义元素名称
• 指定了 extends 选项，但它试图扩展的元素是一个未知元素。

SyntaxError DOMException

如果提供的名称不是有效的自定义元素名称，则抛出此异常。

TypeError

如果引用的构造函数不是构造函数，则抛出此异常。

描述

define() 方法将自定义元素的定义添加到自定义元素注册表中，将其名称映射到将用于创建它的构造函数。

您可以创建两种类型的自定义元素

• 自主自定义元素是独立的元素，不继承自内置 HTML 元素。
• 定制内置元素是继承自并扩展内置 HTML 元素的元素。

要定义自主自定义元素，应省略 options 参数。

要定义定制内置元素，您必须传递 options 参数，并将其 extends 属性设置为您正在扩展的内置元素的名称，并且这必须对应于您的自定义元素类定义所继承的接口。例如，要自定义 <p> 元素，您必须将 {extends: "p"} 传递给 define()，并且您的元素的类定义必须继承自 HTMLParagraphElement。

有效的自定义元素名称

自定义元素名称必须

• 以 ASCII 小写字母 (a-z) 开头
• 包含连字符
• 不包含任何 ASCII 大写字母
• 不包含某些其他字符，具体请参阅 Web Components 规范的有效自定义元素名称部分。
• 不能是以下任何一个
  • "annotation-xml"
  • "color-profile"
  • "font-face"
  • "font-face-src"
  • "font-face-uri"
  • "font-face-format"
  • "font-face-name"
  • "missing-glyph"

示例

定义自主自定义元素

以下类实现了一个最小的自主自定义元素

class MyAutonomousElement extends HTMLElement {
  constructor() {
    super();
  }
}

此元素不执行任何操作：真正的自主元素将在其构造函数和标准提供的生命周期回调中实现其功能。请参阅我们关于使用自定义元素的指南中的实现自定义元素。

但是，上面的类定义满足 define() 方法的要求，因此我们可以使用以下代码来定义它

customElements.define("my-autonomous-element", MyAutonomousElement);

然后我们可以在 HTML 页面中这样使用它

<my-autonomous-element>Element contents</my-autonomous-element>

定义定制内置元素

以下类实现了一个定制内置元素

class MyCustomizedBuiltInElement extends HTMLParagraphElement {
  constructor() {
    super();
  }
}

此元素扩展了内置的 <p> 元素。

在这个最小示例中，该元素没有实现任何自定义，因此它将像普通 <p> 元素一样工作。但是，它满足 define() 的要求，因此我们可以这样定义它

customElements.define(
  "my-customized-built-in-element",
  MyCustomizedBuiltInElement,
  {
    extends: "p",
  },
);

然后我们可以在 HTML 页面中这样使用它

<p is="my-customized-built-in-element"></p>

规范

浏览器兼容性

另见

• 使用自定义元素