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 Language Specification
# sec-string.prototype.towellformed

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch