CustomElementRegistry.getName() — Methode · JavaScript-Referenz

Signatur

CustomElementRegistry.prototype.getName(constructor)

Beschreibung

Die Methode getName() von CustomElementRegistry ist das Gegenstück zu get(). customElements.get(name) liefert zu einem Tag-Namen den Konstruktor. getName(constructor) geht den umgekehrten Weg: Sie liefert zu einer Klasse den Tag-Namen, unter dem sie mit customElements.define() registriert wurde.

Das ist vor allem in Bibliotheken und Basisklassen nützlich. Dort kennt man oft die Klasse, aber nicht den Namen, den der Nutzer für das Element gewählt hat. Mit getName() kann eine Komponente zum Beispiel document.createElement() aufrufen, CSS-Selektoren bauen oder Fehlermeldungen ausgeben, ohne den Tag-Namen fest im Code zu hinterlegen.

Ist der übergebene Konstruktor nicht registriert, gibt die Methode null zurück. Sie wirft also keinen Fehler. Damit eignet sie sich auch zur Prüfung, ob eine Klasse schon definiert wurde, bevor man define() aufruft. Ein Konstruktor lässt sich pro Registry nur unter einem Namen registrieren, deshalb ist das Ergebnis immer eindeutig.

Parameter

Name	Typ	Default	Beschreibung
$constructor Pflicht	Function		Die Konstruktorfunktion bzw. Klasse, deren registrierter Tag-Name gesucht wird. In der Regel eine von `HTMLElement` abgeleitete Klasse.

Rückgabewert

Typ

string | null

Beschreibung

Der registrierte Name des benutzerdefinierten Elements, z. B. "my-button", oder null, wenn der Konstruktor in dieser Registry nicht definiert ist.

Beispiele

Namen eines registrierten Elements abfragen

class MyCard extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hallo aus der Karte';
  }
}

class NotDefined extends HTMLElement {}

customElements.define('my-card', MyCard);

console.log(customElements.getName(MyCard));
console.log(customElements.getName(NotDefined));

my-card null

Instanzen erzeugen, ohne den Tag-Namen fest einzutragen

class BaseWidget extends HTMLElement {
  // Erzeugt ein neues Element der jeweiligen Unterklasse
  static create(props = {}) {
    const tag = customElements.getName(this);
    if (!tag) {
      throw new Error(`${this.name} ist nicht registriert`);
    }
    const el = document.createElement(tag);
    Object.assign(el.dataset, props);
    return el;
  }
}

class UserBadge extends BaseWidget {}
customElements.define('user-badge', UserBadge);

const badge = UserBadge.create({ user: 'anna' });
console.log(badge.outerHTML);

<user-badge data-user="anna"></user-badge>

Nur registrieren, wenn noch nicht definiert

const defineOnce = (name, ctor) => {
  const existing = customElements.getName(ctor);
  if (existing) {
    console.log(`Bereits registriert als <${existing}>`);
    return existing;
  }
  if (customElements.get(name)) {
    console.warn(`Name ${name} ist schon vergeben`);
    return null;
  }
  customElements.define(name, ctor);
  return name;
};

class ToastMessage extends HTMLElement {}
defineOnce('toast-message', ToastMessage);
defineOnce('toast-message', ToastMessage);

Bereits registriert als <toast-message>

Selektor für alle Instanzen einer Klasse bauen

class TodoItem extends HTMLElement {}
customElements.define('todo-item', TodoItem);

document.body.innerHTML = '<todo-item></todo-item><todo-item></todo-item>';

const tag = customElements.getName(TodoItem);
const items = document.querySelectorAll(tag);
console.log(`${items.length} Elemente vom Typ <${tag}>`);

2 Elemente vom Typ <todo-item>

// Wichtig · Fallstricke

Relativ neue Methode: getName() ist erst seit 2023 in allen großen Browsern verfügbar (Chrome/Edge 117, Firefox 116, Safari 17). Für ältere Umgebungen vorher prüfen: typeof customElements.getName === 'function'. Als Ausweichlösung kann man den Namen selbst speichern, etwa als statische Eigenschaft static tagName = 'my-el'.
Nur der exakte Konstruktor zählt: Die Methode sucht nicht in der Vererbungskette. Ist nur die Unterklasse registriert, liefert getName(Basisklasse) den Wert null.
Keine Ausnahme bei ungültigen Werten: Wird ein Wert übergeben, der kein registrierter Konstruktor ist (auch ein normales Objekt), liefert die Methode null statt eines Fehlers.
Registry-spezifisch: Das Ergebnis gilt nur für die abgefragte Registry. Jedes Fenster und jeder iframe hat ein eigenes customElements-Objekt.
Anders als whenDefined() arbeitet getName() synchron. Wird ein Element später definiert, liefert ein früherer Aufruf null.

Siehe auch

CustomElementRegistry.get() CustomElementRegistry.define() CustomElementRegistry.upgrade() CustomElementRegistry.initialize() CustomElementRegistry.whenDefined()