CustomElementRegistry: define() Methode

name

Name für das neue benutzerdefinierte Element. Muss ein gültiger Name für ein benutzerdefiniertes Element sein.

constructor

Konstruktor für das neue benutzerdefinierte Element.

options Optional

Objekt, das steuert, wie das Element definiert wird. Eine Option wird derzeit unterstützt:

extends

Zeichenkette, die den Namen eines integrierten Elements angibt, das erweitert werden soll. Wird verwendet, um ein angepasstes integriertes Element zu erstellen.

Keiner (undefined).

NotSupportedError DOMException

Ausgelöst, wenn:

• Die CustomElementRegistry bereits einen Eintrag mit demselben Namen oder demselben Konstruktor enthält (oder bereits definiert ist).
• Die Option extends angegeben ist und es ein gültiger Name für ein benutzerdefiniertes Element ist.
• Die Option extends angegeben ist, aber das Element, das erweitert werden soll, ein unbekanntes Element ist.

SyntaxError DOMException

Ausgelöst, wenn der angegebene Name kein gültiger Name für ein benutzerdefiniertes Element ist.

TypeError

Ausgelöst, wenn der referenzierte Konstruktor kein Konstruktor ist.

Die define()-Methode fügt eine Definition für ein benutzerdefiniertes Element zur Registry für benutzerdefinierte Elemente hinzu und ordnet seinen Namen dem Konstruktor zu, der zur Erstellung verwendet wird.

Es gibt zwei Arten von benutzerdefinierten Elementen, die Sie erstellen können:

• Autonome benutzerdefinierte Elemente sind eigenständige Elemente, die nicht von integrierten HTML-Elementen erben.
• Angepasste integrierte Elemente sind Elemente, die von integrierten HTML-Elementen erben und diese erweitern.

Um ein autonomes benutzerdefiniertes Element zu definieren, sollten Sie den options-Parameter weglassen.

Um ein angepasstes integriertes Element zu definieren, müssen Sie den options-Parameter mit seiner extends-Eigenschaft übergeben, die auf den Namen des integrierten Elements gesetzt ist, das Sie erweitern, und das muss der Schnittstelle entsprechen, von der Ihre benutzerdefinierte Elementklassen-Definition erbt. Um beispielsweise das <p>-Element anzupassen, müssen Sie {extends: "p"} an define() übergeben, und die Klassendefinition für Ihr Element muss von HTMLParagraphElement erben.

Namen für benutzerdefinierte Elemente müssen:

• mit einem ASCII-Kleinbuchstaben (a-z) beginnen
• ein Bindestrich enthalten
• keine ASCII-Großbuchstaben enthalten
• nicht bestimmte andere Zeichen enthalten, wie in der gültige Namen für benutzerdefinierte Elemente-Sektion der Web-Components-Spezifikation dokumentiert
• keines der folgenden sein:
  • "annotation-xml"
  • "color-profile"
  • "font-face"
  • "font-face-src"
  • "font-face-uri"
  • "font-face-format"
  • "font-face-name"
  • "missing-glyph"

Die folgende Klasse implementiert ein minimales autonomes benutzerdefiniertes Element:

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

Dieses Element macht nichts: Ein echtes autonomes Element würde seine Funktionalität in seinem Konstruktor und in den von der Standard bereitgestellten Lebenszyklus-Callbacks implementieren. Siehe Implementieren eines benutzerdefinierten Elements in unserem Leitfaden zur Arbeit mit benutzerdefinierten Elementen.

Die obige Klassendefinition erfüllt jedoch die Anforderungen der define()-Methode, sodass wir sie mit folgendem Code definieren können:

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

Wir könnten es dann in einer HTML-Seite so verwenden:

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

Die folgende Klasse implementiert ein angepasstes integriertes Element:

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

Dieses Element erweitert das integrierte <p>-Element.

In diesem minimalen Beispiel implementiert das Element keine Anpassungen, sodass es sich wie ein normales <p>-Element verhält. Es erfüllt jedoch die Anforderungen von define(), sodass wir es folgendermaßen definieren können:

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

Wir könnten es dann in einer HTML-Seite so verwenden:

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

• Verwendung von benutzerdefinierten Elementen