侧边导航 · SideNav

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

安装与前置条件

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

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

示例与使用方式

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

API 与上游详细参考

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

Side Nav

A sidebar navigation component for organizing application pages with sections, nested items, and icons. Use SideNav as the primary navigation when an app has 5 or more destinations or requires hierarchical grouping.

使用建议

• Use sections to group related navigation items and help users scan for their destination.
• Pair outline and filled icon variants so the selected state is visually distinct.
• Mark the current page with isSelected: it sets aria-current="page", so the current destination is announced rather than carried by color alone.
• SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short; they name icon-only items unless a meaningful aria-label supplies more context.
• While the nav is collapsed, an item with children shows them in a submenu flyout. On a device that can hover, pointing at the item opens it after a short delay and moving away closes it; a flyout opened by clicking stays open until it is dismissed. On touch, it opens on tap. Do not put an action in there that has no other route to it.
• 避免：Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.
• 避免：Use for filtering content; use tabs or filter buttons instead.

主题 API

{
  "targets": [
    {
      "className": "astryx-side-nav",
      "visualProps": [
        "mode"
      ]
    },
    {
      "className": "astryx-side-nav-heading"
    },
    {
      "className": "astryx-side-nav-item",
      "visualProps": [
        "size"
      ],
      "states": [
        "selected",
        "disabled"
      ]
    },
    {
      "className": "astryx-side-nav-section"
    }
  ]
}

SideNavHeading

SideNavItem

SideNavSection

SideNavCollapseButton

组件结构

• Product icon and name: Branding area at the top of the nav.
• Navigation items: Sections and groups of navigable links.
• Collapse/expand toggle: Toggle to collapse or expand the side nav.

Side Nav Collapse Button

侧边栏折叠切换按钮。放置在 SideNav 内部（自动读取上下文）或外部（向两者传入同一个受控 collapsible 配置）。默认渲染为仅图标的 ghost 按钮。

Side Nav Heading

产品/套件/账户头部，具有智能交互边界逻辑，支持链接和菜单弹出框。

Side Nav Item

导航项，支持图标、选中状态、可选尾部内容，以及通过 children 实现嵌套。

Side Nav Section

分组，支持可选的标题、副标题和尾部内容。