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>

規範

瀏覽器相容性

另見

• 使用自定義元素