# Sidebar 侧栏可折叠侧栏：桌面端 `collapsed` 收窄为图标条，移动端（窄于 `mobile-breakpoint`，默认 768px）自动切换为覆盖式抽屉 + 遮罩，点击外部 / 关闭按钮 / Esc 收起。 ## 基础用法 `items` 属性传菜单 JSON（`[{label, value, icon?}]`）；默认 slot 放自定义内容。

右侧内容区

## 折叠点击底部「«」按钮切换 `collapsed`（受控属性，派发 `oas-collapse`）；折叠态只显示图标，无 icon 的菜单项自动隐藏。`hide-toggle` 可隐藏该按钮（宿主 opt-out，如静态侧栏场景）。 **折叠态嵌套子菜单走 flyout 浮层**：树形父项在折叠态渲染为图标项，点击（或悬停延迟）弹出子菜单面板——面板锚定父项 inline-end（RTL 镜像到左）、碰撞避让、叶子项点击派发 `oas-select` 并关面板，嵌套子树在面板内内联展开；Esc 关闭并回焦父项、点击外部关闭、单开互斥。注意（契约变更）：折叠态父项点击只开 flyout，**不再派发父项自身的 `oas-select`**（父项不是可导航页面）——若此前依赖折叠态父项的 `oas-select` 做导航，请改监听 flyout 内叶子项的 `oas-select`。

静态侧栏：底部无「«」折叠按钮（与「折叠」demo 对照）。

切换折叠 collapsed

右侧内容区

## 移动端抽屉窄屏时侧栏自动变覆盖式抽屉：左上角悬浮 ☰ 按钮打开，遮罩 / 关闭按钮 / Esc 收起。用 `mobile-breakpoint` 调断点（此 demo 用 700px 方便在宽屏观察）。

把窗口 / 预览容器缩到 700px 以下，点击左上角 ☰ 打开抽屉

## 移动端抽屉受控 `drawer-open` 为受控属性：外部设置 / 移除即可开合移动端抽屉（无需点击悬浮 ☰）。此 demo 将断点调高强制移动端形态，方便在宽屏观察。

打开抽屉（设置 drawer-open）

收起抽屉（移除 drawer-open）

外部按钮设置 drawer-open 控制抽屉开合；遮罩 / ✕ / Esc 收起后属性被移除。

## 受控高亮 `active` 为受控属性：外部设置 / 清除即可迁移当前高亮菜单项（无需点击）。

高亮「数据看板」

高亮「设置」

清除高亮

外部按钮设置 active 控制当前高亮菜单项；清除后无高亮项。

## 分组菜单项 `items` 支持可选 `group` 字段：连续同组项在组首项前渲染组标题（纯展示、不可点）；折叠态组标题隐藏，移动抽屉态正常显示。

「概览」「业务」为组标题；「个人中心」无 group 字段，平铺显示。

## 嵌套子菜单菜单项支持 `children` 嵌套：父项点击展开/收起（不派发 `oas-select`），含激活子项的父项自动展开；折叠图标条态子树隐藏。展开/收起带平滑高度动画（`prefers-reduced-motion` 自动降级）；`accordion` 同级互斥——展开一个父项自动收起其他同级父项（适合长导航只保留一个展开区）。 > **嵌套深度**：机制上无限级（递归渲染，3 级已实证：逐级展开、激活级联自动展开与 child-selected 均正常）；但缩进每级叠加约 28px，220px 侧栏下建议 **≤3 级**——更深的树形数据请用 `oas-tree`（为任意深度设计：连接线/虚拟滚动）。

「业务管理 → 用户管理 → 用户组」三级链：active 指向第三级「管理员」时，两级父项自动展开并带 child-selected 指示；逐级缩进与引导线叠加。

依次点击「业务管理」「营销中心」「系统设置」——同级始终只有一个展开区。
点击过程同时是平滑展开/收起动画的演示（grid 高度过渡 + chevron 旋转；`prefers-reduced-motion` 自动降级）。

「业务管理」因含激活子项（用户管理）自动展开；点击父项只切换展开，点击子项才派发选择。

## 徽标与项操作菜单项支持 `badge` 计数徽标（色值走 `--oas-sidebar-badge-bg/-color` 变量开口）与 `actions` 悬停操作按钮（点击派发 `oas-action`，不触发选中）。

悬停「项目」项出现操作按钮；点击派发 oas-action 事件。

## 自定义图标与着色菜单项 `icon` 默认取 `@oas-ui/icons` 内置注册表图标名；应用级自定义图标走官方正路 `registerIcon(name, svg)`（`@oas-ui/ui` 导出）——**一处注册，`` 与侧栏及未来其它消费方全部可见**（勿直接改内置图标数据；按需模式用内置名需 `import '@oas-ui/icons/register'` 一次），同名注册覆盖内置图标。 `iconColor` 给单项目标色：显式时固定该色、优先于禁用/激活态默认色；缺省 `currentColor` 随态着色（激活态走主色）。注册的彩色 SVG（path 自带 `stroke`/`fill`）自带色天然保留，外层 `stroke` 不强制覆盖。

「个人工作台」固定警示橙、「项目仓库」固定主题主色（iconColor 显式 → 不随激活态变色）；「团队动态」未给 iconColor 走随态着色，且其自定义 SVG 自带红色描边天然保留。内置图标同样配 iconColor：「内置星标」用注册表 star 名 + 强制红色（内置单色 path 的 currentColor 也被替换为该色）；「内置心形」未给同样走随态。折叠图标条 tooltip 里的图标同色。

## 分隔线与骨架屏 `{type:"divider"}` 条目渲染分隔线；`loading` 属性显示脉冲骨架屏（数值为骨架行数，默认 4）。

切换 loading

点击按钮切换骨架屏。

## 快捷键与键盘导航 `shortcut` 属性开启 `Ctrl/Cmd+B` 折叠切换（默认关闭，避免劫持全局键）；菜单支持 `↑/↓` 移动焦点、`Home/End` 跳首末、`Enter/Space` 激活。

按 Ctrl+B 折叠/展开；Tab 聚焦到菜单后可用方向键导航。

## 悬停展开（expand-on-hover） `expand-on-hover` 属性：折叠图标条悬停时临时展开（纯视觉态，不改 `collapsed` 受控属性）。

先折叠为图标条

图标条态悬停侧栏即临时展开显示文字，移开收回。

## 形态（variant） `variant` 形态：`sidebar`（默认贴边）/ `floating`（悬浮：外边距 + 圆角 + 阴影）/ `inset`（内嵌：外边距 + 圆角 + 背景对比）。

floating

inset

## 右侧与双侧栏 `side="right"`：移动抽屉从右侧滑入、触发按钮居右；多个侧栏可并存（左右各一，状态相互独立）。

左「主导航」、右「辅助面板」（side=right），各自独立开合（本 demo 强制移动态便于观察）。

## 拖拽调宽（resizable） `resizable` 属性在宿主右缘显示拖拽条，拖拽实时调宽（写回 `width` 属性）；`resize-min`/`resize-max` 夹取范围（默认 160~480）；拖拽条支持方向键微调（±8px，`Home/End` 跳最小/最大）；松手/微调时派发 `oas-resize`。仅桌面非折叠态可用（折叠/移动态自动隐藏）。

拖侧栏右缘的拖拽条实时调宽；聚焦拖拽条也可用方向键微调。

## 拖拽调宽（oas-splitter 组合）侧栏宽度调整推荐用 `oas-splitter` 分割面板组合实现（无需内置 rail）：侧栏置于分割面板左侧，拖拽分割条即调宽。

拖拽中间分割条调整侧栏宽度（侧栏以 `width="100%"` 填满左面板，宽度实时跟随）。

## 自定义宽度 `width` 属性覆盖展开宽度（默认走 `--oas-sidebar-width` token）；折叠态仍收窄为图标条。

180px

280px

默认 token

点击上方按钮切换展开宽度，观察侧栏宽度变化。

## 与 oas-layout 配合 `oas-sidebar` 可直接作为 `oas-layout` 的 sider（slot="sider"）使用。

头部区域

副内容

主要内容区。

flex 1

底部信息

## 子元素声明式通道除 `items` JSON 外，可用 `` / `` 子元素声明式书写（`items` 属性**显式设置时优先**，未设置时解析子元素收敛到同一渲染路径）。默认插槽文本为 label，属性对齐 `SidebarItem` 字段：`value` / `icon` / `group` / `badge`（纯数字字符串转 number，其余保留 string）；`` 内直接嵌套子元素即递归为嵌套 children（可含分隔线）。子元素增删、属性与文本变化会自动重渲染（MutationObserver）。**边界**：`actions`（悬停操作按钮）是对象数组，不适合子元素标量映射，需要时请用 `items` JSON。

「概览」为组标题；分隔线、嵌套子菜单（含激活子项自动展开）与徽标行为均与 `items` 通道一致。
点击底部「«」切换折叠：嵌套子树隐藏、分组标题隐藏、图标 hover 出 tooltip、徽标保留——这套富内容正是折叠态行为的最佳演示。

追加一项

点击按钮追加菜单项，侧栏自动刷新。

## API ### 方法 | 方法 | 说明 | | --- | --- | | `openDrawer()` | 编程打开移动端抽屉（等价于点击内置触发按钮 `part="trigger"`） | | `closeDrawer()` | 编程关闭移动端抽屉（等价于点击遮罩 / 关闭按钮 / 按 Esc） | - 调用方式：`const el = document.querySelector('oas-sidebar') as OASSidebar; el.openDrawer()`。 - 与受控属性 `drawer-open` 等价：方法即该属性的写入/移除语法糖（`openDrawer` 设置、`closeDrawer` 移除），两者可混用；重复调用幂等。 - 仅移动端（视口窄于 `mobile-breakpoint`）生效；桌面态调用由 update 立即回收，不残留浮层。 - 抽屉开合不派发事件：宿主可观察 `drawer-open` 属性（MutationObserver）或自行维护状态；需要开合双态时按自身状态调用 `openDrawer()` / `closeDrawer()`。 ### oas-sidebar #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `accordion` | 手风琴同级互斥（存在即生效：展开一个父项自动收起其他同级父项；默认多父项可同时展开） | `boolean` | — | | `active` | 当前高亮菜单项 value（受控：外部设置/清除立即高亮迁移，重绘） | `string` | — | | `collapsed` | 受控折叠，收窄为图标条（存在即折叠） | `boolean` | — | | `drawer-open` | 移动端抽屉打开态（受控：设置即开、清除即收；断点回桌面自动移除） | `boolean` | — | | `expand-on-hover` | 折叠图标条悬停临时展开（纯视觉态，不改 collapsed 受控） | — | — | | `hide-toggle` | 隐藏底部折叠按钮（桌面端恒显示的内置折叠切换；存在即隐藏，宿主 opt-out，静态侧栏场景用） | `boolean` | — | | `items` | 菜单项 JSON `[{label, value, icon?, iconColor?, group?, badge?, children?, actions?}]`（支持分隔线条目 `{type:"divider"}`；children 嵌套子菜单） | `SidebarEntry[] \| string` | `[]` | | `loading` | 骨架屏加载态（存在即显示脉冲骨架；数值为骨架行数，默认 4） | `string` | `4` | | `mobile-breakpoint` | 移动端断点（px），窄于该值变覆盖式抽屉 | — | — | | `resizable` | 边缘拖拽调宽（存在即显示宿主边缘拖拽条；仅桌面非折叠态可用） | `boolean` | — | | `resize-max` | 拖拽调宽最大宽度（px，默认 480） | `string` | `480` | | `resize-min` | 拖拽调宽最小宽度（px，默认 160） | `string` | `160` | | `shortcut` | 开启 Ctrl/Cmd+B 折叠切换（默认关闭，避免劫持全局键） | `boolean` | — | | `side` | 抽屉侧向：left（默认）/ right（移动抽屉从右侧滑入、触发按钮居右） | — | — | | `variant` | 形态：sidebar（默认贴边）/ floating（悬浮圆角阴影）/ inset（内嵌圆角背景） | — | — | | `width` | 展开宽度，默认走 `--oas-sidebar-width` token | `string` | `0` | #### 事件 | 事件 | 说明 | | --- | --- | | `oas-action` | `detail: { value: string, action: string, label: string }`；触发时机：点击项悬停操作按钮时（不触发 oas-select） | | `oas-collapse` | `detail: { collapsed: boolean }`；触发时机：桌面折叠按钮切换时 | | `oas-resize` | `detail: { width: number }`；触发时机：拖拽调宽松手时 / 方向键微调宽度时 | | `oas-select` | `detail: { value: string, label: string }`；触发时机：选中菜单项时（移动端同时收起抽屉） | #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 菜单项内容（默认插槽文本；直接子元素 `` 递归为嵌套 children） | | `footer` | 侧栏底部自定义内容 | | `header` | 侧栏顶部自定义内容 | #### CSS 变量 | CSS 变量 | 说明 | 默认值 | | --- | --- | --- | | `--oas-sidebar-badge-bg` | 徽标背景色 | `var(--oas-color-primary)` | | `--oas-sidebar-badge-color` | 徽标文字色 | `#fff` | | `--oas-sidebar-bg` | 侧栏背景；默认锚定基础 token（主题 / 暗色 / 品牌自动跟随），宿主覆盖即整体换色 | `var(--oas-color-bg-hover)` | | `--oas-sidebar-collapsed-width` | 折叠图标条宽度 | `64px` | | `--oas-sidebar-item-hover-bg` | 项悬停背景（默认 text-primary 6% 混合） | `color-mix(in srgb, var(--oas-color-text-primary) 6%, transparent)` | | `--oas-sidebar-width` | 展开宽度（`width` 属性优先） | `220px` | ### oas-sidebar-item #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `badge` | 徽标计数（纯数字字符串转 number，其余保留 string；对齐 SidebarItem.badge 的 string\|number） | — | — | | `group` | 分组名（连续同组项在组首项前渲染组标题） | — | — | | `icon` | 前置图标（`@oas-ui/icons` 内置图标名；折叠图标条态显示） | — | — | | `icon-color` | 前置图标颜色：显式时固定该色（替换内置单色 path 的 currentColor，优先于禁用/激活态默认色）；缺省 currentColor 随态着色 | — | — | | `value` | 选中值（子元素声明式通道的数据载体字段） | — | — | #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 侧栏菜单项 label 内容（默认插槽文本）；直接子元素 ``（及 ``）递归为嵌套 children | ### oas-sidebar-divider #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 分隔线数据载体（无属性，宿主解析为 `{type:"divider"}`） | ### 部件（part） `root` / `panel` / `head` / `close` / `nav` / `body` / `foot` / `toggle`（桌面折叠）/ `trigger`（移动触发）/ `mask` / `item`；头尾与主体内容分别通过 `slot="header"`、默认 slot、`slot="footer"` 注入。