布局外壳
ConsoleLayout 负责所有外壳行为：侧栏、顶栏、页签栏、面包屑、内容区、偏好与无障碍设置。 页面只渲染业务内容，不重复实现布局。
三种布局模式
在「设置 → 外观 → 布局」里切换，偏好存在浏览器（appearance 存储键下）：
| 模式 | 值 | 表现 |
|---|---|---|
| 侧边导航 | side | 左侧固定侧栏 + 顶栏；侧栏可折叠成图标条，宽度可调 |
| 顶部 + 侧边导航 | top-side | 顶部主导航 + 左侧分组侧栏，适合菜单层级多的系统 |
| 顶部导航 | top | 只有顶部主导航，侧边菜单由顶部点击展开（覆盖层），不占内容宽度 |
顶部导航模式下：侧栏里的官网入口与品牌字标不出现（避免和顶部重复），顶部只显示头像图标， 面包屑与顶部菜单分两行，展开的侧边菜单跟随顶部菜单滚动。
顶栏快捷操作
默认顺序固定为：
| 顺序 | 操作 | id |
|---|---|---|
| 1 | 搜索（命令面板） | search |
| 2 | 通知 | notifications |
| 3 | 刷新页面 | reload |
| 4 | 全屏 | fullscreen |
| 5 | 语言 | language |
| 6 | 主题 | theme |
| 7 | 仓库（自绘图标） | github |
通知默认排第二，是产品约定：通知是最高频的全局入口。顺序可以在「设置 → 外观 → 顶栏快捷操作」里调整， 新版本新增的入口会按默认位置插回，不会因为用户改过顺序就消失（resolveHeaderActions）。 业务系统也可以直接覆盖某一个 id 的节点：
tsx
<ConsoleLayout
headerActions={{
reload: <PageReloadButton />,
notifications: <NotificationsButton />,
}}
/>1
2
3
4
5
6
2
3
4
5
6
命令面板
⌘K（Windows：Ctrl+K）呼出命令面板，搜索范围只有两处：菜单，以及当前页已渲染的内容。
- 索引方式：遍历主内容区的文本节点（
src/lib/content-search.ts），用文本所在元素做定位目标； 徽标、状态这种<span>文案也能搜到，不再依赖固定标签。 - 上限 800 条 / 单条 240 字符，按路由缓存；页面内容变化时用
MutationObserver标记失效、下次搜索重建。 - 只索引当前路由已渲染的内容：虚拟滚动的行、未展开的折叠区、异步还没回来的数据不在索引里。
- 键盘
↑/↓选择、Enter打开、Esc关闭。 - 主键用
⌘K：命令面板的通行做法，也和文档站（VitePress）的搜索键一致；⌘⇧S保留为兼容别名（⌘S被浏览器"保存网页"占用）。
快捷键
默认组合是 g 开头的两段式跳转：
| 组合 | 目标 |
|---|---|
g d | 工作台 |
g c | 客户管理 |
g n | 通知中心 |
g s | 设置 |
在「设置 → 快捷键」里可以改组合；输入冲突组合会直接提示并拒绝保存（shortcutConflict）。
页签栏与页面过渡
- 页签栏样式：
card（卡片）与line（下划线）两种，见「设置 → 外观 → 页签」。 - 页面过渡支持
none、fade、slide、slide-left、slide-right、slide-up、slide-down与auto。 auto按导航方向自动选：前进向左滑入、后退向右滑入、首屏与 replace 淡入。- 点顶栏"刷新"时不播进入动画（
dataset.transition = 'none'），避免整屏闪一下。 - 打开「减少动效」后所有过渡自动降级为无动画。
侧栏与内容区
- 侧栏宽度可拖拽调整（键盘
←/→也可），折叠态固定 76px 图标条。 - 菜单支持层级：父节点展开后缩进显示子项，当前路由所在分支自动展开；外链菜单带外链图标，按
target决定新窗口 / 当前窗口 / iframe 内嵌（见动态菜单与权限）。 - 收藏夹按用户 ID 隔离（
favoritesKey），最多保存常用页面，缺权限的项会标记失效而不是静默消失。 - 侧栏底部默认显示外链（
footerLinks，可多项、每项可指定图标），传userControl可换成用户菜单。 - 「最大化页面」会临时隐藏页签栏与面包屑，适合看大表格。
ConsoleLayout 常用 props
| prop | 类型 | 说明 |
|---|---|---|
navigation | NavigationItem[] | 全部菜单项，平铺传入 |
groups | NavigationGroupDefinition[] | 分组定义；不传则所有菜单落在一组 |
title | string | 浏览器标题后缀，同时用于移动端侧栏描述 |
brand / brandHref | ReactNode / string | 品牌节点与点击目标，默认用 public/brand |
footerLinks | { href, label, icon? }[] | 侧栏底部外链（官网、仓库等，可多项） |
favoritesKey | string | 传入即启用收藏夹，作为隔离键（通常用用户 ID） |
accountControl | ReactNode | 品牌下方的账户 / 租户切换控件 |
userControl | ReactNode | 侧栏底部用户菜单，不传时显示 footerLinks |
headerActions | Partial<Record<HeaderActionId, ReactNode>> | 覆盖顶栏快捷操作节点 |
pageTitles | Record<string, string> | 动态路由的面包屑标题，取最长匹配父路径 |
fallbackTitle | string | 既不在菜单也不在 pageTitles 时的标题兜底 |