CustomElementRegistry: define() 方法

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>

• 使用自定义元素