Refine项目从2.x到3.x版本迁移指南

Refine项目从2.x到3.x版本迁移指南

refine 一个用于构建内部工具、管理面板、仪表盘和B2B应用程序的React框架，具有无与伦比的灵活性。 项目地址: https://gitcode.com/gh_mirrors/re/refine

前言

Refine项目在3.x版本中进行了重大架构调整，使其成为一个真正的"无头"(Headless)框架，能够与任何UI框架无缝集成。本文将详细介绍从2.x版本迁移到3.x版本的关键步骤和注意事项。

架构变化概述

3.x版本的核心变化是将项目拆分为两个主要部分：

1. 核心包(@pankod/refine-core)：包含所有与UI无关的hooks和组件
2. Ant Design适配包(@pankod/refine-antd)：包含Ant Design特定的组件和hooks

这种架构使得Refine更加灵活，开发者可以自由选择UI框架，同时保持核心功能的一致性。

自动迁移方案（推荐）

使用官方提供的代码迁移工具可以自动完成大部分迁移工作：

npx @pankod/refine-codemod refine2-to-refine3

执行上述命令后，工具会自动处理以下内容：

• 更新包引用路径
• 调整组件导入方式
• 处理样式文件变更

手动迁移步骤

1. 更新依赖包

首先需要卸载旧包并安装新包：

npm uninstall @pankod/refine
npm i @pankod/refine-core @pankod/refine-antd

然后更新所有相关依赖包到3.x版本：

npm i @pankod/refine-airtable@latest
npm i @pankod/refine-graphql@latest
# 其他相关包也需要类似更新

2. 调整导入路径

所有核心功能现在需要从@pankod/refine-core导入，而UI相关组件则从@pankod/refine-antd导入。

示例变更：

- import { Refine, useTable, List } from "@pankod/refine";
+ import { Refine } from "@pankod/refine-core";
+ import { useTable, List } from "@pankod/refine-antd";

3. 样式文件变更

Ant Design的样式文件路径也发生了变化：

- import "@pankod/refine/dist/styles.min.css";
+ import "@pankod/refine-antd/dist/reset.css";

关键组件迁移指南

1. 通知系统(Notification)

3.x版本中通知系统需要显式配置：

import { notificationProvider } from "@pankod/refine-antd";

<Refine
  notificationProvider={notificationProvider}
  // 其他配置...
/>

2. 布局与错误处理

布局和错误组件现在需要从Ant Design包中导入：

import { Layout, ErrorComponent } from "@pankod/refine-antd";

<Refine
  Layout={Layout}
  catchAll={<ErrorComponent />}
  // 其他配置...
/>

3. 登录页面

如果使用默认登录页面，需要从新包导入：

import { LoginPage } from "@pankod/refine-antd";

<Refine
  LoginPage={LoginPage}
  // 其他配置...
/>

4. 配置提供者

configProviderProps已被弃用，改为使用Ant Design的ConfigProvider：

import { ConfigProvider } from "@pankod/refine-antd";

<ConfigProvider direction="rtl">
  <Refine
    // 配置...
  />
</ConfigProvider>

常见问题解答

Q: 为什么需要拆分核心和UI包？ A: 这种架构使Refine更加灵活，开发者可以选择自己喜欢的UI框架，而不被限制在Ant Design中。

Q: 迁移后样式不生效怎么办？ A: 请确保已正确导入新的样式文件，并检查是否有其他自定义样式覆盖了默认样式。

Q: 是否可以逐步迁移？ A: 建议一次性完成迁移，因为2.x和3.x版本的API存在不兼容变更。

迁移后的优势

1. 更灵活的UI选择：可以轻松切换UI框架
2. 更清晰的代码结构：核心逻辑与UI表现分离
3. 更好的维护性：各功能模块职责更明确
4. 更小的包体积：按需引入所需功能

总结

Refine 3.x版本的架构调整使其成为一个真正的Headless框架，虽然迁移过程需要一些工作，但带来的灵活性和可扩展性值得投入。按照本文指南，开发者可以顺利完成迁移，享受新版本带来的诸多优势。

refine 一个用于构建内部工具、管理面板、仪表盘和B2B应用程序的React框架，具有无与伦比的灵活性。 项目地址: https://gitcode.com/gh_mirrors/re/refine