CustomElementRegistry: define()-Methode

Syntax

define(name, constructor)
define(name, constructor, options)

Parameter

name

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

constructor

Konstruktor für das neue benutzerdefinierte Element.

options Optional

Objekt, das steuert, wie das Element definiert wird. Derzeit wird eine Option unterstützt:

extends

Zeichenkette, die den Namen eines eingebauten Elements angibt, das erweitert werden soll. Verwendet, um ein angepasstes, eingebautes Element zu erstellen.

Rückgabewert

Keiner (undefined).

Ausnahmen

NotSupportedError DOMException

Wird ausgelöst, wenn:

• Das CustomElementRegistry bereits einen Eintrag mit demselben Namen oder demselben Konstruktor enthält (oder anderweitig bereits definiert ist).
• Die extends-Option angegeben ist und es sich um einen gültigen benutzerdefinierten Elementnamen handelt (d.h. Sie versuchen, ein benutzerdefiniertes Element zu erweitern).
• Die extends-Option 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 benutzerdefinierter Elementname ist.

TypeError

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

Beschreibung

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 übergeben, die auf den Namen des eingebauten Elements gesetzt ist, das Sie erweitern, und dies muss mit der Schnittstelle übereinstimmen, von der Ihre benutzerdefinierte Elementklassendefinition 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.

Gültige benutzerdefinierte Elementnamen

Benutzerdefinierte Elementnamen müssen:

• mit einem ASCII-Kleinbuchstaben (a-z) beginnen
• einen Bindestrich enthalten
• keine ASCII-Großbuchstaben enthalten
• keine ASCII-Leerzeichen, NULL, / oder > enthalten (U+0000, U+002F oder U+003E, jeweils)
• nicht einer der folgenden sein:
  • "annotation-xml"
  • "color-profile"
  • "font-face"
  • "font-face-src"
  • "font-face-uri"
  • "font-face-format"
  • "font-face-name"
  • "missing-glyph"

Beispiele

Definieren eines autonomen benutzerdefinierten Elements

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 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 es mit dem folgenden Code definieren können:

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

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

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

Definieren eines angepassten eingebauten Elements

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, 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 auf einer HTML-Seite so verwenden:

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Verwenden benutzerdefinierter Elemente