String.raw() — Methode · JavaScript-Referenz

Signatur

String.raw(strings, ...substitutions)

Beschreibung

String.raw() ist eine statische Methode von String und wird meist als Tag-Funktion vor ein Template-Literal geschrieben: String.raw`...`. Sie gibt den Text genau so zurück, wie er im Quelltext steht. Escape-Sequenzen wie \n, \t oder \u00e9 werden also nicht umgewandelt, sondern bleiben als Backslash plus Zeichen erhalten. Platzhalter wie ${ausdruck} werden dagegen ganz normal ausgewertet und eingesetzt.

Das ist praktisch überall, wo Backslashes zum Inhalt gehören: Windows-Pfade, reguläre Ausdrücke für new RegExp(), LaTeX-Formeln oder Code-Schnipsel, die unverändert ausgegeben werden sollen. So musst du Backslashes nicht verdoppeln, und der Code bleibt deutlich lesbarer.

Man kann String.raw() auch direkt als Funktion aufrufen. Dann erwartet sie als erstes Argument ein Objekt mit einer Eigenschaft raw, die ein Array oder ein array-ähnliches Objekt aus Zeichenketten enthält. Die übrigen Argumente werden der Reihe nach zwischen diese Teilstücke gesetzt. Außerdem eignet sich String.raw als Hilfsfunktion in eigenen Tag-Funktionen, um die Teilstücke und Werte wieder zu einer Zeichenkette zusammenzufügen.

Parameter

Name	Typ	Default	Beschreibung
$strings Pflicht	{ raw: ArrayLike<string> }		Ein wohlgeformtes Template-Strings-Array, also ein Objekt mit der Eigenschaft `raw`. Beim Aufruf als Tag wird es automatisch übergeben.
$...substitutions	any		Die Werte der Platzhalter. Jeder Wert wird in eine Zeichenkette umgewandelt und zwischen `raw[i]` und `raw[i + 1]` eingesetzt.

Rückgabewert

Typ

string

Beschreibung

Die zusammengesetzte Roh-Zeichenkette mit eingesetzten Platzhalterwerten. Escape-Sequenzen bleiben dabei unverändert.

Beispiele

Windows-Pfad ohne doppelte Backslashes

const benutzer = 'anna';
const pfad = String.raw`C:\Users\${benutzer}\Documents\neu.txt`;
console.log(pfad);
console.log(pfad.length);

C:\Users\anna\Documents\neu.txt 30

Regulären Ausdruck lesbar aufbauen

const trenner = '-';
const muster = String.raw`^\d{4}${trenner}\d{2}${trenner}\d{2}$`;
const datumRegex = new RegExp(muster);

console.log(muster);
console.log(datumRegex.test('2024-05-17'));
console.log(datumRegex.test('17.05.2024'));

^\d{4}-\d{2}-\d{2}$ true false

Direkter Funktionsaufruf mit raw-Objekt

// Die Werte werden zwischen die raw-Teile gesetzt
const ergebnis = String.raw({ raw: ['Hallo ', ', du bist ', ' Jahre alt.'] }, 'Max', 42);
console.log(ergebnis);

// Ein String als raw wird Zeichen für Zeichen behandelt
console.log(String.raw({ raw: 'abc' }, '-', '+'));

Hallo Max, du bist 42 Jahre alt. a-b+c

String.raw in einer eigenen Tag-Funktion

// Tag-Funktion, die alle eingesetzten Werte in Großbuchstaben umwandelt
const laut = (strings, ...werte) =>
  String.raw(strings, ...werte.map((w) => String(w).toUpperCase()));

const name = 'welt';
console.log(laut`Hallo ${name}!\n`);

Hallo WELT!\n

// Wichtig · Fallstricke

Abschließender Backslash: String.raw`C:\` ist ein Syntaxfehler, weil \` das Backtick-Zeichen maskiert. Abhilfe: String.raw`C:\\` oder den Backslash mit ${'\\'} einsetzen.
Platzhalter werden ausgewertet: ${...} wird auch in Roh-Strings eingesetzt. Soll ${ wörtlich erscheinen, musst du es weiterhin maskieren. Bei \${ bleibt der Backslash dann aber im Ergebnis stehen.
Zeilenumbrüche im Quelltext bleiben als echte Umbrüche erhalten. \r\n im Quelltext wird dabei zu \n normalisiert.
Ungültige Escape-Sequenzen wie \unicode sind seit ES2018 in getaggten Templates erlaubt. Mit String.raw sind sie also unproblematisch, in normalen Template-Literalen sind sie dagegen ein Syntaxfehler.
Überzählige Werte in substitutions werden ignoriert. Ist strings kein Objekt mit raw (z. B. undefined), wird ein TypeError ausgelöst.
Sicherheit: String.raw maskiert nichts. Für HTML- oder SQL-Kontexte bietet es keinerlei Schutz vor Einschleusung.
Wird von allen modernen Browsern und von Node.js ab Version 4 unterstützt, aber nicht vom Internet Explorer.

Siehe auch

String RegExp String.prototype.concat() new RangeError() new Uint32Array()