CustomElementRegistry: метод define()

Метод define() интерфейса CustomElementRegistry добавляет определение пользовательского элемента в реестр пользовательских элементов, сопоставляя его имя с конструктором, который будет использоваться для его создания.

name

Имя нового пользовательского элемента. Должно быть валидным именем пользовательского элемента.

constructor

Конструктор нового пользовательского элемента.

options Необязательно

Объект, который управляет тем, как определяется элемент. В настоящее время поддерживается один параметр:

extends

Строка, указывающая имя встроенного элемента для расширения. Используется для создания настраиваемого встроенного элемента.

Ничего (undefined).

NotSupportedError DOMException

Выбрасывается, если:

• В CustomElementRegistry уже есть запись с таким же именем или таким же конструктором (или если он уже определен).
• Указан параметр extends и он является валидным именем пользовательского элемента
• Указан параметр extends, но элемент, который пытаются расширить, является неизвестным элементом.

SyntaxError DOMException

Выбрасывается, если указанное имя не является валидным именем пользовательского элемента.

TypeError

Выбрасывается, если указанный конструктор не является конструктором.

Метод define() добавляет определение пользовательского элемента в реестр пользовательских элементов, сопоставляя его имя с конструктором, который будет использоваться для его создания.

Существует два типа пользовательских элементов, которые вы можете создать:

• Автономные пользовательские элементы — это самостоятельные элементы, которые не наследуют от встроенных HTML-элементов.
• Настраиваемые встроенные элементы — это элементы, которые наследуют от и расширяют встроенные HTML-элементы.

Для определения автономного пользовательского элемента, следует опустить параметр options.

Для определения настраиваемого встроенного элемента, необходимо указать параметр options с свойством extends установленным в имя встроенного элемента, который вы расширяете, и это должно соответствовать интерфейсу, от которого наследуется определение вашего пользовательского элемента. Например, для настройки элемента <p>, вы должны передать {extends: "p"} в define(), и определение класса вашего элемента должно наследоваться от HTMLParagraphElement.

Имена пользовательских элементов должны:

• начинаться с строчной буквы латинского алфавита (a-z)
• содержать дефис
• не содержать прописных букв латинского алфавита
• не содержать определенные другие символы, как указано в разделе валидных имен пользовательских элементов в спецификации 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>

• Использование пользовательских элементов