可折叠为图标的侧边栏。
侧边栏是最复杂的组件之一。它们是任何应用程序的核心，通常包含许多相互关联的部分。
现在，我们已经拥有了一个坚实的基础，可以在此之上继续构建。可组合。可主题化。 可自定义。
安装
用法
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>
)
}组合
使用以下组合来构建 Sidebar 布局：
SidebarProvider
├── Sidebar
│ ├── SidebarHeader
│ ├── SidebarContent
│ │ ├── SidebarGroup
│ │ │ ├── SidebarGroupLabel
│ │ │ ├── SidebarGroupAction
│ │ │ ├── SidebarGroupContent
│ │ │ └── SidebarMenu
│ │ │ ├── SidebarMenuItem
│ │ │ │ ├── SidebarMenuButton
│ │ │ │ ├── SidebarMenuAction
│ │ │ │ └── SidebarMenuBadge
│ │ │ └── SidebarMenuItem
│ │ │ ├── SidebarMenuButton
│ │ │ └── SidebarMenuSub
│ │ │ ├── SidebarMenuSubItem
│ │ │ └── SidebarMenuSubItem
│ │ └── SidebarGroup
│ │ └── SidebarMenu
│ │ ├── SidebarMenuItem
│ │ └── SidebarMenuItem
│ ├── SidebarFooter
│ └── SidebarRail
├── SidebarInset
└── SidebarTrigger结构
- SidebarProvider — 处理可折叠状态，并向子组件提供侧边栏上下文。
- Sidebar — 主要的可折叠侧边栏面板。
- SidebarHeader — 固定在顶部；用于品牌展示、标题或工作区切换器。
- SidebarFooter — 固定在底部；用于用户菜单、设置或操作。
- SidebarContent — 页眉和页脚之间的可滚动区域。
- SidebarGroup — 将相关导航分组，并可包含标签、操作和内容区域。
- SidebarMenu / SidebarMenuItem — 用于链接、徽章、操作和嵌套子菜单的菜单结构。
- SidebarRail — 在适用时用于调整侧边栏宽度的调整手柄。
- SidebarInset — 使用
inset变体时包裹主要内容。 - SidebarTrigger — 用于切换侧边栏展开或折叠状态的控件。
SidebarProvider
SidebarProvider 组件用于为 Sidebar 组件提供侧边栏上下文。你应始终将应用包裹在 SidebarProvider 组件中。
Props
宽度
如果应用中只有一个侧边栏，可以使用 sidebar.tsx 中的 SIDEBAR_WIDTH 和 SIDEBAR_WIDTH_MOBILE 变量来设置侧边栏的宽度。
const SIDEBAR_WIDTH = "16rem"
const SIDEBAR_WIDTH_MOBILE = "18rem"如果应用中有多个侧边栏，可以在 style 属性中使用 --sidebar-width 和 --sidebar-width-mobile CSS 变量。
<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 组件。
属性
注意： 如果使用 inset 变体，请记得将主要内容包裹在
SidebarInset 组件中。
<SidebarProvider>
<Sidebar variant="inset" />
<SidebarInset>
<main>{children}</main>
</SidebarInset>
</SidebarProvider>useSidebar
useSidebar hook 用于控制侧边栏。
import { useSidebar } from "@/components/ui/sidebar"
export function AppSidebar() {
const {
state,
open,
setOpen,
openMobile,
setOpenMobile,
isMobile,
toggleSidebar,
} = useSidebar()
}SidebarHeader
使用 SidebarHeader 组件为侧边栏添加粘性页眉。
<Sidebar>
<SidebarHeader>
<SidebarMenu>
<SidebarMenuItem>
<DropdownMenuTrigger>
<SidebarMenuButton>
选择工作区
<ChevronDown className="ml-auto" />
</SidebarMenuButton>
<DropdownMenu className="w-[--trigger-width]">
<DropdownMenuItem>
<span>Acme 公司</span>
</DropdownMenuItem>
</DropdownMenu>
</DropdownMenuTrigger>
</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 defaultExpanded className="group/collapsible">
<SidebarGroup>
<SidebarGroupLabel elementType={CollapsibleTrigger}>
帮助
<ChevronDown className="ml-auto transition-transform group-data-expanded/collapsible:rotate-180" />
</SidebarGroupLabel>
<CollapsibleContent>
<SidebarGroupContent />
</CollapsibleContent>
</SidebarGroup>
</Collapsible>SidebarMenu
SidebarMenu 组件用于在 SidebarGroup 中构建菜单。
<SidebarMenu>
{projects.map((project) => (
<SidebarMenuItem key={project.name}>
<SidebarMenuButton href={project.url}>
<project.icon />
<span>{project.name}</span>
</SidebarMenuButton>
</SidebarMenuItem>
))}
</SidebarMenu>SidebarMenuButton
SidebarMenuButton 组件用于在 SidebarMenuItem 中渲染菜单按钮。
默认情况下，SidebarMenuButton 会渲染一个按钮，但传入 href 属性后，它会改为渲染链接。
使用 isActive 属性将菜单项标记为活动状态。
<SidebarMenuButton href="#" isActive>
Home
</SidebarMenuButton>SidebarMenuAction
SidebarMenuAction 组件用于在 SidebarMenuItem 中渲染菜单操作。
<SidebarMenuItem>
<SidebarMenuButton href="#">
<Home />
<span>首页</span>
</SidebarMenuButton>
<SidebarMenuAction>
<Plus /> <span className="sr-only">添加项目</span>
</SidebarMenuAction>
</SidebarMenuItem>SidebarMenuSub
SidebarMenuSub 组件用于在 SidebarMenu 中渲染子菜单。
<SidebarMenuItem>
<SidebarMenuButton />
<SidebarMenuSub>
<SidebarMenuSubItem>
<SidebarMenuSubButton />
</SidebarMenuSubItem>
</SidebarMenuSub>
</SidebarMenuItem>侧边栏菜单徽章
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 添加到解构的 props 中，并将其传递给移动端的 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">Toggle Sidebar</span>
</Button>应用这些更改后，你可以使用 dir 属性来设置方向：
<Sidebar dir="rtl" side="right">
{/* ... */}
</Sidebar>侧边栏将在 LTR 和 RTL 布局中正确定位并处理交互。