HTML エンティティ エンコーダー＆デコーダー：技術アーキテクチャと詳細実践ガイド
HyperText Markup Language（HTML）は、ワールドワイドウェブ（WWW）の構造的基盤を担うマークアップ言語です。[WHATWG HTML Living Standard](https://html.spec.whatwg.org/) および W3C 仕様によって厳格に形式化されている HTML 構文において、一部の記号文字——とりわけアンパサンド（&）、山括弧（<、>）、お
ブラウザ上で100%ローカル実行・サーバー通信ゼロで即座に利用可能。
# HTML エンティティ エンコーダー＆デコーダー：技術アーキテクチャと詳細実践ガイド
HyperText Markup Language（HTML）は、ワールドワイドウェブ（WWW）の構造的基盤を担うマークアップ言語です。WHATWG HTML Living Standard および W3C 仕様によって厳格に形式化されている HTML 構文において、一部の記号文字——とりわけアンパサンド（&）、山括弧（<、>）、およびクォーテーション（"、'）——は、タグとプレーンテキストの境界を決定づける構文デリミタ（構文予約文字）として特別に予約されています。
サニタイズ（無害化）されていない生テキストにこれらの予約文字が含まれている場合、ブラウザの HTML パーサーはテキスト入力をマークアップタグや属性定義と誤認し、レイアウト崩壊、属性トランケーション（属性値の予期せぬ切断）、さらには致命的なクロスサイトスクリプティング（XSS: Cross-Site Scripting）脆弱性を引き起こす原因となります。これらの文字をテキストノード（PCDATA）として決定論的かつ安全に描画するため、Web アプリケーションは予約文字を HTML エンティティ（文字参照: Character References） へと変換する必要があります。
ToolsAA HTML エンティティ エンコーダー＆デコーダー（HTML Entity Encoder & Decoder Online） は、高精度な HTML エンティティ エンコード、双方向の HTML 特殊文字 デコード、および XSS 対策・サニタイズ処理を提供するエンジニア向け開発スイートです。完全なゼロ知識・クライアントサイド実行アーキテクチャ（"use client"）を基盤としており、文字トークン化、辞書マッピング、Unicode コードポイント計算などのすべての処理はお使いのブラウザ内部のローカルメモリ上で 100% 完結します。機密性の高い HTML テンプレート、ソースコード、顧客データを含むパケットは、外部サーバーへ 1 バイトたりとも送信されません。
# 包括的概要と実践的なユースケース
HTML 文字実体参照および数値文字参照は、SGML および XML 文法に準拠した標準化シーケンスを用いて、構文予約文字、不可視文字、あるいは非 ASCII 文字を代替表現する仕組みです。すべてのエンティティは先頭のアンパサンド（&）で開始され、末尾のセミコロン（;）で終了します。この境界の内部に、可読性の高いアルファベット略号（名前付き文字実体参照 / Named Entity Reference）または Unicode コードポイント（数値文字参照 / Numeric Character Reference: NCR）が配置されます。
+---------------------------------------------------------------------------------------------------+
| HTML 文字参照の構造解剖図（Anatomy） |
| 名前付き参照: & amp ; --> 解決先文字: '&' (U+0026) |
| [接頭辞] [ニーモニック] [終端子] |
| 10進数NCR: &# 38 ; --> 解決先文字: '&' (10進数 Unicode) |
| [接頭辞] [10進コード] |
| 16進数NCR: &#x 26 ; --> 解決先文字: '&' (16進数 Unicode) |
| [接頭辞] [16進コード] |
+---------------------------------------------------------------------------------------------------+# 開発・運用現場における主要エンタープライズユースケース
- クロスサイトスクリプティング（XSS）の根本的防御: 不信なユーザー入力を HTML コンテキストに出力する際、
<を<に、>を>にエスケープすることで、ブラウザパーサーに実行可能 DOM ノードではなくプレーンテキスト（PCDATA）として解釈させ、悪意ある<script>や<img>のインジェクションを無害化します。 - 技術ドキュメントや CMS でのソースコード表示: literal な HTML や JSX スニペットを
<code>や<pre>ブロック内で正しく表示するために不可欠です。例えば<div class="hero">を<div class="hero">へ変換することで、マークアップの誤評価を防ぎます。 - 動的フォーム属性のインジェクション防止:
<input value="...">や<a href="...">などの HTML 属性値に動的変数を埋め込む際、二重引用符（"→"）や単一引用符（'→'）を適切にエスケープし、属性値の途中終了による属性脱出（Attribute Injection）攻撃を阻止します。 - タイポグラフィと国際化記号の一貫性維持: 改行禁止スペース（
）、左・右ダブルクォート（“/”）、ダッシュ記号（—）、著作権表示（©）などをプラットフォーム間で文字化けを起こさずに統一的に描画します。 - XML および SVG データフィードの適合性確保: strict な XML 1.0 仕様では、エスケープされていない生のアンパサンド（
&）が存在するだけでパーサーが致命的エラー（Fatal Parse Error）をスローして停止します。RSS フィード、Sitemap.xml、インライン SVG の生成において厳格なエンコードが必須となります。
# クライアントサイド処理（ローカル実行）がプライバシー保護に不可欠な理由
一般的なオンライン HTML エスケープツールの多くは、ユーザーがフォームに貼り付けたテキストを HTTP リクエスト経由でリモートサーバーへ送信し、バックエンド側で変換を行ってレスポンスを返す構成を採っています。しかし、開発業務でエスケープやアンエスケープを必要とするテキストには、極めて秘匿性の高い情報が含まれるのが通例です。
社内リポジトリの未公開ソースコード、機密データベースのスキーマ、顧客の個人情報（PII）、API シークレット、OAuth トークン、あるいは企業の内部ドキュメントなどがその代表例です。これらを外部の第三者サーバーへ送信すると、リモートサーバーのアクセスログ、リバースプロキシのキャッシュ、WAF のパケットバッファ、アナリティクス基盤にデータが永続化される危険に晒され、GDPR、HIPAA、SOC 2、および日本の個人情報保護法（APPI）における重大なコンプライアンス違反・情報漏洩インシデントに発展します。
ToolsAA は、厳格な ゼロサーバー処理モデル（Zero-Server Architecture） を徹底しています。すべての構文解析、正規表現による文字列置換、および Unicode コードポイントの数学的変換処理は、お使いのブラウザ内部でサンドボックス化された JavaScript 仮想マシン上でのみ実行されます。ネットワーク通信は一切発生しないため、最高機密の企業アセットであっても安全に処理を完結できます。
# 技術アーキテクチャと内部動作原理
HTML エンティティ処理を正確にマスターするためには、SGML の歴史的慣習、XML 1.0 の厳密性、WHATWG Living Standard の最新規則、そして JavaScript ランタイムにおけるメモリモデルと文字エンコーディングの境界線を体系的に理解する必要があります。
+-----------------------------------------------------------------------------------------+
| HTML エンティティ処理パイプラインのアーキテクチャ概要 |
+-----------------------------------------------------------------------------------------+
入力文字列（Raw Text / HTML Source）
|
v
[ UTF-16 サロゲートペア検出とコードポイント特定 ] : codePointAt(i)
|
+---> 基本多言語面 (BMP: U+0000 〜 U+FFFF) : 1コードユニット (16-bit)
+---> 補助文字・絵文字 (Astral: U+10000 〜 U+10FFFF) : サロゲートペア計算 (32-bit)
|
v
[ トークン評価とエスケープ変換 ]
|
+---> 予約デリミタ (&, <, >, ", ') ---> 名前付き実体参照 / 10進NCR
+---> 非 ASCII / 特殊記号 ---> 16進NCR / 10進NCR
+---> 通常の ASCII 文字 ---> そのまま保持
|
v
[ 配列バッファ結合（Array-Buffered Chunking） ] : chunks.join("") [O(N) 線形時間]
|
v
出力文字列（完全にサニタイズされた HTML エンティティ文字列）# 1. 標準規格の系譜と差異: HTML 4.01 vs XML 1.0 vs WHATWG Living Standard
Web プラットフォームにおけるエンティティ仕様は、3 つの主要規格の間で差異が存在します。
- XML 1.0（W3C 勧告）: 定義済みエンティティとして認めるのはわずか 5 種類（
&,<,>,",'）のみです。DTD（Document Type Definition）で明示的に定義されていない名前付きエンティティ（例:©や ）を含む XML 文書は構文不正（Well-formedness Error）となります。ただし、数値文字参照（NCR:©等）は DTD なしで常に有効です。 - HTML 4.01（RFC 1866 / W3C 勧告）: 252 個の名前付き文字実体参照を標準化しました。しかし重大な歴史的欠落として、シングルクォート用の
'が仕様から除外されていたため、古い Internet Explorer やレガシーな HTML メール描画エンジンでは'が未定義エンティティとしてそのまま露出・文字化けする問題が頻発しました。 - WHATWG HTML Living Standard: 現代のブラウザ実装が準拠する最新標準であり、数学記号、ギリシャ文字、各種ダイアクリティカルマークを含む合計 2,231 個の名前付き文字参照を網羅的にカタログ化しています。また、セミコロンが省略された不正なレガシー記述（例:
© 2026）に対する決定論的な構文復旧（Error Recovery）規則も厳密に規定されています。
# 2. Unicode と UTF-16 サロゲートペアのバイトレベル力学
JavaScript の文字列プリミティブは、内部的に UTF-16 コードユニット（16 ビット固定幅）のシーケンスとして格納されます。Unicode の基本多言語面（BMP: Basic Multilingual Plane、U+0000 〜 U+FFFF）に属する文字は 1 つのコードユニット（16 ビット）で表現可能ですが、絵文字（例: 🚀 U+1F680）や古代文字などのアストラルプレーン（追加面: U+10000 〜 U+10FFFF）に属する文字は、2 つの 16 ビット値からなるサロゲートペア（Surrogate Pair）（上位サロゲート: 0xD800 〜 0xDBFF、下位サロゲート: 0xDC00 〜 0xDFFF）として表現されます。
古いナイーブなエンコーダーで多用された charCodeAt() は 16 ビット単位でしか文字を評価できないため、サロゲートペアを分割してしまい、�� という不正で破損した 2 つのエンティティを出力してしまいます。ToolsAA では、32 ビット Unicode スカラー値を正しく取得できる codePointAt() を採用し、以下の数学的関係式に基づいて統合コードポイントを算出します。
$$\text{CodePoint} = ((\text{High} - 0\text{xD800}) \times 0\text{x400}) + (\text{Low} - 0\text{xDC00}) + 0\text{x10000}$$
この計算により、アストラルプレーンの文字であっても、正当な単一の数値文字参照（10進数: 🚀、16進数: 🚀）として欠落なく出力されます。
# 3. エンティティ形式の比較: 名前付き実体参照 vs 10進数 NCR vs 16進数 NCR
HTML エンティティには、用途と構文に応じて 3 種類の記述形式が存在します。
- 名前付き文字実体参照（Named Entity Reference:
&name;）: 人間が直感的に読解可能なアルファベットニーモニック（例:&,<,©,€）です。ブラウザ内蔵の辞書テーブルを参照して解決されます。 - 10進数数値文字参照（Decimal NCR:
&#[0-9]+;）: Unicode コードポイントを 10 進数の整数値で指定する形式（例:&,<,©,€）です。DTD の宣言を必要とせず、あらゆる HTML / XML パーサーで普遍的かつ確実に解釈されます。 - 16進数数値文字参照（Hexadecimal NCR:
&#x[0-9a-fA-F]+;）: Unicode コードポイントを 16 進数値で指定する形式（例:&,<,©,€）です。Unicode コードチャート（U+XXXX）と直接対応しており、XML フィードやバイナリデータのテキスト化において好まれます。
# 4. DOMParser & トークン分離: なぜ innerHTML はアンチパターンなのか
Web 開発者が HTML エンティティのデコードを行う際、オフスクリーン DOM 要素を作成して div.innerHTML = encodedStr; return div.textContent; とする簡便な手法が長年紹介されてきました。しかし、このアプローチはエンタープライズ製品において極めて危険なアンチパターンです。
- DOM ベース XSS の即時発火: 渡された文字列にアンエスケープ後に有効となる悪意あるタグ（例:
<img src=x onerror=alert(1)>や<svg onload=fetch(...)>）が含まれていた場合、innerHTMLに代入した瞬間にブラウザの HTML パーサーがスクリプトを実行し、セッションハイジャック等の攻撃が成立します。 - 意図しないマークアップの剥奪（Tag Stripping）: デコード対象の文字列がコードスニペットを含んでいる場合（例:
<code><div>Hello</div></code>）、innerHTMLは内部を実際の DOM 要素ツリーとして解釈してしまい、続くtextContent抽出時に外側のタグ構造が消滅・変質します。 - 不要な外部ネットワークリクエスト: 代入された HTML 内に
<img>や<link>タグが存在すると、ブラウザが非同期で外部画像やスタイルシートのリクエストを発行してしまい、パフォーマンス低下やリファラ漏洩の原因となります。
ToolsAA は、DOM パーサーを介さない純粋な正規表現パースと不変辞書マップによるトークン分離（Token Isolation Architecture） を採用しています。正規表現 /&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);/g を用いてエンティティトークンのみを抽出し、不変ルックアップテーブルおよび厳格な数値バリデーションを通じて文字を直接復元するため、DOM 実行環境への波及リスクを完全に遮断します。
# 5. ブラウザ Web API、パフォーマンスと並行処理設計
ToolsAA は、大規模な HTML ペイロードであってもデスクトップアプリ同様の軽快な応答性を担保するため、以下の最新 Web アーキテクチャを導入しています。
- React 18+ 並行処理（
useDeferredValue）: ユーザーによるタイピング入力イベントと、バックグラウンドでの重い構文解析・エンコード処理を分離。数万文字規模の HTML テンプレートを入力しても、入力欄の 60 FPS 追従性を維持します。 - Array-Buffered Chunking: 文字列の反復的な
+連結（$O(N^2)$ のメモリ再割り当て）を排除し、変換結果をスライスごとに配列バッファへ蓄積して最後にchunks.join("")で一括結合することで、$O(N)$ の線形時間処理を実現しています。 - オフスクリーン HTML5 Canvas レンダリング: 入力文字列に含まれる文字種別（ASCII、ラテン拡張、CJK 漢字、絵文字、エスケープ文字）の構成比率メトリクスを、DOM リフローを一切発生させないオフスクリーン
<canvas>上で直接描画します。 - Web Crypto & WASM パイプライン: 1 MB を超える巨大ペイロードの整合性検証にはブラウザネイティブの
window.crypto.subtle.digest("SHA-256")を用い、高速トークナイザーによるゼロレイテンシ処理を達成しています。
# ステップ・バイ・ステップ実践チュートリアル
ToolsAA HTML エンティティ エンコーダー＆デコーダーの直感的なインターフェースを活用し、様々な要件に応じたエスケープおよびデコードを実施する手順を解説します。
# ステップ 1: データの入力とプリセットの読み込み
変換対象のテキスト、HTML マークアップ、またはエンコード済み文字列を入力ペインに貼り付けます。 右上の「プリセット」から、現場で頻出する設定テンプレートをワンクリックで読み込むことも可能です。
- XSS 防御（XSS Defense）: 安全なテキスト出力のための 5 大デリミタ設定
- XML/SVG クリーン（XML/SVG Clean）: DTD なしで動作する数値文字参照設定
- タイポグラフィ（Typography）:
、©、—などの印刷記号変換
また、ローカルの .html、.txt、.jsx ファイルをドラッグ＆ドロップするか、ファイル選択ダイアログ経由でネイティブ FileReader API を通じて直接読み込むこともできます。
# ステップ 2: 変換スコープとエンコードフォーマットの選択
システムの伝送要件や受け入れ側のパーサー仕様に合わせて、エンコードスコープを指定します。
- Essential Only（主要構文文字のみ / XML Safe）: HTML および XML の骨格を成す 5 つのコア記号（
&,<,>,",'）のみをエスケープします。通信ペイロードの肥大化を抑えつつ安全性を確保する標準設定です。 - Non-ASCII Characters（非 ASCII 文字すべて）: ASCII 領域（
U+0000〜U+007F）の通常文字を維持しつつ、127 を超える文字コード（日本語のひらがな・漢字、アクセント記号、絵文字など）をすべて数値文字参照へ変換します。レガシーな 7 ビット ASCII 専用メールプロトコル等へのデータ送信に最適です。 - All Characters（全文字変換 / 難読化）: 文字列に含まれるすべての文字を数値文字参照へ変換します。
- 出力形式として、名前付き実体参照（Named:
&）、10進数数値文字参照（Decimal:&）、16進数数値文字参照（Hex:&） をタブで自由に切り替え可能です。
# ステップ 3: きめ細やかなエスケープオプションの設定
プロジェクト固有のコーディング規約に合わせ、詳細トグルを調整します。
- クォートの個別制御: 単一引用符（
'）と二重引用符（"）の変換可否を個別に選択できます。単一引用符はレガシー互換性を最優先し、デフォルトで安全な'へマッピングされます。 - 改行禁止スペースの変換: 半角空白がブラウザで連続して折りたたまれるのを防ぐため、ノーブレークスペース（
\u00A0）を明示的に へ変換します。 - 改行コードの
<br />変換: 掲示板やメール本文の表示向けに、改行文字（\n）を自動的に<br />タグへ置換します。
# ステップ 4: 安全な双方向デコード（HTMLデコード処理）
エンティティ化されたテキストを元のリテラル文字へと復元する場合、「デコード（Decode）」タブを選択します。
- 統合抽出デコード: 名前付き参照（
&）、10進数 NCR（&）、16進数 NCR（&）が混在している文字列であっても、単一パスで安全に一括復元します。 - レガシー末尾セミコロン解決: 過去のクアークスモード等で出力されたセミコロン欠落エンティティ（例:
© 2026）も自動認識して正しくデコードします。 - 改行タグの正規化:
<br>や<br />タグを標準の改行コード（\n）へと戻します。
# ステップ 5: メトリクス検証とワンクリック出力エクスポート
変換完了後、入力文字数、出力文字数、UTF-8 総バイト数、およびエンコードによるデータ膨張率（Inflation Ratio）がリアルタイムにインスペクターに表示されます。 結果は「コピー」ボタンで即座にクリップボードへ保存できるほか、テキストファイルとしてローカルマシンへエクスポートできます。
# プロダクションコード実装（TypeScript & Python）
実際のバックエンドサービスやフロントエンドの共通ユーティリティとしてそのまま導入できる、依存ライブラリゼロの堅牢な実装スニペットを提示します。
# 1. モダン TypeScript / JavaScript 実装
サロゲートペア（32 ビットコードポイント）の完全なサポート、名前付き／10進数／16進数のフォーマット切り替え、および正規表現ベースの安全なデコーダーを備えたクラス実装です。
/**
* HTML エンティティ出力フォーマットの型定義
*/
export type EntityFormat = "named" | "decimal" | "hex";
/**
* プロダクション環境向け HTML エンティティ コーデッククラス
*/
export class HtmlEntityCodec {
/**
* 主要な名前付き文字実体参照の不変辞書マップ
*/
private static readonly NAMED_MAP: Record<string, string> = {
"&": "&",
"<": "<",
">": ">",
'"': """,
"'": "'", // レガシー HTML4 互換性を考慮し ' ではなく ' を採用
"\u00A0": " ",
"©": "©",
"®": "®",
"™": "™",
"€": "€",
};
/**
* デコード用逆引きマップ
*/
private static readonly REVERSE_MAP: Record<string, string> = {
"&": "&",
"<": "<",
">": ">",
""": '"',
"'": "'",
"'": "'",
" ": "\u00A0",
"©": "©",
"®": "®",
"™": "™",
"€": "€",
};
/**
* 文字列を HTML エンティティへエンコードする
* @param str 入力文字列
* @param format 出力形式 ('named' | 'decimal' | 'hex')
* @param nonAscii 非 ASCII 文字（コードポイント > 127）もエスケープするか否か
*/
public static encode(
str: string,
format: EntityFormat = "named",
nonAscii = false
): string {
if (!str) return "";
const out: string[] = [];
// codePointAt を用いて 32 ビットサロゲートペアを正しく反復処理
for (let i = 0; i < str.length; ) {
const cp = str.codePointAt(i)!;
const ch = String.fromCodePoint(cp);
if (this.NAMED_MAP[ch]) {
if (format === "named") {
out.push(this.NAMED_MAP[ch]);
} else if (format === "decimal") {
out.push(`&#${cp};`);
} else {
out.push(`&#x${cp.toString(16).toUpperCase()};`);
}
} else if (nonAscii && cp > 127) {
if (format === "hex") {
out.push(`&#x${cp.toString(16).toUpperCase()};`);
} else {
out.push(`&#${cp};`);
}
} else {
out.push(ch);
}
// BMP 超過文字（サロゲートペア）の場合はインデックスを 2 つ進める
i += cp > 0xffff ? 2 : 1;
}
return out.join("");
}
/**
* HTML エンティティ文字列を安全にデコードする（DOMParser を使わないトークン分離方式）
* @param str エンコード済み入力文字列
*/
public static decode(str: string): string {
if (!str) return "";
// 名前付き、10進数 NCR、16進数 NCR を網羅する正規表現
const entityRegex = /&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);/g;
return str.replace(entityRegex, (match, entityBody) => {
// 16進数数値文字参照 (&#x...;)
if (entityBody.startsWith("#x") || entityBody.startsWith("#X")) {
const hexVal = entityBody.slice(2);
const codePoint = parseInt(hexVal, 16);
return this.isValidCodePoint(codePoint)
? String.fromCodePoint(codePoint)
: match;
}
// 10進数数値文字参照 (&#...;)
if (entityBody.startsWith("#")) {
const decVal = entityBody.slice(1);
const codePoint = parseInt(decVal, 10);
return this.isValidCodePoint(codePoint)
? String.fromCodePoint(codePoint)
: match;
}
// 名前付き文字実体参照 (&name;)
return this.REVERSE_MAP[match] || match;
});
}
/**
* コードポイントが有効な Unicode スカラー値であり、サロゲート範囲外であることを検証
*/
private static isValidCodePoint(cp: number): boolean {
return (
!isNaN(cp) &&
cp >= 0 &&
cp <= 0x10ffff &&
!(cp >= 0xd800 && cp <= 0xdfff)
);
}
}# 2. モダン Python 3.11+ 実装
Python 3.11 の型ヒントを完備し、標準ライブラリの html モジュールと正規表現エンジンを安全にラップした堅牢な実装です。
"""
HTML エンティティ コーデック ユーティリティ
Python 3.11+ 標準ライブラリのみを使用（外部依存関係ゼロ）
"""
import html
import re
from typing import Literal
EntityFormat = Literal["named", "decimal", "hex"]
class HtmlEntityCodec:
# エンティティ検出用正規表現パターン
_ENTITY_RE = re.compile(r"&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);")
# コア予約記号のマッピング辞書
_CORE_MAP = {
"&": "&",
"<": "<",
">": ">",
'"': """,
"'": "'", # レガシー環境向けに ' を採用
}
@classmethod
def encode(
cls,
text: str,
fmt: EntityFormat = "named",
non_ascii: bool = False,
) -> str:
"""
文字列を HTML エンティティへエンコードする
サロゲートペア問題を起こさず、Python のネイティブ Unicode を正確に処理
"""
if not text:
return ""
out: list[str] = []
for ch in text:
code_point = ord(ch)
if ch in cls._CORE_MAP:
if fmt == "named":
out.append(cls._CORE_MAP[ch])
elif fmt == "decimal":
out.append(f"&#{code_point};")
else:
out.append(f"&#x{code_point:X};")
elif non_ascii and code_point > 127:
if fmt == "hex":
out.append(f"&#x{code_point:X};")
else:
out.append(f"&#{code_point};")
else:
out.append(ch)
return "".join(out)
@classmethod
def decode(cls, text: str) -> str:
"""
HTML エンティティを安全にデコードする
不正な数値や孤立サロゲートをフォールバック処理
"""
if not text:
return ""
def _replace_token(match: re.Match[str]) -> str:
full_match = match.group(0)
body = match.group(1)
# 16進数数値文字参照
if body.startswith(("#x", "#X")):
try:
cp = int(body[2:], 16)
if 0 <= cp <= 0x10FFFF and not (0xD800 <= cp <= 0xDFFF):
return chr(cp)
except ValueError:
pass
return full_match
# 10進数数値文字参照
if body.startswith("#"):
try:
cp = int(body[1:], 10)
if 0 <= cp <= 0x10FFFF and not (0xD800 <= cp <= 0xDFFF):
return chr(cp)
except ValueError:
pass
return full_match
# 名前付き参照（Python 標準の html.unescape を安全に活用）
return html.unescape(full_match)
return cls._ENTITY_RE.sub(_replace_token, text)# 開発現場における落とし穴とエッジケースのトラブルシューティング
HTML エンティティのエスケープ処理は一見単純に見えますが、本番運用の Web システムでは微妙な仕様差や多重変換による不具合が後を絶ちません。代表的な 6 大トラブルとその防止策を解説します。
#
1. 二重エンコード問題（Double-Encoding: &amp;）
すでにエンコードされた文字列（例: <div>）に対し、後続のテンプレートエンジンやシリアライザーが再度エスケープをかけてしまう現象です。アンパサンド文字自身が & へ変換されるため、&lt;div&gt; と変質し、画面上には < ではなく < という文字列がそのまま露出してしまいます。
- 防止策: エンコードはプレゼンテーション層の出力境界（View 層）で 1 度だけ適用するアーキテクチャを徹底してください。事前に文字列の冪等性を検証したい場合は、
decode(str) !== strを判定することで、文字列内に未解決のエンティティが存在するかを検知できます。
# 2. 文脈依存のエスケープ欠落（Context-Dependent Escaping）
HTML エンティティエンコードは、HTML のテキストノード（PCDATA）および通常の HTML 属性値においてのみ有効です。<script> タグの内部、インラインイベントハンドラ（onclick="..."）、あるいは <a href="..."> の URL クエリパラメータ内部では、パーサーの解釈ルールが全く異なります。 例えば <script>const data = "USER_INPUT";</script> の文脈で HTML エンコードを行っても、JavaScript エンジンはエンティティをデコードせずに構文エラーを起こすか、二重クォート抜けによる XSS を許してしまいます。
- 防止策:
<script>タグ内ではJSON.stringify()を使用し、さらに</script>によるタグ閉じインジェクションを防ぐために<を\u003Cへ置換する JavaScript コンテキスト専用のエスケープ を適用してください。また URL 内ではencodeURIComponent()によるパーセントエンコーディングを使用します。
#
3. レガシー HTML4 における ' の非互換性
シングルクォート（'）を表す ' は XML 1.0 や XHTML、HTML5 では標準ですが、HTML 4.01 仕様には含まれていませんでした。このため、古い Web メールクライアント（Outlook の一部バージョン等）やレガシーな HTML レンダラーに ' を送信すると、エンティティとして認識されず ' という文字列がそのまま出力されてしまいます。
- 防止策: 単一引用符のエスケープには、HTML4、HTML5、XHTML、XML のすべてのパーサーで 100% 確実に解釈される 10進数数値文字参照
'を標準採用してください。
# 4. クアークスモードにおける末尾セミコロン欠落エンティティ
WHATWG 仕様では、過去の後方互換性を維持するため、一部の一般的な名前付き実体参照において末尾のセミコロンが省略されていても解釈を試みるエラーリカバリ（Quirks 解析）が定義されています（例: © 2026 → © 2026）。しかし、厳格な XML / SVG パーサーや API バックエンドにこのような文字列を渡すと、即座に文法違反エラーとなって処理が停止します。
- 防止策: エンティティを生成する際は、常に末尾のセミコロン（
;）を省略せず厳格に付与してください。正規表現によるデコード時も、セミコロン終端を必須パターンとしてマッチさせるのが安全です。
# 5. UTF-16 サロゲートペアのスライス破壊（Broken Emojis）
JavaScript の標準メソッド str.charAt(i) や str.slice() を不用意に使用すると、絵文字（🚀 U+1F680）などの 4 バイト文字が上位サロゲート（0xD83D）と下位サロゲート（0xDE80）の間で分断されてしまいます。この状態で数値エンティティ化を行うと、壊れた 2 つの参照 �� が出力され、ブラウザ上では黒い菱形（``）の文字化けとして描画されます。
- 防止策: 文字列の走査には必ず
codePointAt()またはfor...ofイテレータを使用してください。また、サロゲートペアが含まれる場合はインデックスを 2 つスキップする制御を組み込みます。
# 6. innerHTML 経由の破壊的タグ除去とスクリプト実行リスク
前述のとおり、エンティティをデコードするために div.innerHTML を使用すると、入力データ内に含まれていた意図的な HTML タグが実際の DOM ノードへ変換され、textContent 抽出時にタグが剥奪されたり、インラインスクリプトがブラウザ上で不正実行されます。
- 防止策: デコード処理には DOM を一切介さず、本ガイドに掲載した正規表現置換方式を採用してください。
# 詳細 FAQ セクション（よくある質問と回答）
# Q1: 名前付き文字実体参照、10進数数値文字参照、16進数数値文字参照の決定的な違いと使い分けは？
回答: 名前付き文字実体参照（©）はアルファベットニーモニックを使用し、人間にとっての可読性に優れていますが、XML 文書内では DTD 定義がないと構文エラーになります。10進数数値文字参照（©）および 16進数数値文字参照（©）は Unicode コードポイントを直接指定するため、DTD の有無に関わらず HTML、XHTML、XML、SVG のすべての規格で 100% 確実に解釈されます。データ連携や API 通信では数値文字参照が最も安全です。
#
Q2: なぜ <script> タグ内では HTML エンティティのエンコードだけでは XSS を防げないのですか？
回答: ブラウザは <script> タグの内部を HTML パーサーではなく JavaScript エンジンの文法ルールに基づいて解釈します。JavaScript エンジンは HTML エンティティ（" 等）を自動的に文字列へデコードしないため、構文エラーを引き起こします。さらに、攻撃者がクォートを注入した場合の無害化にはなりません。<script> 内にデータを安全に展開するには、JSON.stringify() で文字列化した上で、</script> タグによるスクリプトブロックの強制終了を防ぐために < を \u003C へ置換する必要があります。
#
Q3: なぜ古いメール配信やレガシーブラウザで ' が文字化け・エラーになり、' が推奨されるのですか？
回答: ' は XML 1.0 で定義されていたものの、W3C の HTML 4.01 仕様策定時に採用が見送られた歴史があります。そのため、HTML4 準拠の古いレンダリングエンジンや各種メールクライアント（古い Outlook 等）は ' を未知の文字列として認識し、文字化けや構文エラーを起こします。10進数表記である ' であれば、すべての世代の HTML および XML パーサーが正しく解釈できます。
# Q4: 4バイトの UTF-8 文字や絵文字（サロゲートペア）を HTML エンティティ化する際の挙動と注意点は？
回答: 絵文字（例: 🔥 U+1F525）などの Unicode 第 1 面（アストラルプレーン）に属する文字は、JavaScript 内部で 2 つの 16 ビットサロゲート（\uD83D\uDD25）として扱われます。古い charCodeAt() で処理するとサロゲートごとに分断された不正なエンティティ（��）が生成されます。codePointAt() を使用して 32 ビットの統合コードポイント（128293）を算出し、🔥 または 🔥 という正当な単一の数値文字参照を生成しなければなりません。
#
Q5: document.createElement('div').innerHTML を使って HTML エンティティをデコードするのが危険な理由は？
回答: 入力文字列に未エスケープの悪意あるコード（例: <img src=x onerror=alert(1)>）が含まれていた場合、innerHTML への代入と同時にブラウザが即座にスクリプトを実行してしまい、DOM ベース XSS 攻撃が成立するためです。また、意図して含めていたマークアップタグが DOM 要素として解釈され、テキスト抽出時に消失する副作用もあります。
# Q6: 文字列が「すでに HTML エンティティにエンコードされているか」をプログラムで正確に判定する方法は？
回答: 2 段階の検証を行います。まず正規表現 /&(#(?:[xX][0-9a-fA-F]+|[0-9]+)|[a-zA-Z0-9]+);/ をテストし、エンティティ構文の存在を確認します。次に、コーデックの decode() 関数を実行し、decode(str) !== str が成立するか（デコードによって内容が変化するか）を検証します。変化があれば、有効なエンティティシーケンスが含まれていたと判定できます。
# Q7: ToolsAA のツール利用時に入力した機密ソースコードやデータがサーバーへ送信されることはありますか？
回答: 一切送信されません。ToolsAA は "use client" ディレクティブを採用した完全クライアントサイド実行モデルで構築されています。エンコード、デコード、Unicode コードポイント計算、メトリクス算出の全処理はお客様のブラウザの JavaScript エンジン内部でのみ実行されます。外部サーバーへの通信リクエストは 1 バイトも発生せず、サーバーログにも残りません。
# Q8: HTML5（WHATWG）でサポートされる名前付き文字参照の数は、HTML4 や XML と比較してどれくらい増えましたか？
回答: XML 1.0 が定義するコアエンティティはわずか 5 種類、HTML 4.01 が定義した実体参照は 252 種類でした。これに対し、最新の WHATWG HTML Living Standard では大幅に拡充され、数学記号、ギリシャ文字、特殊矢印、ダイアクリティカルマークを含む合計 2,231 種類の名前付き文字参照が公式にサポートされています。
# 技術比較マトリクス: HTML エンティティ形式と利用コンテキスト
| 比較項目 / フォーマット | 名前付き実体参照 (&name;) | 10進数数値文字参照 (&#D;) | 16進数数値文字参照 (&#xH;) | 生 UTF-8 文字（Raw） |
|---|---|---|---|---|
| 標準規格ベース | WHATWG / SGML | W3C / ISO 10646 | W3C / RFC 5198 | Unicode Consortium |
| 対応文字数 | 2,231 文字 | 1,114,112 コードポイント | 1,114,112 コードポイント | 1,114,112 コードポイント |
| XML 1.0 適合性 | 主要 5 文字のみ（他は DTD 必須） | 完全適合（DTD 不要） | 完全適合（DTD 不要） | 完全適合 |
| HTML 4.01 適合性 | 252 文字（' は非対応） | 完全適合 | 完全適合 | エンコーディング依存 |
| データサイズ増加率 | 中程度（4〜10 バイト） | コンパクト（4〜9 バイト） | コンパクト（5〜9 バイト） | 最小（1〜4 バイト） |
| 人間に対する可読性 | 高い（© 等） | 低い（© 等） | 低い（© 等） | 最高（グリフそのまま） |
| HTML 属性値の安全性 | 安全（エスケープ時） | 安全 | 安全 | 属性デリミタのエスケープ必須 |
<script> 内の安全性 | 不可（構文エラー・無効） | 不可 | 不可 | JS エスケープ必須 |
# 結論・まとめ
マークアップタグとリテラルテキストの構文境界を正確に制御することは、堅牢で安全なモダン Web アプリケーションを構築する上での絶対的な基礎要件です。クロスサイトスクリプティング（XSS）脆弱性の根本的な抑止、ドキュメント内での構文ハイライト表示、フォーム属性インジェクションの防止、そして厳格な XML / SVG データフィードの配信に至るまで、文字参照による決定論的なエスケープがシステムの安全性と表示の一貫性を支えています。
歴史的な ' の非互換性を避けて ' を標準採用すること、絵文字などのサロゲートペアを 32 ビットコードポイントとして正しく取り扱うこと、そして危険な innerHTML による DOM 代入を廃してトークン分離型の正規表現デコーダーを導入することにより、開発現場を悩ませる二重エンコード障害や予期せぬ実行時例外を未然に根絶できます。
ToolsAA HTML エンティティ エンコーダー＆デコーダー は、あらゆる文字実体参照・数値文字参照の相互変換、フォーマット切り替え、および双方向デコードを、完全なクライアントサイド・ゼロ知識アーキテクチャによって高速かつ安全に提供します。機密データの漏洩リスクを一切冒すことなく、最高水準のデータプライバシーのもとで日々の開発ワークフローを効率化してください。