# 导航标题菜单

## 使用方法

导航标题旁边那个弹出菜单的容器和条目。`NavHeadingMenu` 提供 `role="menu"` 和键盘导航，`NavHeadingMenuItem` 画里面的每一个可选条目。把它放进 `SideNavHeading` 或 `TopNavHeading` 的 `menu` 插槽即可。

```ts
import { NavHeadingMenu } from '@astryx-vue/core/NavMenu'
```

```vue
<script setup lang="ts">
import { NavHeadingMenu, NavHeadingMenuItem } from '@astryx-vue/core/NavMenu'
import { SideNav, SideNavHeading } from '@astryx-vue/core/SideNav'
</script>

<template>
  <SideNav>
    <template #header>
      <SideNavHeading heading="Acme Platform">
        <template #menu>
          <NavHeadingMenu label="Acme Platform" size="lg">
            <NavHeadingMenuItem href="/dashboard" label="控制台" />
            <NavHeadingMenuItem href="/analytics" label="数据分析" />
          </NavHeadingMenu>
        </template>
      </SideNavHeading>
    </template>
  </SideNav>
</template>
```

### 结构

- **菜单**: 导航标题菜单的容器，带菜单语义和键盘导航。
- **条目**: 菜单里可选的动作，或者一个导航链接。
- **图标**: 条目文字前面用 Icon 画出来的图标。
- **用 Text 渲染的条目文字**: 字符串形式的条目文字，交给 Text 渲染。
- **调用方渲染的条目文字**: 条目文字不是字符串时，内容由调用方直接渲染。
- **条目说明**: 条目下面那行辅助说明，交给 Text 渲染。

## NavHeadingMenu 属性

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | — | 菜单的无障碍名称，写到 `aria-label` 上。标题文字本身说不清这个菜单是干什么的时候设置它。 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 菜单宽度档，同时决定每一项的内边距。 |
| `minWidth` | `number \| string` | — | 覆盖按档位算出的最小宽度。数字按像素处理。 |
| `focusRequest` | `'first' \| 'last' \| null` | `null` | 菜单打开后把焦点放到第一项或最后一项。标题的弹出面板会自己传进来，所以用键盘打开时焦点直接落在条目上。 |

## NavHeadingMenu 事件

| 名称 | 说明 |
| --- | --- |
| `close` | 按下 Escape 时触发。`SideNavHeading` 和 `TopNavHeading` 已经接住了它，会把弹出面板关掉。 |

## NavHeadingMenu 插槽

| 名称 | 说明 |
| --- | --- |
| `default` | 菜单里的条目。 |

## NavHeadingMenuItem 属性

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | — | 条目的主要文字。想在条目里放富文本时改用默认插槽。 |
| `description` | `string` | — | 文字下面的一行辅助说明。 |
| `href` | `string` | — | 给出后这个条目渲染成链接。 |
| `as` | `NavLinkComponent` | `'a'` | 链接的根组件，例如 `RouterLink`。此时条目会同时写 `href` 和 `to`。 |
| `iconClass` | `string` | — | 文字前面那个图标的 CSS 类名。 |
| `isDisabled` | `boolean` | `false` | 禁用这个条目。点击不响应，方向键和首字母查找也会跳过它。 |

## NavHeadingMenuItem 事件

| 名称 | 载荷 | 说明 |
| --- | --- | --- |
| `click` | `MouseEvent` | 激活这个条目时触发，触发时机在菜单收起之前。 |

## NavHeadingMenuItem 插槽

| 名称 | 说明 |
| --- | --- |
| `default` | 富文本内容，替代 `label` 属性的纯文字。 |
| `icon` | 图标内容，优先于 `iconClass` 画出来的字形。 |

整个菜单是一个 `role="menu"`：方向键在条目之间移动并循环，直接按字母会跳到以该字母开头的下一个条目，Escape 关掉面板并把焦点还给标题。