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.

toWellFormed() は String 値のメソッドで、この文字列のすべての孤立サロゲートを Unicode 置換文字 U+FFFD に置き換えた文字列を返します。

構文

js
toWellFormed()

引数

なし。

返値

この文字列のコピーで、孤立サロゲートをすべて Unicode 置換文字 U+FFFD に置き換えた新しい文字列です。 もし str が整形式 であれば、やはり新しい文字列が返されます（基本的には str のコピーです）。

解説

JavaScript の文字列は UTF-16 でエンコードされています。UTF-16 エンコーディングにはサロゲートペアという概念があり、これは UTF-16 文字、Unicode コードポイント、書記素クラスターで詳しく紹介されています。

toWellFormed() はこの文字列のコード単位を走査し、すべての孤立サロゲートをUnicode 置換文字 U+FFFD &#fffd; に置き換えます。これは、返す文字列が整形式であることを保証し、encodeURI のような整形式文字列を期待する関数で使用することができます。カスタム実装と比較して、toWellFormed() は、エンジンが文字列の内部表現に直接アクセスすることができるので、より効率的です。

整形式ではない文字列が TextEncoder のような特定の文脈で使用された場合、自動的に同じ置換文字を使って整形された文字列に変換されます。孤立サロゲートがレンダリングされるとき、それらは置換文字（疑問符が内側にある菱形）としてもレンダリングされます。

例

toWellFormed() の使用

js
const strings = [
  // 孤立上位サロゲート
  "ab\uD800",
  "ab\uD800c",
  // 孤立下位サロゲート
  "\uDFFFab",
  "c\uDFFFab",
  // 整形式
  "abc",
  "ab\uD83D\uDE04c",
];

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

encodeURI() のエラーを防止

encodeURI は渡された文字列が整形式でない場合、エラーを発生させます。これは toWellFormed() によって文字列を最初に整形式文字列に変換しておくことで防ぐことができます。

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"

仕様書

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

ブラウザーの互換性

関連情報