合同审查这个场景，我做了快两年。业务方第一句话永远是：几万字的合同，我点左边目录，能不能直接跳到对应的条款？这句话背后就是今天要聊的——React 合同审查组件里的文档结构树渲染与定位问题。文档结构树不是新东西，但放在合同审查这种长文本、强交互、双向联动的业务里，坑比想象中多：层级解析、递归渲染、点击定位、滚动高亮、长文档性能，每一环都能单独写一篇踩坑实录。这篇文章会从零到一拆解这套组件的完整实现思路，适合正在做合同审查、在线文档、法规库、内容管理系统里结构树导航的同学参考。
1. 合同审查场景里，结构树到底解决了什么问题
合同审查业务的典型画像是这样的：审查员打开一份几十页的借款合同，要逐条核对利率、担保方式、违约责任、送达条款，每条都要跟法律规范比对，在风险点旁边批注。几百个条款铺在屏幕上一个滚动容器里，没有导航，只能靠鼠标滚轮一页页翻。翻到"第十二条"，眼睛得在密密麻麻的文字里找半天，翻过了再滚回去，纯体力活。
结构树组件切入的正是这个痛点。左侧一棵大纲树，展示合同的章、条、款层级；右侧正文区展示完整合同内容。点击左侧节点，右侧正文平滑滚动到对应条款；反过来，手动滚动正文时，左侧树节点自动高亮当前所在的条款。业务方要的就是这种双向联动，跟普通的"锚点目录"完全不是一个复杂度级别。
1.1 组件要交付的三项核心能力
我在设计这套组件时，把需求拆成了三块，每一块可以独立验证、独立测试：
- 契约解析：把原始合同文本解析成一棵有层级的TreeNode树，同时生成锚点映射表，保证树节点和正文DOM元素一一对应。这是所有功能的地基，也是80%的坑都埋在里面的地方。
- 树渲染：用递归组件渲染大纲，支持展开/折叠、选中态高亮、左侧树节点自身的长列表滚动。
- 双向定位：左侧点击树节点 → 右侧正文定位；右侧正文滚动 → 左侧树节点高亮跟随。两者相互独立，但在体验上必须同步，不能出现点击完了还没滚到位、或者正文滚到第20条高亮还停在第3条的情况。
很多教程把重点放在第2和第3步，实际上第1步数据模型设计直接决定第3步定位好不好写。我后面会按照这个顺序把每一部分讲透。
提示：这套组件不是某个开源库的包装，而是围绕合同审查交互定制的一套组合。核心交互逻辑其实可以复用到任何"文件大纲+内容预览"的双栏业务里，无需拘泥于合同领域。
2. 动手之前，先把合同文本解析成树
合同文本的层级结构有其独特性。标准合同通常是"章 → 条 → 款/项"三级，部分复杂协议会多出"编""部分"这种顶层结构，辅以"1.1"“1.1.1”这类数字编号。比如：
第一章 总则 第一条 合同目的 1.1 借款用途 1.2 借款金额 第二条 定义这段文本对应到树结构里，就是三个层级。我定义的TreeNode类型长这样：
export interface ContractTreeNode { id: string; // 唯一锚点ID，用于定位 title: string; // 节点显示文本 level: number; // 1=章 2=条 3=款 children: ContractTreeNode[]; rawIndex?: string; // 原始编号文本，如 "第三条" }锚点ID的设计是第一个关键决策。我见过一些实现直接用自增序号当id：parse完文档给每个节点编上node-1、node-2。这个做法在静态文档下没问题，但合同一旦通过增删条款修订后重新解析，序号全部漂移，左侧树node-5对应到正文里的可能是完全不同的另一个条款，定位全部错乱。保险的做法是用条款的原始编号加标题摘要作为id的种子，比如chapter-1-clause-3，这样只要合同内容不变，锚点就是稳定的。
2.1 解析算法：正则匹配 + 栈构建
解析的核心思路是逐行读取文本，用正则识别每行的层级，再用一个栈来维护父子关系。我用的是这样一个简化版：
function parseContractToTree(text: string): ContractTreeNode[] { const lines = text.split('\n'); const root: ContractTreeNode[] = []; const stack: { level: number; node: ContractTreeNode }[] = []; const matchers = [ { level: 1, pattern: /^第[一二三四五六七八九十百零]+[编章节部分]/ }, { level: 2, pattern: /^第[一二三四五六七八九十百零]+条/ }, { level: 3, pattern: /^\d+\.\d+/ }, { level: 4, pattern: /^（[一二三四五六七八九十]+）/ }, ]; for (const line of lines) { const trimmed = line.trim(); if (!trimmed) continue; let matchedLevel = -1; let matchedText = ''; for (const matcher of matchers) { if (matcher.pattern.test(trimmed)) { matchedLevel = matcher.level; matchedText = trimmed.slice(0, 30); // 只保留标题前30字 break; } } if (matchedLevel === -1) continue; const node: ContractTreeNode = { id: generateAnchorId(trimmed), title: matchedText, level: matchedLevel, children: [], }; while (stack.length > 0 && stack[stack.length - 1].level >= matchedLevel) { stack.pop(); } if (stack.length === 0) { root.push(node); } else { stack[stack.length - 1].node.children.push(node); } stack.push({ level: matchedLevel, node }); } return root; }栈的操作逻辑是：新节点到来时，不断弹出层级≥当前节点的栈顶，直到找到比它更浅的父节点。比如读到"第二条"（level 2）时，栈里可能还有"第一章"（level 1），那就把第二条挂到第一章下面；如果读到"第二章"（level 1），则把所有更低层级（包括第一章本身）弹出，第二章成为新的根。
这一步跑完之后，我会在内存里保留一棵完整的树，同时递归遍历这棵树，给每个节点生成并记录它的DOM锚点id。锚点id之后会在渲染正文时渲染到对应标题元素上，作为document.getElementById的索引。
2.2 三类常见的异常合同格式
解析不是写一个正就万事大吉，实际合同文本的混乱程度超出想象。我踩过的三类问题，这里提前说一下：
- 半角数字直接做条号：很多简版合同不写"第一条"，而是写"1."或"1、"开头。如果你的正则只匹配中文条文号，这类合同会直接漏掉。处理方式是把
/^\d+[.、]/也纳入匹配。 - “补充协议”与“主协议”的条文编号完全同构：“第一条 本次补充内容”和主合同里的“第一条”含义不同，但正则识别出的锚点文本一样。我最终在生成锚点id时加了一个前缀参数，传入的是"main"还是"supplement"，避免id冲撞。
- “第X条”和“1.1”混编在同一层：一些合同正文里，"第三条"下面既有"3.1"，也有直接以"（一）"开头的段落。这种情况下，我建议把条第下所有无编号但与条关联的短段落统一归并入当前条的children，不要因为没匹配到编号就丢弃。
解析结果应该在组件mount前完成，最好放到useMemo或状态初始化里，后面第6章我会讲为什么要这么做，因为这块没做好直接导致卡顿。
3. 文档树的递归渲染与组件通信选择
树结构渲染，我直接用递归组件实现。这个思路几乎所有前端都见过，但把组件通信、状态管理、key策略都做对，才是生产可用的关键。
TreeNode组件的大致代码是这样的：
function TreeNode({ node, activeId, expandedIds, onSelect, onToggle, }: TreeNodeProps) { const hasChildren = node.children.length > 0; const isExpanded = expandedIds.has(node.id); const isActive = activeId === node.id; return ( <li> <div className={`tree-node ${isActive ? 'tree-node-active' : ''}`} style={{ paddingLeft: (node.level - 1) * 16 }} onClick={() => onSelect(node)} > {hasChildren ? ( <button onClick={(e) => { e.stopPropagation(); onToggle(node.id); }} > {isExpanded ? '▾' : '▸'} </button> ) : <span className="tree-leaf-placeholder" />} <span className="tree-node-title">{node.title}</span> </div> {hasChildren && isExpanded && ( <ul> {node.children.map((child) => ( <TreeNode key={child.id} node={child} activeId={activeId} expandedIds={expandedIds} onSelect={onSelect} onToggle={onToggle} /> ))} </ul> )} </li> ); }这一段看着简单，但有几个细节决定它能不能真正复用：
key必须用child.id，不能用数组下标。原因很简单：合同文本修订后解析出来的是新树，如果中间插入一条新条款，后面的节点index全部后移，React会把之前节点的state匹配到错误的新节点上。用稳定id做key，Diff才能准确定位增量变化。- 点击事件上用了
e.stopPropagation()，避免点展开按钮时触发节点选中。 - 缩进不搞嵌套div的边距嵌套，而是直接在行内算
paddingLeft。这样在虚拟滚动、折叠动画等场景下不会出现内层容器尺寸爆炸。
3.1 展开/折叠状态放哪里：局部state还是提升到顶层
当前很多树组件示例会在每个TreeNode内部用useState管理自身展开状态，看起来省事，但在合同审查这个场景里会出问题：当用户从"展开全部条款"切换到"只展开到章"时，需要在外部批量修改所有节点的展开状态，如果状态分散在每个子树里，就得递归遍历DOM去触发，既不优雅也容易漏。
我最开始也是用的局部state，直到业务提出"一键展开/一键收起"这个需求后才改成受控组件：所有展开状态集中为expandedIds: Set<string>，放在树组件顶层，通过props下传，配合onToggle回调来更新。这样无论是单点切换、全部展开、全部收起，都只是改一个Set的问题。
const [expandedIds, setExpandedIds] = useState<Set<string>>( () => new Set(defaultExpandedIds) ); const handleToggle = useCallback((id: string) => { setExpandedIds((prev) => { const next = new Set(prev); next.has(id) ? next.delete(id) : next.add(id); return next; }); }, []); const expandAll = useCallback(() => { setExpandedIds(new Set(allTreeNodeIds)); }, [allTreeNodeIds]);注意：setExpandedIds里我用的是创建新Set而不是在原Set上改。React的state更新依赖引用变化，如果原地add/delete，组件不会感知到更新，这是写这类集合状态最容易踩的坑。
3.2 父子通信在树组件里的实际用法
这里正好回答常见的一个问题：React里组件通信父传子、子传父在树组件里到底怎么落地。
- 父传子：树顶层把
activeId、expandedIds这些状态通过props传给TreeNode，递归组件天然就是逐层传props，清晰且可追溯。 - 子传父：TreeNode内部不维护业务状态，所有上报都通过回调函数。点击节点时调用
onSelect(node)，展开时调用onToggle(id)，这是最直接的"子传父"。父组件拿到node对象，接下来要么触发正文定位，要么更新展开集合。
我刻意没有在这套组件里用Redux或Context来管理树状态。原因不是它们不好，而是树状态的范围只覆盖单个审查工作台，状态粒度非常集中，用Context反而会让组件重新渲染的边界变模糊。如果产品形态变成"多个合同tab同步维护同一棵大纲树"，那Context的价值才体现出来。做技术选型时，先问清楚状态的作用域是页面级还是应用级，比盲目引入状态管理库重要得多。
4. 点击树节点定位右侧文档：三种方案实测对比
我在这套组件里先后试过三种定位方案，每个方案都有它的适用场景，但只有第三种真正扛住了合同正文的复杂布局。
| 方案 | 核心实现 | 优点 | 致命问题 |
|---|---|---|---|
| scrollIntoView | el.scrollIntoView({block:'start'}) | 代码量最小，浏览器自动滚到目标 | 会连带滚动所有祖先容器；固定头部场景目标会被遮挡；嵌套滚动容器里行为诡异 |
| 锚点hash跳转 | <a href="#clause-3-2"> | 天然支持 | SPA路由会拦截hash变化，行为不可控；重复点击同一锚点不会触发跳转；页面会闪跳 |
| 手动scrollTo | container.scrollTo({top: offsetTop}) | 可控性最强，兼容性好 | 需要自行计算偏移量，代码量多一些 |
我最终选定方案三，核心代码如下：
function scrollToAnchor(anchorId: string) { const target = document.getElementById(anchorId); if (!target) return; const container = getScrollContainer(target); const targetRect = target.getBoundingClientRect(); const containerRect = container.getBoundingClientRect(); // 目标相对于滚动容器的偏移 const offsetTop = targetRect.top - containerRect.top + container.scrollTop; container.scrollTo({ top: offsetTop - STICKY_HEADER_OFFSET, behavior: 'smooth', }); }这里有几个值得展开讲的点。
getScrollContainer的作用是找到目标元素最近的可滚动祖先。合同正文通常包在一个设置了overflow的div里，而不是直接挂在window上。如果直接用window.scrollTo，页面不动，以为代码写错了，其实是滚动容器搞错了。实现很简单，从目标元素一路向上遍历，检查scrollHeight > clientHeight且有非visible的overflow即返回：
function getScrollContainer(el: HTMLElement): HTMLElement { let current: HTMLElement | null = el; while (current && current !== document.body) { if (current.scrollHeight > current.clientHeight && /(auto|scroll|overlay)/.test(getComputedStyle(current).overflowY)) { return current; } current = current.parentElement; } return document.documentElement; }4.1 吸顶工具栏和行号栏的偏移修正
合同审查的正文区上面通常会有一个吸顶的工具栏，放着"批注""高亮""导出"这些操作按钮，高度大约56px。如果用scrollIntoView或者不做偏移的scrollTo，目标标题会被吸顶栏挡住，审查员看到的是被遮住的一截文字，尤其条款标题这种没有足够上下padding的元素，直接看不见。
STICKY_HEADER_OFFSET这个常量就是用来补偿这个高度的。我实际取值是：
const STICKY_HEADER_OFFSET = 72; // 吸顶栏实际高度56px + 额外16px留白多加16px留白是我的习惯。目标正好停在视口顶部，对阅读来说反而不舒服，稍微往下一点更有呼吸感。这个值建议做成props可配置，因为不同客户端的工具栏高度不一样。
4.2 嵌套滚动容器产生的双重偏移
如果页面布局是"整体页面可滚动 + 左侧树可滚动 + 右侧正文嵌套滚动"，那就得小心了：getBoundingClientRect返回的是相对于视口的坐标，目标元素在正文滚动容器内，正文容器又在页面里偏了一定的位置。我上面的计算公式targetRect.top - containerRect.top + container.scrollTop已经同时处理了这两个偏移，不需要再额外加页面本身的scrollTop。
但如果滚动容器本身又嵌套了一层，比如合同正文放在一个"左侧树+右侧正文"的flex布局里，这个flex布局的父级也能滚动，就得用上面的getScrollContainer找到最近一层的容器来做计算，而不是写死某一个id。我第一版就是写死了document.getElementById('contract-body')，后来页面加了面包屑导航，整个布局往下移，定位变得偏了，改成动态查找后才稳定。
5. 反向联动：滚动文档时树节点自动高亮
点击左侧定位右侧，只是双向联动的半边。另一半是用户直接在右侧正文里滚动浏览，左侧树需要实时高亮"用户当前看到的是第几条"。这个交互做不好，树就只是个单向跳转目录，审查员来回切换时不知道自己在哪。
5.1 滚动事件 + 防抖的常规做法
第一次实现用的是一套"滚动事件 + 遍历判断"的逻辑：
const handleScroll = throttle(() => { const scrollContainer = getScrollContainer(activeTarget); const currentTop = scrollContainer.scrollTop; let currentId = treeNodes[0].id; for (const node of anchorElements) { if (node.offsetTop <= currentTop + STICKY_HEADER_OFFSET) { currentId = node.dataset.anchorId; } else { break; } } setActiveId(currentId); }, 100);思路是：拿到滚动容器的scrollTop，遍历所有带锚点id的标题元素，找到最后一个offsetTop小于当前视口顶部的标题，它就是要高亮的节点。这个方案在几百个节点内性能可用，但要处理两个问题：
- 容器相对页面的偏移。标题元素的
offsetTop是相对于offsetParent的，如果滚动容器内部有嵌套定位，这个值可能不准。用getBoundingClientRect替代会更稳，但每次循环里读布局会触发强制同步布局，滚动时会卡。 - 靠
offsetTop判断要保证元素在文档流中。如果中间有绝对定位元素，索引关系会乱。
后来我把逻辑换成了IntersectionObserver，整体代码不但更简洁，性能也更好。
5.2 用IntersectionObserver替代滚动事件，差距明显
IntersectionObserver的思路是：观察所有标题元素，当它们进入一个激活区时触发回调。合同正文的可视区域很大，一个章节如果占了大半个屏幕，它的标题会一直停留在视口内，上一条和这一条同时可见。所以不能用threshold: 0观察整个视口，而是把观察区缩成一条"水平扁带"：
const observer = new IntersectionObserver((entries) => { for (const entry of entries) { if (entry.isIntersecting) { const id = (entry.target as HTMLElement).dataset.anchorId; if (id) setActiveId(id); } } }, { root: scrollContainer, rootMargin: '-20% 0px -70% 0px', // 激活区缩小为视口顶部20%到30%的区域 threshold: 0, });rootMargin负值会把观察区域压缩成视口中间的横向条带，这样只有当标题进入这个条带时才认为它是"当前条款"。我实测下来，这比滚动事件+遍历少了大约一多半的无效计算，而且不用手动处理防抖——浏览器在滚动过程中自动按帧调度observer回调。
注意：
rootMargin只对指定了root的IntersectionObserver生效。如果不传root，默认观察视口，那滚动容器内部的元素永远不会正确触发，因为对浏览器来说它们都在视口内。这个坑我踩过，调试了好一会儿才醒悟。
5.3 高亮节点后，让左侧树滚动到可见位置
还有一个小交互：左侧树通常比正文短，当用户滚到第80条时，高亮节点可能早就超出左侧树的视口范围了。我的做法是给树容器设置scrollIntoView修正，保证高亮节点可见：
useEffect(() => { const activeEl = treeContainerRef.current?.querySelector('.tree-node-active'); activeEl?.scrollIntoView({ block: 'nearest', behavior: 'smooth', }); }, [activeId]);block: 'nearest'很关键，它只在节点超出容器可视范围时才滚动，节点本来就在视野内时不会产生多余的平滑滚动，避免每次滚动正文时左侧树都在那抽搐。这个小细节做完，整体体验才配得上"联动"这两个字。
6. 长文档渲染的性能瓶颈与实测优化
合同动辄几千上万个条款，结构树渲染的性能不能靠"应该没问题"来赌。我针对这套组件做的三类优化，每一类都有效果，但它们的适用边界差别很大。
6.1 实测数据：几千个树节点会不会把React拖垮
先说结论：在React 18下，几千个树节点的一次完整递归渲染耗时并不高。我拿一份实际项目里的设备采购合同测试过，解析后1,200多个节点，全量展开一次性渲染，首屏渲染耗时约85ms，交互点击响应在16ms上下，整体在可接受范围内。
真正的性能瓶颈不在渲染本身，而在两个容易被忽略的地方：
- 文本解析没有缓存。组件每次更新都重新跑一遍
parseContractToTree，这段纯JS解析在几万字合同上要花30~50ms，一旦有其他state更新触发重渲染，用户会感觉输入、滚动卡顿。 - 树节点的props每次父组件render都会生成新对象，导致所有TreeNode都跟着重渲染。配合React.memo去控制叶子节点的小范围更新，收益最明显。
6.2 useMemo缓存解析结果，一次解析多次复用
解析结果只依赖合同原文，原文不变结果就不变，所以非常合适放进useMemo：
const { treeData, anchorMap } = useMemo( () => parseContractToTree(rawContractText), [rawContractText] );rawContractText未变化时，React会复用上一次的解析结果，不再走解析逻辑。我在实际项目里的感受是：对3万字的合同，缓存前每次热更新或state变化要白等50ms，缓存后再也没有解析耗时的感知。
另外提醒一点，anchorMap也要在这儿一并生成，不要等渲染后再去遍历DOM收集——所有标题节点在解析阶段就分配好id，渲染时直接设置到id属性上，定位时document.getElementById直接命中。这样一致性最好，也不用担心DOM还没刷新的时序问题。
6.3 React.memo的正确用法与滥用后果
我给TreeNode组件加memo是这么做的：
const TreeNodeMemo = memo(TreeNode);但要让它真正生效，必须同时保证父组件传给TreeNode的props引用稳定。实际项目中我遇到过这样的代码：
{node.children.map((child) => ( <TreeNodeMemo key={child.id} node={child} onSelect={(n) => handleSelect(n)} // 每次render都是新函数 /> ))}这样写，memo直接失效，因为onSelect每次都变，TreeNodeMemo的props对比永远不相等。正确做法是把回调函数用useCallback包起来：
const handleSelect = useCallback((node: ContractTreeNode) => { setActiveId(node.id); scrollToAnchor(node.id); }, []); const handleToggle = useCallback((id: string) => { setExpandedIds(prev => { ... }); }, []);把这两个回调传给TreeNodeMemo，配合expandedIds和activeId这两个稳定引用，React才能精准跳过没变化的节点。
但memo也不是万能的，无脑套memo反而会有反效果。如果节点props里带有频繁变化的数据（比如自定义标题的颜色、当前搜索高亮词），每次都触发重渲染，做浅比较本身也要消耗。我见过把整个表格包在三层memo里结果性能更差的案例。对树组件来说，合理的做法是：用memo包住叶子层级（level较高的节点），因为这些节点数量最多、变化最不频繁；对靠近根节点的顶层节点不包，因为它的更新频率本来就高，memo带来的命中率很低。
6.4 什么时候才需要虚拟滚动
我对这套合同的树做过虚拟滚动方案的选型评估，但最终没有上。原因很简单：
- 合同审查场景里，树节点数量通常在几百到两千之间，全量渲染已够用；
- 虚拟滚动对树形结构有一个天然麻烦：展开/折叠某节点会导致所有子节点的高度偏移，需要维护一个"扁平化可见节点列表"，每次状态变化都要重新计算可见范围，复杂度高；
- 二级联动时，高亮节点还要求树自动滚动到可见位置，虚拟滚动下这个滚动计算会叠加更多边界条件。
如果你的目标是做“合同库管理平台”，一棵树几万个节点，那虚拟滚动绕不开。以我当时的需求来说，在性能瓶颈真正暴露之前，选择先优化解析缓存和memo层级，收益更大。
这套组件沉淀下来的三个实用经验
项目从第一版到稳定用了快三周，中间推翻过两次数据模型。最后沉淀下来的经验，简单总结三条：
第一，锚点id是连接树和正文的唯一线索，设计时要想清楚改版后会不会漂移。用条款原文编号做种子，比用自增序号可靠得多。审查系统里合同版本频繁更新，模板一变节点顺序就变，但条款编号是稳定的实义信息。
第二，滚动定位的偏移计算，永远要以"最近可滚动容器"为基准，而不是写死容器id。页面加个面包屑、多了个审批栏，布局整体往下挪，写死id的方案就要返工；动态查找最近的滚动祖先，一套逻辑跑遍所有页面。
第三，双向联动的高亮判断，优先用IntersectionObserver而不是手动监听scroll。前者把边界处理、节流、浏览器调度都接管了，代码量更少，行为更可控。在复杂滚动容器场景里，手写scroll事件的坑（嵌套滚动、offsetParent干扰、强制同步布局）远比想象中多。
这套组件我在后续两个合同类项目里复用了，换汤不换药，核心的解析、定位、高亮三块逻辑基本没改。如果你也在做类似的文档结构树，建议先把数据模型和锚点体系设计好再聊渲染，这步走稳了，后面需求再多也不会慌。
