Refine v5 Ant Design 主题定制实战使用 RefineThemes 预定义主题与实时切换【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine导读在 Refine 与 Ant Design 组合的管理后台中主题Theming是决定产品观感与品牌一致性的关键一环。本文以仓库中的theme-antd-demo示例为实战主线完整讲解如何通过refinedev/antd提供的RefineThemes预定义主题快速套用品牌色如何在运行时实时切换主色与明暗模式并深入源码剖析预定义主题的实现原理最后补充基于ConfigProvider的自定义主题、预设算法以及通知组件主题兼容等进阶用法。示例应用概览一个可实时换肤的 Refine 后台Refine 文档在 refine-themes-antd 示例说明 中明确指出你可以直接使用 Refine 提供的预定义主题示例应用正是通过refinedev/antd导出的RefineThemes构建的并且可以按自己的需求在 Refine 项目中轻松自定义主题。对应的完整示例位于 examples/theme-antd-demo它是一个基于 Vite Refine v5 Ant Design 5 的帖子管理后台具备以下能力认证登录页支持 Google / GitHub 第三方登录占位posts 资源的列表、创建、编辑、详情页通过ThemeSettings悬浮按钮弹出设置面板实时切换 7 种预定义主题色与明暗模式列表页带有分类筛选、状态筛选等 Refine 高级表格能力。其中主题能力集中在两个文件App.tsx应用入口与ConfigProvider装配和 theme-settings/index.tsx换肤交互面板。深入源码RefineThemes 预定义主题的实现原理RefineThemes定义在 packages/antd/src/definitions/themes/index.ts。从源码结构看它本质上是一个RecordThemeNames, ThemeConfig的普通对象每种主题只是一个仅包含token.colorPrimary的 Ant Design 主题配置type ThemeNames | Blue | Purple | Magenta | Red | Orange | Yellow | Green; export const RefineThemes: RefineThemes { Blue: { token: { colorPrimary: #1677FF } }, Purple: { token: { colorPrimary: #722ED1 } }, Magenta: { token: { colorPrimary: #EB2F96 } }, Red: { token: { colorPrimary: #F5222D } }, Orange: { token: { colorPrimary: #FA541C } }, Yellow: { token: { colorPrimary: #FAAD14 } }, Green: { token: { colorPrimary: #52C41A } }, };要点一共提供 7 套预定义主题Blue、Purple、Magenta、Red、Orange、Yellow、Green每套主题都是标准ThemeConfig符合 Ant Design 5 的设计令牌Design Token体系因此可以无缝传给ConfigProvider theme{...}默认主色#1677FFBlue与 Ant Design 5 的默认主色一致其余颜色取自 Ant Design 官方色板由于只覆盖了colorPrimaryAnt Design 会基于该令牌自动推导按钮、链接、选中态等衍生颜色实现一套完整的品牌配色。文档 theming/index.md 中对此也有示例const { Blue, Purple, Magenta, Red, Orange, Yellow } RefineThemes;。快速上手把预定义主题接入 Refine 应用在 theming 指南 中给出了最小接入方式用ConfigProvider包裹整个 Refine 应用把RefineThemes.Blue作为theme传入import { Refine } from refinedev/core; import { ThemedLayout, RefineThemes } from refinedev/antd; import { ConfigProvider } from antd; const App: React.FC () { return ( ConfigProvider theme{RefineThemes.Blue} Refine /* ... */ ThemedLayout{/* ... */}/ThemedLayout /Refine /ConfigProvider ); };而在theme-antd-demo示例中App.tsx 做了更进一步的演示——主题不是写死的而是存放在 React state 中初始值为 Magenta 色 暗色算法const [customTheme, setCustomTheme] useStateThemeConfig({ token: RefineThemes.Magenta.token, algorithm: theme.darkAlgorithm, }); return ( BrowserRouter GitHubBanner / ConfigProvider theme{customTheme} ThemeSettings currentTheme{customTheme} onThemeClick{(theme) setCustomTheme(theme)} / Refine authProvider{authProvider} routerProvider{routerProvider} dataProvider{dataProvider(API_URL)} resources{[ { name: posts, list: /posts, show: /posts/show/:id, create: /posts/create, edit: /posts/edit/:id, meta: { canDelete: true }, }, ]} notificationProvider{useNotificationProvider} options{{ syncWithLocation: true, warnWhenUnsavedChanges: true, }} {/* 路由与认证逻辑 */} /Refine /ConfigProvider /BrowserRouter );这段代码值得注意的几点token: RefineThemes.Magenta.token只取了 Magenta 的令牌而algorithm单独指定theme.darkAlgorithm说明RefineThemes的配色可以与其他算法自由组合ConfigProvider必须在Refine外层Ant Design 组件树才能统一消费主题示例引入ant-design/v5-patch-for-react-19与refinedev/antd/dist/reset.css分别用于 React 19 兼容与样式重置实际项目中按需保留。运行时换肤ThemeSettings 面板的实现拆解示例最有价值的部分是 theme-settings/index.tsx 实现的实时换肤面板其交互与实现逻辑如下1. 打开设置面板——使用 Refine 的useModal()hook 管理Modal的显隐const { show, close, visible } useModal();面板通过固定定位按钮触发position: fixed、bottom: 16px、left: 50%始终悬浮在页面底部中央。2. 渲染全部预定义主题色——利用Object.keys(RefineThemes)遍历 7 套主题为每套生成一个以该主题主色为背景的按钮{Object.keys(RefineThemes).map((name) { const theme RefineThemes[name as ThemeName]; return ( Button key{theme.token?.colorPrimary} onClick{() onTokenColorClick(theme.token)} style{{ background: theme.token?.colorPrimary }} {name} /Button ); })}这里用keyof typeof RefineThemes推导出ThemeName类型既保证类型安全又让新增主题自动出现在面板中。3. 切换主色——点击色板按钮后仅替换token部分保留当前的明暗算法const onTokenColorClick (token: ThemeConfig[token]) { onThemeClick({ ...currentTheme, token }); close(); };4. 切换明暗模式——在theme.defaultAlgorithm与theme.darkAlgorithm之间互换const toggleMode () { onThemeClick({ ...currentTheme, algorithm: mode dark ? theme.defaultAlgorithm : theme.darkAlgorithm, }); setMode((prev) (prev dark ? light : dark)); close(); };由于customTheme存放在 App 顶层 state 中ConfigProvider的theme属性随之更新整棵组件树无需任何额外操作即可完成换肤——这就是 Ant Design 5 Design Token 机制带来的核心收益。自定义主题覆盖组件令牌与全局令牌预定义主题只是起点。在 theming/index.md 的 Overriding the themes 小节 中Refine 官方展示了完全自定义主题的方式直接给ConfigProvider传theme对象其中components用于按组件覆盖如 Button 的圆角、Typography 的标题色token用于覆盖全局令牌如主色import { Refine } from refinedev/core; import { ThemedLayout } from refinedev/antd; import { ConfigProvider } from antd; const App: React.FC () { return ( ConfigProvider theme{{ components: { Button: { borderRadius: 0, }, Typography: { colorTextHeading: #1890ff, }, }, token: { colorPrimary: #f0f, }, }} Refine /* ... */ ThemedLayout{/* ... */}/ThemedLayout /Refine /ConfigProvider ); };这意味着可以不使用RefineThemes完全从零定义自己的品牌主题也可以在RefineThemes.XXX的基础上展开覆盖例如{ ...RefineThemes.Blue, components: { Button: { borderRadius: 4 } } }如果接受默认主题则ConfigProvider并非必需Refine 与 Ant Design 会使用内置默认值。预设算法快速切换暗色与紧凑布局Ant Design 5 提供三套预设算法在 theming/index.md 的 Use Preset Algorithms 小节 中有详细说明theme.defaultAlgorithm默认算法theme.darkAlgorithm暗色算法theme.compactAlgorithm紧凑算法减小间距与尺寸提高信息密度。通过修改ConfigProvider的theme.algorithm即可切换官方文档演示了在Header组件中放一个切换按钮并在 App 层根据useState状态选择算法const [currentTheme, setCurrentTheme] useStatelight | dark(dark); ConfigProvider theme{{ algorithm: currentTheme light ? theme.defaultAlgorithm : theme.darkAlgorithm, }} Refine /* ... */ ThemedLayout Header{Header}{/* ... */}/ThemedLayout /Refine /ConfigProvider主题示例应用正是这一做法的工程化实现把「算法」与「主色令牌」拆成两个独立维度存进ThemeConfig切换互不干扰。让通知组件跟随主题useNotificationProvider 的正确用法在自定义主题时有一个容易踩坑的细节refinedev/antd旧版的notificationProvider导出默认无法消费当前主题上下文导致通知弹窗的观感与应用主题不一致。文档在 theming/index.md 的 useNotificationProvider compatible with Theme 小节 给出了解决方案引入 antd 的App组件包裹 Refine并使用refinedev/antd的useNotificationProviderimport { Refine } from refinedev/core; import { ThemedLayout, useNotificationProvider } from refinedev/antd; import { ConfigProvider, App as AntdApp } from antd; const App: React.FC () { return ( ConfigProvider theme{RefineThemes.Blue} AntdApp Refine notificationProvider{useNotificationProvider} /* ... */ ThemedLayout{/* ... */}/ThemedLayout /Refine /AntdApp /ConfigProvider ); };示例 App.tsx 正是按照该模式编写ConfigProvider主题→ThemeSettings→RefinenotificationProvider{useNotificationProvider}保证刷新、通知等反馈元素与当前主题完全一致。完整项目骨架认证、路由与主题的协同最后把theme-antd-demo的整体结构梳理一遍方便对照仓库阅读 examples/theme-antd-demotheme-antd-demo/ ├── src/ │ ├── App.tsx # 主题状态 ConfigProvider Refine 装配 │ ├── components/ │ │ └── theme-settings/ # 换肤面板色板 明暗切换 │ ├── interfaces/ # IPost / ICategory 类型定义 │ ├── pages/posts/ # list / create / edit / show 四个页面 │ └── utils/authProvider.ts # 认证逻辑 ├── index.html ├── package.json └── vite.config.ts应用的路由结构展示了主题与认证、布局的协同方式未登录访问受保护路由时通过AuthenticatedCatchAllNavigate重定向到/login/login、/register、/forgot-password、/update-password使用refinedev/antd的AuthPage渲染受保护区域用ThemedLayout包裹路由出口用Outlet承接子页面末尾挂载UnsavedChangesNotifier未保存离开提醒与DocumentTitleHandler页面标题同步。小结从RefineThemes的源码实现packages/antd/src/definitions/themes/index.ts到示例应用examples/theme-antd-demo可以总结出 Refine v5 主题定制的完整路径快速起步ConfigProvider theme{RefineThemes.Blue}一行接入 7 套预定义主题运行时换肤把ThemeConfig放进 React state通过token主色与algorithm明暗/紧凑两个维度分别控制配合useModal即可做出如示例一样的主题设置面板深度定制用components覆盖组件级令牌、token覆盖全局令牌或直接使用theme.darkAlgorithm/theme.compactAlgorithm兼容细节使用useNotificationProvider与 antdApp组件让通知、刷新等反馈元素同样跟随主题。建议结合文档 theming/index.md 与示例源码一起阅读前者提供 API 层面的完整说明后者给出可直接运行、可复制的工程化参考。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Refine v5 Ant Design 主题定制实战使用 RefineThemes 预定义主题与实时切换【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine导读在 Refine 与 Ant Design 组合的管理后台中主题Theming是决定产品观感与品牌一致性的关键一环。本文以仓库中的theme-antd-demo示例为实战主线完整讲解如何通过refinedev/antd提供的RefineThemes预定义主题快速套用品牌色如何在运行时实时切换主色与明暗模式并深入源码剖析预定义主题的实现原理最后补充基于ConfigProvider的自定义主题、预设算法以及通知组件主题兼容等进阶用法。示例应用概览一个可实时换肤的 Refine 后台Refine 文档在 refine-themes-antd 示例说明 中明确指出你可以直接使用 Refine 提供的预定义主题示例应用正是通过refinedev/antd导出的RefineThemes构建的并且可以按自己的需求在 Refine 项目中轻松自定义主题。对应的完整示例位于 examples/theme-antd-demo它是一个基于 Vite Refine v5 Ant Design 5 的帖子管理后台具备以下能力认证登录页支持 Google / GitHub 第三方登录占位posts 资源的列表、创建、编辑、详情页通过ThemeSettings悬浮按钮弹出设置面板实时切换 7 种预定义主题色与明暗模式列表页带有分类筛选、状态筛选等 Refine 高级表格能力。其中主题能力集中在两个文件App.tsx应用入口与ConfigProvider装配和 theme-settings/index.tsx换肤交互面板。深入源码RefineThemes 预定义主题的实现原理RefineThemes定义在 packages/antd/src/definitions/themes/index.ts。从源码结构看它本质上是一个RecordThemeNames, ThemeConfig的普通对象每种主题只是一个仅包含token.colorPrimary的 Ant Design 主题配置type ThemeNames | Blue | Purple | Magenta | Red | Orange | Yellow | Green; export const RefineThemes: RefineThemes { Blue: { token: { colorPrimary: #1677FF } }, Purple: { token: { colorPrimary: #722ED1 } }, Magenta: { token: { colorPrimary: #EB2F96 } }, Red: { token: { colorPrimary: #F5222D } }, Orange: { token: { colorPrimary: #FA541C } }, Yellow: { token: { colorPrimary: #FAAD14 } }, Green: { token: { colorPrimary: #52C41A } }, };要点一共提供 7 套预定义主题Blue、Purple、Magenta、Red、Orange、Yellow、Green每套主题都是标准ThemeConfig符合 Ant Design 5 的设计令牌Design Token体系因此可以无缝传给ConfigProvider theme{...}默认主色#1677FFBlue与 Ant Design 5 的默认主色一致其余颜色取自 Ant Design 官方色板由于只覆盖了colorPrimaryAnt Design 会基于该令牌自动推导按钮、链接、选中态等衍生颜色实现一套完整的品牌配色。文档 theming/index.md 中对此也有示例const { Blue, Purple, Magenta, Red, Orange, Yellow } RefineThemes;。快速上手把预定义主题接入 Refine 应用在 theming 指南 中给出了最小接入方式用ConfigProvider包裹整个 Refine 应用把RefineThemes.Blue作为theme传入import { Refine } from refinedev/core; import { ThemedLayout, RefineThemes } from refinedev/antd; import { ConfigProvider } from antd; const App: React.FC () { return ( ConfigProvider theme{RefineThemes.Blue} Refine /* ... */ ThemedLayout{/* ... */}/ThemedLayout /Refine /ConfigProvider ); };而在theme-antd-demo示例中App.tsx 做了更进一步的演示——主题不是写死的而是存放在 React state 中初始值为 Magenta 色 暗色算法const [customTheme, setCustomTheme] useStateThemeConfig({ token: RefineThemes.Magenta.token, algorithm: theme.darkAlgorithm, }); return ( BrowserRouter GitHubBanner / ConfigProvider theme{customTheme} ThemeSettings currentTheme{customTheme} onThemeClick{(theme) setCustomTheme(theme)} / Refine authProvider{authProvider} routerProvider{routerProvider} dataProvider{dataProvider(API_URL)} resources{[ { name: posts, list: /posts, show: /posts/show/:id, create: /posts/create, edit: /posts/edit/:id, meta: { canDelete: true }, }, ]} notificationProvider{useNotificationProvider} options{{ syncWithLocation: true, warnWhenUnsavedChanges: true, }} {/* 路由与认证逻辑 */} /Refine /ConfigProvider /BrowserRouter );这段代码值得注意的几点token: RefineThemes.Magenta.token只取了 Magenta 的令牌而algorithm单独指定theme.darkAlgorithm说明RefineThemes的配色可以与其他算法自由组合ConfigProvider必须在Refine外层Ant Design 组件树才能统一消费主题示例引入ant-design/v5-patch-for-react-19与refinedev/antd/dist/reset.css分别用于 React 19 兼容与样式重置实际项目中按需保留。运行时换肤ThemeSettings 面板的实现拆解示例最有价值的部分是 theme-settings/index.tsx 实现的实时换肤面板其交互与实现逻辑如下1. 打开设置面板——使用 Refine 的useModal()hook 管理Modal的显隐const { show, close, visible } useModal();面板通过固定定位按钮触发position: fixed、bottom: 16px、left: 50%始终悬浮在页面底部中央。2. 渲染全部预定义主题色——利用Object.keys(RefineThemes)遍历 7 套主题为每套生成一个以该主题主色为背景的按钮{Object.keys(RefineThemes).map((name) { const theme RefineThemes[name as ThemeName]; return ( Button key{theme.token?.colorPrimary} onClick{() onTokenColorClick(theme.token)} style{{ background: theme.token?.colorPrimary }} {name} /Button ); })}这里用keyof typeof RefineThemes推导出ThemeName类型既保证类型安全又让新增主题自动出现在面板中。3. 切换主色——点击色板按钮后仅替换token部分保留当前的明暗算法const onTokenColorClick (token: ThemeConfig[token]) { onThemeClick({ ...currentTheme, token }); close(); };4. 切换明暗模式——在theme.defaultAlgorithm与theme.darkAlgorithm之间互换const toggleMode () { onThemeClick({ ...currentTheme, algorithm: mode dark ? theme.defaultAlgorithm : theme.darkAlgorithm, }); setMode((prev) (prev dark ? light : dark)); close(); };由于customTheme存放在 App 顶层 state 中ConfigProvider的theme属性随之更新整棵组件树无需任何额外操作即可完成换肤——这就是 Ant Design 5 Design Token 机制带来的核心收益。自定义主题覆盖组件令牌与全局令牌预定义主题只是起点。在 theming/index.md 的 Overriding the themes 小节 中Refine 官方展示了完全自定义主题的方式直接给ConfigProvider传theme对象其中components用于按组件覆盖如 Button 的圆角、Typography 的标题色token用于覆盖全局令牌如主色import { Refine } from refinedev/core; import { ThemedLayout } from refinedev/antd; import { ConfigProvider } from antd; const App: React.FC () { return ( ConfigProvider theme{{ components: { Button: { borderRadius: 0, }, Typography: { colorTextHeading: #1890ff, }, }, token: { colorPrimary: #f0f, }, }} Refine /* ... */ ThemedLayout{/* ... */}/ThemedLayout /Refine /ConfigProvider ); };这意味着可以不使用RefineThemes完全从零定义自己的品牌主题也可以在RefineThemes.XXX的基础上展开覆盖例如{ ...RefineThemes.Blue, components: { Button: { borderRadius: 4 } } }如果接受默认主题则ConfigProvider并非必需Refine 与 Ant Design 会使用内置默认值。预设算法快速切换暗色与紧凑布局Ant Design 5 提供三套预设算法在 theming/index.md 的 Use Preset Algorithms 小节 中有详细说明theme.defaultAlgorithm默认算法theme.darkAlgorithm暗色算法theme.compactAlgorithm紧凑算法减小间距与尺寸提高信息密度。通过修改ConfigProvider的theme.algorithm即可切换官方文档演示了在Header组件中放一个切换按钮并在 App 层根据useState状态选择算法const [currentTheme, setCurrentTheme] useStatelight | dark(dark); ConfigProvider theme{{ algorithm: currentTheme light ? theme.defaultAlgorithm : theme.darkAlgorithm, }} Refine /* ... */ ThemedLayout Header{Header}{/* ... */}/ThemedLayout /Refine /ConfigProvider主题示例应用正是这一做法的工程化实现把「算法」与「主色令牌」拆成两个独立维度存进ThemeConfig切换互不干扰。让通知组件跟随主题useNotificationProvider 的正确用法在自定义主题时有一个容易踩坑的细节refinedev/antd旧版的notificationProvider导出默认无法消费当前主题上下文导致通知弹窗的观感与应用主题不一致。文档在 theming/index.md 的 useNotificationProvider compatible with Theme 小节 给出了解决方案引入 antd 的App组件包裹 Refine并使用refinedev/antd的useNotificationProviderimport { Refine } from refinedev/core; import { ThemedLayout, useNotificationProvider } from refinedev/antd; import { ConfigProvider, App as AntdApp } from antd; const App: React.FC () { return ( ConfigProvider theme{RefineThemes.Blue} AntdApp Refine notificationProvider{useNotificationProvider} /* ... */ ThemedLayout{/* ... */}/ThemedLayout /Refine /AntdApp /ConfigProvider ); };示例 App.tsx 正是按照该模式编写ConfigProvider主题→ThemeSettings→RefinenotificationProvider{useNotificationProvider}保证刷新、通知等反馈元素与当前主题完全一致。完整项目骨架认证、路由与主题的协同最后把theme-antd-demo的整体结构梳理一遍方便对照仓库阅读 examples/theme-antd-demotheme-antd-demo/ ├── src/ │ ├── App.tsx # 主题状态 ConfigProvider Refine 装配 │ ├── components/ │ │ └── theme-settings/ # 换肤面板色板 明暗切换 │ ├── interfaces/ # IPost / ICategory 类型定义 │ ├── pages/posts/ # list / create / edit / show 四个页面 │ └── utils/authProvider.ts # 认证逻辑 ├── index.html ├── package.json └── vite.config.ts应用的路由结构展示了主题与认证、布局的协同方式未登录访问受保护路由时通过AuthenticatedCatchAllNavigate重定向到/login/login、/register、/forgot-password、/update-password使用refinedev/antd的AuthPage渲染受保护区域用ThemedLayout包裹路由出口用Outlet承接子页面末尾挂载UnsavedChangesNotifier未保存离开提醒与DocumentTitleHandler页面标题同步。小结从RefineThemes的源码实现packages/antd/src/definitions/themes/index.ts到示例应用examples/theme-antd-demo可以总结出 Refine v5 主题定制的完整路径快速起步ConfigProvider theme{RefineThemes.Blue}一行接入 7 套预定义主题运行时换肤把ThemeConfig放进 React state通过token主色与algorithm明暗/紧凑两个维度分别控制配合useModal即可做出如示例一样的主题设置面板深度定制用components覆盖组件级令牌、token覆盖全局令牌或直接使用theme.darkAlgorithm/theme.compactAlgorithm兼容细节使用useNotificationProvider与 antdApp组件让通知、刷新等反馈元素同样跟随主题。建议结合文档 theming/index.md 与示例源码一起阅读前者提供 API 层面的完整说明后者给出可直接运行、可复制的工程化参考。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
