CSSのカスタムハイライトで、ページ内の検索語に色を付ける方法

​​CSS​CSS Custom Highlight API,HTML,JavaScript,Playwright

CSS カスタムハイライト API を使うと、ページ内検索で一致した語に、HTML を書き換えずに色を付けられます。ブラウザーの Ctrl+F のような検索欄をページに置き、一致した語を強調表示したい場面で使えます。一致した位置を Range で表して CSS.highlights に登録し、色は CSS の ::highlight() で指定します。<mark> で囲む方法と違い、記事の DOM は検索の前後で変わりません。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、Playwright 1.63.0、ヘッドレスの Chromium 153 です。幅360pxの画面で HTML と JavaScript だけのページを開き、色はスクリーンショットの画素で調べました。対応ブラウザーは @mdn/browser-compat-data 8.1.8 の互換性データによるもので、Firefox と Safari での表示や、スクリーンリーダーでの読み上げは試していません。

検索欄に「猫」と入力すると、ページ内の7か所の「猫」に色が付き、見出しの「猫」だけがピンク、残りの6か所は水色になる。件数の表示は「7件中 1件目」。続けて「次へ」ボタンを3回クリックすると、ピンクの箇所が2件目、3件目、4件目の「猫」へ移り、件数の表示も「7件中 4件目」まで変わる
「猫」と入力してから「次へ」を3回押す様子。マウスカーソル、下の説明、押した瞬間のピンクの枠と件数の色は、録画のために足したもの

色を付けるまでの4つの手順

MDN の CSS カスタムハイライト API の解説にあるとおり、文字に色を付けるまでの手順は4つです。

  1. 色を付けたい文字の範囲を Range で作る
  2. 範囲をまとめて Highlight を作る
  3. CSS.highlights.set('名前', highlight) で、名前を付けて登録する
  4. CSS の ::highlight(名前) に色を書く

1つの Highlight には、範囲をいくつでも入れられます。ページ内検索なら、一致したすべての箇所を1つの Highlight に入れ、search-results という名前で登録します。

ページ内検索のコード

HTML は、検索欄とボタン、件数を出す <output>、検索の対象になる <article> です。本文の段落の1つは、途中に <strong> を入れてあります。

html
<div class="search" role="search">
  <input id="query" type="search" placeholder="ページ内を検索" aria-label="ページ内を検索">
  <button id="prev" type="button">前へ</button>
  <button id="next" type="button">次へ</button>
  <output id="count" aria-live="polite"></output>
</div>
<article id="content">
  <h2>猫の手で書くノート</h2>
  <p>猫は、日なたで丸くなって寝るのが好きです。窓ぎわの猫は、昼すぎになると場所を少しずつ移します。</p>
  <p>CSS の<strong>カスタム</strong>ハイライトを使うと、DOM を変えずに文字に色を付けられます。</p>
  <p>子猫と大人の猫では、遊び方も寝る時間も違います。猫じゃらしを見せると、子猫はすぐに飛びつきます。</p>
</article>

CSS には、一致したすべての箇所(search-results)と、いま選んでいる1か所(search-current)の色を書きます。

css
/* 一致した箇所すべて */
::highlight(search-results) {
  background-color: #b8f0fa;
  color: #1f2a30;
}

/* いま選んでいる1か所 */
::highlight(search-current) {
  background-color: #d85878;
  color: #ffffff;
}

JavaScript は次のとおりです。

js
const query = document.getElementById('query');
const content = document.getElementById('content');
const count = document.getElementById('count');
const supported = 'highlights' in CSS;

const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

// 文字列の位置 → テキストノードと、その中の位置
function textIndex(root) {
  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
  const nodes = [];
  let text = '';
  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
    nodes.push({ node: n, start: text.length });
    text += n.data;
  }
  const locate = (pos) => {
    let i = nodes.length - 1;
    while (i > 0 && nodes[i].start > pos) i--;
    return [nodes[i].node, pos - nodes[i].start];
  };
  return { text, locate };
}

function findRanges(root, word) {
  if (!word) return [];
  const { text, locate } = textIndex(root);
  const re = new RegExp(escapeRegExp(word), 'gi');
  const ranges = [];
  for (const m of text.matchAll(re)) {
    const range = new Range();
    range.setStart(...locate(m.index));
    range.setEnd(...locate(m.index + m[0].length));
    ranges.push(range);
  }
  return ranges;
}

let ranges = [];
let current = -1;

function showCurrent() {
  if (current < 0) {
    CSS.highlights.delete('search-current');
    count.textContent = ranges.length ? `${ranges.length}件` : (query.value ? '0件' : '');
    return;
  }
  const hit = new Highlight(ranges[current]);
  hit.priority = 1;
  CSS.highlights.set('search-current', hit);
  count.textContent = `${ranges.length}件中 ${current + 1}件目`;
  // 選んだ箇所が画面の外にあれば、画面の中ほどまでスクロールする
  const rect = ranges[current].getBoundingClientRect();
  if (rect.top < 0 || rect.bottom > innerHeight) {
    scrollBy({ top: rect.top - innerHeight / 2 });
  }
}

function search() {
  if (!supported) return;
  ranges = findRanges(content, query.value.trim());
  CSS.highlights.set('search-results', new Highlight(...ranges));
  current = ranges.length ? 0 : -1;
  showCurrent();
}

function move(step) {
  if (!ranges.length) return;
  current = (current + step + ranges.length) % ranges.length;
  showCurrent();
}

query.addEventListener('input', search);
document.getElementById('next').addEventListener('click', () => move(1));
document.getElementById('prev').addEventListener('click', () => move(-1));

textIndex() は、<article> の中のテキストノードをすべてつなげた文字列と、その文字列の位置から「どのテキストノードの何文字目か」を返す関数 locate() を作ります。findRanges() は、つなげた文字列を正規表現で探し、一致した位置ごとに Range を作ります。入力をそのまま正規表現にすると . や * が特別な意味を持つので、escapeRegExp() で記号の前に \ を付けています。

検証環境で「猫」と入力すると、件数の表示は「7件中 1件目」になり、search-results に7つの範囲が入りました。スクリーンショットの画素を調べると、1件目の背景はピンク(#d85878)、2件目は水色(#b8f0fa)でした。「次へ」を1回押すと、1件目が水色に、2件目がピンクに変わりました。

入力を空にすると、件数の表示は消え、search-results の範囲の数は0になり、search-current は登録から外れました。「.*」と入力したときは、記号として探すので「0件」でした。

選んだ箇所が画面の外にあるときは、getBoundingClientRect() で位置を調べ、scrollBy() で画面の中ほどまでスクロールします。段落を増やして縦に長くしたページで「ノート」を探し、最後の段落にある2件目を「次へ」で選ぶと、ページがいちばん下までスクロールされ、2件目は画面の中(上から 552px)に表示されました。

記事の DOM は、検索の前後で変わらない

検証環境で「猫」を検索する前と後で <article> の innerHTML を比べると、同じでした。ページの中の <mark> 要素も0個のままです。MDN の解説にも、DOM 構造に影響を与えずに、文字の範囲に色を付けられると書かれています。

色を消すときも、CSS.highlights.delete() や CSS.highlights.clear() で登録を外すだけで、本文の HTML には手を入れません。

テキストノードごとに探すと、太字をまたぐ語が見つからない

MDN の解説にある検索の例は、テキストノードを1つずつ取り出し、それぞれの中で検索語を探しています。この形だと、<strong> などで分かれた語は見つかりません。

本文の「CSS のカスタムハイライト」は、テキストノードが「CSS の」「カスタム」「ハイライト」の3つに分かれています。検証環境で「カスタムハイライト」を探すと、テキストノードごとに探す書き方では0件、つなげた文字列で探す書き方では1件でした。

上のコードの findRanges() で探した場合も「1件中 1件目」になり、作った Range の文字列は「カスタムハイライト」でした。Range は始まりと終わりを別のテキストノードに置けるので、<strong> の中から外にまたがる範囲もそのまま Highlight に入れられます。

toLowerCase() で探すと、色を付ける位置がずれる

大文字と小文字を区別せずに探すとき、MDN の例のように、文字列を toLowerCase() で小文字にしてから indexOf() で探すと、位置がずれることがあります。小文字にすると文字数が変わる文字があるためです。

検証環境で、「İstanbul の猫と犬」(先頭はトルコ語の、点の付いた大文字の I)から「猫」を探しました。元の文字列は13文字ですが、toLowerCase() の後は14文字になりました。小文字の文字列で見つけた位置(11)をそのまま Range に使うと、色が付く範囲は「猫」ではなく、1文字後ろの「と」になりました。「İstanbul の猫」のように検索語が文字列の最後にあるときは、範囲の終わりが文字列の長さを超え、setEnd() が IndexSizeError を投げました。

上のコードのように、元の文字列を i フラグ付きの正規表現で探せば、見つかった位置は元の文字列の位置です。同じ文字列で、位置は10、範囲の文字列は「猫」でした。「css」と小文字で入力したときも、本文の「CSS」に一致しました。

重なった箇所の色は、priority で決める

いま選んでいる1か所は、search-results と search-current の両方に入っています。重なった部分にどちらの色を使うかは、Highlight の priority で決まります。

MDN の Highlight.priority のページによると、priority の数が大きいほうのスタイルが使われます。priority を設定していなければ、後から登録したハイライトが使われます。CSS で ::highlight() を書いた順番は関係せず、!important を付けても、どちらの色になるかは変わりません。

検証環境で、同じ範囲を2つのハイライトに入れて試しました。

登録の順番 search-current にあたるハイライトの priority 重なった部分の背景
すべて → 選択中 設定しない ピンク(選択中の色)
選択中 → すべて 設定しない 水色(すべての色)
選択中 → すべて 1 ピンク(選択中の色)

上のコードでは、検索のたびに search-results を登録し直し、そのあとで search-current を登録するので、priority がなくても選択中の色になります。それでも priority = 1 を付けておけば、登録の順番が変わったときにも選択中の色が上に出ます。

::highlight() で使えるプロパティは限られる

MDN の ::highlight() のページによると、::highlight() で使えるのは、color、background-color、text-decoration とその関連のプロパティ、text-shadow、-webkit-text-stroke-color、-webkit-text-fill-color、-webkit-text-stroke-width だけです。background-image は無視される、とも書かれています。

検証環境で、::highlight() に1つずつ書いて、何も書かないときのスクリーンショットと比べました。

::highlight() に書いたもの 表示
color: #d85878 変わった
text-decoration: underline wavy #d85878 変わった
font-weight: bold 変わらない
font-size: 48px 変わらない
background-image: linear-gradient(...) 変わらない

強調した語を太字にしたり、大きくしたりはできないので、文字の色、背景の色、下線で見分けられるようにします。

本文を書き換えたら、探し直す

new Range() で作った範囲は、DOM の変更に合わせて位置が動きます。CSS Custom Highlight API の仕様では、Range は DOM の変更に合わせて境界が調整され、StaticRange は調整されないと書かれています。

検証環境で、「白い猫と黒い猫」の最初の「猫」を Range と StaticRange の両方で表し、テキストの先頭に「とても」を足しました。Range の範囲は「猫」のままでしたが、StaticRange の位置にある文字は「も」になりました。

段落の textContent を同じ文字列で書き換えたときは、Range の文字列は空になり、collapsed が true になりました。元のテキストノードが取り除かれたためです。Highlight の中には範囲が2つ残ったままです。

ページ内検索のデモでも、「猫」で検索したあとに1段落目の textContent を「犬は、散歩が好きです。」に書き換えると、7つの範囲のうち2つが空になりました。件数の表示は「7件中 1件目」のままです。書き換えたあとに search() をもう一度呼ぶと、件数は「5件中 1件目」になり、空の範囲はなくなりました。本文を JavaScript で差し替えるページでは、差し替えたあとに search() を呼び直します。

対応ブラウザーと、対応していないときの判定

@mdn/browser-compat-data 8.1.8 では、::highlight()、Highlight、CSS.highlights に、Chrome と Edge は 105、Safari は 17.2 から対応しています。Firefox は Highlight と CSS.highlights に 140 から対応し、::highlight() は 149 から完全な対応で、140〜148 は一部の対応です。互換性データの注記によると、Firefox 146 より前は text-decoration、149 より前は text-shadow を ::highlight() で使えません。

上のコードでは、'highlights' in CSS で対応しているかを調べ、対応していなければ search() の中で何もしません。検証環境の Chromium では true でした。CSS.supports('selector(::highlight(x))') も true でした。上のコードのままだと、対応していないブラウザーでは search() がすぐに戻るので、検索欄は表示されても、入力したときに色も件数も出ません。

​Posted by 86