Skip to content

Sidebar 侧边导航 ​

Sidebar 侧边导航是在同一产品或模块内,以纵向列表持续呈现多个目的地的导航区域。它适合桌面管理工具、开发工具和复杂工作台;它不是任意放在页面左边的工具面板,也不等于 ARIA menu 或 tree。

能力边界与前置知识 ​

本文讨论用于页面导航的 Sidebar,不讨论:

  • 文档大纲;
  • 筛选面板;
  • 属性检查器;
  • 聊天联系人列表;
  • 只放图标的应用启动栏;
  • 可拖动改变主内容的分栏容器。

这些结构可能也位于侧边,但任务、语义和键盘模型不同。

前置知识:

  • 能区分产品级、模块级、对象内导航;
  • 了解 URL、页面标题、当前项和深链;
  • 了解 HTML 链接、列表、nav 地标与焦点顺序;
  • 能列出加载、无权限、窄屏和错误状态。

完成本文后,应能决定是否使用 Sidebar,定义导航数据模型,处理分组、折叠、权限、当前项和窄屏转换,并验证键盘、屏幕阅读器和路由行为。

Sidebar 适合以下条件同时成立的任务:

  • 同一产品范围内有较多稳定目的地;
  • 用户会在多个目的地之间反复切换;
  • 当前目的地需要持续可见;
  • 纵向空间比横向空间充足;
  • 桌面是重要使用环境;
  • 目的地名称需要比图标提供更多信息。

不适用情形:

  • 只有 3 到 5 个稳定顶级区域,顶部导航已足够;
  • 内容阅读需要占满横向空间,导航使用频率低;
  • 侧边内容本质是当前页面筛选;
  • 层级频繁变化且没有稳定命名;
  • 移动端是唯一平台;
  • 用户需要同时查看两个工作对象,实际需要的是分栏而非导航。

导航地标 ​

使用 <nav> 表达一组页面导航链接。

页面只有一个导航地标时,名称可以省略;页面同时有产品导航、项目导航和页内导航时,每个地标需要按目的区分:

html
<nav aria-label="产品">
  <!-- 产品级目的地 -->
</nav>

<nav aria-label="项目">
  <!-- 当前项目目的地 -->
</nav>

名称应表达用途,不写“左侧导航”。位置会随窄屏布局改变,“左侧”不能说明这组链接负责什么。

产品或模块身份 ​

Sidebar 顶部可以显示:

  • 产品名;
  • 当前工作区;
  • 当前项目;
  • 工作区切换入口。

身份区与目的地列表分开。切换工作区会改变整组导航数据和 URL 范围,不应伪装成普通目的地。

分组 ​

分组降低长列表扫描成本。每组需要稳定规则,例如:

  • 工作对象:项目、任务、成员;
  • 运营能力:自动化、报表;
  • 管理能力:权限、账单、审计。

不要按页面所有者团队分组。用户不应先知道功能由“平台组”还是“增长组”开发。

分组标题通常是静态文本。只有标题确实控制子项显示时才使用按钮。

目的地 ​

目的地使用链接,因为它改变页面位置并应支持:

  • 新标签页打开;
  • 复制链接;
  • 浏览器后退和前进;
  • 深链;
  • 访问历史;
  • 链接上下文菜单。

不要用只有 onClick 的 <div> 模拟链接。

当前项 ​

当前项需要同时满足:

  • 视觉高亮;
  • aria-current="page";
  • 页面标题与链接名称对应;
  • URL 匹配正确;
  • 祖先分组在需要时展开;
  • 颜色不是唯一提示。

aria-selected 用于特定复合控件的选择状态,不是普通导航当前页的默认表达。

折叠控制 ​

折叠可以有两种含义:

  1. 整个 Sidebar 从完整模式变成紧凑模式;
  2. 某个分组展开或收起子项。

两者状态、按钮名称和持久化策略必须分开。

整栏折叠按钮应说明结果,例如“收起项目导航”;折叠后按钮名称变为“展开项目导航”。

辅助操作 ​

创建项目、添加成员等高频操作可以靠近相关导航,但必须与目的地链接区分:

  • 导航使用链接;
  • 写操作使用按钮;
  • 危险操作不进入主导航;
  • 操作完成后的目标位置和结果反馈明确。

信息模型 ​

一个目的地至少包含:

json
{
  "id": "project.members",
  "label": "成员",
  "href": "/workspaces/w-17/projects/p-42/members",
  "group": "project",
  "requiredCapability": "project.members.read",
  "match": {
    "kind": "route-segment",
    "value": "members"
  },
  "badge": {
    "kind": "count",
    "value": 3,
    "accessibleLabel": "3 个待处理邀请"
  }
}

字段作用:

字段作用错误表现
id跨语言和改名稳定识别目的地用 label 作键导致改名丢状态
label可见链接文本和可访问名称来源只显示图标,目的不可理解
href深链和浏览器历史点击后只改本地面板
group稳定分组相同入口在多组重复
requiredCapability服务端返回的发现能力前端按角色名硬编码
match当前项匹配规则/team 错误匹配 /teams
badge补充状态,不替代链接名只显示红点且读屏无信息

Sidebar 配置只决定呈现。服务端仍要对目标页面和所有数据执行授权。

路由与当前项匹配 ​

精确匹配 ​

适合没有子路由的目的地:

text
/settings/billing

只有规范化路径完全相同时标记当前。

分段匹配 ​

项目任务入口可以覆盖:

text
/projects/p-42/tasks
/projects/p-42/tasks/t-9

匹配应基于路由结构,不使用简单字符串前缀。否则 /tasks-old 也可能被误判。

查询参数 ​

查询参数只改变筛选时,当前目的地通常不变:

text
/orders?status=refunding

如果参数改变的是稳定任务模式,例如“设计”和“运行”两个独立工作区,应评估是否需要独立路由段或 Tabs。

重定向 ​

先完成规范化重定向,再计算当前项。旧 URL 跳转后,导航只标记最终目的地。

多入口 ​

搜索、通知和最近访问都可以进入同一页面。当前项由目标页面身份决定,不由来源入口决定。

层级:列表、Disclosure 还是 Tree ​

普通列表 ​

多数 Sidebar 使用嵌套列表和普通链接已经足够:

html
<nav aria-labelledby="project-nav-title">
  <h2 id="project-nav-title">项目</h2>
  <ul>
    <li><a href="/overview">概览</a></li>
    <li><a href="/tasks" aria-current="page">任务</a></li>
    <li><a href="/members">成员</a></li>
  </ul>
</nav>

Tab 键按页面顺序逐个到达链接。方向键不应被 JavaScript 接管。

Disclosure 分组 ​

当分组可以折叠时,使用按钮控制嵌套列表:

html
<li>
  <button
    type="button"
    aria-expanded="true"
    aria-controls="automation-links">
    自动化
  </button>
  <ul id="automation-links">
    <li><a href="/rules">规则</a></li>
    <li><a href="/runs">运行记录</a></li>
  </ul>
</li>

行为要求:

  • Enter 或 Space 切换展开;
  • aria-expanded 与真实可见状态同步;
  • 收起包含当前页的分组前应评估是否会隐藏当前位置;
  • 收起时若焦点在子项内,先把焦点移到控制按钮;
  • 页面重新加载后,至少自动展开当前项祖先。

Tree ​

只有在 Sidebar 真正是可交互层级树,并准备实现完整 Tree View 键盘模型时才使用 role="tree"。

Tree 会改变:

  • Tab 序列;
  • 方向键行为;
  • 焦点管理;
  • 展开状态;
  • 层级和选中状态的程序化表达。

把普通站点导航加上 role="tree",却仍让 Tab 遍历每个链接,会制造不一致语义。

整栏展开与折叠 ​

完整模式 ​

显示图标和文字。文字是目的地的主要名称。

紧凑模式 ​

只显示图标时必须保证:

  • 每个链接仍有可访问名称;
  • 图标含义在产品中稳定;
  • 鼠标和键盘都能获得文字说明;
  • 当前项不只通过背景色表达;
  • 徽标不会遮挡图标或焦点;
  • 200% 缩放后仍可操作。

紧凑模式适合熟练用户节省空间,不应作为新用户默认方案,除非同时提供可理解标签。

持久化 ​

折叠偏好可以保存在:

  • 当前页面内存;
  • 当前设备本地存储;
  • 服务端个人偏好。

不要跨不同屏幕宽度直接复用同一个布尔值。桌面“紧凑”与移动端“抽屉关闭”是不同状态。

状态模型 ​

状态可见结果可用操作退出条件
加载导航保留稳定框架或明确加载主内容按独立条件处理权限与导航数据返回
完整图标、文字、分组可见跳转、展开、收起整栏用户收起或进入窄屏
紧凑图标与必要状态可见跳转、展开整栏用户展开
分组收起子链接不可见展开分组用户展开或进入子路由
窄屏关闭主内容可用,显示菜单按钮打开导航用户打开
窄屏打开导航覆盖或推动内容跳转、关闭选择目的地、Escape 或关闭
无权限受限入口被过滤或解释申请权限、返回权限改变
当前项失效当前路由不再可访问进入安全上级重定向完成
导航加载失败已知当前上下文仍保留重试、使用主内容请求恢复

导航加载失败不应把主内容中的已确认数据一起清空。主内容和导航可以有不同请求生命周期。

键盘与焦点 ​

桌面普通列表 ​

  • Tab 和 Shift+Tab 按 DOM 顺序移动;
  • Enter 激活链接;
  • 浏览器提供链接上下文菜单;
  • 不接管方向键;
  • 焦点指示满足可见性与对比要求;
  • 固定头部或底部不能完全遮住焦点。

窄屏抽屉 ​

打开:

  1. 菜单按钮更新 aria-expanded="true";
  2. 导航变为可见;
  3. 焦点进入导航标题或当前项,选择规则保持一致;
  4. 主内容是否变为 inert 取决于是否为模态实现。

关闭:

  1. Escape、关闭按钮或选择目的地可关闭;
  2. aria-expanded 变为 false;
  3. 焦点回到菜单按钮;若导航触发了页面跳转,则进入新页合理起点;
  4. 不把焦点留在已隐藏链接中。

若导航不是模态抽屉而是推动内容,不应错误实现焦点陷阱。

分组收起 ​

焦点位于被收起子项时,收起操作前把焦点移到分组按钮。直接 display:none 会使焦点落到不可见节点。

窄屏与重排 ​

可选方案:

方案适用条件主要风险
模态抽屉目的地多,打开时专注导航焦点陷阱和背景禁用
非模态覆盖用户可能同时参考主内容覆盖内容、焦点位置不清
推动内容导航与主内容都需可见320 CSS px 下空间不足
独立导航页层级深、移动任务以导航为主多一次页面转换
精简顶栏 + 更多页移动端高频目的地少“更多”中的可发现性

窄屏不能简单设置 display:none。必须提供可见触发器、展开状态、关闭方式和焦点恢复。

测试条件:

  • 320 CSS px 等效宽度;
  • 200% 文本缩放;
  • 40 字目的地名称;
  • 系统大字体;
  • 横屏与竖屏切换;
  • 触屏、键盘和读屏;
  • 当前项在列表底部;
  • 导航内容本身可滚动。

权限与动态导航 ​

隐藏还是禁用 ​

用于导航的无权限目的地通常有三种处理:

处理适用情况风险
隐藏用户无需知道该能力存在难以发现升级或申请路径
显示并进入说明页允许了解能力和申请方式必须避免泄露受限数据
禁用并解释当前上下文暂不可用禁用链接的语义和键盘体验较差

选择必须按产品权限模型确定,不是一条通用规则。

权限变化 ​

权限可能在页面打开后变化:

  1. 服务端返回新的导航能力;
  2. 当前项仍可读时更新其他入口;
  3. 当前项不可读时进入明确无权限状态;
  4. 提供安全上级或申请权限;
  5. 不把用户静默送回首页;
  6. 所有目标页面继续执行服务端授权。

功能开关 ​

功能开关改变入口时,记录:

  • 谁能看见;
  • 旧深链怎样处理;
  • 当前项在开关关闭后去哪里;
  • 搜索和帮助文档是否同步;
  • 已保存书签怎样恢复。

徽标与动态数量 ​

徽标适合补充:

  • 未读数;
  • 待处理数;
  • 运行中状态;
  • 新功能标记。

边界:

  • 链接名称仍能独立表达目的地;
  • 数量说明对象,例如“3 个待处理邀请”;
  • 高频更新不反复打断读屏;
  • 大数量使用明确上限展示,但可访问名称不制造错误精度;
  • 数量请求失败不让整个导航不可用;
  • 徽标不作为高风险告警的唯一入口。

案例一:资产管理平台 ​

任务与数据 ​

管理员在设备、成员、策略、自动化和审计之间频繁切换。

固定数据:

  • 6 个顶级模块;
  • “设备”下 4 个子目的地;
  • 2 个角色;
  • 18,000 台设备;
  • 3 个待处理策略;
  • 一个被功能开关关闭的实验模块。

方案 ​

使用完整 Sidebar:

text
资产平台
├─ 概览
├─ 设备
│  ├─ 全部设备
│  ├─ 分组
│  ├─ 软件
│  └─ 合规
├─ 成员
├─ 策略          [3]
├─ 自动化
└─ 审计

“设备”分组使用 disclosure;各子项仍是普通链接。“策略 3”表达待处理策略,不是未读消息。

当前项 ​

访问:

text
/workspaces/w-17/devices/d-2048/software

Sidebar 标记“软件”为当前页,同时展开“设备”。“设备”父项不再额外标记为当前页,只通过展开和视觉层级表达祖先关系。

权限分支 ​

普通成员不能访问“审计”:

  • 导航不显示“审计”;
  • 直接 URL 返回无权限页;
  • 无权限页仍显示工作区身份;
  • 提供返回“概览”的链接;
  • 不显示任何审计事件名称或数量。

失败注入 ​

导航数量请求返回 503。

正确结果:

  • 目的地链接仍可使用;
  • “策略”徽标显示不可用或暂时省略;
  • 当前项不丢失;
  • 不把整个 Sidebar 替换成错误页;
  • 错误日志包含徽标请求 ID。

验证 ​

  • Owner 与 Member 的入口符合服务端能力;
  • 旧审计书签对 Member 不泄露数据;
  • Tab 顺序与视觉顺序一致;
  • 收起“设备”时焦点不会消失;
  • 当前项重载后自动展开;
  • 200% 缩放后长名称可换行。

案例二:移动端告警深链 ​

任务 ​

值班人员从通知打开服务告警,查看详情后切换到同一服务的运行记录。

入口 ​

text
/services/s-42/alerts/a-9

窄屏默认关闭 Sidebar,页面顶部显示:

  • 产品名;
  • 当前服务“支付 API”;
  • “打开服务导航”按钮;
  • 告警详情标题。

打开导航 ​

导航内容:

text
支付 API
├─ 概览
├─ 告警
├─ 运行记录
├─ 部署
└─ 设置

当前项为“告警”。选择“运行记录”后:

  1. 路由进入 /services/s-42/runs;
  2. Sidebar 关闭;
  3. 页面标题更新;
  4. 焦点进入新页面主标题;
  5. 浏览器后退回到原告警详情,不重复打开导航。

会话过期 ​

如果用户打开导航后会话过期:

  • 认证界面不保留敏感告警名称;
  • 登录后恢复原深链;
  • 重新获取当前服务和权限;
  • 若服务已删除,进入明确失效状态;
  • 不回退到不相关的产品首页。

窄屏失败 ​

旧实现把 Sidebar 放在 position: fixed 层,关闭后没有恢复焦点,键盘焦点仍进入隐藏链接。

修正:

  • 关闭时把导航从可交互树移除;
  • 若没有发生跳转,焦点回菜单按钮;
  • 若已跳转,焦点进入新页主标题;
  • 自动化测试检查隐藏区域不存在可聚焦后代。

工程实现 ​

数据与渲染分层 ​

  1. 服务端根据主体、工作区和功能开关返回能力。
  2. 路由配置把能力映射为允许发现的目的地。
  3. 当前路由通过结构化匹配计算当前项。
  4. 展开状态由当前项祖先和用户偏好共同决定。
  5. 视口状态决定呈现为固定 Sidebar 还是窄屏导航。
  6. 目标页面独立执行授权。

不变量 ​

  • 同一 Sidebar 最多一个 aria-current="page";
  • 所有可见目的地 ID 唯一;
  • 当前项可见时,其祖先分组必须展开;
  • 隐藏分组中不能保留焦点;
  • 窄屏关闭后导航链接不可交互;
  • 当前 URL 必须映射到一个目的地或明确“未映射”;
  • 权限过滤不产生空分组;
  • 折叠偏好不覆盖窄屏打开状态。

性能 ​

Sidebar 通常不需要虚拟化。若目的地多到必须虚拟化,应先检查信息架构是否失控。

可优化:

  • 导航配置与主内容并行获取;
  • 对稳定配置使用版本化缓存;
  • 徽标独立请求和独立失败;
  • 预取高频只读页面,但缓存键包含工作区与权限;
  • 路由切换不重新挂载整个导航;
  • 图标使用可缓存资源,不为每项加载独立大图。

不要预取用户无权限的数据,也不要让旧权限缓存长期保留入口。

调试路径 ​

当前项错误 ​

检查顺序:

  1. 浏览器最终 URL;
  2. 重定向是否完成;
  3. 路由参数是否规范化;
  4. 查询参数是否参与页面身份;
  5. 匹配规则是否误用字符串前缀;
  6. 是否有两个目的地同时匹配;
  7. 页面标题是否来自同一节点配置。

折叠后焦点丢失 ​

检查:

  • 收起动作发生时 document.activeElement;
  • 子列表隐藏前是否移动焦点;
  • CSS 只改变透明度还是同时禁止交互;
  • 动画期间是否仍可 Tab 进入;
  • 组件卸载后焦点是否退回 body。

窄屏不能关闭 ​

检查:

  • Escape 监听是否只在导航打开时启用;
  • 关闭按钮是否在 Tab 顺序内;
  • 遮罩是否遮挡按钮;
  • aria-expanded 与视觉状态是否同步;
  • 路由变化后是否清理打开状态;
  • 焦点陷阱是否把用户困在已关闭区域。

权限变化出现空组 ​

检查服务端能力结果、客户端过滤顺序和分组清理。先过滤目的地,再删除没有任何可见子项且没有独立作用的分组。

指标与验证 ​

任务指标 ​

  • 从入口到目标页面的成功率;
  • 错误进入相邻模块的比例;
  • 进入后 10 秒内返回或改用搜索的比例;
  • 桌面与窄屏的导航打开到选择转化;
  • 深链后使用 Sidebar 切换同对象页面的成功率。

指标按角色、平台、入口、数据规模和新旧用户分群。点击多可能代表高频使用,也可能代表绕路,不能单独判断。

无障碍验证 ​

  1. 用地标列表识别“产品”和“项目”导航。
  2. 用 Tab 遍历所有可见链接和分组按钮。
  3. 检查当前页被程序化表达。
  4. 收起含焦点的分组。
  5. 打开和关闭窄屏导航。
  6. 在 200% 缩放下滚动到末项。
  7. 开启高对比模式检查当前项和焦点。
  8. 使用屏幕阅读器确认徽标数量有对象名称。
  9. 禁用 CSS 后检查链接列表仍有合理顺序。
  10. 直接进入深链并确认页面标题和导航上下文。

失败注入 ​

  • 导航配置请求失败;
  • 徽标请求失败;
  • 当前角色权限被撤销;
  • 当前项目归档;
  • 当前项名称为 40 个汉字;
  • 路由重定向两次;
  • 功能开关在页面打开后关闭;
  • 窄屏打开时发生路由跳转;
  • 当前项位于收起分组;
  • 浏览器从后退缓存恢复页面。

每次记录可见结果、焦点位置、URL、当前项、网络响应和控制台错误。

综合练习 ​

为一个至少有 20 个目的地的管理工具设计并实现 Sidebar。

交付物:

  • 产品、模块和对象内导航边界;
  • 节点数据模型;
  • 分组与当前项匹配规则;
  • 普通列表或 disclosure 的语义 HTML;
  • 完整、紧凑、窄屏打开和窄屏关闭状态;
  • Owner 与 Member 权限差异;
  • 两个徽标及其失败降级;
  • 深链、重定向和浏览器历史测试;
  • 键盘与屏幕阅读器记录;
  • 失败注入结果。

验收标准:

  • 每个目的地使用真实链接;
  • 同时只有一个当前页;
  • 当前项祖先不会被隐藏;
  • 无权限入口与目标页面授权一致;
  • 整栏折叠、分组折叠和移动端关闭是独立状态;
  • 窄屏关闭后不存在隐藏可聚焦链接;
  • Escape、关闭按钮和路由跳转后的焦点结果明确;
  • 徽标失败不阻断导航;
  • 320 CSS px、200% 缩放和长文本可完成任务;
  • 服务端不信任 Sidebar 的显示状态进行授权。

来源 ​

从前端走向软件产品工程的长期路线图。