DOCX 字段绑定连续改三次还在偏移？根因是坐标空间没对齐
做过「在线填表生成 DOCX」功能的同学可能遇到过这种情况：用户在浏览器里圈选一段占位下划线，点击绑定；后端拿到 { paragraphIndex, start, end } 去改 word/document.xml；生成后的文件看起来对，但打开一看——该替换的下划线旁边还多出来一个 _，或者根本没替换。
改一次不行，再改，还不行，第三次依然偏。git log 上全是 fix: align word coordinate binding offsets。
这不是启发式逻辑的问题，是客户端和服务端数字符的坐标空间从一开始就没有对齐。
现象
- 生成 DOCX 后，注入值旁边有多余下划线（如
地址：杭州市_）。 - 部分字段绑定正常，部分完全不注入——UI 显示"已绑定"，实际文件没变。
- 断点追踪发现，出错字段的段落恰好含有
<w:br/>，或者其上方有空段落用作视觉间隔。 - 测试套件全绿，生产环境报错——因为测试用的是手写 mock，从未真正渲染过
.docx。
根因
docx-preview 把 Word XML 渲染成 HTML 时，某些元素的字符宽度和服务端 XML 遍历器的计算方式不一致，导致四类静默偏移：
1. <w:br/> 换行符：docx-preview 渲染成 <br>，其 textContent 贡献 0 个字符；但浏览器的 range.toString() 在 <br> 边界会注入 \n（1 个字符）。服务端如果把 <w:br/> 算作 \n，双方对同一段落的文本长度就差 1，每多一个换行符就多偏移 1 位。
2. 自闭合 <w:p/> 段落索引偏移：Word 用自闭合 <w:p/> 表示空段落或分节间隔。服务端常见的正则 /<w:p\b[\s\S]*?<\/w:p>/g 会跳过自闭合形式，贪婪地把它并入下一个段落。客户端按 DOM 数到的第 N 段，服务端对应的实际上是第 N-K 段（K = 前面自闭合段落数）。
3. 严格模式静默失败：一种常见"防御性"写法是：有 wordLocation 但匹配不上时直接返回原始 XML，不报错、不记日志。坐标偏移 + 严格静默 = 合同生成完全正确地失败了。
docx-preview 渲染 <w:br/> 为零宽 <br>，paragraph.textContent 里看不到它；但 range.toString() 会在 Chrome 里多出 \n，服务端如果按 \n 计 1 字符，每个换行符就多出 1 个字符的偏移，最终替换到错误位置，原位留下一个多余 _。
正解
核心思路：以 paragraph.textContent 为唯一坐标基准，让客户端和服务端都用同一套字符计数规则。
服务端 runText 计数规则统一如下：
// <w:t>...</w:t> → 文本内容（正常计）
// <w:tab/> → '\t'（1 字符，与 docx-preview 的 em-space 对齐）
// <w:br/>、<w:cr/> → ''（0 字符，与 <br> 的 textContent 对齐）客户端偏移计算：
// 优先走 SHOW_TEXT 节点游走（准确）
// 降级到 range.toString() 时，必须 strip 掉 \n 和 \r：
const text = range.toString().replace(/[\n\r]/g, '')服务端段落正则，必须同时匹配自闭合和正常形式：
// 错误：跳过 <w:p/>，导致段落索引偏移
/<w:p\b[\s\S]*?<\/w:p>/g
// 正确：自闭合和正常段落都计数
/<w:p\b[^>]*\/>|<w:p\b[^>]*>[\s\S]*?<\/w:p>/g把 <w:br/> 在服务端统一为 0 字符、客户端 range.toString() 路径 strip \n、服务端段落正则同时匹配自闭合 <w:p/>——三处对齐之后，坐标契约才真正稳定。
一个快速探针
怀疑坐标空间是否对齐时，5 行 Node 脚本可以在读代码之前先复现症状：
// 服务端 joined text（错误计法）：'地址：\n______'（length 10）
// text.slice(3, 9) => '\n_____' ← 吃掉换行，留一个下划线
//
// 服务端 joined text（正确计法）：'地址：______'（length 9）
// text.slice(3, 9) => '______' ← 精准命中先跑这个探针，确认偏移来源，再改代码——比直接读几百行渲染器快得多。
测试套件里 docx.renderAsync = (_, c) => c.innerHTML = '<p>...</p>' 这类 mock 完全绕过了库的真实渲染逻辑，所有 <w:br/> / <w:tab/> / <w:p/> 的分歧都会被隐藏。需要用 Playwright + 实际 .docx 文件跑集成测试才能捕获到坐标契约的断裂。
一句话外卖
浏览器 DOM 的
textContent和服务端 XML 遍历器对"字符长度"的定义，默认不相等——在做任何坐标传递之前，必须显式对齐双端的计数规则。