JavaScriptのString.fromCodePoint()：コードポイントから文字列を作る

数値で管理された文字を表示したいときに使う

文字データが、文字そのものではなくUnicodeのコードポイントとして渡されることがあります。例えば、記号の一覧を数値で管理する設定ファイルや、文字を選ぶ開発用ツールです。この数値をJavaScriptの文字列へ変換するのがString.fromCodePoint()です。

コードポイントは、Unicodeの文字空間における番号です。資料にあるU+3042は16進数表記で、JavaScriptでは数値リテラル0x3042として記述できます。この番号から「あ」を生成できます。

この記事では、数値から文字列を生成し、外部入力を受け取る場合には生成前に検証する流れを扱います。文字列から番号を調べる処理とは逆方向の操作です。仕様上の構文や引数はMDNのString.fromCodePoint()で確認できます。

動作環境とバージョン

String.fromCodePoint()はECMAScript 2015で導入された標準組み込みメソッドです。ブラウザー専用のDOM APIではなく、ブラウザーとNode.jsの両方で利用できます。

2026年11月13日時点で参照したMDNでは、2015年9月から主要ブラウザーで広く利用可能な機能とされています。本記事の利用対象は現行のChrome、Edge、Firefox、Safari、およびNode.js 22以降です。これらは本記事で選ぶ実行対象であり、導入された最小バージョンを意味しません。

Node.jsでは標準搭載の機能として利用し、追加パッケージや実験用フラグは不要です。Node.jsにおける標準機能と実験用フラグの関係は公式のECMAScript解説に説明があります。

古いブラウザーや組み込みのJavaScript環境では、呼び出す前にtypeof String.fromCodePoint === "function"で存在を確認してください。未対応の場合は、対応環境への更新や別実装の導入が必要です。

引数と戻り値を理解する

Stringに対して直接呼び出す

基本形はString.fromCodePoint(...codePoints)です。静的メソッドなので、文字列の変数ではなくStringに対して呼び出します。

• 引数はコードポイントを表す数値で、複数指定できます。
• 数値へ変換された値が、0以上0x10FFFF以下の整数である必要があります。
• 戻り値は、指定した順番に文字を連結した文字列です。
• 引数を省略すると空文字列になります。

例えばString.fromCodePoint(0x41, 0x42)の戻り値は"AB"です。配列を渡す場合は、String.fromCodePoint(...points)のようにスプレッド構文で各要素を引数へ展開します。

文字数とlengthは一致しないことがある

JavaScriptの文字列のlengthはUTF-16のコード単位数です。例えば「😀」は1つのコードポイントですが、UTF-16では2つのコード単位を使うため、生成した文字列のlengthは2になります。

さらに、見た目が1文字でも複数のコードポイントで構成される場合があります。入力した数値の個数、length、画面上の文字数は、それぞれ異なる尺度です。この区別はMDNのStringの解説で説明されています。

コピーして実行する基本例

次のコードは、ブラウザーとNode.jsで共通して使えます。外部ライブラリー、ネットワーク通信、事前の変数定義は必要ありません。

(() => {
  if (typeof String.fromCodePoint !== "function") {
    console.log("この環境はString.fromCodePoint()に未対応です");
    return;
  }

  const points = [0x41, 0x3042, 0x1F600];
  const text = String.fromCodePoint(...points);

  console.log(`生成結果: ${text}`);
  console.log(`UTF-16コード単位数: ${text.length}`);
  console.log(`引数なしは空文字列: ${String.fromCodePoint() === ""}`);
})();

ブラウザーでの実行方法

ブラウザーで空のページなどを開き、開発者ツールのConsoleを表示します。上のJavaScriptだけをコピーして実行してください。HTMLファイルや開発サーバーは不要です。

コード全体を即時実行関数で囲んでいるため、繰り返し貼り付けても、このコードの変数名による再宣言エラーを避けられます。Consoleが最後に表示するundefinedは、関数の戻り値の表示であり、次のログには含めません。

Node.jsでの実行方法

Node.jsを導入し、上のコードをUTF-8のfrom-code-point.cjsとして保存します。ターミナルで保存先のフォルダーへ移動し、次のコマンドを実行してください。.cjsを使うことで、周辺プロジェクトのモジュール設定に左右されにくくなります。

node --version
node from-code-point.cjs

ファイル名をnodeコマンドへ渡す実行方法はNode.js公式の実行ガイドでも確認できます。

期待出力

対応環境では、両方とも次のログになります。これは仕様から導いた期待値であり、本記事作成時に実機実行した結果ではありません。

生成結果: Aあ😀
UTF-16コード単位数: 4
引数なしは空文字列: true

Aと「あ」が各1コード単位、「😀」が2コード単位なので、合計は4です。絵文字の形や色はOSやフォントによって異なります。

不正な入力と例外に対処する

範囲外や小数はRangeErrorになる

負数、小数、NaN、上限を超える数値などを指定するとRangeErrorになります。例外が発生した呼び出しでは、途中まで作られた文字列を戻り値として受け取ることもできません。

次のコードは独立して実行できます。Node.jsでは別の.cjsファイルに保存し、基本例と同様に実行してください。

(() => {
  const invalidValues = [-1, 3.5, 0x110000, NaN];

  for (const value of invalidValues) {
    try {
      String.fromCodePoint(value);
      console.log("変換成功");
    } catch (error) {
      if (!(error instanceof RangeError)) {
        throw error;
      }
      console.log(`${String(value)}: ${error.name}`);
    }
  }
})();

期待出力は次のとおりです。

-1: RangeError
3.5: RangeError
1114112: RangeError
NaN: RangeError

エラーメッセージ本文はブラウザーによって異なるため、例ではerror.nameを表示しています。詳細はMDNのコードポイントに関するRangeErrorを参照してください。このAPIは同期処理なので、awaitやPromiseの拒否処理は必要ありません。

外部入力にはアプリ側の条件を追加する

このAPIには数値変換があるため、String.fromCodePoint("65")も"A"になります。入力仕様を「数値だけ」と決めたい場合は、APIの暗黙変換に任せず、先に型と範囲を検証します。

次は、数値の配列を受け取り、サロゲート領域も拒否する実用例です。サロゲート領域の拒否と件数制限は、この例が独自に追加する条件です。

(() => {
  function buildText(points) {
    if (!Array.isArray(points)) {
      throw new TypeError("数値の配列を指定してください");
    }
    if (points.length > 1000) {
      throw new RangeError("一度に指定できるのは1000件までです");
    }

    let result = "";
    for (const point of points) {
      if (typeof point !== "number") {
        throw new TypeError("各要素には数値を指定してください");
      }
      if (
        !Number.isInteger(point) ||
        point < 0 ||
        point > 0x10FFFF ||
        (point >= 0xD800 && point <= 0xDFFF)
      ) {
        throw new RangeError("Unicodeスカラー値を指定してください");
      }
      result += String.fromCodePoint(point);
    }
    return result;
  }

  try {
    console.log(buildText([0x3042, 0x3044, 0x3046]));
    console.log(buildText([0xD800]));
  } catch (error) {
    if (!(error instanceof Error)) {
      throw error;
    }
    console.log(`${error.name}: ${error.message}`);
  }
})();

期待出力は次のとおりです。

あいう
RangeError: Unicodeスカラー値を指定してください

buildText()は配列を引数に取り、検証が成功すれば文字列を返します。途中で不正値が見つかれば例外を投げ、部分的な結果は返しません。

制約と活用事例

String.fromCodePoint()自体は0xD800から0xDFFFまでの値も受け付けます。そのため、範囲内の整数であることだけでは、孤立サロゲートのない文字列になる保証はありません。上の実用例は各要素をUnicodeスカラー値に限定し、この問題を生成前に防いでいます。

また、変換に成功しても、その番号に表示可能な文字が割り当てられているとは限りません。制御文字や未割り当ての値もあり、フォントがなければ四角などで表示される場合があります。生成の成功と表示の保証は分けて考えましょう。

大量の配列を一度にスプレッド構文で渡す方法は、実行環境の引数数の上限にも注意が必要です。実用例では1要素ずつ変換し、さらに1000件というアプリ側の上限を設けています。1000件はJavaScriptの仕様上の制限ではありません。

活用先としては、文字選択ツール、Unicode番号付きのテストデータ生成、数値で保存された記号設定の表示が挙げられます。採用の判断基準は、入力の元データがコードポイントかどうかです。固定の文章なら、読みやすい文字列リテラルを使う方法も適しています。

実装を改善するなら、変換処理の入口で型、件数、許可する文字の範囲をまとめて検証してください。APIが扱える範囲と、業務上受け付けたい文字の範囲を明確にでき、後続処理での予期しない表示を減らせます。

公式参考資料

• MDN：String.fromCodePoint()の構文と仕様
• MDN：StringとUTF-16・コードポイントの関係
• MDN：不正なコードポイントによるRangeError
• Node.js：ECMAScript 2015以降の機能
• Node.js：コマンドラインからスクリプトを実行する