CustomElementRegistry: `define()`-Methode

name

Name für das neue benutzerdefinierte Element. Muss ein gültiger Name für benutzerdefinierte Elemente 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

String, der den Namen eines eingebauten Elements spezifiziert, um es zu erweitern. Wird verwendet, um ein angepasstes eingebautes Element zu erstellen.

Kein (undefined).

NotSupportedError DOMException

Wird ausgelöst, wenn:

• Das CustomElementRegistry bereits einen Eintrag mit demselben Namen oder Konstruktor enthält (oder bereits anderweitig definiert ist).
• Die Option extends angegeben ist und es sich um einen gültigen Namen für benutzerdefinierte Elemente handelt.
• Die Option extends angegeben ist, aber das Element, das erweitert werden soll, ein unbekanntes Element ist.

SyntaxError DOMException

Wird ausgelöst, wenn der angegebene Name kein gültiger Name für benutzerdefinierte Elemente ist.

TypeError

Wird ausgelöst, wenn der referenzierte Konstruktor kein Konstruktor ist.

Die define()-Methode fügt eine Definition für ein benutzerdefiniertes Element zum benutzerdefinierten Elementregister hinzu und ordnet dessen 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 eingebauten HTML-Elementen erben.
• Angepasste eingebaute Elemente sind Elemente, die von eingebauten HTML-Elementen erben und diese erweitern.

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

Um ein angepasstes eingebautes Element zu definieren, müssen Sie den options-Parameter mit seiner extends-Eigenschaft festlegen, die den Namen des eingebauten Elements angibt, das Sie erweitern möchten, und dies muss mit der Schnittstelle übereinstimmen, von der Ihre benutzerdefinierte Elementklassen-Definition erbt. Zum Beispiel, um das <p>-Element anzupassen, müssen Sie {extends: "p"} an define() übergeben, und die Klassendefinition für Ihr Element muss von HTMLParagraphElement erben.

Benutzerdefinierte Elementnamen müssen:

• mit einem ASCII-Kleinbuchstaben (a-z) beginnen
• einen Bindestrich enthalten
• keine ASCII-Großbuchstaben enthalten
• keine bestimmten anderen Zeichen enthalten, wie in der Abschnitt über gültige Namen für benutzerdefinierte Elemente der Web Components-Spezifikation dokumentiert
• keiner 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 vom Standard bereitgestellten Lifecycle-Rückrufen implementieren. Siehe Implementierung eines benutzerdefinierten Elements in unserem Leitfaden zur Arbeit mit benutzerdefinierten Elementen.

Jedoch erfüllt die obige Klassendefinition die Anforderungen der define()-Methode, sodass wir es 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 eingebautes Element:

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

Dieses Element erweitert das eingebaute <p>-Element.

In diesem minimalen Beispiel implementiert das Element keine Anpassungen, es wird sich also wie ein normales <p>-Element verhalten. Es erfüllt jedoch die Anforderungen von define(), sodass wir es so 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