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

Syntax

js
toWellFormed()

Parameter

Keine.

Rückgabewert

Ein neuer String, der eine Kopie dieses Strings ist, mit allen alleinstehenden Surrogaten durch das Unicode-Ersatzzeichen U+FFFD ersetzt. Wenn str wohlgeformt ist, wird trotzdem ein neuer String zurückgegeben (im Wesentlichen eine Kopie von str).

Beschreibung

Strings in JavaScript sind UTF-16-codiert. Die UTF-16-Codierung enthält das Konzept der Surrogatpaare, welches im Abschnitt UTF-16-Zeichen, Unicode-Codepunkte und Graphem-Cluster ausführlich erläutert wird.

toWellFormed() iteriert durch die Codeeinheiten dieses Strings und ersetzt alle alleinstehenden 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 fehlerhaft geformte Strings in bestimmten Kontexten verwendet werden, wie z.B. bei TextEncoder, werden sie automatisch in wohlgeformte Strings umgewandelt, indem dasselbe Ersatzzeichen verwendet wird. Wenn alleinstehende Surrogate gerendert werden, werden sie ebenfalls als das Ersatzzeichen gerendert (ein Diamant mit einem Fragezeichen darin).

Beispiele

Verwendung von toWellFormed()

js
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"

Fehler in encodeURI() vermeiden

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 zu konvertieren.

js
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

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
toWellFormed

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support

Siehe auch