この記事について
この記事は、生成AIを活用した自動生成フローで作成しています。CSS.escapeとquerySelectorの公式仕様・解説を確認し、架空チケットIDの静的教材を用意しました。Node.jsで疑似DOMを使った判定と入力検査を確認しましたが、実ブラウザーでの表示・操作、GitHub Pagesへの到達、WordPressでの表示は未確認です。検証ステータス:📘 仕様確認・ロジック確認済み/ブラウザー操作未確認
CSS.escapeでquerySelectorが失敗する?コロン・ピリオド・数字始まりのIDを安全に探す
「ボタンを押したのに対象が見つからない」「IDが分かっているのにquerySelectorで例外になる」。そんな現象が、一覧画面のチケット番号や外部サービスの識別子にコロンやピリオドが含まれるだけで起きます。原因は、HTMLのIDとCSSセレクターが別の文法を持つことです。この記事では、架空の4件でその差を体験し、使い分けと注意点まで整理します。
できること・試す環境
| 項目 | 内容 |
|---|---|
| 対象 | CSS.escapeとquerySelectorを利用できるブラウザー、HTML/CSS/JavaScript |
| 用意するもの | ブラウザーとローカル保存した静的HTML/JavaScript。外部サービスへの登録は不要 |
| 題材 | 架空のチケットID4件。実際の顧客番号・社内IDは不要 |
| 確認済み | Node.js 22.16.0で疑似rootを用いた13項目の判定テスト |
| 未確認 | 実ブラウザーのCSSパーサー・画面操作、Pages到達、WordPressでの表示 |
HTML・JavaScript・README・テスト一式(固定コミット)
ブラウザーでリンクが開けない場合は、GitHubの同じコミットの docs/demos/css-escape-selector-lab/ にある index.html と app.js を同じフォルダーに置き、HTMLをローカルで開いてください。公開URLの有無と画面が正常動作した事実は別です。結果の説明は仕様に基づく期待値であり、ここでブラウザーの実測値と偽っていません。
まず試す:一文字変えるだけで結果が変わる
画面にある「探すID」に ticket:01 を入力して検索します。用意した一覧には「コロン付きID / ticket:01」があるので、対応ブラウザーなら「見つかった」と表示される想定です。入力欄を書き換えても、検索ボタンを押すまでは表示は変わりません。これにより、入力の変更と検索の実行を分けて観察できます。
続けて ticket.02、123-start、a[b] を一つずつ入力します。対象は同じ4件の一覧です。コロン、ピリオド、数字始まり、角括弧という性質だけを変えるため、どの入力で検索結果が変わったのか追いやすくなります。最後に missing を入力すると、一致する項目がないので「一致なし」の想定です。空欄でも不正なセレクターを生成せず「一致なし」にします。
| 検索するID | 期待する結果 | 注目すること |
|---|---|---|
ticket:01 | コロン付きIDが見つかる | :を擬似クラスと誤解させない |
ticket.02 | ピリオド付きIDが見つかる | .をクラス指定と誤解させない |
123-start | 数字始まりIDが見つかる | CSS識別子としての先頭文字制約を吸収 |
a[b] | 角括弧付きIDが見つかる | 属性セレクターと混同しない |
missing または空欄 | 一致なし | 見つからない状態と実装エラーを分ける |
この比較で意外なのは、同じIDでもHTML側では使えて、CSSの #ID としてはそのまま書けない場合があることです。IDに特別な文字があるから「データが壊れている」と決めつける前に、検索に使う文法を疑う必要があります。
なぜ # と文字列を足すだけではだめなのか
document.querySelector() や要素の querySelector() に渡す引数は、IDそのものではなくCSSセレクターです。単純に "#" + id と書くと、コロンは疑似クラス、ピリオドはクラス指定、角括弧は属性セレクターの開始として解釈されます。数字始まりの値もCSS識別子として別の書き方が必要です。単に見つからない場合と、文法エラーで例外になる場合があり、文字ごとに同じ失敗になるとは限りません。
一方で CSS.escape(id) は、IDをCSSの識別子として安全に埋め込める形へ変換します。例えば「ticket:01」のコロンは、CSSセレクターの記号ではなくIDの一部だと認識できる書き方になります。変換後の文字列が見た目に複雑でも、検索対象のIDそのものを書き換える処理ではありません。表示される値は元のまま、検索の書き方だけを変えるのがポイントです。
教材の中心処理は次のとおりです。 escapeFn にブラウザーの CSS.escape を渡せるようにすることで、疑似DOMを使ったロジックテストと画面側の実行を分けています。
function selectById(root, id, escapeFn) {
if (typeof id !== "string" || id.length > 80) {
throw new RangeError("IDは80文字以内の文字列にしてください");
}
if (id.length === 0) return null;
if (typeof escapeFn !== "function") {
throw new TypeError("CSS.escapeが使えません");
}
return root.querySelector("#" + escapeFn(id));
}
最初の条件はデモ固有の入力制限です。80文字はCSS.escapeそのものの上限ではありません。次の空文字チェックがないと、 "#" だけの不正なセレクターになり、検索処理が例外になり得ます。APIの存在を確認した後、最後の行で初めて検索を実行します。検索対象は画面内の一覧要素 root に限定しているため、この例の意図はページ全体から無関係な要素を探すことではありません。
図で見る:IDとセレクターが分かれる位置
次の図はエスケープする位置だけを示しています。入力のID値を変えるのではなく、セレクター文字列を組み立てる直前に変換する点を確認してください。検索結果が null の場合と、構文エラーの場合も別の経路です。
flowchart TD
A[検索したいID] --> B{空文字か}
B -->|はい| N[一致なし]
B -->|いいえ| C[CSS.escapeで識別子へ変換]
C --> D[先頭に # を付ける]
D --> E[querySelectorで検索]
E --> F{対象はあるか}
F -->|はい| G[対象の文字を表示]
F -->|いいえ| N
図が表しているのは、DOMの作成、変更、保存ではありません。検索キーをどの段階で変換するかという処理順だけです。実際の教材では、ブラウザーがCSS.escapeに対応しないときや入力が長すぎるときの例外を受け、画面に理由を示します。
1条件だけ変えて、別の対処と比べる
ここまでの方法は「CSSセレクターで探す必要がある」場合のものです。しかし、目的が単にページ内のIDを指定するだけなら document.getElementById(id) を使う選択肢もあります。このメソッドはCSSセレクターとして解析せず、ID文字列として探すため、セレクター用のエスケープを考えずに済みます。教材は一覧要素の子孫だけを探すので root.querySelector() を使っていますが、検索範囲が文書全体ならどちらが適切かを先に決めると整理できます。
比較の際は、検索対象を変えず、検索方法だけを変えます。例えば ticket:01 を探すときに、CSSの #ticket:01 を生のまま渡す方法、 CSS.escape を通す方法、文書全体をIDで探す方法を区別します。生のセレクターが失敗しても、IDそのものが存在しないとは限りません。また、IDが重複しているページでは最初の要素が選ばれ得るため、どの方法を採用しても重複したHTMLの設計を自動修復するものではありません。
もう一つの境界は空白です。HTMLのID属性値にASCII空白を含めるのは仕様に適合しません。旧版の教材にあった a b という例は、特殊文字の紹介として不適切だったため、今回 a[b] に置き換えました。ブラウザーが不適切なIDを扱う場面があっても、それを業務画面で推奨する根拠にはしません。
検索できないときの切り分け
最初に画面の状態を見ます。「一致なし」と出るなら、入力したIDに対応する要素がないか、検索範囲が異なる可能性があります。前後の空白、大文字小文字、ハイフンやコロンを一文字ずつ確認してください。ここで入力文字列を勝手に正規化すると、本来別の識別子まで同じものとして扱うおそれがあるので、デモは入力を自動修正しません。
「検索できません」と表示されたら、APIに対応していない、入力値が関数の範囲外、CSSセレクターを組み立てる途中で例外が出た、といった原因を確認します。ブラウザーの開発者ツールでエラーの内容を見れば、未検出と構文例外を混同せずに済みます。画面がまったく反応しなければ、まず app.js と index.html が同じフォルダーにあるか、スクリプトが読み込まれているかを確かめます。HTMLを表示できただけではJavaScriptが動作したとは言えません。
検索結果が「違うチケット」を指す場合は、CSS.escapeだけでは解決できない問題です。IDが重複していないか、動的に一覧を再描画した直後か、検索対象の root が期待した一覧かを調べます。querySelector() は複数一致したものをすべて返す仕組みではありません。複数を扱う必要があるなら別の選択APIを設計し、単一ID検索へ無理に押し込まない方が安全です。
業務でどう使い分けるか
管理画面で外部サービスのチケット番号をDOMのIDに使い、番号にコロンやピリオドが含まれる場合、従来の "#" + 番号 方式では突然検索できなくなったように見えることがあります。そのときに本当に確認したいのは、データの正誤だけでなく、データの文字列をどの文法へ渡したかです。CSSセレクターを組み立てる場面だけ CSS.escape を使い、同時に対象範囲やIDの一意性を確認するのが実用的です。
一方、これから新規画面を設計するなら、特殊記号を含む識別子をわざわざHTMLのIDに採用しない方法もあります。業務上のコードを data-* 属性に分離する、表示用テキストと内部キーを分ける、または単なるID探索には getElementById を使う方法です。CSS.escapeはCSSセレクター用の変換であり、XSS対策、SQL対策、認可チェックの代わりではありません。教材は結果表示に textContent を使用し、外部からの文字列をHTMLとして解釈させない作りにしています。
今回のNode.jsテストは、文字列の検査とエスケープ関数への受渡し、未検出・空文字・長さ超過・非対応の分岐を確認したものです。実際のブラウザーが ticket:01 等を検索して画面表示した結果の証明ではありません。最初の導入は架空データとローカルHTMLで試し、実際の運用画面へ広げる前に使っているブラウザー、DOMの生成順、重複ID、アクセシビリティを確認してください。
