Refine 与 Mantine 深度集成指南用 refinedev/mantine 快速构建内部工具与 Admin 面板【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine导读Refine 是一个用于构建内部工具、管理后台、Dashboard 与 B2B 应用的 React 框架。本文基于 Refine v5 官方文档中 Mantine UI 集成章节系统讲解refinedev/mantine集成包的安装、表格、表单、通知、预定义组件布局、按钮、视图、字段、认证页、主题以及 Inferencer 自动生成等核心能力。读完本文你将掌握如何在一小时内用 Refine Mantine v5 搭建一个具备 CRUD、认证、权限控制与主题切换能力的完整管理后台并理解集成包的底层实现原理。集成包概览补充而非替代Refine 为 Mantine 提供了一整套开箱即用的集成包refinedev/mantine。它提供了一系列将 Refine 能力与 Mantine 组件桥接的组件与 Hooks表格状态管理、表单校验与提交、认证流程、通知系统、路由导航、权限校验等全部以 Mantine 的视觉语言呈现。需要特别强调的一点是这个集成包不是 Mantine 的替代品。你可以像在普通 React 应用中一样使用 Mantine 的全部功能mantine/core、mantine/hooks、mantine/form等Refine 集成只是让这些组件与 Refine 的 data provider、auth provider、resources 等机制协同工作。从 packages/mantine/package.json 的依赖声明可以看到refinedev/mantine本身就以mantine/core、mantine/form、mantine/hooks、mantine/notifications、emotion/react、tabler/icons-react为依赖最终通过 packages/mantine/src/index.tsx 统一导出 components、providers、hooks、theme、definitions、contexts 六大部分export * from ./components/index.js; export * from ./providers/index.js; export * from ./hooks/index.js; export * from ./theme/index.js; export * from ./definitions/index.js; export * from ./contexts/index.js;安装零额外配置安装refinedev/mantine及其配套依赖只需要一条命令无需任何额外配置npm install refinedev/mantine refinedev/react-table mantine/core5 mantine/hooks5 mantine/form5 mantine/notifications5 emotion/react11 tabler/icons-react tanstack/react-table版本支持说明Refine 的 Mantine 集成目前基于Mantine v5。这一点在 packages/mantine/package.json 中有明确佐证——其 peerDependencies 声明了mantine/core^5.10.4、mantine/form^5.10.4、mantine/hooks^5.10.4、mantine/notifications^5.10.4同时要求refinedev/core^5.0.0并支持react^18.0.0 || ^19.0.0、types/react^18.0.0 || ^19.0.0。安装时请务必锁定 Mantine 的5主版本避免与集成包不兼容。各依赖的职责划分如下依赖包作用refinedev/mantineRefine 的 Mantine 集成包提供组件、Hooks、Provider、主题refinedev/react-table基于 RefineuseTable与 TanStack Table 的表格管理方案mantine/core5Mantine 核心 UI 组件库mantine/hooks5Mantine 的 React Hooks 集合mantine/form5Mantine 表单状态与校验库mantine/notifications5Mantine 通知系统emotion/react11Mantine v5 底层依赖的 CSS-in-JS 引擎tabler/icons-react图标库Refine 组件内部大量使用tanstack/react-tableTanStack Table v8表格列与排序过滤的底层实现基本用法包裹 Provider 并组织路由集成包的使用模式非常固定先用 Mantine 的MantineProvider /包裹应用以提供主题再把 Refine 提供的布局组件如ThemedLayout /包裹在路由外层。以下以 React Routerrefinedev/react-router为例给出完整的应用骨架该示例完整代码可见 documentation/docs/ui-integrations/mantine/introduction/previews/usage-react-router-dom.tsximport { Refine, Authenticated } from refinedev/core; import { ErrorComponent, ThemedLayout, RefineThemes, useNotificationProvider, AuthPage, } from refinedev/mantine; import { NotificationsProvider } from mantine/notifications; import { MantineProvider, Global } from mantine/core; import dataProvider from refinedev/simple-rest; import routerProvider, { NavigateToResource, } from refinedev/react-router; import { BrowserRouter, Routes, Route, Outlet, Navigate } from react-router; const App: React.FC () { return ( BrowserRouter MantineProvider theme{RefineThemes.Blue} withNormalizeCSS withGlobalStyles Global styles{{ body: { WebkitFontSmoothing: auto } }} / NotificationsProvider positiontop-right Refine notificationProvider{useNotificationProvider} routerProvider{routerProvider} dataProvider{dataProvider(https://api.fake-rest.refine.dev)} authProvider{authProvider} resources{[ { name: products, list: /products, show: /products/:id, edit: /products/:id/edit, create: /products/create, meta: { canDelete: true }, }, ]} Routes Route element{ Authenticated fallback{Navigate to/login /} Outlet / /Authenticated } Route element{ ThemedLayout Outlet / /ThemedLayout } Route index element{NavigateToResource resourceproducts /} / Route path/products element{Outlet /} Route index element{ProductList /} / Route pathcreate element{ProductCreate /} / Route path:id element{ProductShow /} / Route path:id/edit element{ProductEdit /} / /Route Route path* element{ErrorComponent /} / /Route /Route {/* 登录、注册等认证路由 */} Route path/login element{AuthPage typelogin /} / /Routes /Refine /NotificationsProvider /MantineProvider /BrowserRouter ); };这里有几个值得注意的编排细节Authenticated /守卫通过fallback属性把未认证用户重定向到登录页认证路由组内则用NavigateToResource把已登录用户引导到资源首页。ThemedLayout /包裹受保护路由布局、侧边导航、头部只在登录后渲染。resources声明list/show/edit/create映射了每个操作对应的路由路径Refine 的按钮、面包屑、菜单会自动依据这份声明生成导航。meta.canDelete开启后列表视图会渲染删除按钮并启用确认对话框与撤销undoable通知。如果你使用Next.js或Remix模式完全相同只是路由部分换成各自的路由方案refinedev/nextjs-router、refinedev/remix-router仓库中分别提供了对应的使用示例见 documentation/docs/ui-integrations/mantine/introduction/previews/usage-next-js.tsx 与 documentation/docs/ui-integrations/mantine/introduction/previews/usage-remix.tsx。表格refinedev/react-table 驱动的数据列表Mantine 自带风格化的 Table 原语 与 TanStack Table v8 的useTable之上把两种表格能力合二为一。Refine 的 Mantine 文档与示例默认使用该包做表格管理但你完全可以替换成任何其他表格管理方案。下面是一个完整的产品列表页含操作列与分页import React from react; import { useTable } from refinedev/react-table; import { ColumnDef, flexRender } from tanstack/react-table; import { List, ShowButton, EditButton, DeleteButton } from refinedev/mantine; import { Box, Group, ScrollArea, Table, Pagination } from mantine/core; const columns [ { id: id, header: ID, accessorKey: id }, { id: name, header: Name, accessorKey: name, meta: { filterOperator: contains }, }, { id: price, header: Price, accessorKey: price }, { id: actions, header: Actions, accessorKey: id, enableColumnFilter: false, enableSorting: false, cell: function render({ getValue }) { return ( Group spacingxs noWrap ShowButton hideText recordItemId{getValue() as number} / EditButton hideText recordItemId{getValue() as number} / DeleteButton hideText recordItemId{getValue() as number} / /Group ); }, }, ]; export const ProductList () { const { reactTable: { getHeaderGroups, getRowModel }, refineCore: { setCurrentPage, pageCount, currentPage, tableQuery: { data: tableData }, }, } useTableIProduct({ columns }); return ( ScrollArea List Table highlightOnHover thead {getHeaderGroups().map((headerGroup) ( tr key{headerGroup.id} {headerGroup.headers.map((header) ( th key{header.id} {flexRender(header.column.columnDef.header, header.getContext())} /th ))} /tr ))} /thead tbody {getRowModel().rows.map((row) ( tr key{row.id} {row.getVisibleCells().map((cell) ( td key{cell.id} {flexRender(cell.column.columnDef.cell, cell.getContext())} /td ))} /tr ))} /tbody /Table br / Pagination positionright total{pageCount} page{currentPage} onChange{setCurrentPage} / /List /ScrollArea ); };理解这个返回结构是掌握refinedev/react-table的关键reactTable命名空间透出 TanStack Table 的全部能力getHeaderGroups、getRowModel、setOptions等因此列定义、过滤、排序、虚拟化等生态工具都能直接使用。refineCore命名空间透出 Refine 核心useTable的能力currentPage、pageCount、setCurrentPage、tableQuery等分页状态与 data provider 的查询天然联动。列上的meta.filterOperator声明该列使用的过滤操作符如contains供过滤表单生成对应的查询参数。enableColumnFilter/enableSorting按列关闭过滤或排序常用于操作列。排序与过滤同样可以直接挂在refineCoreProps上例如设置初始排序const { ... } useTable({ columns, refineCoreProps: { sorters: { initial: [{ field: id, order: desc }], }, }, });仓库中提供了大量可运行的表格示例refinedev/react-table集成包的源码位于 packages/react-table完整示例项目见 examples/table-mantine-basic 与 examples/table-mantine-advanced对应的端到端测试在 cypress/e2e/table-mantine-basic 与 cypress/e2e/table-mantine-advanced。表单useForm 与表单生态Refine 与mantine/form的useForm完成。它内部桥接 Refine 核心的数据操作create/update与 Mantine 的表单状态管理。以下是一个创建产品页Create 视图import { Create, useForm } from refinedev/mantine; import { TextInput, NumberInput } from mantine/core; export const ProductCreate () { const { saveButtonProps, getInputProps, errors } useForm({ initialValues: { name: , material: , price: 0, }, }); return ( Create saveButtonProps{saveButtonProps} form TextInput mt{8} idname labelName placeholderName {...getInputProps(name)} / TextInput mt{8} idmaterial labelMaterial placeholderMaterial {...getInputProps(material)} / NumberInput mt{8} idprice labelPrice placeholderPrice {...getInputProps(price)} / /form /Create ); };useForm返回值的用法要点saveButtonProps直接透传给Create /或Edit /的保存按钮点击后触发对应的 create/update mutation并自动处理加载态、成功/失败通知与数据失效invalidation。getInputProps(field)Mantine 表单的标准接线方式把字段值、变更回调、校验错误绑定到TextInput、NumberInput等组件上。errors服务端返回的表单校验错误映射可用于展示配合mantine/form的校验机制。编辑场景useForm会根据当前路由中的资源 id 自动回填数据还可以开启自动保存从refineCore中取出autoSaveProps传入Edit autoSaveProps{autoSaveProps}const { saveButtonProps, getInputProps, errors, refineCore: { query, autoSaveProps } } useForm({ initialValues: { name: , material: , price: 0 }, refineCoreProps: { autoSave: { enabled: true }, }, });除基础useForm外集成包还针对不同交互形态提供了专门 HooksHook适用场景文档useModalForm在弹窗Modal内完成创建/编辑use-modal-formuseDrawerForm在抽屉Drawer内完成创建/编辑use-drawer-formuseStepsForm分步表单多步骤向导use-steps-formuseSelect关联数据下拉选择如外键字段use-select其中useSelect复用了refinedev/core的useSelect能基于资源的 data provider 自动拉取选项列表并映射label/value非常适合实现选择某个分类/用户这类关系型字段还内置了搜索onSearch与排序支持。仓库中对应的可运行示例包括 examples/form-mantine-use-form、examples/form-mantine-use-modal-form、examples/form-mantine-use-drawer-form、examples/form-mantine-use-steps-form以及校验相关示例 examples/form-mantine-mutation-mode 与 examples/server-side-form-validation-mantine对应的 Cypress 测试位于 cypress/e2e/form-mantine-use-form 等目录。通知无缝接入 Mantine NotificationsMantine 自带内置通知系统mantine/notifications与自身 UI 元素配合默契。Refine 通过useNotificationProvider把 Refine 的动作/事件通知成功、错误、进度桥接到 Mantine 的通知系统上直接赋值给Refine /的notificationProvider属性即可import { Refine } from refinedev/core; import { useNotificationProvider } from refinedev/mantine; import { NotificationsProvider } from mantine/notifications; const App () { return ( // mantine/notifications 也需要一个 context provider 才能工作 NotificationsProvider positiontop-right Refine notificationProvider{useNotificationProvider} {/* ... */} /Refine /NotificationsProvider ); };从源码 packages/mantine/src/providers/notificationProvider.tsx 可以看到其底层实现逻辑open方法区分两种通知类型type progress渲染一个带倒计时圆环RingCountdown实现见 packages/mantine/src/components/ring-countdown/index.tsx的进度通知配合undoableTimeout展示可撤销倒计时并提供撤销按钮IconRotate2点击后调用cancelMutation?.()取消变更。这正是 DeleteButton 等破坏性操作支持撤销机制的来源。成功/失败通知成功用IconCheck 主色失败用IconX 红色默认autoClose: 50005 秒自动关闭description作为标题展示。close(key)根据通知 key 移除并隐藏对应通知。实现内部维护activeNotifications数组通过addNotification/removeNotification/isNotificationActive实现按 key 的去重更新先showNotification后续用updateNotification原地更新。源码同时保留了旧导出notificationProvideruseNotificationProvider的别名并标记为 deprecated统一使用useNotificationProvider命名。预定义组件与视图布局、菜单与面包屑Refine 提供基于 Mantine 组件打造的布局组件内置了导航菜单、头部、认证与授权等 Refine 特性。其实现位于 packages/mantine/src/components/themedLayout/index.tsx内部由 Sider、Header、HamburgerMenu、Title 等子组件组成。ThemedLayout /由三部分组成Sider侧边栏根据Refine /的resources声明自动生成导航菜单项如果配置了 auth provider还会显示登出按钮。Header头部展示应用 logo 与名称如果配置了 auth provider还会显示当前用户信息。内容区渲染children即当前路由页面。三种框架下的布局写法分别见 layout-react-router-dom.tsx、layout-next-js.tsx 与 layout-remix.tsx。此外Breadcrumb /组件以 Mantine 组件为基底根据当前路由自动生成合适的面包屑导航并默认嵌入在 Refine 提供的基础视图中。按钮Mantine 集成包提供了多种建立在 MantineButton /之上的业务按钮内置了大量逻辑功能授权检查根据 access control provider 决定显隐/禁用确认对话框如删除确认加载状态mutation 进行中显示 loading数据失效操作完成后刷新相关查询导航跳转到对应资源路由表单动作提交保存导入/导出例如EditButton /在列表操作列中的用法import React from react; import { useTable } from refinedev/react-table; import { ColumnDef, flexRender } from tanstack/react-table; import { List, EditButton } from refinedev/mantine; const columns [ { id: id, header: ID, accessorKey: id }, { id: name, header: Name, accessorKey: name, meta: { filterOperator: contains } }, { id: price, header: Price, accessorKey: price }, { id: actions, header: Actions, accessorKey: id, cell: function render({ getValue }) { return EditButton hideText recordItemId{getValue() as number} /; }, }, ]; export const ProductList () { const table useTable({ columns }); return ( /* ... */ ); };recordItemId指定按钮操作的目标记录hideText只显示图标。完整按钮清单如下每个按钮的源码与单元测试位于 packages/mantine/src/components/buttonsCreateButton /EditButton /ListButton /ShowButton /CloneButton /DeleteButton /SaveButton /RefreshButton /ImportButton /ExportButton /这些按钮大多已内置于 Refine 提供的基础视图中——使用List /、Show /、Edit /、Create /时合适的按钮会自动出现在正确位置无需手工拼装。视图视图Views是页面内容的包装器设计为在布局内使用提供基于资源的标题、面包屑、相关操作与授权检查。它们基于 Mantine 的Box /List /Show /Edit /Create /字段组件字段Fields组件用于以 Mantine 的恰当设计与格式渲染值构建在对应 Mantine 组件之上并附带值的格式化逻辑。它们可以组合或扩展以满足定制需求。字段组件源码位于 packages/mantine/src/components/fieldsBooleanField /DateField /EmailField /FileField /MarkdownField /NumberField /TagField /TextField /UrlField /详情页展示示例import { useShow } from refinedev/core; import { Show, TextField, NumberField, MarkdownField } from refinedev/mantine; import { Title } from mantine/core; export const ProductShow () { const { result: product, query } useShow(); const { data, isLoading } query; return ( Show isLoading{isLoading} Title mtxs order{5}Name/Title TextField value{product?.name} / Title mtxs order{5}Description/Title MarkdownField value{product?.description} / Title mtxs order{5}Price/Title NumberField value{product?.price} options{{ style: currency, currency: USD }} / /Show ); };注意NumberField的options直接透传给Intl.NumberFormat因此可以像这里一样用style: currency, currency: USD输出本地化的货币格式MarkdownField内部基于react-markdownremark-gfm渲染 Markdown 内容相关依赖见 packages/mantine/package.json。认证页面认证页面Auth Pages专门用于应用认证流程通过复用 Refine 的认证 Hooks提供开箱即用的登录、注册、忘记密码与重置密码页面。它们构建在 Mantine 基础组件如TextInput /、Card /之上实现位于 packages/mantine/src/components/pages/auth。可用类型AuthPage typelogin /AuthPage typeregister /AuthPage typeforgot-password /AuthPage typereset-password /用法参见 documentation/docs/ui-integrations/mantine/components/auth-page/index.md。在 App.tsx 中它通常与Authenticated守卫配合例如传入formProps预填演示账号AuthPage typelogin formProps{{ initialValues: { email: demorefine.dev, password: demodemo, }, }} /错误组件集成包还提供ErrorComponent /用于渲染 404 页面。它不提供太多功能但能保证错误页与整体设计语言一致import { ErrorComponent } from refinedev/mantine; const NotFoundPage () { return ErrorComponent /; };主题开箱即用的 RefineThemes 与深浅色支持Refine 提供了应用级组件布局、侧边栏、头部和页面级组件因此与 Mantine 样式的协同至关重要。refinedev/mantine导出的所有组件与 Provider 都会自动跟随 Mantine 的当前主题无需额外配置。同时Refine 提供了一套精心设计的 Mantine 主题输出与 Refine 组件搭配良好的 UI支持亮色与暗色模式。主题以RefineThemes对象形式从refinedev/mantine导出直接传入MantineProvider theme{...}即可import { MantineProvider } from mantine/core; import { RefineThemes } from refinedev/mantine; MantineProvider theme{RefineThemes.Blue} withNormalizeCSS withGlobalStyles从源码 packages/mantine/src/theme/index.ts 可以看到主题系统的完整实现内置 7 套品牌色Blue、Purple、Magenta、Red、Orange、Yellow、Green每套都是一组 10 档的 Mantine 色阶如 Blue 从#E7F5FF到#1864AB统一映射到brand主色并设置为primaryColor。全局背景联动每套主题都注入globalStyles根据theme.colorScheme自动切换body背景色暗色用dark[8]亮色用gray[0]因此切换主题即切换深浅色背景。默认主题细节commonThemeProperties定义了 Montserrat 字体栈、defaultRadius: 6、以及Table组件的表头/表行样式定制表头灰底、圆角行底部分隔线确保 Refine 组件观感统一。仓库还单独导出了LightTheme与DarkTheme基于一套绿色系primary色阶可用作无品牌色的基础主题。若需要更深入的主题定制颜色、字体、圆角、组件样式可参考 Mantine 官方主题对象文档 与主题演示示例 examples/theme-mantine-demo。Inferencer用 AI 生成视图代码refinedev/inferencer可以根据你的 data provider 数据结构自动生成资源的列表、详情、编辑、创建视图。它从refinedev/mantine集成导出以下组件MantineListInferencer自动生成列表页MantineShowInferencer自动生成详情页MantineEditInferencer自动生成编辑页MantineCreateInferencer自动生成创建页MantineInferencer四者合一的组合组件典型用法是把MantineInferencer /挂到某个资源路由上让 Refine 自动生成并渲染对应视图生成后的代码可直接复制到项目中作为起点继续开发。更完整的说明见 Mantine Inferencer 文档Inferencer 的 Mantine 渲染实现位于 packages/inferencer/src/inference-resolvers对应mantine解析器配套示例项目见 examples/inferencer-mantine。小结与快速上手路径从本文可以总结出refinedev/mantine的完整使用路径安装一次性安装refinedev/mantine及其依赖注意锁定 Mantine5。组织应用MantineProvider主题→NotificationsProvider通知→Refine /providers resources→ 路由与ThemedLayout。按需取用表格用refinedev/react-table的useTable表单用useForm/useModalForm/useDrawerForm/useStepsForm关联字段用useSelect展示用 Fields操作与导航用 Buttons页面骨架用 Views 与 AuthPage。提升效率用RefineThemes一键获得品牌化主题与深浅色支持用 Inferencer 自动生成视图代码再人工打磨。如果想直接运行一个完整可用的示例仓库中的 examples/form-mantine-use-form、examples/table-mantine-advanced、examples/auth-mantine 以及 examples/base-mantine 都是很好的起点每个示例都包含package.json与完整的src目录可直接安装依赖后启动。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考