如何使用 shadcn/ui 与 Base-UI 构建管理员仪表盘的侧边栏

作为React开发者，管理面板是您最常需要开发的实际应用中的UI组件之一。几乎所有的管理面板的核心都包含一个侧边栏——这个永久性存在的导航面板能够将各种页面、工具和功能整理成结构清晰、便于浏览的形式。

从头开始构建一个侧边栏，所涉及的内容远不止一个

元素而已。您需要实现可折叠的子菜单、能够跟踪父项和子项的活跃状态、支持键盘导航的功能、为过长的导航列表提供滚动区域，同时还需要确保设计体系在不同的屏幕尺寸下都能保持一致。

在本教程中，您将学习如何使用shadcn/ui来构建一个功能完备、易于使用的管理面板侧边栏。shadcn/ui是一组设计精美且符合无障碍设计标准的React组件，而Shadcn Space提供的预建社区模块则为这些组件增添了可供直接使用的管理面板UI模板。

完成本教程后，您将获得这样一个可正常使用的侧边栏，它包含以下功能：

使用大写字母作为标签的分组导航栏
可折叠的父菜单项以及其中的子链接

能够同时跟踪父项和子项的活跃状态

具有独立滚动区域的浮动侧边栏
侧边栏底部固定的宣传卡片

先决条件
您将构建什么
为什么选择shadcn/ui？
什么是Shadcn Space？
如何安装侧边栏模块
如何理解文件夹结构
如何构建页面布局
如何开发应用侧边栏组件
如何定义导航数据
如何构建NavMain组件
如何处理活跃状态与可折叠菜单
如何为侧边栏添加样式
实时预览功能
总结

先决条件

在开始之前，请确保您具备以下条件：

您的计算机上已安装Node.js 18或更高版本
具备React和TypeScript的基本知识
熟悉Tailwind CSS中的实用类
已经安装了包管理工具（npm、pnpm、yarn或bun）

你不需要具备使用 shadcn/ui 的相关经验，但至少阅读过一次官方文档会很有帮助。

你将构建什么

在这篇文章中，你将会构建一个具备以下功能的完整管理面板侧边栏：

浮动式侧边栏框架：采用卡片样式设计，边框呈圆角，带有阴影效果，宽度也可进行配置。
分组导航功能：导航项按照“管理面板”、“页面”、“应用”和“表单元素”等分类标签进行组织。
可折叠子菜单：像“博客”和“Shadcn 表单”这样的父级选项，点击后可以展开显示子链接。
活动状态高亮显示：无论何时，选中的父级项和子级项都会被可视化地突出显示出来。
侧边栏开关功能
页面头部有一个按钮，用于切换侧边栏的显示状态。

推广卡片：在侧边栏滚动区域的底部会显示一张“升级高级版”的推荐卡片。

为什么选择 shadcn/ui?

shadcn/ui是一组设计精美、易于使用的 React 组件，这些组件基于 Radix UI 构建，并采用了 Tailwind CSS 进行样式设计。

与安装传统的组件库不同，你可以直接使用 CLI 将这些组件复制到自己的项目中。这样一来，你就可以完全掌控代码的结构和样式设置——你可以阅读每一行代码，对其进行任意修改，而且也不会因为第三方库的更新而导致你的项目出现问题。

shadcn/ui 的一些主要优点包括：

默认情况下就已经具备无障碍使用功能，其基础组件基于 Radix UI 和 Base UI 构建。

所有样式都通过 Tailwind CSS 的实用类进行统一管理。

完全不依赖任何第三方库：代码直接保存在你的项目中，而不会存在于 node_modules 目录中。

兼容 Next.js、React、Astro、Vite 等各种框架。

拥有由社区成员开发的丰富组件库和资源库。

在本教程中使用的 侧边栏、可折叠元素、滚动区域、卡片和按钮 这些组件都来自 shadcn/ui。

什么是 Shadcn Space?

Shadcn Space是一个开源的预构建 UI 组件库，这些组件都是基于 shadcn/ui 开发而成的。它提供了各种现成的管理面板布局、侧边栏、表格、卡片等常用UI元素，因此你不必每次都从头开始组装这些组件。

Shadcn Space 中的每个组件都可以直接通过 shadcn CLI 安装到你的项目中。一旦安装完成，这些代码就完全属于你了——你可以随意阅读、修改它们，并根据自己的设计需求进行调整，而完全不需要依赖 Shadcn Space 本身。

在本教程中，您将使用sidebar-06这个组件块（它可以免费使用）。这个组件块是一个浮动式的管理员侧边栏，具有分组导航功能、可折叠的子菜单以及集成的滚动区域。

Shadcn Space还提供了一套配套的Figma UI Kit，这套工具包与这些组件块所采用的设计系统相匹配。如果您需要在开发工作中同时进行设计工作，那么这个工具包会非常有用。

您可以在Shadcn Space官方文档中查看完整的组件库以及入门指南。

如何设置项目

如果您还没有Next.js项目，首先创建一个新项目：

npx shadcn@latest init --preset b0 --base base --template next

这条命令会：

创建一个Next.js项目

配置Tailwind CSS样式系统

将Base UI作为组件基础框架进行设置

使用Nova风格预设

配置Lucide图标

使用Inter字体

应用中性主题样式

按照提示设置基础颜色、CSS变量以及组件输出目录。这样就能建立components/ui目录，并配置所有shadcn/ui组件所依赖的Tailwind相关设置。

初始化完成后，您的components.json文件将会被创建在项目根目录下。这个文件会告诉shadcn CLI应将组件放置在哪里、使用哪些路径别名，以及遵循哪种样式配置。

在components.json文件中添加以下内容：

{ "registries": { "@shadcn-space": { "url": "https://shadcnspace.com/r/{name}.json", } } }

如何安装sidebar组件块

在完成shadcn/ui的初始化配置后，您就可以从Shadcn Space中获取sidebar-06这个组件块了。虽然Shadcn Space提供了适用于Radix UI和Base UI的组件，但本教程中使用的是Base UI版本。根据您使用的包管理器，运行以下相应的命令之一：

npm:

npx shadcn@latest add @shadcn-spacesidebar-06

pnpm:

pnpm dlx shadcn@latest add @shadcn-space sidebar-06

yarn:

yarn dlx shadcn@latest add @shadcn-spacesidebar-06

bun:

bunx --bun shadcn@latest add @shadcn-space sidebar-06

这条命令会从Shadcn Space的注册系统中下载该组件块，并自动将所有所需的组件文件添加到您的项目中。同时，如果您的目录中还没有这些依赖组件（比如以及Collapsible），这条命令也会将这些组件安装进来。

您可以在他们的shadcn侧边栏页面上预览该组件，并找到相应的安装命令。

如何理解文件夹结构

安装完成后，您的项目将会包含以下新文件：

app/ sidebar-06/ page.tsx ← 路由入口点 assets/ logo/ logo.tsx ← 标志组件 components/ shadcn-space/ blocks/ sidebar-06/ app-sidebar.tsx ← 主侧边栏框架 nav-main.tsx ← 导航逻辑与渲染代码

每个文件都有明确的职责：

appsidebar-06/page.tsx：路由入口点，通过SidebarProvider将侧边栏集成到页面布局中。

assets/logo/logo.tsx：在侧边栏头部渲染的标志组件。

components/shadcn-space/blockssidebar-06/app-sidebar.tsx：主侧边栏框架，包含标题、滚动区域、导航内容和宣传卡片等元素。

components/shadcn-space/blocks/sidebar-06/nav-main.tsx：所有导航相关的渲染逻辑，包括章节标签、子菜单项、可折叠的父级菜单以及活动状态的管理。

在接下来的内容中，您会详细了解这些文件的功能与作用。

如何构建页面布局

打开appsidebar-06/page.tsx文件。这个文件是您的仪表板页面的入口点。它使用SidebarProvider在整个页面中维护侧边栏的状态，并通过SidebarTrigger在页面头部渲染一个切换按钮。

import { SidebarProvider, SidebarTrigger } from 「@components/ui sidebar」; import { AppSidebar } from 「@components/shadcn-space/blockssidebar-06/app-sidebar」; const Page = () => { return ( {/* 主内容区域 */} ); }; export default Page;

让我们来分析一下这个布局的关键组成部分：

SidebarProvider包裹了页面上的所有内容。它负责管理侧边栏的打开/关闭状态，并通过React上下文将这些状态传递给子组件。任何需要读取或修改侧边栏状态的组件，包括SidebarTrigger和AppSidebar，都必须是SidebarProvider的子孙组件。

`–sidebar-width` 这个CSS自定义属性用于控制侧边栏的显示宽度。由于TypeScript默认不识别这个自定义属性，因此需要通过类型断言（`as React.CSSProperties`）来明确指定它的用途。将这个属性设置在这里而不是在CSS文件中，可以使得每页的侧边栏宽度都能被单独配置。

SidebarTrigger是一个切换按钮组件，它会从最近的SidebarProvider上下文中获取侧边栏的打开/关闭状态，并在用户点击时切换这些状态。这个组件会被放置在页面头部，因此无论用户当前处于什么滚动位置，都可以随时使用这个切换按钮。

`bg-muted`属性应用于SidebarProvider时，会为侧边栏创建一层浅灰色的背景色，这样浮动式的侧边栏内容就能在视觉上从页面中突出出来。
如何构建应用侧边栏组件打开文件components/shadcn-space/blockssidebar-06/app-sidebar.tsx。这个组件是侧边栏的核心结构，它结合了shadcn/ui提供的Sidebar、SidebarHeader和SidebarContent等布局元素，并使用ScrollArea组件来包裹可滚动的导航区域，从而实现溢出内容的独立处理。 "use client"; import { Sidebar, SidebarContent, SidebarHeader, SidebarMenu, SidebarMenuItem, } from 「@components/ui sidebar」; import { ScrollArea } from 「@components/ui/scroll-area」; import { Card, CardContent } from 「@components/ui/card」; import { Button } from 「@components/ui/button」; import Logo from 「@assets/logo/logo」; import { NavItem, NavMain } from 「@components/shadcn-space/blockssidebar-06/nav-main」; import { AlignStartVertical, PieChart, CircleUserRound, ClipboardList, Notebook, NotepadText, Table, Languages, Ticket, } from "lucide-react"; 在文件顶部添加"use client"指令是必要的，因为这个组件需要使用React的状态（通过NavMain实现）以及事件处理程序，而这些功能都需要在浏览器环境中运行，而不能由Next.js在服务器端进行渲染。如何定义导航数据在app-sidebar.tsx文件中，导航结构被定义为一个包含NavItem对象的扁平数组。这些导航项可以分为三类：
章节标题项会使用isSection: true属性以及label字符串进行标记，渲染时会显示为大写的章节标题。普通导航链接项包含title、icon和href属性，但没有子元素，因此会直接作为导航链接显示。
父级导航项包含title、icon以及一个子元素数组children，点击后会展开这些子元素，从而显示更多的导航选项。

export const navData: NavItem[] = [ // 控制面板部分 { label: "控制面板", isSection: true }, { title: "分析报告", icon: PieChart, href: "#" }, { title: "CRM控制面板", icon: ClipboardList, href: "#" }, // 页面部分 { label: "页面", isSection: true }, { title: "表格", icon: Table, href: "#" }, { title: "表单", icon: ClipboardList, href: "#" }, { title: "用户资料", icon: CircleUserRound, href: "#" }, // 应用程序部分 { label: "应用程序", isSection: true }, { title: "笔记", icon: Notebook, href: "#" }, { title: "工单", icon: Ticket, href: "#" }, { title: "博客", icon: Languages, children: [ { title: "博客文章", href: "#" }, { title: "博客详情", href: "#" }, { title: "编辑博客", href: "#" }, { title: "创建博客", href: "#" }, { title: "管理博客", href: "#" }, ], }, // 表单元素部分 { label: "表单元素", isSection: true }, { title: "Shadcn表单", icon: NotepadText, children: [ { title: "按钮", href: "#" }, { title: "输入框", href: "#" }, { title: "下拉菜单", href: "#" }, { title: "复选框", href: "#" }, { title: "单选按钮", href: "#" }, ], }, { title: "表单布局", icon: AlignStartVertical, children: [ { title: "水平布局表单", href: "#" }, { title: "垂直布局表单", href: "#" }, { title: "表单验证", href: "#" }, { title: "表单示例", href: "#" }, { title: "表单向导", href: "#" }, ], }, ];

这种扁平数组结构的设计初衷就是便于维护。由于NavMain组件会根据每个元素的类型来处理相应的渲染逻辑，因此我们不需要使用嵌套的树形结构。添加新的部分、元素或子菜单，只需要在数组中添加一个新的对象即可。

如何构建NavMain组件

打开components/shadcn-space/blocks sidebar-06/nav-main.tsx文件。这个文件包含了所有的导航渲染逻辑。首先来看类型定义以及顶层的NavMain函数：

"use client"; import * as React from "react"; import { ChevronRight, LucideIcon } from "lucide-react"; import { cn } from "@/lib/utils"; import { Collapsible, CollapsibleTrigger, CollapsibleContent, } from"wcomponents/ui/collapsible"; import { SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubItem, SidebarMenuSubButton, } from"wcomponents/uisidebar"; export type NavItem = { label?: string; isSection?: boolean; title?: string; icon?: LucideIcon; href?: string; children?: NavItem[]; }; export function NavMain({ items }: { items: NavItem[] }) { const [activeParent, setActiveParent] = React.useState〈string | null〉( items.find((i) => !i.isSection?.title || null ); const [activeChild, setActiveChild] = React.useState〈string | null〉(null); return ( {items.map((item, index) => ( ))} ); }

activeParent用于追踪当前被选中的顶级导航项。它的初始值是列表中第一个非分组项的标题，因此侧边栏在首次渲染时总会显示某个被选中的选项，从而避免出现侧边栏完全空白的情况。activeChild则用于追踪可折叠菜单中当前被选中的子项。

这两个状态值都会作为属性传递给每一个NavMainItem》组件，因此列表中的每个元素都能获取到当前的选中状态，并据此进行相应的更新。
如何处理活跃状态与可折叠菜单 NavMainItem会根据传入元素的类型，选择三种不同的渲染路径之一来进行渲染。如何渲染章节标题 if (item.isSection && item.label) { return ( {item.label} ); } 章节标题使用了first:pt-0这个样式，从而去除了第一个章节的顶部边距，使得导航栏与页眉处于同一水平线上。如何渲染可折叠的父级元素 if (hasChildren && item.title) { return ( setActiveParent(item.title)} className={cn( "rounded-md text-sm font-medium px-3 py-2 h-9 transition-colors cursor-pointer", isParentActive ? "bg-primary! text-primary-foreground!" : "" )} > {item'icon && } {item.title} } /gt> {item.children!.map((child, index) => ( ))} ); } NavMainItem组件中的useEffect函数会将本地的isOpen状态与activeParent属性进行同步。这样一来，当父元素的状态发生变化时，之前处于打开状态的子元素会保持开启状态，直到用户明确将其关闭。 React.useEffect(() => { if (isParentActive) { setIsOpen(true); } }, [isParentActive]); 当子菜单被打开时，ChevronRight图标会旋转90度，这一效果是通过Tailwind CSS的过渡类实现的。 <ChevronRight className={cn( "ml-auto transition-transform duration-200", isOpen && "rotate-90" )} /> 如何渲染叶子节点 if (item.title) { return ( <SidebarGroup className="p-0"> <SidebarMenu> <SidebarMenuItem> {item'icon && <item.icon />} {item.title} ); } SidebarMenuButton组件中的render属性会将默认的按钮元素替换为标签。这样既能保持链接的正确语义和可访问性，又能保留按钮的视觉样式。当用户点击叶子节点时，activeChild属性会被重置为null，因为此时已经没有需要跟踪的子元素了。如何渲染子菜单中的子项 NavMainSubItem组件负责处理可折叠结构中的子项。当用户点击某个子项时，该组件的activeChild属性会被设置为当前子项的标题，同时activeParent属性也会被设置为其父元素的标题，这样父元素就会在视觉上保持高亮显示状态。 if (item.title) { return ( {item.title} ); } 子元素采用了与父元素不同的活跃样式：子元素使用的是bg-muted搭配text-foreground，而父元素则使用bg-primary搭配text-primary-foreground。这种视觉上的差异使得人们能够轻松分辨自己当前处于哪个部分，以及哪一个具体页面是处于活跃状态的。子项也支持嵌套结构。如果某个子项本身拥有children数组，那么NavMainSubItem就会渲染另一个Collapsible元素，并在其中嵌套SidebarMenuSub元素，这样就可以构建多级导航结构，而无需对数据结构进行任何修改。如何为侧边栏设置样式完整的AppSidebar渲染函数会将所有组件组合在一起： export function App Sidebar() { return ( <;/a> <>/SidebarMenuItem> <>/SidebarMenu> <>/SidebarHeader> {/* 可滚动的导航内容 */} /div> {/* 促销卡片 */} /p> /p> <>/div> 让我们来了解一下这些关键的样式设置： variant="floating" 这一设置使得侧边栏呈现出卡片状的外观，角部为圆角，并带有淡淡的阴影效果。这样的设计使侧边栏在视觉上与背景区分开来，而不会像普通的侧边栏那样与页面边缘齐平。 [&_[data-slot=sidebar-inner]]:h-full 是一个自定义的 Tailwind 变体选择器，用于定位 shadcn/ui 中内部的侧边栏元素。如果没有这个设置，侧边栏的内部容器就无法占据整个可用的高度，从而导致布局紊乱。data-slot 属性正是 shadcn/ui 用来识别复合组件中内部子元素的。 h-[calc(100vh-100px)] 这一代码应用于 ScrollArea 元素上，使得导航列表可以独立滚动。其中减去的 100px 是为了容纳侧边栏的标题和内边距，这样滚动区域就不会超出可视窗口的范围。当导航列表在滚动时，页面的其他部分布局仍然保持不变。位于滚动区域底部的 bg-secondary 颜色的卡片元素，是管理员控制面板中常见的设计模式——它以一种不会妨碍导航的方式，被动地提示用户进行升级或完成新功能的学习流程。有关侧边栏组件的 API、变量设置以及配置选项的更多详细信息，请参阅 shadcn/ui 官方文档中的侧边栏相关章节。实时预览总结恭喜！您已经成功使用 shadcn/ui 以及 Shadcn Space 提供的社区组件，构建出了一个功能完备、可直接用于生产环境的管理员控制面板侧边栏。以下是您所学习内容的总结：设置了 Next.js 项目，并使用了 shadcn/ui 进行初始化；同时从 Shadcn Space 安装了预构建好的侧边栏组件。通过 React 上下文，使用 SidebarProvider 和 SidebarTrigger 来控制整个页面布局中侧边栏的开启/关闭状态。将导航数据定义为包含 NavItem 对象的扁平数组，这些对象用于表示不同的导航章节、子项以及可折叠的父项。从同一个 navData 数据源中，分别在 NavMain 和 NavMainItem 组件中渲染这三种类型的导航元素。将 activeParent 和 activeChild 状态存储在同一个地方，并通过属性传递给相关组件，这样所有导航项都能读取并更新这个共享的选择状态。使用 Collapsible 组件，并结合 useEffect 动效，在父项处于激活状态时保持其展开状态；同时实现展开/折叠时的箭头图标动画效果。应用了 floating 变体、自定义的 Tailwind 插槽选择器，以及计算得出高度的 ScrollArea，最终得到了一个美观且适合生产环境使用的侧边栏布局。这种模式的可扩展性远远超出了你目前所构建的内容。你可以为`NavItem`添加额外的字段，比如徽章数量、权限标志或外部链接指示器。你也可以使用真实的`href`值，并将`activeParent`与`activeChild`与你的路由系统连接起来，这样选择的内容就能始终反映当前的URL。此外，你还可以在`navData`中添加更多的内容，而无需修改任何渲染逻辑。为了让你能快速了解这个示例的实现方式，我们在这个仪表盘框架中使用了Shadcn Space提供的免费仪表盘组件。如果你想了解更多基于shadcn/ui开发的预构建管理界面组件和模板，你可以访问Shadcn Space来浏览完整的资源库。资源 Shadcn UI组件 Shadcn UI组件 Shadcn Space入门指南 Figma UI设计系统 shadcn/ui侧边栏组件文档 Base UI

如何使用 shadcn/ui 与 Base-UI 构建管理员仪表盘的侧边栏

如何为侧边栏设置样式

实时预览

总结

相关文章

如何构建属于自己的、针对特定语言的大语言模型——[完整手册]

使用 MedGemma、Ollama 以及 OpenWebUI 自主构建属于自己的医疗人工智能助手

如何在一个单一代码库中构建可扩展的设计系统

如何使用 React、AWS Lambda、DynamoDB 以及 Cognito Auth 来构建一个功能完备的 CRUD 应用程序