布局组件为应用程序提供结构组织和导航功能。它们专注于侧边栏、导航菜单和可滚动区域的可组合模式。
布局组件系统包含三个主要组件及其关联的子组件
组件结构映射到代码实体
来源
侧边栏系统提供了一个围绕上下文提供者模式构建的全面布局解决方案。它包含 24 个导出的组件和实用程序，用于创建响应式、可折叠的侧边栏。
来源
侧边栏系统定义了几个控制其行为的常量
| 常量 | 值 | 目的 |
|---|---|---|
SIDEBAR_COOKIE_NAME | "sidebar_state" | 用于持久化的 Cookie 名称 |
SIDEBAR_COOKIE_MAX_AGE | 60 * 60 * 24 * 7 | 一周过期 |
SIDEBAR_WIDTH | "16rem" | 默认桌面宽度 |
SIDEBAR_WIDTH_MOBILE | "18rem" | 移动端覆盖宽度 |
SIDEBAR_WIDTH_ICON | "3rem" | 折叠图标模式宽度 |
SIDEBAR_KEYBOARD_SHORTCUT | "b" | 键盘快捷键 |
| 组件 | 属性 | 类型 | 值 |
|---|---|---|---|
侧边栏 | side | "left" | "right" | 放置侧边 |
侧边栏 | variant | "sidebar" | "floating" | "inset" | 视觉变体 |
侧边栏 | collapsible | "offcanvas" | "icon" | "none" | 折叠行为 |
SidebarProvider | defaultOpen | 布尔值 | 初始状态 |
SidebarMenuButton | variant | "default" | "outline" | 按钮样式 |
SidebarMenuButton | size | "default" | "sm" | "lg" | 按钮大小 |
来源
SidebarProvider 通过 React 上下文模式管理侧边栏状态。它集成了移动端检测、键盘快捷键和基于 Cookie 的持久化
SidebarProvider 接受这些属性，扩展了 React.ComponentProps<"div">
defaultOpen?: boolean - 初始打开状态（默认值：true）open?: boolean - 受控打开状态onOpenChange?: (open: boolean) => void - 状态更改回调来源
主 Sidebar 组件通过条件逻辑处理响应式渲染和变体样式
该组件使用 cn() 实用程序，并根据属性进行条件类设置
variant === "floating" || variant === "inset" 控制内边距和宽度计算side === "left" 与 side === "right" 确定 left-0 与 right-0 类扩展了 React.ComponentProps<"div"> 并添加了额外属性
side?: "left" | "right"（默认值："left"）variant?: "sidebar" | "floating" | "inset"（默认值："sidebar"）collapsible?: "offcanvas" | "icon" | "none"（默认值："offcanvas"）来源
侧边栏系统包含几个用于布局和交互的结构化组件
| 组件 | 目的 | 主要功能 |
|---|---|---|
SidebarHeader | 固定顶部区域 | flex flex-col gap-2 p-2 |
SidebarContent | 可滚动主区域 | flex min-h-0 flex-1 flex-col gap-2 overflow-auto |
SidebarFooter | 固定底部区域 | flex flex-col gap-2 p-2 |
SidebarGroup | 内容区域 | relative flex w-full min-w-0 flex-col p-2 |
SidebarInset | 主内容包装器 | 处理 variant=inset 间距 |
| 组件 | 扩展 | 核心功能 |
|---|---|---|
SidebarTrigger | 按钮 | 调用 toggleSidebar()，使用 PanelLeft 图标 |
SidebarRail | button | 隐式切换轨道，光标调整大小指示器 |
SidebarSeparator | Separator | 带有侧边栏主题的水平分隔符 |
SidebarInput | 输入 | 带有侧边栏特定样式的输入字段 |
该系统提供了几个实用组件以增强功能
SidebarMenuSkeleton - 带有随机宽度的加载状态data-sidebar 属性进行样式挂钩group-data-[collapsible=icon] 类以实现响应式行为来源
侧边栏导航系统使用结构化的菜单组件层次结构
SidebarMenuButton 使用 cva() 进行变体管理
| 组件 | 主要属性 | 特殊功能 |
|---|---|---|
SidebarMenuButton | asChild, isActive, tooltip | 与 TooltipContent 集成 |
SidebarMenuAction | showOnHover | 绝对定位，悬停透明度 |
SidebarMenuBadge | 标准 div 属性 | 根据尺寸响应定位顶部值 |
SidebarMenuSub | 标准 ul 属性 | 边框左样式，图标折叠时隐藏 |
来源
侧边栏系统使用独立于主主题系统的专用 CSS 变量。这些变量在侧边栏安装指南中有详细说明
Tailwind 配置需要侧边栏颜色实用程序
来源
该系统支持复杂的布局，例如sidebar-09中的嵌套侧边栏
来源
NavigationMenu 组件包装了 @radix-ui/react-navigation-menu 并使用了 shadcn/ui 的样式。它提供了带视口管理和动画的下拉导航。
根组件接受一个 viewport 布尔属性来控制视口渲染
使用 cva() 为触发器样式进行全面的状态类设置
来源
| 组件 | 基本元素 | 主要属性 | 目的 |
|---|---|---|---|
NavigationMenu | NavigationMenuPrimitive.Root | viewport?: boolean | 带可选视口的根容器 |
NavigationMenuList | NavigationMenuPrimitive.List | 标准 div 属性 | 菜单项的 Flex 容器 |
NavigationMenuItem | NavigationMenuPrimitive.Item | 标准属性 | 单个菜单项包装器 |
| 组件 | 基本元素 | 主要功能 |
|---|---|---|
NavigationMenuTrigger | NavigationMenuPrimitive.Trigger | 包含 ChevronDownIcon，旋转动画 |
NavigationMenuContent | NavigationMenuPrimitive.Content | 复杂的动画类，视口感知样式 |
NavigationMenuLink | NavigationMenuPrimitive.Link | 活动状态样式，焦点管理 |
NavigationMenuViewport - 包装在定位 div 中，处理高度/宽度 CSS 变量NavigationMenuIndicator - 包含旋转边框元素以进行视觉指示所有组件都使用 data-slot 属性作为样式钩子
data-slot="navigation-menu"data-slot="navigation-menu-list"data-slot="navigation-menu-trigger"来源
该组件包含复杂的视口处理
使用广泛的 Tailwind 动画实用工具
data-[motion^=from-]:animate-in data-[motion^=to-]:animate-outdata-[motion^=from-]:fade-in data-[motion^=to-]:fade-outdata-[motion=from-end]:slide-in-from-right-52data-[state=open]:animate-in data-[state=closed]:animate-out实现全面的焦点样式
focus-visible:ring-ring/50focus-visible:ring-[3px] focus-visible:outline-1outline-none transition-[color,box-shadow]ChevronDownIcongroup-data-[state=open]:rotate-180relative top-[1px] ml-1 size-3来源
适用于没有下拉视口的简单布局
用于匹配触发器外观的自定义按钮样式
来源
ScrollArea 组件包装了 @radix-ui/react-scroll-area，用于提供自定义滚动条样式和焦点管理。
处理垂直和水平方向
来源
视口包含全面的焦点样式
focus-visible:ring-ring/50 - 环颜色带不透明度focus-visible:ring-[3px] focus-visible:outline-1 - 环尺寸和轮廓transition-[color,box-shadow] - 平滑焦点过渡| 方向 | 类 | 目的 |
|---|---|---|
vertical (垂直) | h-full w-2.5 border-l border-l-transparent | 全高，窄宽度，左边框 |
horizontal (水平) | h-2.5 flex-col border-t border-t-transparent | 窄高度，列 Flex，上边框 |
touch-none select-none 用于移动端交互bg-border relative flex-1 rounded-full 进行视觉样式设计ScrollAreaPrimitive.Corner 处理边角情况使用 data-slot 属性作为样式钩子
data-slot="scroll-area"data-slot="scroll-area-viewport"data-slot="scroll-area-scrollbar"data-slot="scroll-area-thumb"来源
需要显式 SCROLLBAR 并设置 orientation="horizontal"
该组件自动包含 ScrollAreaPrimitive.Corner 来处理两个滚动条的交叉点。
来源
布局组件旨在协同工作，以实现常见的应用程序模式。注册表中包含几个展示集成的块示例。
来自块注册表的站点标题和侧边栏模式
具有多个面板的复杂嵌套侧边栏
布局组件可与核心 shadcn/ui 组件集成
| 布局组件 | 集成对象 | 模式 |
|---|---|---|
SidebarProvider | TooltipProvider | 包装整个侧边栏系统 |
SidebarContent | ScrollArea | 可滚动内容区域 |
SidebarMenuButton | Button、Tooltip | 交互式菜单项 |
Sidebar (移动端) | Sheet、SheetContent | 移动响应式覆盖层 |
NavigationMenu | Radix primitives | 下拉导航 |
来源
布局组件在注册表中具有特定的依赖模式
复杂的块，例如 sidebar-09 结合了多个系统
| 模块 | 核心依赖项 | 附加依赖 |
|---|---|---|
sidebar-09 | sidebar、breadcrumb、separator | collapsible、dropdown-menu、avatar、switch、label |
sidebar-16 | sidebar、breadcrumb、separator | collapsible、dropdown-menu、avatar、button、label |
cn()、cva() 和 hooks 这样的通用工具来源
defaultOpen 并与 Cookie 集成以保存用户偏好useIsMobile() Hook 自动处理响应式行为open/onOpenChange 进行程序化控制data-sidebar、data-slot 和 data-state 进行 CSS 目标定位collapsible="none"variantSidebarMenu → SidebarMenuItem → SidebarMenuButton 的层级结构cn() 实用函数进行条件样式设置cva() 模式来定义组件变体group-data-[state]: 和类似的 CSS 选择器React.Suspense 配合 SidebarMenuSkeleton 进行动态内容加载React.useMemo 和 React.useCallback来源
升级或切换主题时，请考虑
来源