库 / Navigation

Navigation

用于复杂服务的紧凑且可扩展的导航面板。

@gravity-ui/navigation · npm package CI storybook

侧边栏头部导航 · 预览 →

安装

npm install @gravity-ui/navigation

请确保您的项目中已安装对等依赖项

npm install --dev @gravity-ui/uikit@^8.0.0 @gravity-ui/icons@^2.2.0 @bem-react/classname@^1.6.0 react@^19.0.0 react-dom@^19.0.0

迁移

从 7.x 版本升级(@gravity-ui/uikit 8, React 18 或 19):请参阅 MIGRATION_GUIDE_v8.md。

从 4.x, 5.x 或 6.x 版本升级:请先遵循 MIGRATION_GUIDE_v7.md,然后再遵循 MIGRATION_GUIDE_v8.md。

用法

将 AsideHeader 作为应用程序的骨架进行渲染。它是一个受控组件 — 您可以通过 compact/onChangeCompact 来管理折叠状态 — 并且您的页面内容通过 renderContent 传入。请先设置 @gravity-ui/uikit 的样式和 Provider(请参阅 uikit 样式指南)。

import React from 'react';
import {AsideHeader} from '@gravity-ui/navigation';
import {Gear, House} from '@gravity-ui/icons';
import {Provider} from '@gravity-ui/uikit';

import '@gravity-ui/uikit/styles/styles.css';

export function App() {
  const [compact, setCompact] = React.useState(false);

  return (
    <Provider theme="light">
      <AsideHeader
        logo={{text: 'My App', href: '/'}}
        compact={compact}
        onChangeCompact={setCompact}
        menuItems={[
          {id: 'home', title: 'Home', icon: House, current: true},
          {id: 'settings', title: 'Settings', icon: Gear},
        ]}
        renderContent={() => <main>Page content</main>}
      />
    </Provider>
  );
}

Sandboxes

基础示例 https://codesandbox.io/p/devbox/navigation-demo-simple-x9k5sd

高级示例 https://codesandbox.io/p/devbox/recursing-dawn-6kc9vh

2025 年路线图

  1. 支持 SSR
  2. 向 Gravity UI 添加更多文档和示例
  3. 支持 UIKit 主题中的导航
  4. 统一 subheaderItem, menuItem, footerItem 的 API

组件

CSS API

用于导航组件的主题化

许可证

在 MIT 许可证下分发。详情请参阅 LICENSE。

致 AI 代理

Gravity UI 应用的应用程序外壳导航组件 — 可折叠的 AsideHeader 侧边栏,以及用于构成整个页面的页脚、抽屉、Logo、快捷键和设置面板。

何时使用

  • 应用的主要导航框架:AsideHeader(可折叠侧边导航),包含 menuItems、子头部和页脚部分。
  • 支持性的外壳 UI:Drawer/DrawerItem、Footer/MobileFooter、MobileHeader、HotkeysPanel、Settings、ActionBar、Logo。
  • 通过 renderContent / PageLayout 在导航框架内布局页面内容。

何时避免使用

  • 通用的页面内控件(按钮、标签页、菜单、面包屑)— 请使用 @gravity-ui/uikit;此包是应用程序的外部框架,而非通用组件。
  • 从配置中渲染页面主体本身 — 请使用 @gravity-ui/page-constructor。
  • 客户端路由 — 此包仅提供导航 UI;请将点击事件连接到您自己的路由。

常见陷阱

  • AsideHeader 是受控组件。 您需要通过 compact 属性来管理折叠状态,并在 onChangeCompact 中更新它;如果只传递 compact 而不提供处理函数,侧边栏将无法交互。
  • 菜单项是 menuItems,通过 id 键控。 每个菜单项的结构为 {id, title, icon, current, onItemClick};icon 属性需要一个图标组件(例如来自 @gravity-ui/icons),而不是一个字符串名称。
  • 需要对等依赖。 除了 react/react-dom 外,还需要安装 @gravity-ui/uikit、@gravity-ui/icons 和 @bem-react/classname。
  • 需要 uikit 设置。 请在 Provider 组件内渲染,并导入 @gravity-ui/uikit/styles/styles.css,否则侧边栏将无法正常显示样式。
  • 页面内容通过 renderContent 渲染。 请通过 renderContent 属性或 PageLayout 组件来渲染您的路由内容,而不是直接作为 children。

AI 代理文档

已安装版本的 AI 代理可读文档位于 node_modules/@gravity-ui/navigation/build/docs/INDEX.md。

关于库
用星标支持该库
版本
8.0.3
最后更新
20.11.2026
代码仓库
github.com/gravity-ui/navigation
许可证
MIT License
维护者