String.prototype.toWellFormed()

Baseline 2023

Newly available

Since October 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Die toWellFormed() Methode von String-Werten gibt einen String zurück, bei dem alle einsamen Surrogate dieses Strings durch das Unicode-Ersatzzeichen U+FFFD ersetzt werden.

Ein neuer String, der eine Kopie dieses Strings ist, wobei alle einsamen Surrogate durch das Unicode-Ersatzzeichen U+FFFD ersetzt wurden. Wenn str wohlgeformt ist, wird dennoch ein neuer String zurückgegeben (im Wesentlichen eine Kopie von str).

Beschreibung

Strings in JavaScript sind UTF-16 kodiert. In der UTF-16-Kodierung gibt es das Konzept der Surrogatpaare, das im Abschnitt über UTF-16-Zeichen, Unicode-Codepunkte und Graphemcluster ausführlich erläutert wird.

toWellFormed() durchläuft die Codeeinheiten dieses Strings und ersetzt alle einsamen Surrogate durch das Unicode-Ersatzzeichen U+FFFD �. Dies stellt sicher, dass der zurückgegebene String wohlgeformt ist und in Funktionen verwendet werden kann, die wohlgeformte Strings erwarten, wie z.B. encodeURI. Im Vergleich zu einer benutzerdefinierten Implementierung ist toWellFormed() effizienter, da Engines direkt auf die interne Darstellung von Strings zugreifen können.

Wenn schlecht geformte Strings in bestimmten Kontexten verwendet werden, wie zum Beispiel beim TextEncoder, werden sie automatisch in wohlgeformte Strings umgewandelt, indem das gleiche Ersatzzeichen verwendet wird. Wenn einsame Surrogate gerendert werden, werden sie ebenfalls als Ersatzzeichen gerendert (ein Diamant mit einem Fragezeichen darin).

Beispiele

Verwendung von toWellFormed()

const strings = [
  // Lone leading surrogate
  "ab\uD800",
  "ab\uD800c",
  // Lone trailing surrogate
  "\uDFFFab",
  "c\uDFFFab",
  // Well-formed
  "abc",
  "ab\uD83D\uDE04c",
];

for (const str of strings) {
  console.log(str.toWellFormed());
}
// Logs:
// "ab�"
// "ab�c"
// "�ab"
// "c�ab"
// "abc"
// "ab😄c"

Vermeidung von Fehlern in encodeURI()

encodeURI wirft einen Fehler, wenn der übergebene String nicht wohlgeformt ist. Dies kann vermieden werden, indem toWellFormed() verwendet wird, um den String zuerst in einen wohlgeformten String umzuwandeln.

const illFormed = "https://example.com/search?q=\uD800";

try {
  encodeURI(illFormed);
} catch (e) {
  console.log(e); // URIError: URI malformed
}

console.log(encodeURI(illFormed.toWellFormed())); // "https://example.com/search?q=%EF%BF%BD"

Spezifikationen

Specification
ECMAScript® 2025 Language Specification # sec-string.prototype.towellformed

String.prototype.toWellFormed()

Syntax

Parameter

Rückgabewert