Plate TOC 导航点击失效的排查实录/blocks/toc-demo 路由调试方案【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文以 Plate 仓库中的调试计划文档 2026-04-07-debug-toc-demo-nav.md 为主体完整还原一次针对/blocks/toc-demo独立块路由的 TOCTable of Contents导航失效排查点击 TOC 行既不滚动定位、也不产生导航高亮且所有行都错误地渲染出aria-currenttrue。读完后你可以掌握一套「先确认端口对应的代码库、再对比渲染入口契约、最后以 DOM 可观测属性验证」的 Next.js 演示路由调试方法并能复现 BlockPreviewPage 与 ComponentPreview 两条示例渲染路径的id传递约定。问题目标与失败形态原始计划文档docs/plans/2026-04-07-debug-toc-demo-nav.md将目标定义为一句话Fixhttp://localhost:3002/blocks/toc-demoso TOC clicks navigate to the target heading and the target flash is visible.即修复http://localhost:3002/blocks/toc-demo路由使 TOC 点击能滚动到目标标题且目标标题的闪烁高亮可见。文档中同时记录了浏览器复现已确认的两个失败形态这是整个调试过程的锚点在/blocks/toc-demo上所有 TOC 行都错误地渲染出aria-currenttrue正常应只有激活行携带该属性点击 TOC 行既不触发滚动也不设置导航高亮。此外文档还留下了一条重要的约束性备注避免大范围重建www包Avoid broadwwwbuild unless absolutely needed——这暗示排查应优先走定点验证而非全量构建。分阶段排查计划计划文档将工作拆分为六个阶段并标注了完成状态阶段状态在/blocks/toc-demo复现并确认失败形态已完成检查既有经验与相关路由/组件模式待办隔离 bug 位于 blocks demo 包装层、生成的 registry 载荷还是 TOC 运行时待办实现最小的持久修复待办用测试、lint、必要时重建 registry、以及在/blocks/toc-demo上的浏览器验证收尾待办其中「隔离 bug 位于哪一层」这一阶段是方法论的核心候选范围包括 blocks demo 的路由包装组件、registry 构建产出的 JSON 载荷、以及platejs/toc的运行时钩子。这一假设空间在后续两份姊妹文档中被逐步收敛。关键发现端口 3002 服务的是另一个工作树两份伴随文档提供了完整的证据链。2026-04-07-debug-toc-demo-nav-findings.md 记录了四条关键发现toc-node.tsx源码已经使用aria-current{item.id activeContentId ? location : undefined}重建后的 registry JSON 也反映了该源码但在/blocks/toc-demo上实时 DOM/React props 仍显示每一行都带aria-currenttrue端口 3002 的实际工作目录是/Users/zbeyens/git/plate-2/apps/www即另一个工作树checkout。结论由此浮现plate-2 这个旧工作树的toc-node仍是「每行裸写aria-current 旧版 click-only 钩子」的实现。2026-04-07-debug-toc-demo-nav-progress.md 进一步佐证曾把导航闪烁时长调到 10 秒并加了可见的标题高亮样式但独立路由依然不导航registry 重建没有修复独立路由最终确认 3002 端口服务的是 plate-2 而非当前 checkout于是把验证迁移到http://localhost:3001/blocks/toc-demo。这是一次典型的「在错误的代码库上调试」陷阱症状、失败形态、甚至部分修复尝试都是真实的但根因不在当前仓库。当前仓库的源码印证在当前仓库中TOC 元素组件 toc-node.tsx 的实现与 findings 文档描述完全一致激活行高亮与 ARIA 状态由activeContentId驱动const { activeContentId, headingList } state; // 每一行 TOC 按钮 onClick{(e) btnProps.onClick(e, item, smooth)} aria-current{item.id activeContentId ? location : undefined}点击行为委托给platejs/toc/react导出的useTocElement(state)提供的btnProps.onClick第三个参数smooth决定平滑滚动。也就是说滚动与高亮逻辑在platejs/toc包内实现而aria-current与data-nav-highlight这类 DOM 可观测属性是验证其是否生效的探针。demo 内容本身定义在 toc-value.tsx其中包含hh2Benefits of Using TOC/hh2标题——progress 文档中「点击 Benefits of Using TOC 后出现一个aria-currentlocation行与一个data-nav-targettrue标题高亮」的浏览器验证正是以这一行为目标的。registry 元数据方面registry-ui.ts 将toc-node声明为依赖platejs/toc的 UI 条目关联文档路由/docs/toc并把toc-demo列为其示例registry-examples.ts 中toc-demo示例的registryDependencies为plate/toc-kit、plate/toc-node、plate/editor-kit文件清单指向examples/demo.tsx与examples/values/toc-value.tsx。生成产物见 registry-docs.json 与 toc-docs.json。同日的关联缺陷blocks 路由必须传入示例 id同一天的解决方案文档 2026-04-07-blocks-demo-pages-must-pass-example-id.md 记录了同一路由上更前置的另一个缺陷独立块路由/blocks/toc-demo曾返回500 Internal Server Error而文档预览路径正常。根因是 registry 的通用Demo组件不是自描述组件——它需要 demo slug 才能调用createValue(id)得到正确的种子键而 blocks 路由渲染时漏传了idprop。修复方式是把ComponentPreview已有的 id 派生约定镜像到 blocks 路由// apps/www/src/components/component-preview.tsx Component {...props} id{props.id ?? name.replace(-demo, )} /当前仓库中该约定仍然保留在 component-preview.tsx而独立的 blocks 路由则由 block-preview-page.tsx 承担直接以id: name.replace(-demo, )创建组件React.createElement(Component, { id: name.replace(-demo, ) })两条渲染路径由此共享同一份「示例渲染契约」toc-demo派生出idtoccreateValue(toc)才能命中 toc-value.tsx 注册的文档数据。该解决方案文档还明确将「先当作 TOC 包 bug 去查useTocElement」「重建 registry 输出」列入了无效尝试与本文 findings 中 registry 重建无效的记录相互印证。验证清单与可复现步骤综合三份文档最终被采纳的验证口径progress 文档为pnpm --filter www typecheck通过pnpm lint:fix通过浏览器验证http://localhost:3001/blocks/toc-demo点击Benefits of Using TOC后DOM 中恰好出现一个aria-currentlocation的 TOC 行以及一个data-nav-targettrue的标题高亮。这套断言可直接作为回归探针激活行必须唯一携带aria-currentlocation而非true点击后目标标题应出现data-nav-target高亮。调试经验与预防要点从计划、findings、progress 三份文档的完整闭环中可以提炼出四条可迁移的经验端口与 checkout 一致性优先当本地多个工作树同时起 dev server 时如 3001 与 3002调试前必须先确认端口实际服务的代码目录否则一切症状分析都可能建立在错误代码库上。计划文档末尾的备注与 progress 文档中「Next step: sanity check current repo on port 3001 and report the mismatch clearly」均指向此点对比渲染入口而非先怀疑运行时独立块路由与文档预览是同一示例的两个渲染面出现「一处好一处坏」时先对比两个包装组件的 props 契约此处即id传递再考虑底层插件运行时用 ARIA 与 data 属性做 DOM 级断言aria-currentlocation的「存在性 唯一性 取值」组合比肉眼观察滚动更能精确定位高亮逻辑是否执行控制构建面在修复不确定归属时优先走 typecheck、lint 与单页浏览器验证避免触发全量www构建拉长反馈周期。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考