# 导航项

## 使用方法

`NavItem` 是侧栏、顶栏和菜单里的一条导航。有 `href` 时渲染成链接，禁用或没有地址时渲染成按钮。图标用 `iconClass` 传入 CSS icon，也可以用 `icon` 插槽。需要圆形强调底时用同目录导出的 `NavIcon`。

链接根默认是 `a`。接入 Vue Router 时把 `RouterLink` 传给 `as`，组件会同时带上 `href` 和 `to`。

```vue
<script setup lang="ts">
import { NavItem } from '@astryx-vue/core/NavItem'
</script>

<template>
  <NavItem href="/home" icon-class="i-carbon-home" is-selected label="首页" />
</template>
```

## 最佳实践

| 指引 | 实践 |
| --- | --- |
| 推荐 | 当前页设置 `isSelected`，组件会写上 `aria-current="page"`。 |
| 推荐 | 只显示图标时打开 `isIconOnly`，`label` 仍会成为无障碍名称。 |
| 避免 | 不要把图标做成独立的图标组件再塞进导航。图标走 class 或插槽。 |

## 示例

### 基本用法

导航标题上的圆形图标容器。搜索和日历并排放在一起。

```vue
<script setup lang="ts">
import { NavIcon } from '@astryx-vue/core/NavItem'
import { HStack } from '@astryx-vue/core/Stack'
</script>

<template>
  <HStack align="center" :gap="4">
    <NavIcon icon-class="i-carbon-search" />
    <NavIcon icon-class="i-carbon-calendar" />
  </HStack>
</template>
```

## NavItem Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | - | 可见文字。图标模式下作为无障碍名称。 |
| `href` | `string` | - | 有地址且未禁用时渲染成链接。 |
| `as` | `NavLinkComponent` | `'a'` | 链接根组件，例如 `RouterLink`。 |
| `target` | `string` | - | 链接的 target。为 `_blank` 时自动补上 `noopener noreferrer`。 |
| `rel` | `string` | - | 链接的 rel。 |
| `isSelected` | `boolean` | `false` | 当前页。会设置 `aria-current="page"`。 |
| `isDisabled` | `boolean` | `false` | 禁用后渲染成按钮，不进入 Tab 顺序。 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 高度和内边距。 |
| `iconClass` | `string` | - | 图标的 CSS class，例如 `i-carbon-home`。 |
| `selectedIconClass` | `string` | - | 选中时替换 `iconClass`。 |
| `isIconOnly` | `boolean` | `false` | 只显示图标，文字留给读屏。 |
| `block` | `boolean` | `false` | 占满所在行的宽度。 |
| `plain` | `boolean` | `false` | 去掉自己的底色，由外层负责外观。 |
| `expanded` | `boolean` | - | 是否展开下级。不传则不设置 `aria-expanded`。 |
| `controls` | `string` | - | 展开内容的 id，写到 `aria-controls`。 |
| `hasPopup` | `string` | - | 打开的弹出层类型，写到 `aria-haspopup`。 |

## NavItem 事件

| 名称 | 说明 |
| --- | --- |
| `click` | 点击时触发。禁用时会先阻止默认行为。 |

## NavItem Slots

| 名称 | 说明 |
| --- | --- |
| `default` | 替换可见文字。不传时使用 `label`。 |
| `icon` | 图标。优先于 `iconClass` 的默认字形。 |
| `selectedIcon` | 选中时的图标。 |
| `end` | 文字右侧的附加内容，例如箭头或计数。 |

## NavIcon Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `iconClass` | `string` | - | 圆形底上的 CSS 图标 class。 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 圆形的直径。 |
| `label` | `string` | - | 有文字时作为图片的无障碍名称；不传则对读屏隐藏。 |