侧边索引需用JS扫描h2-h4标题并清洗ID（去标点、去重、去空）、用scrollIntoView精准滚动、DocumentFragment离屏构建DOM、事件委托绑定，避免卡顿与定位失败。
侧边索引怎么绑定到标题元素上
侧边索引本身不“知道”页面里有哪些标题，必须靠 JS 主动扫描并建立映射关系。常见错误是只给 h2 加 id 却忽略清洗逻辑：中文、空格、标点直接当 id 值会导致无效锚点，浏览器静默失败。
- 用
document.querySelectorAll("h2, h3, h4")获取目标标题，别漏掉h3/h4—— 它们常被当作子章节，跳转需求同样强烈 -
id必须满足 HTML 标识符规范：首字符不能是数字，只能含字母、数字、下划线、短横线。清洗示例：text.replace(/[^a-z0-9\u4e00-\u9fa5]/gi, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "") - 重复标题（如多个“配置说明”）必须加序号后缀，否则后一个会覆盖前一个
id，导致只有最后一个能跳转 - 空标题（
）或纯空白文本要skip，否则生成id=""，触发控制台警告且破坏后续逻辑
点击索引项如何精准滚动而不跳顶
直接改 location.href = "#xxx" 看似简单，但会强制整页跳转、URL 地址栏刷新、无法取消、也不支持平滑滚动（除非全局设 scroll-behavior: smooth，但 Safari 旧版不认，且影响所有滚动行为）。
- 优先用
element.scrollIntoView({ behavior: "smooth", block: "start" })，它不改 URL，可监听、可中断、兼容性好（IE 不支持，但 IE 已淘汰） - 必须先检查目标元素是否存在：
if (targetEl) targetEl.scrollIntoView(...)，否则报错Cannot read property 'scrollIntoView' of null - 目标在折叠面板（
display: none）里？得先show再滚动，否则无效；可用getComputedStyle(targetEl).display === "none"判断 - 移动端 Safari 对
behavior: "smooth"支持不稳定，建议降级：behavior: "smooth"→behavior: "auto"，或用window.scrollTo()手动算位置
侧边索引 DOM 怎么生成才不卡顿
几十个标题逐个 appendChild 或拼 innerHTML，在低端设备上会明显卡顿，因为每次操作都触发重排（reflow）。关键不是“有没有索引”，而是“DOM 构建是否离屏”。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 绝对不要用
innerHTML += ...累加，每赋一次值都解析一遍 HTML 并重排 - 用
document.createDocumentFragment()先离屏构建完整索引树，最后一次性appendChild - 缩进靠 CSS 实现（如
margin-left: calc(var(--level) * 1.5em)），别用 JS 动态设style.marginLeft - 绑定点击事件用事件委托（监听索引容器），而不是每个索引项单独绑，减少内存占用和事件监听器数量
为什么点击没反应却没报错
这类问题最棘手：控制台安静，页面无变化，用户以为功能坏了。根源往往不在 JS 逻辑，而在 DOM 状态或 CSS 隐藏规则。
- 检查目标元素是否真有
id：右键审查元素，看属性栏里有没有你期望的id值，不是看 innerText - 确认索引项点击时是否触发了默认跳转（比如用了
a标签但没e.preventDefault()），结果页面跳到顶部，掩盖了滚动意图 - 目标区域是否被
overflow: hidden或transform等 CSS 属性截断？scrollIntoView在这种容器里可能失效 - JS 是否在 DOM 加载完成前就执行？确保放在
<script></script>底部，或包裹在DOMContentLoaded里
侧边索引最难的从来不是“怎么写出来”，而是“怎么让每个标题都稳稳对应、每次点击都准确定位、每台设备都不卡不崩”。清洗 id、判断可见性、离屏构建、防默认行为——这些细节一漏，用户就卡在半路。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
