本文介绍一种安全、可控的 javascript 方法，通过正则匹配与 dom 操作结合，在原始 html 字符串中精准插入 `` 等标签，包裹跨元素边界的文本范围（如 `"a text"` 到 `"needs"`），避免破坏原有结构。
直接对 innerHTML 使用 .replace()（如 el.innerHTML = el.innerHTML.replace(...)）看似简洁，但存在严重风险：它会将整个 HTML 重新解析为字符串再替换，极易导致事件丢失、表单状态清空、自定义元素销毁，且无法正确处理嵌套标签、属性转义或文本节点与元素节点的边界问题。
✅ 推荐方案：基于 DOM 的文本节点遍历 + 范围包裹（Range-based wrapping）
该方法不依赖字符串替换，而是真实操作 DOM 树，确保结构完整性与语义准确性：
This is a text that needs to be manipulated
function wrapTextInRange(parentElement, startText, endText, options = {}) {
const { id = 'phrase_1', className = '' } = options;
// 创建包裹用的 span 元素
const wrapper = document.createElement('span');
wrapper.id = id;
if (className) wrapper.className = className;
// 获取所有文本节点（深度优先）
const walker = document.createTreeWalker(
parentElement,
NodeFilter.SHOW_TEXT,
{ acceptNode: node => node.textContent.trim() ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT }
);
let foundStart = false;
let startNode = null;
let startOffset = -1;
let endNode = null;
let endOffset = -1;
// 第一遍：定位 startText 和 endText 所在的文本节点及偏移
const nodes = [];
while (walker.nextNode()) {
nodes.push(walker.currentNode);
}
for (const node of nodes) {
const text = node.textContent;
if (!foundStart && text.includes(startText)) {
startNode = node;
startOffset = text.indexOf(startText);
foundStart = true;
}
if (foundStart && !endNode && text.includes(endText)) {
endNode = node;
// 匹配 endText 在其所在文本中的起始位置，并延伸至末尾（含）
const endIdx = text.indexOf(endText);
endOffset = endIdx + endText.length;
break;
}
}
if (!startNode || !endNode) {
console.warn('⚠️ Start or end text not found in DOM');
return null;
}
// 构建 Range 并包裹
const range = document.createRange();
range.setStart(startNode, startOffset);
range.setEnd(endNode, endOffset);
// 将选中内容移动到 wrapper 中
range.surroundContents(wrapper);
return wrapper;
}
// 使用示例：
const container = document.getElementById('container');
wrapTextInRange(container, 'a text', 'needs', { id: 'phrase_1' });执行后，DOM 将变为：
立即学习“前端免费学习笔记（深入）”；
This is a text that needs to be manipulated
? 关键注意事项：
- ✅ 支持跨多个文本节点和嵌入元素（如 ）的连续语义范围；
- ⚠️ range.surroundContents() 要求范围必须完全位于同一个父节点内；若 startText 和 endText 分属不同父级（如被
或块级元素硬性分割），需先合并父容器或改用 range.extractContents() + 手动插入；- ? 若原始 HTML 来自不可信来源，请务必在插入前对 startText/endText 做 HTML 实体转义（如用 textContent 替代 innerHTML 渲染），防止 XSS；
- ? 进阶可封装为 Web Component 或支持正则匹配、多段包裹、撤销机制等。
此方法兼顾精确性、健壮性与可维护性，是现代前端处理动态文本标注、高亮、富编辑等场景的推荐实践。
- ⚠️ range.surroundContents() 要求范围必须完全位于同一个父节点内；若 startText 和 endText 分属不同父级（如被
