Redux-Form 从 v5 迁移到 v6 的完整指南

阮曦薇Joe

于 2025-06-03 09:04:29 发布

阅读量252

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00343/article/details/148392755

Redux-Form 从 v5 迁移到 v6 的完整指南

redux-form A Higher Order Component using react-redux to keep form state in a Redux store 项目地址: https://gitcode.com/gh_mirrors/re/redux-form

前言

Redux-Form 是一个用于管理 React 表单状态的流行库。在 v6 版本中，它经历了一次重大的架构重构，这带来了显著的性能提升，但也意味着从 v5 升级到 v6 需要一些必要的代码修改。本文将详细解析这些变化，并提供清晰的迁移路径。

架构变化：控制反转

v6 版本最核心的变化是采用了控制反转的设计模式：

v5 架构问题：
- 只有最外层的表单组件连接到 Redux 状态
- 每次按键都会导致整个表单重新渲染
- 对于大型表单（几十或上百个字段）性能问题明显
v6 改进方案：
- 每个字段(Field)都直接连接到 Redux 存储
- 外层表单组件的连接方式优化，避免不必要的重渲染
- 这种变化显著提升了大型表单的性能

由于这种根本性的架构改变，v5 到 v6 没有渐进式的升级路径，必须进行完整的迁移。

字段处理：从 fields 到 Field 组件

v5 的实现方式

在 v5 中，你需要提供一个字段名称数组，然后通过 fields 属性获取字段对象：

// v5 示例
class MyForm extends React.Component {
  render() {
    const { fields: { username, password } } = this.props;
    return (
      <form>
        <input type="text" {...username} />
        <input type="password" {...password} />
      </form>
    );
  }
}

export default reduxForm({
  form: 'myForm',
  fields: ['username', 'password']  // 字段名称数组
})(MyForm);

v6 的新方式

v6 引入了 Field 组件，每个字段独立管理：

// v6 示例
const renderInput = ({ input, meta, type }) => (
  <div>
    <input {...input} type={type} />
    {meta.touched && meta.error && <span>{meta.error}</span>}
  </div>
);

class MyForm extends React.Component {
  render() {
    return (
      <form>
        <Field
          name="username"
          component={renderInput}
          type="text"
        />
        <Field
          name="password"
          component={renderInput}
          type="password"
        />
      </form>
    );
  }
}

export default reduxForm({
  form: 'myForm'
  // 不再需要 fields 数组
})(MyForm);

主要变化点

不再需要 fields 数组声明
使用 Field 组件替代直接展开字段对象
字段验证错误信息现在通过 meta 属性访问
可以创建可复用的字段渲染组件

表单提交处理

表单提交的主要变化是验证错误的处理方式：

v5 的提交处理

<MyForm
  onSubmit={values =>
    ajax.send(values).catch(error => {
      if (error.validationErrors) {
        return Promise.reject(error.validationErrors);
      }
      // 其他错误处理
    })
  }
/>

v6 的改进

<MyForm
  onSubmit={values =>
    ajax.send(values).catch(error => {
      if (error.validationErrors) {
        throw new SubmissionError(error.validationErrors);
      }
      // 其他错误处理
    })
  }
/>

关键变化是验证错误现在需要包装在 SubmissionError 对象中，这样可以明确区分验证错误和其他类型的错误。

状态映射与 Action 绑定

在 v5 中，reduxForm() 装饰器可以接受 mapStateToProps 和 mapDispatchToProps 参数。在 v6 中，这一功能被移除了，你需要手动使用 connect()：

// v6 方式
import { connect } from 'react-redux';
import { reduxForm } from 'redux-form';

class MyForm extends React.Component {
  // ...
}

const mapStateToProps = (state) => ({
  // 映射状态
});

const mapDispatchToProps = {
  // 绑定 action creators
};

export default connect(
  mapStateToProps,
  mapDispatchToProps
)(reduxForm({
  form: 'myForm'
})(MyForm));

验证机制

同步验证

同步验证在 v6 中保持不变，唯一需要注意的是如果使用 ImmutableJS，传入的 values 会是 Immutable.Map 类型，但错误信息仍需返回普通 JS 对象。

异步验证

异步验证的工作方式与 v5 完全相同，无需修改。

字段数组处理

对于字段数组（动态表单字段），v6 引入了 FieldArray 组件：

v5 的实现

render() {
  const { fields: { awards } } = this.props;
  return (
    <div>
      <ul>
        {awards.map((award, index) => (
          <li key={index}>
            <input type="text" {...award.input}/>
          </li>
        ))}
      </ul>
      <button onClick={() => awards.addField()}>Add Award</button>
    </div>
  );
}

v6 的新方式

const renderAwards = ({ fields }) => (
  <div>
    <ul>
      {fields.map((name, index) => (
        <li key={index}>
          <Field name={name} type="text" component="input"/>
        </li>
      ))}
    </ul>
    <button onClick={() => fields.push()}>Add Award</button>
  </div>
);

render() {
  return (
    <div>
      <FieldArray name="awards" component={renderAwards}/>
    </div>
  );
}

数据标准化（Normalization）

数据标准化的位置从 reducer 转移到了字段级别：

v5 的方式

const upper = value => value && value.toUpperCase();

const reducer = combineReducers({
  form: form.normalize({
    myForm: {
      myField: upper
    }
  })
});

v6 的方式

const upper = value => value && value.toUpperCase();

// 在组件中
<Field name="myField" component="input" normalize={upper}/>

状态结构变化

如果你使用了 plugin() API 监听其他 action，需要注意内部状态结构的变化：

v5 的状态结构

{
  myField: {
    value: 'myValue',
    initial: 'myInitialValue',
    asyncError: 'myAsyncError',
    submitError: 'mySubmitError',
    touched: true,
    visited: true
  }
}

v6 的新结构

{
  values: { myField: 'myValue' },
  initial: { myField: 'myInitialValue' },
  asyncErrors: { myField: 'myAsyncError' },
  submitErrors: { myField: 'mySubmitError' },
  fields: {
    myField: {
      touched: true,
      visited: true
    }
  }
}