主次导航DOM必须语义嵌套或视觉分离，主导航用，次导航紧贴服务内容区域并设aria-current；响应式需分层折叠，禁用aria-hidden；须与URL、路由联动。

主次导航的 DOM 层级不能平级堆叠

主导航（如顶部横栏）和次导航（如左侧菜单或页面内 Tab）必须有明确的语义嵌套或视觉分离，否则屏幕阅读器会混淆层级，aria-current 也容易失效。常见错误是把两个 nav 元素并列放在 header 里，结果次导航被读作“另一个独立导航”，而非“当前页面下的子路径”。

• 主导航用
  ，包裹全局跳转链接（首页、产品、关于等）
• 次导航应紧贴其服务的内容区域：若在文章页，次导航放 article 内部；若为模块化面板，放在对应 section 的开头
• 避免把次导航塞进 header 或 aside 后再靠 CSS 定位到内容区——DOM 位置和视觉位置不一致时，键盘焦点流和语义树会断裂

次导航必须绑定当前上下文，不能靠 class 切换状态

仅靠 class="active" 控制样式无法让辅助技术感知“当前所处位置”。例如次导航中“API 文档”高亮了，但没声明它是当前页主题，视障用户仍需逐项确认。

• 每个次导航项使用 aria-current="page"（当前页面）或 aria-current="step"（向导步骤），且仅对真实匹配的项设置
• 若次导航动态加载（如通过 JS 渲染），必须同步更新 aria-current，不能只改 class
• 不要用 aria-selected="true" 替代 aria-current：前者用于可切换的 tablist，后者才表示“当前位置”

响应式下主次导航的折叠逻辑要分层处理

移动端常把主次导航都收进汉堡菜单，但一并折叠会导致信息密度爆炸——用户点开后看到 15 个选项，根本分不清哪些是全局入口、哪些只属于当前模块。

DeepBI DHTML 页面生成器

生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur

下载

• 主导航折叠进一级菜单（menu-primary），保持始终可访问
• 次导航默认隐藏，仅当用户进入对应模块（如点击“开发者”主项后）才动态注入二级菜单容器 menu-secondary
• 折叠后的次导航项应带视觉前缀（如灰色小箭头 + “在「开发者」中：”），避免孤立呈现

用 role="navigation" 补位时得小心语义污染

有些老项目用 div role="navigation" 代替 nav，看似能绕过语义限制，实则更危险：多个同级 role="navigation" 会让读屏软件全部播报为“navigation”，毫无区分度。

• 优先用原生 nav，最多两个：一个 aria-label="primary"，一个 aria-label="secondary"
• 若必须用 role（如框架限制），至少补全 aria-labelledby 指向唯一标题元素，例如：

  配置选项
• 绝对不要给次导航加 aria-hidden="true" 再靠 JS 显隐——这等于直接砍掉语义，比不写还糟

次导航最容易被忽略的，是它和 URL 路径、history.state、以及服务端路由模板之间的联动。DOM 结构再规范，如果点击次导航项不触发真正的 URL 变更（哪怕只是 hash），或者 SSR 没预置对应激活态，整个导航链就断在第一环。