顶部导航 · TopNav

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

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

{
  "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 属性。

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

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

超级菜单 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	标准正文下方渲染的自定义内容。

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

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

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

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

完整示例的额外依赖

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

npm install @heroicons/react@2.2.0

顶部导航