NgRx v14 升级指南：ng update 迁移、router-store 序列化器重构与 @ngrx/component 行为变更

前端状态管理【免费下载链接】platformReactive State for Angular项目地址https://gitcode.com/gh_mirrors/pl/platform点击查看免费下载本篇指南以 NgRx 官方 V14 Update Guide 为核心系统梳理从 v13 升级到 v14 的完整路径如何使用 Angular CLIng update自动迁移、确认版本依赖要求、逐项适配 router-store 序列化器重命名、component 包在无 zone 模式与LetDirective/PushPipe上的行为变化以及用LetModule/PushModule替换已弃用的ReactiveComponentModule。读完你可以直接照单执行升级并理解每处破坏性变更背后的源码实现与迁移原理。Angular CLI update一条命令完成依赖升级NgRx 支持通过 Angular CLI 的ng update命令升级依赖。升级过程中会自动执行对应的迁移 schematicsMigration Schematics这些 schematics 会替你修复一部分破坏性变更让升级过程更平滑。将包升级到 v14 最新发布版本只需在项目根目录执行ng update ngrx/store14执行后Angular CLI 会读取 NgRx 各包ngrx/store、ngrx/router-store、ngrx/effects、ngrx/component、ngrx/schematics等携带的迁移 schematic并逐一应用到你的工作区中。以 router-store 的序列化器重命名为例仓库中modules/router-store/migrations/14_0_0/index.ts正是这条迁移链的实现它通过visitTSSourceFiles遍历工程内所有 TypeScript 源文件凡是 import 声明中包含ngrx/router-store的文件都会执行renameSerializers()——先将DefaultRouterStateSerializer统一替换为FullRouterStateSerializer再对 import 声明、属性赋值如initializer、属性访问表达式以及变量声明的类型标注进行文本级替换最终通过commitChanges写回文件。因此升级后无需手工搜索替换代码中的旧序列化器名称会被自动纠正。Dependenciesv14 的最低版本要求升级前请确认项目满足以下最低版本要求Angular 版本14.xAngular CLI 版本14.xTypeScript 版本4.6.xRxJS 版本^6.5.3 || ^7.5.0也就是说NgRx v14 同时兼容 RxJS 66.5.3与 RxJS 77.5.0你可以在保持现有 RxJS 版本不变的前提下完成 NgRx 升级。TypeScript 4.6.x 与 Angular 14.x 是对应配套版本若项目仍停留在更早版本请先升级 Angular 与 TypeScript。Breaking changes破坏性变更逐项适配ngrx/router-store默认序列化器与序列化器命名调整router-store 在 v14 中调整了序列化器的默认值与命名直接影响你在StoreRouterConnectingModule.forRoot(...)中配置的serializer与routerState选项原DefaultRouterStateSerializer更名为FullRouterStateSerializer用于配合RouterState.FullMinimalRouterStateSerializer成为默认序列化器用于配合RouterState.Minimal。NgRx 提供了专门迁移自动将DefaultRouterStateSerializer重命名为FullRouterStateSerializer仓库中的实现位于 router-store 14_0_0 迁移其renames映射即为{ DefaultRouterStateSerializer: FullRouterStateSerializer }。从源码看两者定位差异非常清晰FullRouterStateSerializer 输出SerializedRouterStateSnapshot它会递归序列化整棵路由快照树保留routeConfig.component、paramMap、queryParamMap、component、root、parent、pathFromRoot等完整结构因此体积大、信息全适合需要完整路由上下文的场景MinimalRouterStateSerializer 输出MinimalRouterStateSnapshot只保留routeConfig.path/pathMatch/redirectTo/outlet/title、url、params、queryParams、fragment、data、outlet、title、firstChild与children等最小字段剔除了component、paramMap等重对象避免把组件引用存入 store从而显著减小状态体积。两者都继承自 RouterStateSerializer 抽象基类该基类约束自定义序列化器至少输出含url的状态并统一serialize(routerState: RouterStateSnapshot): T签名。如果你此前直接new DefaultRouterStateSerializer()并显式传入RouterState.Full升级后应改名为FullRouterStateSerializer如果之前未显式指定序列化器升级后默认行为即切换到MinimalRouterStateSerializerstore 中保存的 router 状态会自动变瘦。ngrx/component无 zone 模式下改用全局渲染策略ngrx/component在无 zonezone-less模式下将原先的本地渲染策略替换为全局渲染策略以获得更好的性能。变更前BEFORE在无 zone 模式下变更检测通过changeDetectorRef.detectChanges触发即只针对当前视图做局部检测。变更后AFTER在无 zone 模式下变更检测改为通过ɵmarkDirty触发即标记组件及其祖先为脏交由全局变更检测调度。这一变更的底层实现在 RenderScheduler它以Injectable()形式在组件/指令层级提供内部注入ChangeDetectorRef与TickSchedulerschedule()方法会将组件及其祖先标记为 dirty并在无 zone 模式下调度新一轮变更检测。LetDirective在Directive装饰器中直接providers: [RenderScheduler]见 let.directive.tsPushPipe也通过createRenderScheduler()走同一套机制见 push.pipe.ts。因此升级后无需改动模板与组件代码zone-less 场景下渲染路径会自动从detectChanges切到markForCheck/ɵmarkDirty的全局策略。ngrx/componentLetDirective上下文中的$error变为错误值LetDirective视图上下文中的$error属性其含义从是否出错的布尔标志改为具体的错误对象或undefined。BEFOREp *ngrxLetobs$; $error as e{{ e }}/p当obs$发出 error 事件时e为true当obs$发出 next/complete 事件时e为false。AFTERp *ngrxLetobs$; $error as e{{ e }}/p当obs$发出 error 事件时e为被抛出的错误对象当obs$发出 next/complete 事件时e为undefined。模板写法完全不变只是$error携带的信息从有没有错升级为错是什么。从当前源码看LetViewContext 除$implicit、ngrxLet外还暴露了error与complete上下文error直接保存错误对象complete为布尔标志并借助RenderScheduler在同步事件与非同步事件之间智能调度渲染。如果你的模板此前用$error做真假判断如*ngIf$error直接判断有错误升级后逻辑依然成立错误对象为真、undefined为假但若依赖$error true/false的严格比较需要改为判断是否为undefined。ngrx/component支持传入非 Observable 值v14 进一步放宽并收紧了对输入值的类型处理分为两点1. 传入null/undefined时上下文获得强类型BEFOREp *ngrxLetnull as n{{ n }}/p p *ngrxLetundefined as u{{ u }}/pn的类型为anyu的类型为any。AFTERp *ngrxLetnull as n{{ n }}/p p *ngrxLetundefined as u{{ u }}/pn的类型为nullu的类型为undefined。现在LetDirective的类型守卫ngTemplateContextGuard会基于输入值推导上下文类型模板中对别名变量的访问能得到准确的类型提示与编译期检查。2. 数组、可迭代对象、生成器函数与可读流不再被当作 observable 处理在 v13 中LetDirective/PushPipe会把这些类 observable输入自动当作可订阅源处理v14 起不再如此。若要保留原行为请先用rxjs的from函数将其转换为 observable再传给LetDirective/PushPipe。BEFOREComponent({ template: p *ngrxLetnumbers as n{{ n }}/p p{{ numbers | ngrxPush }}/p , }) export class NumbersComponent { numbers [1, 2, 3]; }AFTERComponent({ template: p *ngrxLetnumbers$ as n{{ n }}/p p{{ numbers$ | ngrxPush }}/p , }) export class NumbersComponent { numbers$ from([1, 2, 3]); }注意 AFTER 示例中需要先从rxjs导入from。这一收紧让输入语义更清晰ngrxLet/ngrxPush只负责要么渲染普通值要么订阅真正的 Observable可订阅源与非可订阅值之间的边界由类型系统严格约束对应实现见 potential-observable 相关逻辑 与 PushPipe。ngrx/schematics移除defaultCollectionngrx/schematics移除了defaultCollection选项改用 Angular 官方的schematicCollections。变更前通过angular.json中的cli.defaultCollection指定ngrx/schematics为默认集合变更后安装 schematics 时ngrx/schematics会被自动添加到angular.json文件的cli.schematicCollections数组中。NgRx 提供了专门迁移将ngrx/schematics自动加入schematicCollections。也就是说升级后无需手工编辑angular.json。迁移完成后你在 CLI 中直接执行ng generate例如ng g feature、ng g action时Angular CLI 会从schematicCollections中解析出ngrx/schematics提供的集合行为与旧的defaultCollection一致。若迁移未自动执行也可手动将ngrx/schematics补入cli.schematicCollections数组。Deprecations弃用项与替换方案ngrx/componentReactiveComponentModule弃用ReactiveComponentModule已弃用取而代之的是按需拆分的LetModule与PushModule。前者继续提供*ngrxLet指令后者提供ngrxPush管道。三种使用场景的迁移方式如下。场景一只用了*ngrxLet指令BEFOREimport { ReactiveComponentModule } from ngrx/component; NgModule({ imports: [ // ... other imports ReactiveComponentModule, ], }) export class MyFeatureModule {}AFTERimport { LetModule } from ngrx/component; NgModule({ imports: [ // ... other imports LetModule, ], }) export class MyFeatureModule {}场景二只用了ngrxPush管道BEFOREimport { ReactiveComponentModule } from ngrx/component; NgModule({ imports: [ // ... other imports ReactiveComponentModule, ], }) export class MyFeatureModule {}AFTERimport { PushModule } from ngrx/component; NgModule({ imports: [ // ... other imports PushModule, ], }) export class MyFeatureModule {}场景三同时使用*ngrxLet与ngrxPushimport { LetModule, PushModule } from ngrx/component; NgModule({ imports: [ // ... other imports LetModule, PushModule, ], }) export class MyFeatureModule {}从仓库证据看这条替换链路是有自动化支撑的虽然 v14 文档中该模块被标记为弃用仓库的 component 15_0_0-beta 迁移 提供了一份专门的迁移 schematic它会把ngrx/component导入中的ReactiveComponentModule替换为LetModule, PushModulereactiveComponentModuleReplacement LetModule, PushModule并同时处理NgModule.imports、NgModule.exports与 standaloneComponent.imports中的使用位置。对应的 迁移测试 也验证了在 NgModule 中替换与在 standalone 组件中替换两条路径输出均为import { LetModule, PushModule } from ngrx/component。升级检查清单完成 v14 升级后建议按以下清单逐项核对依赖版本Angular 14.x、Angular CLI 14.x、TypeScript 4.6.x、RxJS^6.5.3 || ^7.5.0执行迁移运行ng update ngrx/store14确认 router-store 序列化器重命名与 schematics 集合迁移均已应用DefaultRouterStateSerializer全部变为FullRouterStateSerializerangular.json中出现schematicCollections检查 router-store 配置确认StoreRouterConnectingModule使用的RouterState枚举与序列化器匹配Minimal对应默认序列化器Full对应FullRouterStateSerializer检查 component 用法将依赖$error布尔语义的模板改为判断错误对象/undefined把传入LetDirective/PushPipe的数组、可迭代对象、生成器函数、可读流用from()显式转成 observable将ReactiveComponentModule替换为LetModule与/或PushModule回归验证 zone-less 应用确认无 zone 模式下组件渲染正常渲染路径已切换到全局策略。以上要点对应文档原文位于 projects/www/src/app/pages/guide/migration/v14.md各迁移与实现的源码证据可分别在 router-store 迁移、serializers 目录 与 component 迁移 中查看。赞分享前端状态管理【免费下载链接】platformReactive State for Angular项目地址https://gitcode.com/gh_mirrors/pl/platform点击查看免费下载相关推荐读懂 NgRx Platform 的 CHANGELOG版本演进、破坏性变更与迁移路径v14 至 v22读懂 NgRx Platform 的 CHANGELOG版本演进、破坏性变更与迁移路径v14 至 v22 本文以仓库根目录的 CHANGELOG.md h前端状态管理如何成为python-fitparse维护者从用户到核心贡献者的完整路径指南如何成为python fitparse维护者从用户到核心贡献者的完整路径指南 想要为开源项目贡献力量但不知从何开始python fitparse作为一款专业物联网FreeJ2ME让经典Java手机游戏在现代设备上重生的完整指南FreeJ2ME让经典Java手机游戏在现代设备上重生的完整指南 还记得那些在诺基亚、索尼爱立信等老式手机上玩过的Java游戏吗《贪吃蛇》、《空间大战》、《上一篇NEP 52 深度解读NumPy 2.0 的 Python API 清理与命名空间重构下一篇Visual Studio 卸载工具从零到一开源方案彻底清除顽固残留创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考