CSS Custom Highlight API 怎样高亮搜索结果而不改 DOM

做站内搜索时，我以前常用字符串替换，把命中的文字包进 。这种办法直观，却会改写正文 DOM：连续输入查询词时要反复还原，跨节点文本还要额外处理，事件和选择状态也容易被打断。CSS Custom Highlight API 提供了另一条路径：JavaScript 只创建文本范围，CSS 通过 ::highlight() 负责着色，因此可以高亮搜索结果而不插入标记节点。

官方文档：https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API

它的核心关系可以记成：Range 描述位置，Highlight 收集范围，CSS.highlights 按名称登记，::highlight(name) 读取登记结果。下面按一个文章内搜索框展开，代码是解释性示例，不代表本机运行记录。

先把高亮职责拆成四个对象

这个 API 最容易误解的地方，是把“找到文字”和“修改文字”混为一谈。Range 只是指向节点和偏移量的范围；它不会把文本从原节点搬走。Highlight 可以装入一个或多个范围，同一个高亮名可以覆盖多个不连续命中。随后把它放入 CSS.highlights 这个类似 Map 的注册表，最后由 ::highlight(search-results) 选择它。

这个拆分也解释了它和插入 span 的差异：页面原有文本节点仍然是正文，视觉层只是额外挂上的标记集合。需要取消高亮时，删除注册表中的名称即可，不必遍历正文把标签拆回来。

从文章文本节点中找出每个匹配范围

一个可控的搜索入口，先把搜索范围限制在目标 article 内，再用 TreeWalker 收集文本节点。这样不会把输入框自身、按钮文字或其他页面区域纳入匹配。每个文本节点单独查找，命中的起点和结束位置都以该文本节点的偏移量表示。

const query = document.querySelector("#query");
const article = document.querySelector("article");

// 只收集正文文本节点，避免把搜索框和控件文字也纳入结果。
const walker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT);
const textNodes = [];
let node = walker.nextNode();
while (node) {
  textNodes.push(node);
  node = walker.nextNode();
}

function rangesFor(text) {
  const needle = text.trim().toLocaleLowerCase();
  if (!needle) return [];

  // 每个文本节点独立计算偏移，Range 的端点不会跨节点猜测。
  return textNodes.flatMap((textNode) => {
    const source = textNode.textContent.toLocaleLowerCase();
    const ranges = [];
    let start = 0;
    while (start 

这里刻意没有把多个文本节点拼成一个字符串。跨节点匹配当然可以做，但需要同时维护全局偏移与节点边界；如果文章搜索只要求命中一个文本节点内的词，先采用这个边界更容易保持 Range 的端点正确。

把多个 Range 注册为一个搜索高亮

得到范围数组后，创建一个 Highlight，再把它以稳定名称放进 CSS.highlights。CSS 选择器中的名称必须和注册表键一致。::highlight() 支持的可继承和文本装饰属性有明确限制，因此把它当作“文字标记层”，不要假设可以像普通元素一样设置所有盒模型属性。

// 用一个稳定名称承载本次搜索命中的所有文本范围。
function paintSearchResults(input) {
  if (!CSS.highlights) {
    article.dataset.highlightFallback = "unsupported";
    return;
  }

  // 先移除旧集合，避免连续输入时残留上一次的命中。
  CSS.highlights.delete("search-results");
  const ranges = rangesFor(input);
  if (ranges.length === 0) return;

  const searchHighlight = new Highlight(...ranges);
  CSS.highlights.set("search-results", searchHighlight);
}

query.addEventListener("input", (event) => {
  // 输入事件触发时只更新范围注册表，不重建 article 的 DOM。
  paintSearchResults(event.currentTarget.value);
});

/* 只设置高亮伪元素允许的文字表现，避免伪装成普通元素盒子。 */
::highlight(search-results) {
  background-color: #ffe08a;
  color: #1f2937;
  text-decoration: underline;
  text-decoration-color: #c2410c;
}

如果要同时显示“当前用户”和“拼写问题”两种颜色，可以注册不同的 Highlight 名称，并分别写 ::highlight() 规则。不要在每次输入时创建不可追踪的随机名称，否则清理时无法准确删除旧条目。

连续输入时要先清理，再处理空值和降级

连续输入的重点不是“重新画一次”，而是让注册表只保留当前查询对应的集合。空查询应删除旧高亮后直接返回；不支持 CSS.highlights 时则保留原文，并显示一个不依赖该 API 的提示或使用现有的服务端标记方案。不要为了兼容而偷偷修改正文，因为那会把两种渲染路径混成另一套状态。

function clearSearchHighlight() {
  // delete 只移除注册项，不会删除 article 中的原始文本节点。
  if (CSS.highlights) CSS.highlights.delete("search-results");
  delete article.dataset.highlightFallback;
}

function updateSearch(value) {
  const text = value.trim();
  if (!text) {
    clearSearchHighlight();
    return;
  }
  paintSearchResults(text);
}

query.addEventListener("input", (event) => {
  // 空值、能力缺失和正常命中都从同一个入口进入，状态更容易复查。
  updateSearch(event.currentTarget.value);
});

如果正文会被整体替换，之前保存的文本节点引用也会失效，需要在正文更新后重新建立 TreeWalker 索引。反过来，只是修改高亮颜色或注册表内容，就不必重新扫描全文。

别把视觉高亮当成语义和无障碍标记

Custom Highlight API 的优势是保留 DOM 结构，但这也意味着它不会自动给辅助技术提供“这是搜索结果”的语义。需要让高亮承担拼写错误、语法错误或重要提示时，应结合产品语义提供额外文本说明；对必须有语义的内容，可以考虑 或可访问的状态提示。视觉上看见黄色背景，不等于读屏用户获得了相同信息。

兼容性也应按目标浏览器确认。MDN 将该 API 标记为 Baseline 2025，并说明较旧设备可能不支持；代码入口中的能力判断是必要的。工程上可以把“高亮增强”设计成渐进增强：不支持时仍能搜索和阅读，只是没有额外的视觉范围层。

常见问题

为什么 DOM 没有新增 span，却能看到背景色？因为高亮由 Range 和 HighlightRegistry 保存，CSS 用 ::highlight() 绘制表现，不需要插入元素。

多个命中要创建多个 Highlight 吗？不必。同一种视觉样式可以把多个 Range 放进一个 Highlight；只有样式或优先级不同，才拆成多个注册名称。

清空 CSS.highlights 会删除正文吗？不会。它只清理高亮注册项，文章文本节点仍由原来的 DOM 持有。

为什么跨标签的词没有被命中？示例按单个文本节点查找。跨节点匹配需要建立全局偏移到节点端点的映射，不能把两个节点的偏移直接拼在同一个 Range 上。

CSS Custom Highlight API 适合把“搜索定位”和“正文结构”分离：用 Range 表示位置，用 Highlight 聚合命中，用 CSS 控制显示，用注册表完成清理。只要把能力检测、空值清理和无障碍降级一起设计，它就能成为不改 DOM 的轻量搜索高亮层。