Symbol.toStringTag — Eigenschaft · JavaScript-Referenz

Signatur

Symbol.toStringTag

Beschreibung

Symbol.toStringTag ist eine statische Dateneigenschaft von Symbol und enthält eines der sogenannten bekannten Symbole (well-known symbols). Object.prototype.toString() fragt diese Eigenschaft am Objekt ab. Ist ihr Wert ein String, erscheint er als Tag in der Ausgabe [object Tag].

Viele eingebaute Objekte haben die Eigenschaft bereits, z. B. Map, Set, Promise, Symbol, ArrayBuffer, JSON, Math sowie Generator- und Async-Funktionen. Auch zahlreiche DOM- und Web-API-Objekte bekommen ihre Tags wie [object HTMLDivElement] auf diesem Weg. Bei Array, Date, RegExp, Error und Function ermittelt die Engine den Tag dagegen über interne Slots.

Eigene Klassen liefern ohne diese Eigenschaft nur [object Object]. Mit einem Getter get [Symbol.toStringTag]() machen Sie Ihre Objekte in Logs, beim Debuggen und bei generischen Typprüfungen über Object.prototype.toString.call() leichter erkennbar.

Die Eigenschaft selbst ist nicht beschreibbar, nicht aufzählbar und nicht konfigurierbar (writable: false, enumerable: false, configurable: false).

Rückgabewert

Typ

symbol

Beschreibung

Das bekannte Symbol Symbol.toStringTag. Nutzen Sie es als Eigenschaftsschlüssel, dessen Wert ein string sein sollte.

Beispiele

Eingebaute Tags auslesen

const tag = (value) => Object.prototype.toString.call(value);

console.log(tag(new Map()));
console.log(tag(Promise.resolve()));
console.log(tag(Symbol('x')));
console.log(tag(function* () {}));
console.log(tag(null));
console.log(new Map()[Symbol.toStringTag]);

[object Map] [object Promise] [object Symbol] [object GeneratorFunction] [object Null] Map

Eigene Klasse mit sprechendem Tag

class Warenkorb {
  #artikel = [];

  hinzufuegen(name) {
    this.#artikel.push(name);
    return this;
  }

  get [Symbol.toStringTag]() {
    return 'Warenkorb';
  }
}

const korb = new Warenkorb().hinzufuegen('Kaffee');
console.log(Object.prototype.toString.call(korb));
console.log(String(korb));
console.log(`${korb}`);

[object Warenkorb] [object Warenkorb] [object Warenkorb]

Generische Typprüfung in einer Hilfsfunktion

const typVon = (value) =>
  Object.prototype.toString.call(value).slice(8, -1);

const werte = [[], new Date(), /re/, new Set(), 42, 'text', undefined];
console.log(werte.map(typVon));

[ 'Array', 'Date', 'RegExp', 'Set', 'Number', 'String', 'Undefined' ]

Dynamischer Tag abhängig vom Zustand

class Verbindung {
  constructor() {
    this.offen = false;
  }
  get [Symbol.toStringTag]() {
    return this.offen ? 'Verbindung:offen' : 'Verbindung:geschlossen';
  }
}

const v = new Verbindung();
console.log(`${v}`);
v.offen = true;
console.log(`${v}`);

[object Verbindung:geschlossen] [object Verbindung:offen]

// Wichtig · Fallstricke

Keine zuverlässige Typprüfung: Jedes Objekt kann den Tag frei setzen, z. B. { [Symbol.toStringTag]: 'Array' } liefert [object Array]. Für echte Prüfungen nutzen Sie Array.isArray(), instanceof oder Brand-Checks mit privaten Feldern (#feld in obj).
Ist der Wert kein String, wird er ignoriert. Dann greift der Standard-Tag, meist Object.
Der Tag wirkt nur, wenn Object.prototype.toString tatsächlich aufgerufen wird. Überschreibt eine Klasse toString(), oder ruft Array.prototype.toString die Methode join auf, spielt der Tag keine Rolle.
Definieren Sie den Tag am besten als Getter auf dem Prototyp (get [Symbol.toStringTag]()) statt als Instanzfeld. So taucht er nicht in Object.keys() oder bei JSON.stringify auf. Als Symbol-Schlüssel ist er dort ohnehin ausgeschlossen.
Die Konsolen-Ausgabe (console.log(obj)) in Node.js und im Browser kann den Tag berücksichtigen, zum Beispiel Warenkorb [Warenkorb] {}. Das Format ist aber nicht standardisiert.
Kompatibilität: Baseline, alle modernen Browser und Node.js ab Version 6. In älteren Umgebungen wie dem Internet Explorer fehlt die Unterstützung.

Siehe auch

Object.prototype.toString() Symbol Symbol.toPrimitive Symbol.hasInstance Symbol.iterator Array.isArray() instanceof