ngx-formly 7.0 升级指南：从 6.0 迁移到 7.0 的关键变化

ngx-formly 7.0 升级指南：从 6.0 迁移到 7.0 的关键变化

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

前言

ngx-formly 是一个强大的 Angular 表单构建库，它通过 JSON 配置的方式简化了复杂表单的开发。随着 7.0 版本的发布，ngx-formly 引入了一些重要的变化和改进。本文将详细介绍从 6.0 升级到 7.0 版本需要注意的关键变更点，帮助开发者顺利完成迁移。

环境要求变更

首先需要注意的是，ngx-formly 7.0 对 Angular 版本的要求有所提高：

• 最低 Angular 版本要求：现在需要 Angular 18 或更高版本

这意味着如果你的项目还在使用 Angular 17 或更早版本，你需要先升级 Angular 框架本身，然后才能使用 ngx-formly 7.0。

核心变化：独立组件(Standalone Components)支持

7.0 版本最重要的新特性是全面支持 Angular 的独立组件(Standalone Components)模式。这一变化顺应了 Angular 的发展方向，为开发者提供了更灵活的组件使用方式。

新旧 API 对比

ngx-formly 7.0 提供了与独立组件兼容的新 API，同时也保留了传统的 NgModule 方式。下面是新旧 API 的对比表：

| NgModule API | 独立组件替代 API | |-------------------------|--------------------------| | FormlyModule | FormlyForm | | FormlyModule.forRoot | provideFormlyCore | | FormlyModule.forChild | provideFormlyConfig | | FormlyBootstrapModule | withFormlyBootstrap | | FormlyMaterialModule | withFormlyMaterial | | Formly{...UI}Module | withFormly{...UI} |

使用说明

1. 传统 NgModule 方式：如果你仍然使用 NgModule 组织代码，可以继续使用原有的 API，不需要做任何改变。

2. 独立组件方式：如果你想采用独立组件模式，可以使用新的 API 替代原有的 NgModule 导入方式。

3. 混合使用：两种方式可以共存于同一个项目中，ngx-formly 7.0 完全支持这种渐进式迁移策略。

废弃 API 移除

ngx-formly 7.0 清理了一些在之前版本中已经被标记为废弃的 API。下面是这些被移除的 API 及其替代方案：

| 废弃方法 | 替代方法 | |--------------------|----------------------| | _markForCheck | detectChanges | | _buildForm | build | | _markForCheck | checkExpressions |

迁移建议

1. 全局搜索：在你的代码库中搜索上述废弃方法，确保没有遗漏。

2. 逐步替换：对于每个找到的废弃方法调用，按照上表的对应关系进行替换。

3. 测试验证：替换完成后，务必进行全面的测试，特别是表单的动态更新和表达式计算功能。

升级策略建议

为了确保平稳升级，建议采取以下步骤：

1. 备份项目：在进行任何重大升级前，确保项目有完整备份。

2. 升级 Angular：首先将 Angular 升级到 18 或更高版本。

3. 逐步替换：可以先替换废弃的 API，然后再考虑是否要迁移到独立组件模式。

4. 测试验证：在每个步骤完成后运行完整的测试套件。

5. 性能监控：升级后监控应用性能，特别是表单密集的页面。

总结

ngx-formly 7.0 带来了对 Angular 最新特性的支持，特别是独立组件模式，为开发者提供了更多的选择和灵活性。虽然升级过程需要一些工作，但这些改进将为项目带来更好的可维护性和未来发展空间。

通过遵循本文的指导，你应该能够顺利完成从 6.0 到 7.0 的升级过程。如果在迁移过程中遇到任何问题，建议查阅最新的官方文档获取更多细节和示例。

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