CustomElementRegistry: define()-Methode

Syntax

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

Parameter

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. Er kann die folgenden Instanzmethoden haben (definiert auf constructor.prototype):

• connectedCallback
• disconnectedCallback
• connectedMoveCallback
• adoptedCallback
• attributeChangedCallback

Er kann die folgenden statischen Eigenschaften haben:

• observedAttributes: ein Array von Strings. Wird nur gelesen, wenn attributeChangedCallback definiert ist.
• disabledFeatures: ein Array, das die Werte "internals" und/oder "shadow" enthält.
• formAssociated: ein boolescher Wert.

Wenn formAssociated den Wert true hat, kann er zusätzlich die folgenden Instanzmethoden haben:

• formAssociatedCallback
• formResetCallback
• formDisabledCallback
• formStateRestoreCallback

Alle diese Methoden und Eigenschaften werden nur einmal abgerufen, wenn define() aufgerufen wird. Informationen zu ihrem Verhalten finden Sie unter Using custom elements.

options Optional

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

extends

String, der den Namen eines zu erweiternden integrierten Elements angibt. Wird verwendet, um ein angepasstes integriertes Element zu erstellen.

Rückgabewert

Keiner (undefined).

Ausnahmen

NotSupportedError DOMException

Wird ausgelöst, wenn:

• Die CustomElementRegistry bereits einen Eintrag mit demselben Namen oder demselben Konstruktor enthält (oder anderweitig bereits definiert ist).
• Die Option extends angegeben ist und ein gültiger Name für ein benutzerdefiniertes Element ist (d.h. Sie versuchen, ein benutzerdefiniertes Element zu erweitern).
• Die Option extends angegeben ist, das Element, das erweitert werden soll, jedoch ein unbekanntes Element ist.

SyntaxError DOMException

Wird ausgelöst, wenn der bereitgestellte Name kein gültiger Name für ein benutzerdefiniertes Element ist.

TypeError

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

Beschreibung

Die define()-Methode fügt dem Registry für benutzerdefinierte Elemente eine Definition für ein benutzerdefiniertes Element hinzu und ordnet dessen Namen dem Konstruktor zu, der zu seiner 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 Parameter options weglassen.

Um ein angepasstes integriertes Element zu definieren, müssen Sie den Parameter options übergeben, wobei seine Eigenschaft extends auf den Namen des integrierten Elements gesetzt ist, das Sie erweitern. Dies muss der Schnittstelle entsprechen, von der die Klassendefinition Ihres benutzerdefinierten Elements erbt. Um beispielsweise das Element <p> anzupassen, müssen Sie {extends: "p"} an define() übergeben, und die Klassendefinition Ihres Elements muss von HTMLParagraphElement erben.

Gültige Namen für benutzerdefinierte Elemente

Namen für benutzerdefinierte Elemente müssen:

• mit einem ASCII-Kleinbuchstaben (a-z) beginnen
• einen Bindestrich enthalten
• keine ASCII-Großbuchstaben enthalten
• keine ASCII-Leerzeichen, NULL, / oder > enthalten (jeweils U+0000, U+002F oder U+003E)
• keiner der folgenden Namen 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 bewirkt nichts: Ein echtes autonomes Element würde seine Funktionalität in seinem Konstruktor und in den vom Standard bereitgestellten Lifecycle-Callbacks implementieren. Siehe Implementing a custom element 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);

Anschließend könnten wir sie in einer HTML-Seite wie folgt verwenden:

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

Definieren eines angepassten integrierten Elements

Die folgende Klasse implementiert ein angepasstes integriertes Element:

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

Dieses Element erweitert das integrierte Element <p>.

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

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

Anschließend könnten wir es in einer HTML-Seite wie folgt verwenden:

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Using custom elements