

一个可折叠为图标的侧边栏。
侧边栏是最复杂的组件之一。它们是任何应用的核心,通常包含许多动态部分。
我们现在拥有了坚实的基础可以在此之上构建。可组合。可主题化。 可自定义。
安装
pnpm dlx shadcn@latest add sidebar
结构
Sidebar 组件由以下部分组成:
SidebarProvider- 处理折叠状态。Sidebar- 侧边栏容器。SidebarHeader和SidebarFooter- 分别位于侧边栏的顶部和底部,且为粘性定位。SidebarContent- 可滚动的内容区域。SidebarGroup-SidebarContent中的分组区域。SidebarTrigger- 用于触发侧边栏的开关。
使用方法
import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar"
import { AppSidebar } from "@/components/app-sidebar"
export default function Layout({ children }: { children: React.ReactNode }) {
return (
<SidebarProvider>
<AppSidebar />
<main>
<SidebarTrigger />
{children}
</main>
</SidebarProvider>
)
}import {
Sidebar,
SidebarContent,
SidebarFooter,
SidebarGroup,
SidebarHeader,
} from "@/components/ui/sidebar"
export function AppSidebar() {
return (
<Sidebar>
<SidebarHeader />
<SidebarContent>
<SidebarGroup />
<SidebarGroup />
</SidebarContent>
<SidebarFooter />
</Sidebar>
)
}SidebarProvider
SidebarProvider 组件用于为 Sidebar 组件提供侧边栏上下文。你应该始终用 SidebarProvider 组件包裹你的应用。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
defaultOpen | boolean | 侧边栏的默认打开状态。 |
open | boolean | 侧边栏的打开状态(受控)。 |
onOpenChange | (open: boolean) => void | 设置侧边栏的打开状态(受控)。 |
宽度
如果你的应用中只有一个侧边栏,可以在 sidebar.tsx 中使用 SIDEBAR_WIDTH 和 SIDEBAR_WIDTH_MOBILE 变量来设置侧边栏的宽度。
const SIDEBAR_WIDTH = "16rem"
const SIDEBAR_WIDTH_MOBILE = "18rem"如果应用中有多个侧边栏,可以在 style 属性中使用 CSS 变量 --sidebar-width 和 --sidebar-width-mobile。
<SidebarProvider
style={
{
"--sidebar-width": "20rem",
"--sidebar-width-mobile": "20rem",
} as React.CSSProperties
}
>
<Sidebar />
</SidebarProvider>键盘快捷键
触发侧边栏使用 Mac 上的 cmd+b,Windows 上的 ctrl+b 快捷键。
const SIDEBAR_KEYBOARD_SHORTCUT = "b"Sidebar
主要的 Sidebar 组件用于渲染可折叠的侧边栏。
参数
| 属性 | 类型 | 描述 |
|---|---|---|
side | left 或 right | 侧边栏所在的边。 |
variant | sidebar、floating 或 inset | 侧边栏的变体类型。 |
collapsible | offcanvas、icon 或 none | 侧边栏的折叠状态。 |
| 属性 | 描述 |
|---|---|
offcanvas | 可折叠的侧边栏,会从左侧或右侧滑入。 |
icon | 折叠为图标的侧边栏。 |
none | 不可折叠的侧边栏。 |
注意: 如果你使用 inset 变体,记得将你的主内容包裹在 SidebarInset 组件中。
<SidebarProvider>
<Sidebar variant="inset" />
<SidebarInset>
<main>{children}</main>
</SidebarInset>
</SidebarProvider>useSidebar
useSidebar 钩子用于控制侧边栏。
import { useSidebar } from "@/components/ui/sidebar"
export function AppSidebar() {
const {
state,
open,
setOpen,
openMobile,
setOpenMobile,
isMobile,
toggleSidebar,
} = useSidebar()
}| 属性 | 类型 | 描述 |
|---|---|---|
state | expanded 或 collapsed | 侧边栏当前状态。 |
open | boolean | 侧边栏是否打开。 |
setOpen | (open: boolean) => void | 设置侧边栏的打开状态。 |
openMobile | boolean | 移动端侧边栏是否打开。 |
setOpenMobile | (open: boolean) => void | 设置移动端侧边栏的打开状态。 |
isMobile | boolean | 是否为移动端侧边栏。 |
toggleSidebar | () => void | 切换侧边栏。支持桌面端和移动端。 |
SidebarHeader
使用 SidebarHeader 组件为侧边栏添加一个粘性头部。
<Sidebar>
<SidebarHeader>
<SidebarMenu>
<SidebarMenuItem>
<DropdownMenu>
<DropdownMenuTrigger asChild>
<SidebarMenuButton>
选择工作区
<ChevronDown className="ml-auto" />
</SidebarMenuButton>
</DropdownMenuTrigger>
<DropdownMenuContent className="w-[--radix-popper-anchor-width]">
<DropdownMenuItem>
<span>Acme Inc</span>
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
</SidebarMenuItem>
</SidebarMenu>
</SidebarHeader>
</Sidebar>SidebarFooter
使用 SidebarFooter 组件为侧边栏添加一个粘性底部。
<Sidebar>
<SidebarFooter>
<SidebarMenu>
<SidebarMenuItem>
<SidebarMenuButton>
<User2 /> 用户名
</SidebarMenuButton>
</SidebarMenuItem>
</SidebarMenu>
</SidebarFooter>
</Sidebar>SidebarContent
SidebarContent 组件用于包裹侧边栏的内容。这里可以添加你的 SidebarGroup 组件。内容区域是可滚动的。
<Sidebar>
<SidebarContent>
<SidebarGroup />
<SidebarGroup />
</SidebarContent>
</Sidebar>SidebarGroup
使用 SidebarGroup 组件创建侧边栏内的分组区块。
SidebarGroup 包含一个 SidebarGroupLabel,一个 SidebarGroupContent,以及一个可选的 SidebarGroupAction。
<SidebarGroup>
<SidebarGroupLabel>应用</SidebarGroupLabel>
<SidebarGroupAction>
<Plus /> <span className="sr-only">添加项目</span>
</SidebarGroupAction>
<SidebarGroupContent></SidebarGroupContent>
</SidebarGroup>如果你想让 SidebarGroup 可折叠,可以用 Collapsible 组件包裹它。
<Collapsible defaultOpen className="group/collapsible">
<SidebarGroup>
<SidebarGroupLabel asChild>
<CollapsibleTrigger>
帮助
<ChevronDown className="ml-auto transition-transform group-data-[state=open]/collapsible:rotate-180" />
</CollapsibleTrigger>
</SidebarGroupLabel>
<CollapsibleContent>
<SidebarGroupContent />
</CollapsibleContent>
</SidebarGroup>
</Collapsible>SidebarMenu
SidebarMenu 组件用于在 SidebarGroup 内构建菜单。
<SidebarMenu>
{projects.map((project) => (
<SidebarMenuItem key={project.name}>
<SidebarMenuButton asChild>
<a href={project.url}>
<project.icon />
<span>{project.name}</span>
</a>
</SidebarMenuButton>
</SidebarMenuItem>
))}
</SidebarMenu>SidebarMenuButton
SidebarMenuButton 组件用于渲染 SidebarMenuItem 内的菜单按钮。
默认情况下,SidebarMenuButton 渲染为按钮,但你可以通过 asChild 属性来渲染为其他组件,比如 Link 或 a 标签。
使用 isActive 属性标记菜单项为激活状态。
<SidebarMenuButton asChild isActive>
<a href="#">首页</a>
</SidebarMenuButton>SidebarMenuAction
SidebarMenuAction 组件用于在 SidebarMenuItem 中渲染操作按钮。
<SidebarMenuItem>
<SidebarMenuButton asChild>
<a href="#">
<Home />
<span>首页</span>
</a>
</SidebarMenuButton>
<SidebarMenuAction>
<Plus /> <span className="sr-only">添加项目</span>
</SidebarMenuAction>
</SidebarMenuItem>SidebarMenuSub
SidebarMenuSub 组件用于在 SidebarMenu 内渲染子菜单。
<SidebarMenuItem>
<SidebarMenuButton />
<SidebarMenuSub>
<SidebarMenuSubItem>
<SidebarMenuSubButton />
</SidebarMenuSubItem>
</SidebarMenuSub>
</SidebarMenuItem>SidebarMenuBadge
SidebarMenuBadge 组件用于在 SidebarMenuItem 里渲染徽章。
<SidebarMenuItem>
<SidebarMenuButton />
<SidebarMenuBadge>24</SidebarMenuBadge>
</SidebarMenuItem>SidebarMenuSkeleton
SidebarMenuSkeleton 组件用于渲染 SidebarMenu 的骨架屏。
<SidebarMenu>
{Array.from({ length: 5 }).map((_, index) => (
<SidebarMenuItem key={index}>
<SidebarMenuSkeleton />
</SidebarMenuItem>
))}
</SidebarMenu>SidebarTrigger
使用 SidebarTrigger 组件渲染一个切换侧边栏的按钮。
import { useSidebar } from "@/components/ui/sidebar"
export function CustomTrigger() {
const { toggleSidebar } = useSidebar()
return <button onClick={toggleSidebar}>切换侧边栏</button>
}SidebarRail
SidebarRail 组件用于在 Sidebar 内渲染侧边栏轨道。这个轨道可用来切换侧边栏。
<Sidebar>
<SidebarHeader />
<SidebarContent>
<SidebarGroup />
</SidebarContent>
<SidebarFooter />
<SidebarRail />
</Sidebar>受控侧边栏
使用 open 和 onOpenChange 属性来控制侧边栏。
export function AppSidebar() {
const [open, setOpen] = React.useState(false)
return (
<SidebarProvider open={open} onOpenChange={setOpen}>
<Sidebar />
</SidebarProvider>
)
}主题化
我们使用以下 CSS 变量来给侧边栏设置主题。
@layer base {
:root {
--sidebar-background: 0 0% 98%;
--sidebar-foreground: 240 5.3% 26.1%;
--sidebar-primary: 240 5.9% 10%;
--sidebar-primary-foreground: 0 0% 98%;
--sidebar-accent: 240 4.8% 95.9%;
--sidebar-accent-foreground: 240 5.9% 10%;
--sidebar-border: 220 13% 91%;
--sidebar-ring: 217.2 91.2% 59.8%;
}
.dark {
--sidebar-background: 240 5.9% 10%;
--sidebar-foreground: 240 4.8% 95.9%;
--sidebar-primary: 0 0% 98%;
--sidebar-primary-foreground: 240 5.9% 10%;
--sidebar-accent: 240 3.7% 15.9%;
--sidebar-accent-foreground: 240 4.8% 95.9%;
--sidebar-border: 240 3.7% 15.9%;
--sidebar-ring: 217.2 91.2% 59.8%;
}
}样式技巧
这里提供一些基于不同状态给侧边栏设置样式的建议。
<Sidebar collapsible="icon">
<SidebarContent>
<SidebarGroup className="group-data-[collapsible=icon]:hidden" />
</SidebarContent>
</Sidebar><SidebarMenuItem>
<SidebarMenuButton />
<SidebarMenuAction className="peer-data-[active=true]/menu-button:opacity-100" />
</SidebarMenuItem>RTL(从右到左)
要在 shadcn/ui 中启用 RTL 支持,请参阅RTL 配置指南。
查看 RTL 侧边栏更新日志
RTL 支持
如果你是从之前版本升级 Sidebar 组件,需要应用以下更新以添加 RTL 支持:
在 Sidebar 组件中添加 dir 属性。
在解构的属性中添加 dir,并传递给移动端的 SheetContent:
function Sidebar({
side = "left",
variant = "sidebar",
collapsible = "offcanvas",
className,
children,
+ dir,
...props
}: React.ComponentProps<"div"> & {
side?: "left" | "right"
variant?: "sidebar" | "floating" | "inset"
collapsible?: "offcanvas" | "icon" | "none"
}) {然后在移动端视图中传递给 SheetContent:
<Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
<SheetContent
+ dir={dir}
data-sidebar="sidebar"
data-slot="sidebar"
data-mobile="true"向侧边栏容器添加 data-side 属性。
为侧边栏容器元素添加 data-side={side}:
<div
data-slot="sidebar-container"
+ data-side={side}
className={cn(更新侧边栏容器定位类名。
使用 CSS 数据属性选择器替代 JavaScript 三元条件类名:
className={cn(
- "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex",
- side === "left"
- ? "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]"
- : "right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
+ "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex data-[side=left]:left-0 data-[side=right]:right-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",更新 SidebarRail 定位类名。
将 SidebarRail 组件改为使用物理定位:
className={cn(
- "hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-end-4 group-data-[side=right]:start-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] sm:flex",
+ "hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 ltr:-translate-x-1/2 rtl:-translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] sm:flex",在 SidebarTrigger 图标中添加 RTL 翻转。
在 SidebarTrigger 中的图标添加 className="rtl:rotate-180" 以支持 RTL 模式下翻转:
<Button ...>
- <PanelLeftIcon />
+ <PanelLeftIcon className="rtl:rotate-180" />
<span className="sr-only">切换侧边栏</span>
</Button>完成上述改动后,你就可以使用 dir 属性来设置方向:
<Sidebar dir="rtl" side="right">
{/* ... */}
</Sidebar>侧边栏将能正确定位并在 LTR 和 RTL 布局中正常交互。