Navigation
用于复杂服务的紧凑且可扩展的导航面板。
@gravity-ui/navigation ·

侧边栏头部导航 · 预览 →

安装
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 年路线图
- 支持 SSR
- 向 Gravity UI 添加更多文档和示例
- 支持 UIKit 主题中的导航
- 统一 subheaderItem, menuItem, footerItem 的 API
组件
- AsideHeader
- AllPagesPanel
- PageLayout
- PageLayoutAside
- AsideFallback
- FooterItem
- Logo
- Drawer
- DrawerItem
- MobileHeader
- MobileHeaderFooterItem
- MobileLogo
- HotkeysPanel
- Footer
- MobileFooter
- ActionBar
- Settings
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。