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

構文

toWellFormed()

引数

なし。

返値

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

解説

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

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

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

例

toWellFormed() の使用

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() によって文字列を最初に整形式文字列に変換しておくことで防ぐことができます。

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"

仕様書

ブラウザーの互換性

関連情報

• String.prototype.toWellFormed のポリフィル (core-js)
• es-shims によるString.prototype.toWellFormed のポリフィル
• String.prototype.isWellFormed()
• String.prototype.normalize()