# 顶部导航

## 使用方法

`TopNav` 是页面顶部的导航地标。`heading`、`start`、默认插槽和 `center` 从左到右排，`end` 靠右。`TopNavHeading` 可以带标志、上下行和标题菜单。`TopNavMenu` 打开普通菜单，`TopNavMegaMenu` 打开带分组和推荐卡的大菜单。推荐卡可以放图片，行动文字单独成链接。方向键在菜单项之间移动，Escape 关闭。

传入 `mobileQuery` 后，查询命中时起始和中间的内容收进 `MobileNav`，栏上只留标题、结束内容和开关。同一个插槽不会同时出现在两处。

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

<template>
  <TopNav mobile-query="(max-width: 800px)">
    <template #heading>
      <TopNavHeading heading="Northwind" href="/" />
    </template>
    <TopNavMenu label="产品" :items="[{ label: '分析', href: '/analytics' }]" />
  </TopNav>
</template>
```

### 结构

- **产品图标和名称**: 在导航栏里标识产品。
- **导航项**: 指向产品级目的地的主要链接。
- **更多菜单**: 收纳放不下的导航项的溢出菜单。
- **弹性区域**: 放搜索、主要操作按钮或其他控件的弹性区域。

## 最佳实践

| 指引 | 实践 |
| --- | --- |
| 推荐 | 菜单项用 `href` 做导航。键盘用 ArrowDown 打开，方向键移动，Escape 关闭。 |
| 推荐 | 窄屏用 `mobileQuery`，不要把同一组链接再复制进抽屉。 |
| 避免 | 大菜单里不要塞表单。它是导航，不是对话框。 |

## 示例

### 居中导航

导航项居中。标题留在起始侧，操作留在结束侧。

```vue
<script setup lang="ts">
import { Button } from '@astryx-vue/core/Button'
import { NavIcon } from '@astryx-vue/core/NavItem'
import { TopNav, TopNavHeading, TopNavItem } from '@astryx-vue/core/TopNav'
</script>

<template>
  <div class="nav-frame">
    <TopNav label="Main navigation">
      <template #heading>
        <TopNavHeading heading="My App" href="#home">
          <template #icon>
            <NavIcon icon-class="i-carbon-cube" />
          </template>
        </TopNavHeading>
      </template>
      <template #center>
        <TopNavItem href="#home" is-selected label="Home" />
        <TopNavItem href="#products" label="Products" />
        <TopNavItem href="#about" label="About" />
      </template>
      <template #end>
        <Button is-icon-only label="Search" variant="ghost">
          <template #icon>
            <span class="i-carbon-search" />
          </template>
        </Button>
        <Button is-icon-only label="Profile" variant="ghost">
          <template #icon>
            <span class="i-carbon-user" />
          </template>
        </Button>
      </template>
    </TopNav>
  </div>
</template>
```

### 应用顶栏

带图标的导航项、搜索、通知，以及一个主要操作。

```vue
<script setup lang="ts">
import { Button } from '@astryx-vue/core/Button'
import { NavIcon } from '@astryx-vue/core/NavItem'
import { TopNav, TopNavHeading, TopNavItem } from '@astryx-vue/core/TopNav'
</script>

<template>
  <div class="nav-frame">
    <TopNav label="Main navigation">
      <template #heading>
        <TopNavHeading heading="My App" href="#home">
          <template #icon>
            <NavIcon icon-class="i-carbon-cube" />
          </template>
        </TopNavHeading>
      </template>
      <TopNavItem href="#dashboard" icon-class="i-carbon-home" is-selected label="Dashboard" />
      <TopNavItem href="#reports" icon-class="i-carbon-document" label="Reports" />
      <template #end>
        <Button is-icon-only label="Search" variant="ghost">
          <template #icon>
            <span class="i-carbon-search" />
          </template>
        </Button>
        <Button is-icon-only label="Notifications" variant="ghost">
          <template #icon>
            <span class="i-carbon-notification" />
          </template>
        </Button>
        <Button label="Upgrade" variant="primary" />
      </template>
    </TopNav>
  </div>
</template>
```

### 悬停菜单

悬停打开产品菜单，每一项有图标和说明。

```vue
<script setup lang="ts">
import { Button } from '@astryx-vue/core/Button'
import { NavIcon } from '@astryx-vue/core/NavItem'
import { TopNav, TopNavHeading, TopNavItem, TopNavMenu } from '@astryx-vue/core/TopNav'
</script>

<template>
  <div class="nav-frame">
    <TopNav label="Main navigation">
      <template #heading>
        <TopNavHeading heading="My App" href="#home">
          <template #icon>
            <NavIcon icon-class="i-carbon-cube" />
          </template>
        </TopNavHeading>
      </template>
      <TopNavItem href="#home" is-selected label="Home" />
      <TopNavMenu
        label="Products"
        :items="[
          { description: 'Track and analyze user behavior', href: '#analytics', iconClass: 'i-carbon-analytics', label: 'Analytics' },
          { description: 'Enterprise-grade protection', href: '#security', iconClass: 'i-carbon-security', label: 'Security' },
          { description: 'Streamline your workflows', href: '#automation', iconClass: 'i-carbon-flash', label: 'Automation' },
          { description: 'APIs, SDKs, and CLI tools', href: '#dev-tools', iconClass: 'i-carbon-code', label: 'Developer Tools' },
        ]"
      />
      <TopNavItem href="#pricing" label="Pricing" />
      <template #end>
        <Button is-icon-only label="Profile" variant="ghost">
          <template #icon>
            <span class="i-carbon-user" />
          </template>
        </Button>
      </template>
    </TopNav>
  </div>
</template>
```

### 大菜单

通栏的大菜单里有产品项。推荐卡上方是图片，底部的行动文字单独跳转。

```vue
<script setup lang="ts">
import { Button } from '@astryx-vue/core/Button'
import { NavIcon } from '@astryx-vue/core/NavItem'
import { TopNav, TopNavHeading, TopNavItem, TopNavMegaMenu, TopNavMegaMenuFeaturedCard, TopNavMegaMenuItem } from '@astryx-vue/core/TopNav'
</script>

<template>
  <div class="nav-frame">
    <TopNav label="Marketing navigation">
      <template #heading>
        <TopNavHeading heading="My App" href="#home">
          <template #icon>
            <NavIcon icon-class="i-carbon-cube" />
          </template>
        </TopNavHeading>
      </template>
      <TopNavMegaMenu label="Products">
        <TopNavMegaMenuItem description="Track and analyze user behavior across your apps" href="#analytics" icon-class="i-carbon-analytics" title="Analytics" />
        <TopNavMegaMenuItem description="Enterprise-grade protection for your data" href="#security" icon-class="i-carbon-security" title="Security" />
        <TopNavMegaMenuItem description="Streamline workflows with intelligent tools" href="#automation" icon-class="i-carbon-flash" title="Automation" />
        <TopNavMegaMenuItem description="APIs, SDKs, and CLI for integration" href="#dev-tools" icon-class="i-carbon-code" title="Developer Tools" />
        <TopNavMegaMenuItem description="Low-latency edge infra in 40+ regions" href="#network" icon-class="i-carbon-globe" title="Global Network" />
        <template #featured>
          <TopNavMegaMenuFeaturedCard
            description="AI-powered analytics and real-time collaboration."
            image="/template-assets/light-working-horizontal-1.png"
            link-href="#announcement"
            link-label="Read the announcement"
            title="What's new in v4.0"
          />
        </template>
      </TopNavMegaMenu>
      <TopNavItem href="#pricing" label="Pricing" />
      <TopNavItem href="#docs" label="Docs" />
      <template #end>
        <Button label="Sign in" variant="ghost" />
        <Button label="Get started" variant="primary" />
      </template>
    </TopNav>
  </div>
</template>
```

### 带菜单的标题

标题有套件名、产品名和账户名。套件名可以单独跳转，箭头打开产品菜单。

```vue
<script setup lang="ts">
import { NavIcon } from '@astryx-vue/core/NavItem'
import { NavHeadingMenu, NavHeadingMenuItem } from '@astryx-vue/core/NavMenu'
import { TopNav, TopNavHeading, TopNavItem } from '@astryx-vue/core/TopNav'
</script>

<template>
  <div class="nav-frame">
    <TopNav label="Product navigation">
      <template #heading>
        <TopNavHeading
          heading="Console"
          heading-href="#console"
          subheading="Northwind"
          superheading="Acme Suite"
          superheading-href="#suite"
        >
          <template #logo>
            <NavIcon icon-class="i-carbon-cube" />
          </template>
          <template #menu>
            <NavHeadingMenu label="Switch product">
              <NavHeadingMenuItem href="#console" label="Console" />
              <NavHeadingMenuItem description="Usage and reports" href="#analytics" label="Analytics" />
              <NavHeadingMenuItem href="#settings" label="Settings" />
            </NavHeadingMenu>
          </template>
        </TopNavHeading>
      </template>
      <TopNavItem href="#overview" is-selected label="Overview" />
      <TopNavItem href="#docs" label="Docs" />
    </TopNav>
  </div>
</template>
```

### 多个下拉菜单

一条顶栏里有多个悬停菜单，指针移到另一个菜单时前一个会关上。

```vue
<script setup lang="ts">
import { NavIcon } from '@astryx-vue/core/NavItem'
import { TopNav, TopNavHeading, TopNavItem, TopNavMenu } from '@astryx-vue/core/TopNav'
</script>

<template>
  <div class="nav-frame">
    <TopNav label="Main navigation">
      <template #heading>
        <TopNavHeading heading="My App" href="#home">
          <template #icon>
            <NavIcon icon-class="i-carbon-cube" />
          </template>
        </TopNavHeading>
      </template>
      <TopNavMenu
        label="Products"
        :items="[
          { description: 'Track behavior', href: '#analytics', iconClass: 'i-carbon-analytics', label: 'Analytics' },
          { description: 'Enterprise protection', href: '#security', iconClass: 'i-carbon-security', label: 'Security' },
        ]"
      />
      <TopNavMenu
        label="Resources"
        :items="[
          { href: '#docs', label: 'Documentation' },
          { href: '#api', label: 'API Reference' },
          { href: '#community', label: 'Community Forum' },
        ]"
      />
      <TopNavItem href="#pricing" label="Pricing" />
    </TopNav>
  </div>
</template>
```

### 带标志

标题前面是产品标志，结束侧是个人资料操作。

```vue
<script setup lang="ts">
import { Button } from '@astryx-vue/core/Button'
import { NavIcon } from '@astryx-vue/core/NavItem'
import { TopNav, TopNavHeading, TopNavItem } from '@astryx-vue/core/TopNav'
</script>

<template>
  <div class="nav-frame">
    <TopNav label="Main navigation">
      <template #heading>
        <TopNavHeading heading="My App" href="#home">
          <template #icon>
            <NavIcon icon-class="i-carbon-cube" />
          </template>
        </TopNavHeading>
      </template>
      <TopNavItem href="#overview" is-selected label="Overview" />
      <TopNavItem href="#analytics" label="Analytics" />
      <TopNavItem href="#reports" label="Reports" />
      <template #end>
        <Button is-icon-only label="Profile" variant="ghost">
          <template #icon>
            <span class="i-carbon-user" />
          </template>
        </Button>
      </template>
    </TopNav>
  </div>
</template>
```

## TopNav Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | 当前语言的「顶部导航」 | 导航地标的无障碍名称。 |
| `mobileQuery` | `string` | - | 命中这条媒体查询时，起始和中间内容收进移动导航。 |

## TopNav Slots

| 名称 | 说明 |
| --- | --- |
| `heading` | 品牌标题，窄屏时仍留在顶栏。 |
| `start` | 标题右侧的内容。 |
| `default` | 和 `start` 排在一起的导航项、菜单。 |
| `center` | 居中区域。存在时顶栏改成三列。 |
| `end` | 右侧操作。窄屏时仍留在顶栏。 |

## TopNavMenu Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | - | 触发按钮上的文字。 |
| `items` | `TopNavMenuItem[]` | - | 数据项。也可以用默认插槽写 `NavMenuItem`。 |
| `showDelay` | `number` | `150` | 悬停打开前的等待，毫秒。 |
| `hideDelay` | `number` | `200` | 指针离开后的关闭等待，毫秒。 |

## TopNavMegaMenu Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | - | 触发按钮上的文字，也是面板的无障碍名称。 |
| `showDelay` | `number` | `150` | 悬停打开前的等待，毫秒。 |
| `hideDelay` | `number` | `250` | 指针离开后的关闭等待，毫秒。 |

默认插槽放 `TopNavMegaMenuItem`。`featured` 插槽放 `TopNavMegaMenuFeaturedCard`。抽屉里同一组内容变成手风琴，不再使用菜单角色。

## TopNavHeading Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `heading` | `string` | - | 产品或应用名称。只有标志、没有文字时可以不传。 |
| `href` | `string` | - | 主标题链接。和 `headingHref` 相同，后者优先。 |
| `headingHref` | `string` | - | 主标题链接。 |
| `superheading` | `string` | - | 主标题上方的小字。 |
| `superheadingHref` | `string` | - | 上方小字的链接。 |
| `subheading` | `string` | - | 主标题下方的小字。 |
| `subheadingHref` | `string` | - | 下方小字的链接。 |
| `logoLabel` | `string` | - | 标志单独成链接、旁边没有可读文字时的无障碍名称。不传则用 `heading`。 |
| `as` | `NavLinkComponent` | `'a'` | 有地址时使用的链接根组件，可同时接收 `href` 和 `to`。 |

只有主标题有链接、且没有菜单时，整段标题是一个链接。有菜单、没有任何链接时，整段标题打开菜单。菜单和链接同时存在时，各行自己跳转，只有箭头打开菜单。

## TopNavHeading Slots

| 名称 | 说明 |
| --- | --- |
| `logo` | 标题前的标志。和 `icon` 是同一个位置，`logo` 优先。 |
| `icon` | 标题前的图标。 |
| `end` | 标题行末尾，例如徽章。 |
| `menu` | 弹出菜单，通常放 `NavHeadingMenu`。作用域提供 `close` 和 `focusRequest`。 |

## TopNavMegaMenuFeaturedCard Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `title` | `string` | - | 卡片标题。 |
| `description` | `string` | - | 标题下面的说明。 |
| `href` | `string` | - | 整张卡片的链接。同时写了 `linkLabel` 时，链接改到卡片底部。 |
| `image` | `string` | - | 正文上方的图片地址。 |
| `imageAlt` | `string` | - | 图片的替代文本。不传时图片是装饰，读屏会跳过。 |
| `linkLabel` | `string` | - | 卡片底部的行动文字。 |
| `linkHref` | `string` | - | 行动文字的地址。不传则用 `href`。 |
| `as` | `NavLinkComponent` | `'a'` | 链接根组件。 |