Angular Material V9 HammerJS 迁移完全指南移除手势依赖与 GestureConfig 迁移方案【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/componentsAngular Material 自 v9 起不再要求任何组件依赖 HammerJS此前依赖 HammerJS 的组件也不再提供可用于模板事件绑定的HAMMER_GESTURE_CONFIG。本文以当前仓库 guides/v9-hammerjs-migration.md 为骨架结合仓库源码逐一拆解迁移原因、schematic 自动迁移的执行步骤、GestureConfig废弃引用的处理方式、测试迁移策略以及迁移报告歧义用法时的两种处置方案帮助你在升级 v9 时干净利落地移除 HammerJS。为什么需要迁移在 v8 及更早版本中部分 Angular Material 组件如滑块的拖拽交互、滑动开关等依赖 HammerJS 提供手势识别能力。许多项目纯粹是为了 Angular Material 才安装hammerjs依赖。当升级到 v9 后所有组件的手势能力均已由组件内部的原生实现替代不再依赖 HammerJSAngular Material 不再提供HAMMER_GESTURE_CONFIG来启用模板中的 HammerJS 事件angular/material/core导出的GestureConfig被标记为废弃deprecated并将在 v10 中正式移除。这一现状在当前仓库中可以得到印证查看 src/material/package.json 的peerDependencies其中只包含angular/cdk、angular/core、angular/common、angular/forms、angular/platform-browser与rxjs已经完全没有hammerjs的身影再看 src/material/core/public-api.tsGestureConfig也已不在公开导出之列说明 v10 之后该符号确实被彻底移除。因此迁移的意义有两层清理无用依赖如果 HammerJS 只是为 Angular Material 而装、应用本身并未直接使用升级 v9 后应将其从项目中移除补齐事件配置如果应用在模板中直接使用了 HammerJS 事件如(swipe)、(pan)等此前是依赖 Angular Material 模块帮忙注册 HammerJS 事件插件HammerModule提供的能力在 Angular 8 及以下默认开启v9 后必须手动引入 Angular 的HammerModule才能继续使用这些事件绑定。迁移工具做了什么升级时通过ng update触发的迁移 schematic 会自动完成三类工作自动移除 HammerJS——如果检测到 HammerJS 未被应用直接使用则从项目中整体移除生成应用级手势配置——如果应用直接使用了 Angular MaterialGestureConfig中定义的自定义手势如slide、slide-start、slide-end、swipe、swipe-start、swipe-end等迁移会生成一份应用专属的新手势配置消除对废弃GestureConfig的依赖补充HammerModule导入——只要检测到应用使用了GestureConfig提供的自定义手势或 HammerJS 默认手势迁移就会在相应模块中导入 Angular 的HammerModule恢复模板事件绑定能力该能力在 Angular 8 及以下默认开启。迁移的触发入口由包的ng-update元数据声明见 src/material/package.json 中ng-update: { migrations: ./schematics/migration.json }schematic 集合定义在 src/material/schematics/migration.json。需要说明的是当前仓库的迁移清单只包含 v22 迁移migration-v22HammerJS 迁移属于 v9 时代的历史迁移早已随版本演进从迁移清单中移除——这本身也从侧面印证了 HammerJS 已是过去式。特例如果应用同时满足提供了自定义HAMMER_GESTURE_CONFIG且还引用了废弃的 Angular MaterialGestureConfig迁移无法自动处理会打印歧义警告需要人工干预详见下文歧义用法一节。schematic 如何移除 HammerJSHammerJS 的引入方式多种多样迁移只覆盖最常见、也是 Angular Material 历史上推荐过的几种方式。迁移依次执行以下三步清理1. 从 package.json 移除依赖{ dependencies: { hammerjs: ... } }迁移会删除dependencies及devDependencies中的hammerjs条目。2. 移除 index.html 中的脚本引入script srchttps://my-cdn.io/hammer.min.js/script通过 CDN 或本地静态资源方式引入的hammer.min.js脚本标签会被删除。3. 移除 side-effect 导入import hammerjs;只为了注册全局 Hammer 实例而写的副作用导入side-effect import会被自动清除。局限说明迁移无法自动清理测试中的 HammerJS 引用例如 src/test.ts 中的import hammerjs;。测试设置需要手动清理并逐一解决测试报错具体见下文测试迁移一节。如何迁移废弃的GestureConfig引用GestureConfig的消费方式有多种迁移覆盖最常见的一种在NgModule的providers中直接提供GestureConfigimport {GestureConfig} from angular/material/core; NgModule({ ... providers: [ {provide: HAMMER_GESTURE_CONFIG, useClass: GestureConfig} ], }) export class AppModule {}针对该模式迁移按以下逻辑处理若模板确实用到了废弃配置提供的手势事件说明组件依赖GestureConfig才能使用模板中的 HammerJS 事件。迁移会自动创建一个新的手势配置该配置支持被使用到的 HammerJS 事件并把所有指向废弃GestureConfig的引用重写为新建的配置。HAMMER_GESTURE_CONFIG提供者仍由 Angular 平台自带应用只需保证HammerModule已导入若模板没有用到任何废弃配置提供的事件providers声明可以被安全移除迁移会自动完成删除。以下模式迁移无法自动处理只会被报告并要求人工清理继承extends GestureConfig废弃配置注入inject(GestureConfig)废弃配置将废弃配置与其他自定义手势配置组合使用。如何迁移测试如果你的组件测试涉及 Angular Material 组件的手势交互需要按以下顺序处理识别失败的手势测试找出所有因手势支持变更而失败的用例重写或删除手势测试改用派发真实 DOM 事件如mousedown/mouseup/click、触摸事件序列来模拟手势无法改造的测试直接删除。特别地针对mat-slide-toggle的手势测试应当删除——mat-slide-toggle在新版本中不再支持手势交互处理依赖废弃GestureConfig的测试引用要么删除并改用 DOM 事件重写测试要么改为指向迁移新建的手势配置清理提供 HammerJS 的测试设置如果迁移已从项目中移除 HammerJS需要重构测试入口文件通常是 src/test.ts中引入 HammerJS 的代码import hammerjs;当前仓库中mat-slide-toggle的实现与测试恰好印证了这一迁移结果查看 src/material/slide-toggle/slide-toggle.ts组件只保留change与toggleChange两个Output没有任何基于手势的事件而 src/material/slide-toggle/slide-toggle.spec.ts 中的交互测试也全部改用labelElement.click()、buttonElement.click()派发点击事件来驱动断言dragTriggered计数恒为 0说明拖拽手势逻辑已被彻底移除、测试以 DOM 事件取代。迁移报告歧义用法时该怎么办迁移基于静态分析检测模板事件绑定无法百分之百确定某个事件绑定最终绑定到 Hammer 手势插件还是组件的真实Output因此在以下两种情况下会打印警告。Case 1无法确定事件绑定归属模板中出现了既可能是废弃GestureConfig事件、又可能是组件Output的事件绑定。例如image-rotator (rotate)onRotate()/image-rotatorrotate既可能是废弃GestureConfig提供的手势事件也可能是image-rotator的Output。迁移无法静态区分因此可能错误地保留了 HammerJS。此时请人工判断若rotate确实是组件Output可以手动将 HammerJS 从项目中移除若确实需要手势事件则保留并导入HammerModule。Case 2废弃配置与自定义配置混用应用同时存在自定义HAMMER_GESTURE_CONFIG与废弃的 Angular MaterialGestureConfig。由于迁移无法判断某个手势事件绑定对应的是自定义配置还是废弃配置会报告警告。此时需要人工确认如果应用并未使用废弃GestureConfig提供的手势事件删除对它的引用如果需要保留这些事件则更新现有的自定义手势配置使其覆盖废弃 Angular MaterialGestureConfig原本提供的事件。迁移清单与注意事项完成迁移后建议做一次全面自检全局搜索hammerjs、GestureConfig、HammerModule关键字确认没有残留引用运行项目测试重点检查滑块mat-slider与滑动开关mat-slide-toggle相关的交互用例确认模板中使用的手势事件(swipe)、(pan)、(pinch)、(rotate)等所在模块已导入HammerModule。遵循上述步骤即可在升级到 Angular Material v9 时彻底摆脱 HammerJS 的历史包袱同时保证手势相关功能在新版本中的行为一致。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
