Refine shadcn/ui 集成实战Layout 01 后台布局组件的安装、用法与源码解析【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine本文围绕 Refine 文档站中 shadcn/ui 集成的 Layout 01 布局组件展开介绍如何用一条 shadcn registry 命令把「侧边栏 顶部导航 主内容区」的完整后台骨架装入项目并结合packages/refine-ui下的 registry 源码逐层解析 Layout 01 的组件结构、导航生成机制与主题系统帮助你在 Refine 应用中快速落地专业级管理后台界面。一、Layout 01 是什么Refine shadcn/ui 的后台布局骨架Layout 01 是 Refine 官方 shadcn/ui 组件集refine-uiregistry中的一个「block」级组件提供一套开箱即用的管理后台布局可折叠侧边栏collapsible sidebar从 Refine 的resources配置自动生成导航菜单支持图标折叠为 icon-only 模式、分组group、多级子菜单折叠面板 / 收起态下的下拉菜单顶部 Header包含主题切换light / dark / system与用户控制头像、退出登录下拉菜单并针对桌面端与移动端提供两套实现主内容区一个居中的container页面路由内容通过Outlet渲染其中。在典型的 Refine 应用中Layout 通常是第一个引入的 UI 组件——它奠定了用户熟悉的后台体验品牌 Logo 与导航在侧边栏内容居中配合面包屑breadcrumb见第七节帮助用户理解当前位置。其源码位于仓库的 registry 目录对应 shadcn registry 中的layout-01条目可在 registry.json 中查到完整定义组件实现文件包括 layout.tsx、sidebar.tsx、header.tsx。二、安装通过 shadcn CLI 拉取 registry blockLayout 01 不是 npm 包而是通过 shadcn CLI 从 Refine 自建的组件 registry 拉取到当前项目的源码文件。官方文档给出的安装命令为npx shadcnlatest add https://ui.refine.dev/r/layout-01.json该命令会自动安装布局所需的一切包括布局组件本身、主题系统以及 sidebar、avatar、button、dropdown-menu 等 shadcn/ui 依赖组件。对照仓库中 registry.json 里layout-01条目的声明可以确认「自动安装」的具体范围npm 依赖dependenciesrefinedev/core提供useMenu、useLink、useLogout等 hooks与lucide-react图标registry 依赖registryDependenciessidebar、avatar、button、separator、dropdown-menu、collapsible六个 shadcn/ui 基础组件外加 registry 内的theme-provider即主题系统对应 theme-provider.tsx落地文件files数组共 5 个及在目标项目中的写入位置targetregistry 源文件写入目标项目的路径作用layout.tsxsrc/components/refine-ui/layout/layout.tsx布局根组件header.tsxsrc/components/refine-ui/layout/header.tsx顶部导航sidebar.tsxsrc/components/refine-ui/layout/sidebar.tsx侧边栏user-avatar.tsxsrc/components/refine-ui/layout/user-avatar.tsx用户头像user-info.tsxsrc/components/refine-ui/layout/user-info.tsx用户信息展示也就是说npx shadcn add完成后你的项目里多了上述 5 个 refine-ui 组件文件和 6 个 shadcn/ui 基础组件文件外加依赖包安装——这就是文档中「自动安装所有必要内容」的仓库级依据。三、基本用法用 Layout 包裹应用路由文档给出的接入方式很简洁用Layout组件包裹应用路由它会自动读取 Refine 的resources生成导航并托管侧边栏、Header 与内容区。完整示例import { Refine } from refinedev/core; import { BrowserRouter, Routes, Route, Outlet } from react-router; // highlight-next-line import { Layout } from /components/refine-ui/layout/layout; function App() { return ( BrowserRouter Refine resources{[ { name: posts, list: /posts, create: /posts/create, edit: /posts/:id/edit, show: /posts/:id, }, ]} Routes {/* highlight-start */} Route element{ Layout Outlet / /Layout } {/* highlight-end */} Route path/posts element{PostList /} / Route path/posts/create element{PostCreate /} / Route path/posts/:id element{PostShow /} / Route path/posts/:id/edit element{PostEdit /} / /Route /Routes /Refine /BrowserRouter ); }关键要点resources是唯一需要维护的「导航配置」。Refine组件上的resources数组声明了每个资源的name与list/create/edit/show四个页面路径Layout 01 的侧边栏并不重复定义菜单而是通过 Refine 的useMenu()hook 把这些资源转换成树形菜单项TreeMenuItem因此新增资源时侧边栏会自动出现对应入口LayoutOutlet //Layout写法将 Layout 放在父级Route的element上子路由通过Outlet注入其main区域页面切换时侧边栏与 Header 保持挂载不重渲染接入后即获得全部交互能力折叠侧边栏、light/dark 主题切换、导航时的面包屑反馈——无需额外配置。四、布局根组件三层 Provider 套娃结构从 layout.tsx 的源码看Layout本体非常薄本质是一个三层 Provider 容器export function Layout({ children }: PropsWithChildren) { return ( ThemeProvider SidebarProvider Sidebar / SidebarInset Header / main className{cn(container/main, container, mx-auto, ...)} {children} /main /SidebarInset /SidebarProvider /ThemeProvider ); }结构拆解ThemeProvider最外层为整个布局提供 dark/light/system 主题能力实现在 theme-provider.tsx默认值defaultTheme system用户选择持久化在localStorage的refine-ui-theme键下并在html元素上切换light/darkclasssystem模式下通过window.matchMedia((prefers-color-scheme: dark))跟随系统。这就是文档所说「主题系统」随布局一起安装的原因SidebarProviderSidebarInset来自 shadcn/ui 的 sidebar 组件负责侧边栏的打开/收起状态管理useSidebar()与响应式布局SidebarInset是侧边栏右侧的「内缩」区域Header 与主内容都渲染在其中main内容区使用container/mainTailwind 容器查询、container、mx-auto、flex-1等类名实现居中容器与自适应高度children即路由Outlet落在其中。五、侧边栏从 resources 到导航菜单的生成机制sidebar.tsx 是 Layout 01 的核心它体现了「导航由 Refine 元数据驱动」的设计。源码要点1. 菜单数据来自useMenu()export function Sidebar() { const { open } useShadcnSidebar(); const { menuItems, selectedKey } useMenu(); ... }useMenu()由refinedev/core提供返回当前resources及路由/权限过滤后的树形菜单项menuItems和当前选中项的selectedKey。menuItems的每一项是TreeMenuItem带有name、label、route、icon、meta、children等字段。2. 一个递归分发器处理四类节点SidebarItem按节点类型分发渲染item.meta?.group为真 →SidebarItemGroup渲染为分组标题大写小字 顶部分隔线子项继续递归有children且侧边栏展开→SidebarItemCollapsible使用 shadcnCollapsible渲染可折叠子菜单箭头图标在展开时旋转 90 度有children且侧边栏收起icon 模式→SidebarItemDropdown点击父项弹出DropdownMenusideright子项以链接形式列出——这解决了「收起态下无法展开折叠面板」的经典交互问题叶子节点 →SidebarItemLink渲染为SidebarButton通过useLink()Refine 注入的 router Link 组件跳转item.route。3. 选中态与显示名selectedKey item.key的项会获得bg-sidebar-primary高亮与font-semibold显示名取item.meta?.label ?? item.label ?? item.name的优先级链图标取item.meta?.icon ?? item.icon缺省回退到ListIcon。4. 侧边栏头部品牌与折叠触发器SidebarHeader从useRefineOptions()读取title即Refine组件上的options{{ title: { icon, text } }}渲染品牌区并内嵌SidebarTrigger折叠按钮收起态下隐藏移动端保持可见。整个侧边栏声明为collapsibleicon即支持折叠为纯图标模式。六、Header桌面/移动双形态与用户控制header.tsx 通过useSidebar()的isMobile在两套实现间切换export const Header () { const { isMobile } useSidebar(); return {isMobile ? MobileHeader / : DesktopHeader /}/; };DesktopHeadersticky top-0、高 164rem、bg-sidebar右对齐放置ThemeToggle与UserDropdownMobileHeader高 123rem左侧为侧边栏触发按钮rotate-180使其方向适配移动抽屉 品牌标题右侧为h-8 w-8的ThemeToggleUserDropdown这里有一个防御性细节——先取useActiveAuthProvider()若当前 authProvider 没有实现getIdentity则整个下拉不渲染return null否则展示UserAvatar菜单项调用useLogout().mutate退出登录并在isPending时显示 Logging out...。用户头像组件 user-avatar.tsx 通过useGetIdentityUser()拉取当前用户加载中渲染圆形Skeleton占位有avatar字段时显示图片否则回退到首字母缩写getInitials取姓名首、末词首字母大写拼接。ThemeToggle随 registry 一并安装的 theme-toggle.tsx则读取第四节提到的ThemeProvidercontext完成 dark / light / system 的循环切换并写入localStorage。七、面包屑随布局生态交付的独立 registry 项文档提到用户在导航中能看到面包屑。从仓库结构看面包屑并不内嵌在 Header 中而是作为独立 registry 条目breadcrumb交付breadcrumb.tsxregistry 目标路径为src/components/refine-ui/layout/breadcrumb.tsx依赖refinedev/core与 shadcnbreadcrumb基础组件见 registry.json 的breadcrumb条目描述为「基于当前路由和资源结构自动生成面包屑」。它与 views 类组件list/create/edit/show viewregistryDependencies中显式引用breadcrumb.json配合在页面级头部展示层级路径layout-01的registryDependencies虽未直接包含它但同属 refine-ui 的导航生态可按需另行npx shadcn add拉取。八、相关文件与延伸阅读本文对应的文档源文件index.mdregistry 总清单含各组件的依赖与文件目标路径registry.jsonLayout 01 源码三件套layout.tsx / sidebar.tsx / header.tsx主题系统theme-provider.tsx、theme-toggle.tsx面包屑组件breadcrumb.tsxrefine-ui registry 运行说明基于 Next.js Tailwind v4 的 registry-templateshadcn build构建、条目以静态 JSON 分发README.md小结Layout 01 的价值在于把「Refine 元数据 → 导航 UI」这条链路固化成了可复制的 shadcn 源码——npx shadcn add一条命令拿到 5 个 refine-ui 组件与 6 个基础组件LayoutOutlet //Layout两行代码完成接入而侧边栏由useMenu()驱动、Header 适配桌面/移动双形态、主题选择经localStorage持久化到htmlclass这些机制都可以直接在仓库 registry 源码中对照验证与二次定制。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考