База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / JavaScript

customElements.define — регистриране на персонализиран елемент

customElements.define свързва името на елемент с конструктор в регистъра на документа. Научете разликата между самостоятелните персонализирани елементи и персонализираните вградени елементи, както и основните ограничения при регистрация.

Версия: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Синтаксис

customElements.define(name, constructor);
customElements.define(name, constructor, { extends: baseLocalName });

customElements.define(name, constructor, options) регистрира дефиниция в регистъра, достъпен чрез window.customElements, и връща undefined, а не инстанция или обещание. Това е API на HTML Living Standard, а не функция на конкретно издание на ECMAScript. Съвременните браузърни машини поддържат самостоятелни персонализирани елементи; наличието на Node 24 в хранилище не доказва, че този API е достъпен.

Самостоятелният елемент използва клас, който наследява HTMLElement. Едно просто валидно име, например cktis-greeting, започва с малка ASCII буква, съдържа тире и не съдържа главни ASCII букви; някои имена също са запазени. Регистрацията позволява създаване на инстанции и надграждане на съответстващи елементи, които вече се намират в документа. Сама по себе си тя не добавя нов елемент в DOM.

Вариантът { extends: "button" } дефинира персонализиран вграден елемент: класът му наследява HTMLButtonElement, а инстанция се създава с document.createElement("button", { is: name }), а не с document.createElement(name). Проверете отделно поддръжката на този вариант в целевите браузъри.

Невалидно име причинява SyntaxError, а повторното използване на име или конструктор в същия регистър причинява NotSupportedError; и двете са изключения DOMException. Аргумент, който не е конструктор, причинява TypeError. Примерът задава съдържанието в connectedCallback, след като елементът е добавен; не добавяйте деца или атрибути в конструктора. Презаредете документа, преди да изпълните кода отново: премахването на инстанция не премахва дефиницията ѝ.

Примери

(() => {
  class CktisGreeting extends HTMLElement {
    connectedCallback() {
      this.textContent = "Hello!";
    }
  }

  customElements.define("cktis-greeting", CktisGreeting);
  const element = document.createElement("cktis-greeting");
  document.body.append(element);
  console.log(element.textContent);
  console.log(element instanceof CktisGreeting);
  element.remove();
})();

Резултат

Hello!
true

Показаният код и заявеният резултат са проверени в изолирана среда по метода, записан в доказателството за проверка на тази точна версия.

Източници