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。
hide-toggle（隐藏折叠按钮，静态侧栏）
collapsed 图标态
移动端抽屉
窄屏时侧栏自动变覆盖式抽屉：左上角悬浮 ☰ 按钮打开，遮罩 / 关闭按钮 / Esc 收起。用 mobile-breakpoint 调断点（此 demo 用 700px 方便在宽屏观察）。
移动端抽屉（breakpoint 700）
移动端抽屉受控
drawer-open 为受控属性：外部设置 / 移除即可开合移动端抽屉（无需点击悬浮 ☰）。此 demo 将断点调高强制移动端形态，方便在宽屏观察。
受控 drawer-open
drawer-open 控制抽屉开合；遮罩 / ✕ / Esc 收起后属性被移除。 受控高亮
active 为受控属性：外部设置 / 清除即可迁移当前高亮菜单项（无需点击）。
受控 active
active 控制当前高亮菜单项；清除后无高亮项。 分组
菜单项 items 支持可选 group 字段：连续同组项在组首项前渲染组标题（纯展示、不可点）；折叠态组标题隐藏，移动抽屉态正常显示。
分组（items.group）
嵌套子菜单
菜单项支持 children 嵌套：父项点击展开/收起（不派发 oas-select），含激活子项的父项自动展开；折叠图标条态子树隐藏。展开/收起带平滑高度动画（prefers-reduced-motion 自动降级）；accordion 同级互斥——展开一个父项自动收起其他同级父项（适合长导航只保留一个展开区）。
嵌套深度：机制上无限级（递归渲染，3 级已实证：逐级展开、激活级联自动展开与 child-selected 均正常）；但缩进每级叠加约 28px，220px 侧栏下建议 ≤3 级——更深的树形数据请用
oas-tree（为任意深度设计：连接线/虚拟滚动）。
三级嵌套（业务管理 → 用户管理 → 用户组）
手风琴（accordion 同级互斥）
点击过程同时是平滑展开/收起动画的演示（grid 高度过渡 + chevron 旋转；`prefers-reduced-motion` 自动降级）。
嵌套子菜单（items.children）
徽标与项操作
菜单项支持 badge 计数徽标（色值走 --oas-sidebar-badge-bg/-color 变量开口）与 actions 悬停操作按钮（点击派发 oas-action，不触发选中）。
徽标与项操作
悬停「项目」项出现操作按钮；点击派发 oas-action 事件。
自定义图标与着色
菜单项 icon 默认取 @oas-ui/icons 内置注册表图标名；应用级自定义图标走官方正路 registerIcon(name, svg)（@oas-ui/ui 导出）——一处注册，<oas-icon> 与侧栏及未来其它消费方全部可见（勿直接改内置图标数据；按需模式用内置名需 import '@oas-ui/icons/register' 一次），同名注册覆盖内置图标。
iconColor 给单项目标色：显式时固定该色、优先于禁用/激活态默认色；缺省 currentColor 随态着色（激活态走主色）。注册的彩色 SVG（path 自带 stroke/fill）自带色天然保留，外层 stroke 不强制覆盖。
自定义图标与着色（registerIcon + iconColor）
iconColor 显式 → 不随激活态变色）；「团队动态」未给 iconColor 走随态着色，且其自定义 SVG 自带红色描边天然保留。内置图标同样配 iconColor：「内置星标」用注册表 star 名 + 强制红色（内置单色 path 的 currentColor 也被替换为该色）；「内置心形」未给同样走随态。折叠图标条 tooltip 里的图标同色。 分隔线与骨架屏
{type:"divider"} 条目渲染分隔线；loading 属性显示脉冲骨架屏（数值为骨架行数，默认 4）。
分隔线 + loading
快捷键与键盘导航
shortcut 属性开启 Ctrl/Cmd+B 折叠切换（默认关闭，避免劫持全局键）；菜单支持 ↑/↓ 移动焦点、Home/End 跳首末、Enter/Space 激活。
快捷键（shortcut）+ 键盘导航
悬停展开（expand-on-hover）
expand-on-hover 属性：折叠图标条悬停时临时展开（纯视觉态，不改 collapsed 受控属性）。
expand-on-hover
形态（variant）
variant 形态：sidebar（默认贴边）/ floating（悬浮：外边距 + 圆角 + 阴影）/ inset（内嵌：外边距 + 圆角 + 背景对比）。
variant: floating / inset
右侧与双侧栏
side="right"：移动抽屉从右侧滑入、触发按钮居右；多个侧栏可并存（左右各一，状态相互独立）。
side=right + 双侧栏
拖拽调宽（resizable）
resizable 属性在宿主右缘显示拖拽条，拖拽实时调宽（写回 width 属性）；resize-min/resize-max 夹取范围（默认 160~480）；拖拽条支持方向键微调（±8px，Home/End 跳最小/最大）；松手/微调时派发 oas-resize。仅桌面非折叠态可用（折叠/移动态自动隐藏）。
resizable 边缘拖拽调宽
拖拽调宽（oas-splitter 组合）
侧栏宽度调整推荐用 oas-splitter 分割面板组合实现（无需内置 rail）：侧栏置于分割面板左侧，拖拽分割条即调宽。
oas-splitter + sidebar
自定义宽度
width 属性覆盖展开宽度（默认走 --oas-sidebar-width token）；折叠态仍收窄为图标条。
width 属性
与 oas-layout 配合
oas-sidebar 可直接作为 oas-layout 的 sider（slot="sider"）使用。
sidebar 作 sider 使用
主要内容区。
子元素声明式通道
除 items JSON 外，可用 <oas-sidebar-item> / <oas-sidebar-divider> 子元素声明式书写（items 属性显式设置时优先，未设置时解析子元素收敛到同一渲染路径）。默认插槽文本为 label，属性对齐 SidebarItem 字段：value / icon / group / badge（纯数字字符串转 number，其余保留 string）；<oas-sidebar-item> 内直接嵌套子元素即递归为嵌套 children（可含分隔线）。子元素增删、属性与文本变化会自动重渲染（MutationObserver）。边界：actions（悬停操作按钮）是对象数组，不适合子元素标量映射，需要时请用 items JSON。
子元素声明式（分组 / 分隔线 / 嵌套 / 徽标）
点击底部「«」切换折叠：嵌套子树隐藏、分组标题隐藏、图标 hover 出 tooltip、徽标保留——这套富内容正是折叠态行为的最佳演示。
动态增删（MutationObserver 自动刷新）
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 }；触发时机：选中菜单项时（移动端同时收起抽屉） |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 菜单项内容（默认插槽文本；直接子元素 <oas-sidebar-item> 递归为嵌套 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 内容（默认插槽文本）；直接子元素 <oas-sidebar-item>（及 <oas-sidebar-divider>）递归为嵌套 children |
oas-sidebar-divider
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 分隔线数据载体（无属性，宿主解析为 {type:"divider"}） |
部件（part）
root / panel / head / close / nav / body / foot / toggle（桌面折叠）/ trigger（移动触发）/ mask / item；头尾与主体内容分别通过 slot="header"、默认 slot、slot="footer" 注入。