# 顶部导航 · TopNav

- 页面: https://jiguang132.com/zh/resources/astryx/docs/top-nav
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

顶部导航用于导航场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **顶部导航 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **顶部导航 · 综合展示 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 综合展示 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 综合展示 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 综合展示 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 综合展示 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 综合展示 7**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 交互示例 8**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 交互示例 9**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 基础用法 10**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 交互示例 11**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 基础用法 12**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 交互示例 13**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 基础用法 14**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 基础用法 15**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 基础用法 16**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 基础用法 17**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 交互示例 18**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **顶部导航 · 交互示例 19**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Top Nav

TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| heading | ReactNode |  | Heading slot content (logo, brand): positioned at the left edge of the nav bar. |
| startContent | ReactNode |  | Start content slot for navigation items or breadcrumbs: positioned after the heading, left-aligned. |
| children | ReactNode |  | Alias for startContent. Prefer startContent when composing with heading, centerContent, or endContent; children keeps the common React nav-item pattern from silently dropping items. |
| centerContent | ReactNode |  | Center content slot (tabs, search bar, primary navigation): when provided, switches the layout to a three-column CSS grid for true horizontal centering. |
| endContent | ReactNode |  | End content slot for search, icons, or user profile: positioned at the right edge. |
| label | string | 'Top navigation' | Accessible label for the navigation landmark, applied as aria-label on the <nav> element. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}. |

### 使用建议

- Include a product logo and name in the heading slot to clearly identify the application.
- Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load.
- 避免：Avoid using TopNav to filter page content; use Tabs or filter controls instead.
- 避免：Avoid deeply nested navigation hierarchies; keep menus to one level of depth.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-top-nav",
      "states": [
        "mode"
      ]
    },
    {
      "className": "astryx-top-nav-item",
      "states": [
        "mode",
        "selected"
      ]
    },
    {
      "className": "astryx-top-nav-heading"
    },
    {
      "className": "astryx-top-nav-mega-menu",
      "states": [
        "mode"
      ]
    },
    {
      "className": "astryx-top-nav-mega-menu-item",
      "states": [
        "mode"
      ]
    },
    {
      "className": "astryx-top-nav-mega-menu-featured-card"
    },
    {
      "className": "astryx-top-nav-menu"
    }
  ]
}
```

## TopNavHeading



## TopNavItem



## TopNavMenu



## TopNavMegaMenu



## TopNavMegaMenuItem



## TopNavMegaMenuFeaturedCard



### 组件结构

- **Product icon and name**: Identifies the product in the navigation bar.
- **Navigation items**: Primary links for product-level destinations.
- **More menu**: Overflow menu for additional navigation items.
- **Flex area**: Flexible region for search, primary action buttons, or other controls.

## Top Nav Heading

TopNav 标题插槽的产品/套件/账户标题组件。支持智能交互边界逻辑：标志、标题文本、独立链接的上标题/下标题，以及带自动箭头指示器的可选菜单弹出层。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| logo | ReactNode |  | 在标题文本前显示的标志元素。可以是图片、NavIcon 或任何 ReactNode。 |
| heading | string |  | 作为主标题文本显示的产品/应用名称。 |
| headingHref | string |  | 标题文本的链接（如产品首页）。当没有菜单且这是唯一的 href 时，整个标题变为一个可点击链接。 |
| superheading | string |  | 标题上方的文本（如套件名称）。以较小的次要样式渲染。 |
| superheadingHref | string |  | 上标题文本的链接（如套件首页）。与菜单一起提供时，渲染为独立的内联链接。 |
| subheading | string |  | 标题下方的文本（如账户上下文）。以较小的次要样式渲染。 |
| subheadingHref | string |  | 下标题文本的链接。与菜单一起提供时，渲染为独立的内联链接。 |
| headerEndContent | ReactNode |  | 在标题行尾部渲染的内容（如徽章或状态指示器）。 |
| menu | ReactNode |  | 在弹出层下拉菜单中显示的菜单内容。提供时自动显示箭头指示器。交互边界由 href 的存在决定：没有 href 时整个标题为触发器；有 href 时链接独立，箭头区域为触发器。 |
| as | LinkComponentType |  | 用于替代 <a> 的自定义链接组件。覆盖 LinkProvider 设置的默认组件。必须接受 href、className、style 和 children 属性。 |
| xstyle | StyleXStyles |  | 用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。 |

## Top Nav Item

用于 TopNav startContent 的导航链接项，渲染为具有悬停和选中状态的锚点。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 导航项的无障碍标签。用作可见文本，或作为仅图标项的 aria-label。 |
| href | string |  | 导航目标 URL。 |
| isSelected | boolean | false | 此导航项是否为当前选中状态。设置 aria-current="page" 并应用高亮样式。 |
| isDisabled | boolean | false | 导航项是否被禁用。设置 aria-disabled，移除 href/target 使其无法导航，并阻止交互。 |
| isIconOnly | boolean | false | Renders the item as a square icon-only element. When true, label becomes the aria-label and visible text is hidden. Requires icon to be set. |
| icon | ReactNode |  | 在标签前显示的可选图标。如果在没有子元素的情况下提供，项目变为仅图标模式。 |
| children | ReactNode |  | 替代标签文本渲染的自定义内容。省略且提供了图标时，项目变为仅图标模式。 |
| as | LinkComponentType |  | 替代 <a> 渲染的自定义组件。覆盖 LinkProvider 设置的提供者级别默认值。必须接受 href、className、style 和 children 属性。 |

## Top Nav Mega Menu

导航项，在悬停时显示全宽超级菜单面板。使用插槽 API（items 和 featured）。TopNavMegaMenuItem 在桌面和移动抽屉模式中自行渲染。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 触发按钮的可见标签。 |
| items | ReactNode |  | 菜单项插槽，通常为 TopNavMegaMenuItem 组件，但接受任何 ReactNode。 |
| featured | ReactNode |  | 特色内容插槽，桌面端显示在右侧面板，移动抽屉中显示在项目下方。 |
| delay | number | 150 | 悬停时显示菜单前的延迟（毫秒）。 |
| hideDelay | number | 250 | 鼠标离开后隐藏菜单的延迟（毫秒）。 |
| onOpenChange | (isOpen: boolean) => void |  | 超级菜单打开或关闭时触发的回调。用于协调包装器样式。 |

## Top Nav Mega Menu Featured Card

超级菜单 featured 插槽的标准特色卡片。提供带可选图片、标题、描述和 CTA 链接的一致卡片。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title * | string |  | 卡片标题。 |
| description | string |  | 标题下方的描述文本。 |
| image | string |  | 正文上方显示的可选图片 URL。 |
| imageAlt | string |  | 图片的替代文本。省略时图片会被显式标记为装饰性（alt=""、role="presentation"、aria-hidden）——由于卡片已有可见标题，这通常是正确的。仅当图片传达标题和描述之外的信息时才提供。 |
| linkLabel | string |  | CTA 链接文本。 |
| linkHref | string |  | CTA 链接 URL。 |
| children | ReactNode |  | 标准正文下方渲染的自定义内容。 |

## Top Nav Mega Menu Item

超级菜单中的单个项目。在桌面端（弹出层网格）和移动抽屉模式中都会自行渲染。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title * | string |  | 菜单项的显示标题。 |
| description | string |  | 标题下方的可选描述文本。 |
| icon | ReactNode |  | 左侧显示的可选图标元素。 |
| href | string |  | 点击时导航的 URL。 |
| onClick | () => void |  | 点击项目时的回调。 |
| as | LinkComponentType |  | 用于替代 <a> 的自定义链接组件。覆盖 LinkProvider 设置的默认组件。 |

## Top Nav Menu

导航项，在悬停时显示弹出菜单，包含带图标、标题和可选描述的丰富菜单项。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 触发按钮的可见标签。 |
| items * | TopNavMenuItemData[] |  | 在悬停弹出框中显示的菜单项。 |
| delay | number | 150 | 悬停时显示菜单前的延迟（毫秒）。 |
| hideDelay | number | 200 | 鼠标离开后隐藏菜单的延迟（毫秒）。 |


## 完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

```bash
npm install @heroicons/react@2.2.0
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt