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 einzelnen Surrogate dieses Strings durch das Unicode-Ersatzzeichen U+FFFD ersetzt werden.

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

Beschreibung

Strings in JavaScript sind UTF-16-codiert. Die UTF-16-Codierung hat das Konzept von Surrogatpaaren, das im Abschnitt UTF-16-Zeichen, Unicode-Codepunkte und Graphem-Cluster ausführlich erläutert wird.

toWellFormed() durchläuft die Code-Einheiten dieses Strings und ersetzt alle einzelnen Surrogate mit dem 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 etwa encodeURI. Im Vergleich zu einer benutzerdefinierten Implementierung ist toWellFormed() effizienter, da Engines direkt auf die interne Darstellung von Strings zugreifen können.

Wenn nicht wohldefinierte Strings in bestimmten Kontexten verwendet werden, wie zum Beispiel bei TextEncoder, werden sie automatisch in wohldefinierte Strings mit demselben Ersatzzeichen umgewandelt. Wenn einzelne 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 löst einen Fehler aus, wenn der übergebene String nicht wohldefiniert ist. Dies kann vermieden werden, indem toWellFormed() verwendet wird, um den String zuerst in einen wohldefinierten 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® 2026 Language Specification # sec-string.prototype.towellformed

String.prototype.toWellFormed()

Syntax

Parameter

Rückgabewert