KeystoneJS 自定义 Admin UI 导航栏开发指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00559/article/details/148418304

KeystoneJS 自定义 Admin UI 导航栏开发指南

keystone The most powerful headless CMS for Node.js — built with GraphQL and React 项目地址: https://gitcode.com/gh_mirrors/key/keystone

作为一款优秀的 Headless CMS 框架，KeystoneJS 提供了高度可定制的 Admin UI 界面。本文将深入讲解如何通过自定义 Navigation 组件来打造专属的后台导航系统。

为什么需要自定义导航栏

默认情况下，KeystoneJS 会自动为每个数据模型生成导航项。但在实际项目中，我们经常需要：

添加额外的功能入口（如文档链接）
调整导航项的顺序和分组
实现更复杂的导航交互逻辑
集成外部系统链接

通过自定义导航组件，开发者可以完全掌控 Admin UI 的导航结构。

实现步骤详解

1. 创建配置文件

首先需要在项目根目录下创建 /admin/config.ts 文件，这是 KeystoneJS 的标准配置入口：

// /admin/config.ts
import type { AdminConfig } from '@keystone-6/core/types'
import { CustomNavigation } from './components/CustomNavigation'

export const components: AdminConfig['components'] = {
  Navigation: CustomNavigation
}

这个配置告诉 KeystoneJS 使用我们自定义的导航组件替代默认实现。

2. 构建自定义导航组件

在 /admin/components/CustomNavigation.tsx 文件中创建 React 组件：

// admin/components/CustomNavigation.tsx
import { NavigationContainer, NavItem, ListNavItems } from '@keystone-6/core/admin-ui/components'
import type { NavigationProps } from '@keystone-6/core/admin-ui/components'

export function CustomNavigation({ lists }: NavigationProps) {
  return (
    <NavigationContainer>
      <NavItem href="/">控制面板</NavItem>
      <ListNavItems lists={lists}/>
      <NavItem href="https://keystonejs.com/">
        官方文档
      </NavItem>
    </NavigationContainer>
  )
}

这个组件使用了 KeystoneJS 提供的三个核心组件：

NavigationContainer - 导航容器组件，提供统一的样式和布局
NavItem - 单个导航项组件
ListNavItems - 自动生成数据模型导航项的组件

3. 关键组件解析

NavigationContainer

这个容器组件确保自定义导航与 KeystoneJS 的默认样式保持一致，它处理了：

响应式布局
滚动行为
主题适配
无障碍访问支持

NavItem

每个导航项的核心组件，特性包括：

内置的选中状态样式
无障碍访问属性
与 Next.js 路由的深度集成
支持外部链接

ListNavItems

这个智能组件自动处理：

数据模型的可见性过滤
路由生成
国际化标签显示
支持按需加载特定模型

高级定制技巧

选择性显示数据模型

如果只需要显示部分数据模型，可以使用 include 属性：

<ListNavItems lists={lists} include={["User", "Post"]} />

自定义选中状态

对于特殊导航项，可以手动控制选中状态：

<NavItem 
  href="/custom-page"
  isSelected={router.pathname.startsWith('/custom')}
>
  自定义页面
</NavItem>

分组导航项

通过组合这些组件，可以实现分组导航：

<NavigationContainer>
  <div className="nav-group">
    <h3>内容管理</h3>
    <ListNavItems lists={lists} include={["Post", "Category"]} />
  </div>
  
  <div className="nav-group">
    <h3>系统设置</h3>
    <ListNavItems lists={lists} include={["User", "Role"]} />
  </div>
</NavigationContainer>