highlight api 的 range 必须用 document.createrange() 创建并精确锚定到同文档的文本节点内，跨 iframe 或 shadow dom 会失败；关键词定位需遍历文本节点匹配 textcontent；注册后无效多因 ::highlight() 伪元素样式未正确配置。

Highlight API 的 Range 对象必须由当前文档真实节点构造

不能用 new Range() 创建后直接塞进 Highlight，浏览器会静默忽略。必须调用 document.createRange()，再用 setStart() 和 setEnd() 精确锚定到 DOM 节点内部的文本位置。

• 起点和终点必须落在同一文档的 Text 节点或元素节点内，跨 iframe 或 Shadow DOM 边界会失败
• 如果目标文本被换行、空格或零宽字符打断，Range 的 startOffset 和 endOffset 需按实际 textContent 索引计算，不是视觉位置
• 常见错误：对富文本（含 <strong></strong>、<span></span>）直接查 innerText 定位，结果偏移量错乱——应统一用 textContent 做字符串匹配，再映射回 DOM 节点树

如何从关键词定位到合法的 Range

手动遍历文本节点并匹配关键词最可靠，尤其当目标文本被 HTML 标签切分时。不要依赖 innerHTML 字符串查找，它会混入标签字符。

Wechat HTML Publisher

直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

下载

• 用 document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT) 遍历所有文本节点
• 对每个 node.textContent 执行 .indexOf(keyword)，拿到起始索引后调用 range.setStart(node, startIndex) 和 range.setEnd(node, startIndex + keyword.length)
• 若关键词跨两个相邻文本节点（如 “helloworld” 中搜索 “lowor”），需拆成两段 Range，Highlight API 支持一个 Highlight 包含多个 Range

Highlight 注册后不生效？检查 CSS 伪元素样式是否覆盖

即使 Range 构造正确、注册成功，没高亮大概率是 CSS 没配对。Highlight API 只提供语义标记，渲染完全依赖 ::highlight() 伪元素。

• 必须写 ::highlight(my-highlight)（括号内名称要和 Highlight 实例名一致），不能漏掉括号或写成 :highlight
• Chrome 目前只支持 background-color、color、text-decoration 等少数属性，border 或 box-shadow 会被忽略
• 若父容器有 overflow: hidden 或 transform，可能裁剪高亮区域——这是渲染层限制，Range 本身无误

动态更新高亮时，Range 对象不会自动同步 DOM 变化

原始 Range 绑定的是快照式节点引用。如果高亮范围内的 DOM 被删改（比如用户编辑内容、框架重渲染），该 Range 会变成“分离状态”，range.toString() 返回空字符串，但不会报错。

• 每次触发更新（如输入、AJAX 回填）后，必须重新执行文本匹配逻辑，重建 Range 数组
• 不要复用旧 Range 对象，哪怕只改了 setEnd() —— DOM 变动后其内部锚点已失效
• 可监听 MutationObserver 检测目标区域变化，但开销大；更实用的是在业务逻辑中明确插入/删除节点后主动刷新高亮

实际用起来，最麻烦的不是创建 Range，而是确保它始终指向“还活着”的文本节点——DOM 不是静态快照，而是一直在呼吸的活体。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！