Menubar 应用菜单栏
桌面应用式顶部菜单条（文件 / 编辑 / 视图），点击 / 悬停展开子菜单（级联浮出），支持方向键、Alt 访问键与焦点陷阱。
多组单选（radio 组独立勾选）
type: "group" 项的 value 作为组 id，同一组内的叶子按该组独立记录选中值；value 属性传 JSON 对象（{"组id":"选中值"}）时各组互不干扰——「模式」和「主题」两组可各自显示打勾。
多组单选（组独立勾选）
动作项（kind: "action"）
kind: "action" 的叶子项按普通动作渲染（menuitem），无勾选态、点击不写回 value、只派发 oas-select（detail.kind === "action"）——适合「打开 / 保存 / 关于」这类非设置项。
动作项（kind: action）
快捷键（shortcut）
shortcut 字段（如 "Ctrl+N"）：右侧渲染快捷键提示，并自动绑定 document 级 keydown——命中即触发对应项选择（preventDefault 拦截浏览器默认行为）。绑定规则：修饰键+键 直接绑定；单键仅限功能键（F1–F12）可绑定，其余单键（字母/数字/Delete 等）仅作展示不绑定。
快捷键（shortcut）
基础用法
基础用法
禁用项与分组
子菜单内支持 disabled、type: "divider" 分隔线与 type: "group" 分组标题。
禁用项与分组
受控选中
value 属性受控（已列入 observedAttributes）：外部 setAttribute('value', ...) 即时生效，选中项（勾选/高亮）同步到对应叶子项；组件内部点击也会写回 value（非受控通道），宿主可监听 oas-select 自行接管。
受控选中（value 属性）
复选与不收起（checkbox + close-on-select）
kind: "checkbox" 叶子按多选勾选（value 为 JSON 数组），点击切换勾选不收起子菜单（连续勾选场景）；close-on-select="false" 让 radio/动作项选中后也保持展开。close-on-select 为布尔属性：存在即真（含空值），仅显式 "false" 关闭——未设置时缺省收起。
复选与不收起（checkbox + close-on-select）
受控打开（open）
open 属性表达当前打开的顶级菜单 value（"" 为全部收起）。受控属性：外部 setAttribute('open', ...) 即时打开/切换/关闭；组件内部变化会写回 open 并派发 oas-open-change（detail: { value, open }），宿主可监听接管。
受控打开（open 属性）
触发方式与方向键循环（trigger / loop）
trigger="click"（缺省）：顶级菜单首开用点击，一旦有菜单打开，hover 顶级项即切换（桌面应用共识）；trigger="hover" 保持 hover 直开。loop="false" 关闭方向键在边界处循环。
hover 直开（trigger 配置）
方向键不循环（loop 配置）
整栏禁用（disabled）
disabled 整栏禁用：顶级项/子项点击、键盘导航、shortcut 快捷键与 Alt 访问键全部拦截。
整栏禁用（disabled）
弹出定位与箭头（side / align / offset / show-arrow）
side 控制一级下拉弹出侧（缺省 bottom）、align 对齐（缺省 start）、offset 与触发器的间距（px）；show-arrow 显示指向触发器的视觉箭头。
弹出定位与箭头（side / align / offset / show-arrow）
竖排（orientation）
orientation="vertical"：bar 纵向排布，一级下拉缺省向右弹出；键盘 ↑/↓ 移动顶级项、→ 打开子菜单。
竖排（orientation 配置）
移动端汉堡收纳（breakpoint）
breakpoint="600"：视口宽度 ≤ 600px 时菜单栏折叠为汉堡按钮 + 弹出菜单（窄宽收纳）；拉宽窗口自动恢复完整菜单栏。
移动端汉堡收纳（breakpoint）
图标（icon）
顶级项与子项支持 icon 字段（图标集名），图标跟随文字色。
图标（icon）
图标颜色（iconColor）
顶级项与子项支持 iconColor 字段（显式固定图标色，优先于选中/禁用态默认色；缺省 currentColor 随文字色）。子元素声明式通道用 icon-color 属性。
图标颜色（iconColor / icon-color）
链接导航（href）
叶子项（子菜单内与顶级叶子）带 href 时渲染为真链接 <a>：可右键新窗口、中键新开、利于 SEO；点击仍照常派发 oas-select 并写回 value（链接默认跳转不拦截）。target="_blank" 自动补 rel="noopener"。
链接导航（href 真链接）
子元素声明式通道
除 items JSON 外，可用 <oas-menubar-item> / <oas-menubar-group> / <oas-menubar-divider> 子元素声明式书写（items 属性显式设置时优先，未设置时解析子元素收敛到同一渲染路径）。默认插槽文本为 label，属性对齐 MenubarItem 字段：value / disabled / icon / kind / danger / href / target / rel / shortcut / access-key / indeterminate；<oas-menubar-item> 内直接嵌套子元素即递归为子菜单，<oas-menubar-group> 的 label 属性为组标题（value 可作 radio 组 id），组内子元素平铺同层。子元素增删、属性与文本变化会自动重渲染（MutationObserver）。
子元素声明式（分组 / 分隔线 / 嵌套 / checkbox / indeterminate / shortcut / danger / href）
动态增删（MutationObserver 自动刷新）
水平溢出收纳（···）
容器宽度不足时，放不下的顶级项自动收进末尾「···」收纳项，点击弹层显示被收项（点选即选中）；选中项被收纳时「···」高亮。仅水平模式；竖排与移动端汉堡不收纳。被收纳的含子菜单顶级项在弹层内按叶子项点选（弹层内不展开级联子菜单）。
水平溢出收纳（窄容器自动收进 ···）
半选态（indeterminate）
kind: "checkbox" 项支持 indeterminate: true：渲染 aria-checked="mixed" + 方块内横线减号（区别于全选的 ✓），供父子联动「部分选中」场景——半选状态由宿主算好后随 items JSON 传入，点击切换勾选后宿主可更新 items 取消半选标记。
checkbox 半选（indeterminate）
头尾插槽（start / end）
slot="start"（logo 位）/ slot="end"（头像位）装饰插槽：有内容时在 bar 内渲染，键盘导航自动跳过（不参与方向键/焦点陷阱）。
start / end 插槽（logo / 头像）
start 位放 logo 文字/图形，end 位放头像；方向键在菜单项间移动，不会跳进插槽。
API
oas-menubar
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
align | 一级下拉对齐：start（缺省）/ center / end；side 为 top/bottom 时沿水平轴，为 left/right 时沿垂直轴 | string | — |
breakpoint | 移动端断点（px，如 600）：视口宽度 ≤ 断点时 bar 折叠为汉堡按钮 + 弹出菜单（窄宽收纳） | string | — |
close-on-select | 选中叶子项后是否收起展开的子菜单，缺省 true（桌面菜单栏共识）；close-on-select="false" 保持展开（连选场景）；kind:"checkbox" 项勾选切换永不收起 | string | — |
disabled | 整栏禁用：顶级项/子项点击、键盘导航、shortcut 快捷键、Alt 访问键全部拦截，视觉降饱和 | boolean | — |
items | 顶级菜单项 JSON（含子菜单 children） | string | [] |
loop | 方向键循环导航开关，缺省 true（边界循环）；显式 loop="false" 时边界停止 | string | — |
offset | 一级下拉与触发器间距（px，缺省 4） | string | — |
open | 当前打开的顶级菜单 value（open="" 表示全部收起）。受控属性（observedAttributes）：外部 setAttribute('open', ...) 即时打开/切换/关闭；内部点击/hover/键盘变化会写回本属性并派发 oas-open-change，宿主可监听接管 | string | — |
orientation | 排列方向：horizontal（缺省）/ vertical（竖排：bar 纵向、一级下拉缺省向右弹、键盘上下移动顶级） | — | — |
show-arrow | 显示弹出层指向触发器的视觉箭头 | — | — |
side | 一级下拉弹出侧：bottom（水平缺省）/ top / left / right（竖排缺省）；级联子菜单不受影响 | string | — |
trigger | 顶级菜单触发方式：click（默认，首开需点击、打开后 hover 切换——桌面应用共识）/ hover（hover 直开） | — | — |
value | 选中值。纯字符串时全局单选（无组场景，兼容旧用法）；JSON 对象字符串（如 {"mode":"preview","theme":"dark"}）时按组 id 作用域独立记录——type:"group" 项的 value 作组 id；JSON 数组字符串（如 ["grid","wrap"]）时为 checkbox 勾选集（kind:"checkbox" 项多选） | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-open-change | 顶级打开菜单变化，detail: { value, open }（value = 当前打开顶级菜单 value，open = 是否打开）。受控 setAttribute('open') 与内部点击/hover/键盘触发都会派发（首帧不派发） |
oas-select | 选择某项，detail: { value, kind?, checked? }。kind 仅动作项（kind: "action"）出现，值为 "action"；checkbox 项带 checked（切换后勾选态）；radio 项 detail.kind 不出现 |
插槽
| 名称 | 说明 |
|---|---|
end | 栏尾装饰位（如头像）：<div slot="end"> 有内容时显示，键盘导航跳过 |
start | 栏首装饰位（如 logo）：<div slot="start"> 有内容时显示，键盘导航跳过 |
oas-menubar-item
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
access-key | Alt 访问键（单字符）；缺省取 label 首个 ASCII 字母 | — | — |
danger | 破坏性项：红色语义（删除/退出等危险操作） | — | — |
disabled | 禁用该项 | — | — |
href | 链接地址：有 href 时渲染为原生 <a>（真实跳转 + 照常派发 oas-select） | — | — |
icon | 前置图标（@oas-ui/icons 内置图标名） | — | — |
icon-color | 图标颜色：显式固定该色（优先于选中/禁用态默认色）；缺省 currentColor 随文字色 | — | — |
indeterminate | checkbox 半选态：渲染 aria-checked="mixed" + 方块内横线减号（仅 kind="checkbox" 项生效） | — | — |
kind | 叶子项语义：radio（默认，可勾选）/ action（动作项，无勾选态、不写回 value）/ checkbox（多选勾选，value 数组勾选集） | — | — |
rel | 链接 rel（配合 href） | — | — |
shortcut | 快捷键提示（如 "Ctrl+N"）：右侧 kbd 提示 + document 级 keydown 命中触发 select | — | — |
target | 链接 target（配合 href） | — | — |
value | 选中值（子元素声明式通道的数据载体字段） | — | — |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 菜单栏项 label 内容（默认插槽文本）；直接子元素 <oas-menubar-item>/<oas-menubar-group>/<oas-menubar-divider> 递归为子菜单 children |
oas-menubar-group
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
label | 分组标题（组标题小字、次要色、不可点） | — | — |
value | radio 组 id（组内点选只更新该组选中值） | — | — |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 组内菜单项：子元素 <oas-menubar-item>/<oas-menubar-group>/<oas-menubar-divider> 平铺同层 |
oas-menubar-divider
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 分隔线数据载体（无属性，宿主解析为 type: "divider"） |
事件 detail 说明：
oas-select的detail是组件内部对象（含value/kind），不是原生Event——不能preventDefault()或直接读原生event.target。如需原生事件对象，在事件监听器上用外层参数（如addEventListener('oas-select', (e) => ...)的e是 CustomEvent，e.detail才是组件数据）。
MenubarItem 字段（继承 MenuItem）：
| 字段 | 说明 | 类型 |
|---|---|---|
label | 菜单文字 | string |
value | 选中值（items JSON 中声明；渲染后宿主标签上对应 data-value 小写属性，供内部定位，宿主不应依赖其作为公共 API） | string |
kind | 叶子项语义：radio（默认，可勾选、参与 value）/ action（动作项，无勾选态、点击不写回 value） | string |
shortcut | 快捷键提示（如 "Ctrl+N"）；渲染为右侧 kbd，并自动绑定 document 级 keydown（命中即选择该项、preventDefault） | string |
accessKey | Alt 访问键（单字符）；缺省取 label 首个 ASCII 字母 | string |
disabled | 禁用 | boolean |
children | 子菜单项（可继续嵌套，级联向右浮出） | MenubarItem[] |
键盘：顶级 ←/→ 切换、↓/Enter 打开子菜单、Esc 关闭；子菜单内 ↑/↓ 移动、→ 进入级联、← 返回父级；Home/End 跳转。Alt 单独按下聚焦菜单栏，Alt + 访问键 打开对应顶级菜单。子菜单打开时 Tab 在子项间循环（焦点陷阱），roving tabindex 只保留当前顶级项可 Tab 到达。