# Menubar 应用菜单栏 桌面应用式顶部菜单条（文件 / 编辑 / 视图），点击 / 悬停展开子菜单（级联浮出），支持方向键、`Alt` 访问键与焦点陷阱。 ## 多组单选（radio 组独立勾选） `type: "group"` 项的 `value` 作为**组 id**，同一组内的叶子按该组独立记录选中值；`value` 属性传 JSON 对象（`{"组id":"选中值"}`）时各组互不干扰——「模式」和「主题」两组可各自显示打勾。 mode: preview, theme: dark ## 动作项（kind: "action"） `kind: "action"` 的叶子项按普通动作渲染（`menuitem`），无勾选态、点击**不写回** `value`、只派发 `oas-select`（`detail.kind === "action"`）——适合「打开 / 保存 / 关于」这类非设置项。 value: mode（动作项点击不改变） ## 快捷键（shortcut） `shortcut` 字段（如 `"Ctrl+N"`）：右侧渲染快捷键提示，并自动绑定 `document` 级 keydown——命中即触发对应项选择（`preventDefault` 拦截浏览器默认行为）。绑定规则：`修饰键+键` 直接绑定；单键仅限功能键（F1–F12）可绑定，其余单键（字母/数字/Delete 等）仅作展示不绑定。 按 Ctrl+N / Ctrl+O / Ctrl+S 试试 ## 基础用法 尚未选择 ## 禁用项与分组 子菜单内支持 `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"` 关闭——未设置时缺省收起。 勾选集: ["grid"] ## 受控打开（open） `open` 属性表达当前打开的顶级菜单 value（`""` 为全部收起）。受控属性：外部 `setAttribute('open', ...)` 即时打开/切换/关闭；组件内部变化会写回 `open` 并派发 `oas-open-change`（`detail: { value, open }`），宿主可监听接管。 打开「文件」 打开「编辑」 收起 open: - ## 触发方式与方向键循环（trigger / loop） `trigger="click"`（缺省）：顶级菜单**首开用点击**，一旦有菜单打开，hover 顶级项即切换（桌面应用共识）；`trigger="hover"` 保持 hover 直开。`loop="false"` 关闭方向键在边界处循环。 hover 即开（无 click-first） ← 在首项、→ 在末项停止 ## 整栏禁用（disabled） `disabled` 整栏禁用：顶级项/子项点击、键盘导航、shortcut 快捷键与 Alt 访问键全部拦截。 整栏不可交互 ## 弹出定位与箭头（side / align / offset / show-arrow） `side` 控制一级下拉弹出侧（缺省 `bottom`）、`align` 对齐（缺省 `start`）、`offset` 与触发器的间距（px）；`show-arrow` 显示指向触发器的视觉箭头。 side=top / align=end / offset=8 / show-arrow ## 竖排（orientation） `orientation="vertical"`：bar 纵向排布，一级下拉缺省向右弹出；键盘 ↑/↓ 移动顶级项、→ 打开子菜单。 ## 移动端汉堡收纳（breakpoint） `breakpoint="600"`：视口宽度 ≤ 600px 时菜单栏折叠为汉堡按钮 + 弹出菜单（窄宽收纳）；拉宽窗口自动恢复完整菜单栏。 拉窄窗口（≤600px）试试汉堡按钮 ## 图标（icon） 顶级项与子项支持 `icon` 字段（图标集名），图标跟随文字色。 ## 图标颜色（iconColor） 顶级项与子项支持 `iconColor` 字段（显式固定图标色，优先于选中/禁用态默认色；缺省 `currentColor` 随文字色）。子元素声明式通道用 `icon-color` 属性。 ## 链接导航（href） 叶子项（子菜单内与顶级叶子）带 `href` 时渲染为真链接 ``：可右键新窗口、中键新开、利于 SEO；点击仍照常派发 `oas-select` 并写回 `value`（链接默认跳转不拦截）。`target="_blank"` 自动补 `rel="noopener"`。 点叶子项会导航并派发 oas-select ## 子元素声明式通道 除 `items` JSON 外，可用 `` / `` / `` 子元素声明式书写（`items` 属性**显式设置时优先**，未设置时解析子元素收敛到同一渲染路径）。默认插槽文本为 label，属性对齐 `MenubarItem` 字段：`value` / `disabled` / `icon` / `kind` / `danger` / `href` / `target` / `rel` / `shortcut` / `access-key` / `indeterminate`；`` 内直接嵌套子元素即递归为子菜单，`` 的 `label` 属性为组标题（`value` 可作 radio 组 id），组内子元素平铺同层。子元素增删、属性与文本变化会自动重渲染（MutationObserver）。 文件 项目 A 项目 B 保存 组件文档 视图 全选 网格线 删除 尚未选择（试试 Alt+F 打开「文件」、Ctrl+S 触发保存） 追加顶级项 文件 新建 ## 水平溢出收纳（···） 容器宽度不足时，放不下的顶级项自动收进末尾「···」收纳项，点击弹层显示被收项（点选即选中）；选中项被收纳时「···」高亮。仅水平模式；竖排与移动端汉堡不收纳。被收纳的含子菜单顶级项在弹层内按叶子项点选（弹层内不展开级联子菜单）。 容器固定 380px，超宽项收进「···」 ## 半选态（indeterminate） `kind: "checkbox"` 项支持 `indeterminate: true`：渲染 `aria-checked="mixed"` + 方块内横线减号（区别于全选的 ✓），供父子联动「部分选中」场景——半选状态由宿主算好后随 items JSON 传入，点击切换勾选后宿主可更新 items 取消半选标记。 「全选」为半选（mixed） ## 头尾插槽（start / end） `slot="start"`（logo 位）/ `slot="end"`（头像位）装饰插槽：有内容时在 bar 内渲染，键盘导航自动跳过（不参与方向键/焦点陷阱）。

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` | 栏尾装饰位（如头像）：`
` 有内容时显示，键盘导航跳过 | | `start` | 栏首装饰位（如 logo）：`
` 有内容时显示，键盘导航跳过 | ### oas-menubar-item #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `access-key` | Alt 访问键（单字符）；缺省取 label 首个 ASCII 字母 | — | — | | `danger` | 破坏性项：红色语义（删除/退出等危险操作） | — | — | | `disabled` | 禁用该项 | — | — | | `href` | 链接地址：有 href 时渲染为原生 ``（真实跳转 + 照常派发 `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 内容（默认插槽文本）；直接子元素 ``/``/`` 递归为子菜单 children | ### oas-menubar-group #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `label` | 分组标题（组标题小字、次要色、不可点） | — | — | | `value` | radio 组 id（组内点选只更新该组选中值） | — | — | #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 组内菜单项：子元素 ``/``/`` 平铺同层 | ### 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 到达。