ngx-formly 5.0 版本升级指南：核心变更与适配方案-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00049/article/details/148756615

ngx-formly 5.0 版本升级指南：核心变更与适配方案

ngx-formly 📝 JSON powered / Dynamic forms for Angular 项目地址: https://gitcode.com/gh_mirrors/ng/ngx-formly

前言

ngx-formly 是一个强大的 Angular 动态表单库，它允许开发者通过 JSON 配置快速构建复杂的表单界面。在 5.0 版本中，ngx-formly 引入了一些重要的 API 变更和架构调整，本文将详细解析这些变更，并提供平滑升级的解决方案。

核心模块变更 (@ngx-formly/core)

1. 自定义字段类型的生命周期方法调整

在 5.0 版本中，自定义字段类型不再需要调用父类的生命周期方法（如 ngOnInit、ngOnChanges 等）。这是 Angular 社区推荐的做法，简化了继承逻辑。

升级前代码：

export class CustomFormlyField extends FieldType {
  ngOnInit() {
    super.ngOnInit(); // 不再需要
    // 自定义逻辑
  }
}

升级后代码：

export class CustomFormlyField extends FieldType {
  ngOnInit() {
    // 直接编写自定义逻辑
  }
}

2. 表单验证消息组件简化

FormlyValidationMessage 组件移除了冗余的 fieldForm 输入属性，现在只需传入 field 即可。

升级前：

<formly-validation-message [field]="field" [fieldForm]="formcontrol"></formly-validation-message>

升级后：

<formly-validation-message [field]="field"></formly-validation-message>

3. 类型重命名

Field 类型被重命名为更语义化的 FieldType，这更准确地反映了其用途。

变更示例：

// 旧版
import { Field } from '@ngx-formly/core';

// 新版
import { FieldType } from '@ngx-formly/core';

4. 表单字段组件输入简化

formly-field 组件现在只需要 field 输入属性，其他属性（model、options、form）会自动从上下文中获取。

简化对比：

<!-- 旧版 -->
<formly-field [form]="form" [field]="field" [options]="options" [model]="model"></formly-field>

<!-- 新版 -->
<formly-field [field]="field"></formly-field>

5. 自定义控件创建方式变更

创建自定义表单控件的方式从 createControl 静态方法迁移到了 prePopulate 钩子中，这提供了更大的灵活性。

升级方案：

// 旧版方式（已废弃）
export class FormlyFieldCustomType extends FieldType {
  static createControl(model: any, field: FormlyFieldConfig): AbstractControl {
    return new FormControl(...);
  }
}

// 新版推荐方式
export class FormlyFieldCustomType extends FieldType {
  prePopulate(field: FormlyFieldConfig) {
    if (field.formControl) {
      return;
    }
    field.formControl = new FormControl(...);
  }
}

6. 生命周期钩子重构

lifecycle 选项被重命名为 hooks，并且回调函数的参数结构发生了变化，现在接收完整的 field 对象。

变更示例：

// 旧版
fields = [{
  key: 'email',
  lifecycle: {
    onInit: (form, field, model, options) => { /*...*/ }
  }
}]

// 新版
fields = [{
  key: 'email',
  hooks: {
    onInit: (field) => {
      const { form, model, options } = field;
      /*...*/
    }
  }
}]

7. 扩展机制变更

manipulators 配置被更通用的 extension 机制取代，提供了更清晰的扩展方式。

配置变更：

// 旧版
FormlyModule.forRoot({
  manipulators: [{ method: 'run', class: TemplateAddons }],
})

// 新版
FormlyModule.forRoot({
  extensions: [{ name: 'addons', extension: addonsExtension }],
})