PrimeNG v21 迁移指南无破坏升级策略、CSS 动画迁移与弃用 API 处理【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng导读本文是 PrimeNGAngular UI 组件库v21 的官方迁移指南面向从 v20或更早版本升级到 v21 的开发者。文章将详细解读 v21 唯一的破坏性变更——从 Angular animations 包迁移到原生 CSS 动画说明showTransitionOptions/hideTransitionOptions的弃用与替代方案并完整覆盖 v21 的弃用清单、移除项与新特性。读完本文你将能安全完成 v21 升级并掌握基于motionOptions与p-motion/pMotion的新动画定制方式。一、v21 升级策略基本可视为无缝替换从 PrimeNG v20 开始PrimeTek 对增量主版本升级采用了“无破坏性变更no-breaking-change”政策v21 延续了这一政策唯一例外是动画相关的 API详见下文第二节。这意味着除动画定制场景外v21 可以视为 drop-in replacement直接替换。升级时只需更新依赖版本现有组件代码无需大规模改动如果升级过程中遇到任何问题官方建议在 GitHub 上提交 issue 反馈。二、唯一破坏性变更从 Angular animations 迁移到原生 CSS 动画2.1 变更背景由于 Angular 在 v20.2 中弃用了angular/animationsanimations包PrimeNG v21 将组件动画全面迁移到了原生 CSS 动画方案。这一迁移直接影响了 animations API 中的两个属性showTransitionOptionshideTransitionOptions2.2 破坏性影响说明这两个属性在 v21 中已被弃用且不再生效。官方文档特别强调v21 不会因为这两个属性报错属性仍然存在但你的自定义动画配置将被忽略。也就是说升级后代码可以正常编译运行但通过showTransitionOptions/hideTransitionOptions定制的动画效果会静默失效这是升级后最容易被忽略的“隐性破坏”。从源码可以印证这一点overlayoptions.ts 中这两个字段已标注/** * The transition options for showing the overlay. * deprecated since v21.0.0. Use motionOptions instead. */ showTransitionOptions?: string; /** * The transition options for hiding the overlay. * deprecated since v21.0.0. Use motionOptions instead. */ hideTransitionOptions?: string; /** * The motion options for the overlay. */ motionOptions?: MotionOptions;同样在组件层面例如 datepicker.ts 中/** * Transition options of the show animation. * group Props * deprecated since v21.0.0, use motionOptions instead. */ Input() showTransitionOptions: string .12s cubic-bezier(0, 0, 0.2, 1); /** * Transition options of the hide animation. * group Props * deprecated since v21.0.0, use motionOptions instead. */ Input() hideTransitionOptions: string .1s linear;并在同文件datepicker.ts新增了替代输入motionOptions inputMotionOptions | undefined(undefined);2.3 新方案motionOptions与p-motion/pMotion如果你此前使用上述两个属性定制动画请改用新的动画 API。仓库中新增的motion模块packages/primeng/src/motion提供了两种使用方式组件形式p-motionmotion.component.ts和指令形式pMotionmotion.directive.ts二者输入输出基本一致输入组件 / 指令别名说明默认值visible元素是否可见falsemountOnEnter/unmountOnLeave进入时挂载、离开时卸载truename动画名称可使用预定义 motion 名称或自定义名称undefinedtype动画类型合法值为transition和animationundefinedduration动画时长undefinedenter/leave/appear是否执行进入 / 离开 / 首次出现动画true/true/falsehideStrategy隐藏策略display或visibilitydisplayenterFromClass/enterToClass/enterActiveClass进入动画的 from / to / active 类undefinedleaveFromClass/leaveToClass/leaveActiveClass离开动画的 from / to / active 类undefinedoptions指令为pMotionOptions完整的MotionOptions配置对象{}指令形式还暴露了完整的事件输出pMotionOnBeforeEnter、pMotionOnEnter、pMotionOnAfterEnter、pMotionOnEnterCancelled、pMotionOnBeforeLeave、pMotionOnLeave、pMotionOnAfterLeave等便于在动画各阶段挂接回调motion.directive.ts。此外动画阶段类遵循 Vue 风格的命名约定[name]-enter、[name]-enter-active、[name]-enter-to、[name]-leave、[name]-leave-active、[name]-leave-to与primeuix/motion的createMotion配合使用源码见 motion.directive.ts。2.4 内置 CSS 动画类参考原生 CSS 动画通过样式类 keyframes 组合实现.{classname}-enter-active与.{classname}-leave-active指定动画名称、时长和缓动函数。你既可以全局覆盖默认动画类影响所有组件也可以给单个组件添加作用域类来独立修改其动画。各组件对应的内置动画类可参考 animations 文档下表为关键组件清单组件进入类离开类Accordion / Panel / Fieldset / Stepper / PanelMenu.p-collapsible-enter-active.p-collapsible-leave-activeAutoComplete / CascadeSelect / ColorPicker / ConfirmPopup / ContextMenu / DatePicker / Menu / MultiSelect / Password / Select / TieredMenu / TreeSelect.p-anchored-overlay-enter-active.p-anchored-overlay-leave-activeDialog.p-dialog-enter-active.p-dialog-leave-activeDrawer.p-drawer-enter-active.p-drawer-leave-activeGalleria.p-galleria-enter-active.p-galleria-leave-activeImage.p-image-original-enter-active.p-image-original-leave-activeMessage.p-message-enter-active.p-message-leave-activeModal Masks.p-overlay-mask-enter-active.p-overlay-mask-leave-activeToast.p-toast-message-enter-active.p-toast-message-leave-active如需禁用或减弱个别动画可通过调整动画时长实现详见动画文档的 Disable 一节。三、v21 弃用清单Deprecationsv21 标记弃用的项目如下表均计划在 v22 中移除API弃用版本替代方案移除版本showTransitionOptionsv21原生 CSS 动画motionOptions等v22hideTransitionOptionsv21原生 CSS 动画motionOptions等v22指令型 PT 属性名如ptInputTextv21PT 后缀命名如pInputTextPTv22contextMenuSelectionMode的joint模式v21使用separate模式适用于 Tree、TreeTable、Tablev223.1 指令型 PT 属性重命名ptInputText→pInputTextPT为统一 PassThrough 命名规范v21 将指令上的 PT 属性名从ptInputText这类前缀式改成了pInputTextPT后缀式。源码证据见 inputtext.ts/** * Used to pass attributes to DOM elements inside the InputText component. * deprecated use pInputTextPT instead. */ ptInputText inputInputTextPassThrough(); /** * Used to pass attributes to DOM elements inside the InputText component. */ pInputTextPT inputInputTextPassThrough();实际读取逻辑也兼容了两者this.ptInputText() || this.pInputTextPT()。升级建议将代码中的ptInputText等旧名直接替换为pInputTextPT并在 v22 之前完成迁移。3.2contextMenuSelectionMode移除joint模式contextMenuSelectionMode用于定义右键菜单选择行为separate独立模式上下文菜单更新独立的contextMenuSelection属性joint联合模式与行选择共用同一个selection属性开启行选择时右键选择会与行选择联动。v21 起joint模式被弃用v22 将彻底移除统一采用separate。该属性涉及 Table、Tree、TreeTable 三个组件源码中的默认值并不一致升级时请特别核对table.ts默认separatetree.ts默认jointtreetable.ts默认separate两种模式的分支逻辑可分别查看 table.ts 与 treetable.tsseparate模式只更新contextMenuSelectionjoint模式则写入selection并触发selectionChange同时也会同步更新contextMenuSelection。相关行为在 tree.spec.ts、treetable.spec.ts 中均有测试用例覆盖。升级建议将 Tree 中显式指定的contextMenuSelectionModejoint改为separateTable / TreeTable 默认即separate无需改动并调整依赖“右键即选中行”的业务逻辑。四、v21 移除项Removalsv21没有任何 API 被移除。关于计划在 v22 中移除的 API 清单请参考 v20 迁移文档的弃用章节例如primeng/themes→primeuix/themes、pTemplate→ 模板引用变量、CamelCase 选择器 → Kebab case、styleClass→class等建议在 v21 阶段就着手迁移这些已被弃用的 API。五、v21 新特性亮点Whats NewPrimeNG v21 是 PrimeTek 产品愿景的一次重大推进主要亮点如下PassThrough attributesPT 属性增强定制通过每个组件内置的pt属性直接访问底层 DOM 元素自由施加样式、aria、data-*或自定义属性与事件监听实现“Your Components, Not Ours”的定制哲学。PT 对象可在组件级或全局providePrimeNG的pt选项定义组件级优先级更高还支持生命周期钩子hooks、子组件pc前缀命名与ptOptions合并策略mergeSections/mergeProps详见 PassThrough 文档。Unstyled Mode无样式模式完全移除设计令牌的 CSS 变量及其规则集只保留核心功能与无障碍支持配合 Tailwind CSS PassThrough 实现完全自由的样式控制。可通过providePrimeNG({ unstyled: true })全局开启或对单个组件使用unstyled属性示例见 unstyled 文档。现代 CSS 动画Modern CSS-based animations即本文第二节所述的核心变更动画体系全面基于 CSS 实现。provideAnimationsAsync可安全移除由于动画已不再依赖angular/animations应用中已弃用的provideAnimationsAsync提供者可以且建议移除从而减小打包体积、简化引导配置。初始 Zoneless 支持v21 开始支持 Angular 的 Zoneless 变更检测以提升运行时性能。仓库 showcase 自身已在 app.config.ts 中使用provideZonelessChangeDetection()且大量组件测试如 accordion.spec.ts也通过provideZonelessChangeDetection()运行可作为实践参考。AI 增强文档面向开发者体验的 AI 辅助文档改进。六、升级注意事项primeuix依赖版本检查升级 v21 时请确保内部包版本满足要求内部包primeuix/styles和primeuix/themes版本应为2.0.2 或更高。全新安装时这些包会自动更新。如果你在升级后发现视觉效果或动画异常请优先检查这两个包的版本是否过旧。从 v20 起PrimeNG 已迁移到 PrimeUIX 共享主题体系组件样式来自primeuix/styles设计令牌主题预设来自primeuix/themes相关说明见 v20 迁移文档。七、升级检查清单全局搜索代码中的showTransitionOptions/hideTransitionOptions改用motionOptions或 CSS 动画类定制全局搜索ptInputText等指令型 PT 旧命名替换为pInputTextPT后缀命名检查 Tree / TreeTable / Table 的contextMenuSelectionMode移除joint模式的使用移除已弃用的provideAnimationsAsync以及angular/animations相关导入确认primeuix/styles与primeuix/themes不低于 2.0.2必要时重新安装依赖如需 Zoneless 优化参照 app.config.ts 在应用配置中加入provideZonelessChangeDetection()顺带核对 v20 迁移文档 中计划于 v22 移除的弃用 API尽早迁移。按照以上步骤完成迁移后即可平滑享受 v21 带来的 CSS 动画体系、PassThrough 深度定制、Unstyled 模式与 Zoneless 性能提升。【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PrimeNG v21 迁移指南：无破坏升级策略、CSS 动画迁移与弃用 API 处理
PrimeNG v21 迁移指南无破坏升级策略、CSS 动画迁移与弃用 API 处理【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng导读本文是 PrimeNGAngular UI 组件库v21 的官方迁移指南面向从 v20或更早版本升级到 v21 的开发者。文章将详细解读 v21 唯一的破坏性变更——从 Angular animations 包迁移到原生 CSS 动画说明showTransitionOptions/hideTransitionOptions的弃用与替代方案并完整覆盖 v21 的弃用清单、移除项与新特性。读完本文你将能安全完成 v21 升级并掌握基于motionOptions与p-motion/pMotion的新动画定制方式。一、v21 升级策略基本可视为无缝替换从 PrimeNG v20 开始PrimeTek 对增量主版本升级采用了“无破坏性变更no-breaking-change”政策v21 延续了这一政策唯一例外是动画相关的 API详见下文第二节。这意味着除动画定制场景外v21 可以视为 drop-in replacement直接替换。升级时只需更新依赖版本现有组件代码无需大规模改动如果升级过程中遇到任何问题官方建议在 GitHub 上提交 issue 反馈。二、唯一破坏性变更从 Angular animations 迁移到原生 CSS 动画2.1 变更背景由于 Angular 在 v20.2 中弃用了angular/animationsanimations包PrimeNG v21 将组件动画全面迁移到了原生 CSS 动画方案。这一迁移直接影响了 animations API 中的两个属性showTransitionOptionshideTransitionOptions2.2 破坏性影响说明这两个属性在 v21 中已被弃用且不再生效。官方文档特别强调v21 不会因为这两个属性报错属性仍然存在但你的自定义动画配置将被忽略。也就是说升级后代码可以正常编译运行但通过showTransitionOptions/hideTransitionOptions定制的动画效果会静默失效这是升级后最容易被忽略的“隐性破坏”。从源码可以印证这一点overlayoptions.ts 中这两个字段已标注/** * The transition options for showing the overlay. * deprecated since v21.0.0. Use motionOptions instead. */ showTransitionOptions?: string; /** * The transition options for hiding the overlay. * deprecated since v21.0.0. Use motionOptions instead. */ hideTransitionOptions?: string; /** * The motion options for the overlay. */ motionOptions?: MotionOptions;同样在组件层面例如 datepicker.ts 中/** * Transition options of the show animation. * group Props * deprecated since v21.0.0, use motionOptions instead. */ Input() showTransitionOptions: string .12s cubic-bezier(0, 0, 0.2, 1); /** * Transition options of the hide animation. * group Props * deprecated since v21.0.0, use motionOptions instead. */ Input() hideTransitionOptions: string .1s linear;并在同文件datepicker.ts新增了替代输入motionOptions inputMotionOptions | undefined(undefined);2.3 新方案motionOptions与p-motion/pMotion如果你此前使用上述两个属性定制动画请改用新的动画 API。仓库中新增的motion模块packages/primeng/src/motion提供了两种使用方式组件形式p-motionmotion.component.ts和指令形式pMotionmotion.directive.ts二者输入输出基本一致输入组件 / 指令别名说明默认值visible元素是否可见falsemountOnEnter/unmountOnLeave进入时挂载、离开时卸载truename动画名称可使用预定义 motion 名称或自定义名称undefinedtype动画类型合法值为transition和animationundefinedduration动画时长undefinedenter/leave/appear是否执行进入 / 离开 / 首次出现动画true/true/falsehideStrategy隐藏策略display或visibilitydisplayenterFromClass/enterToClass/enterActiveClass进入动画的 from / to / active 类undefinedleaveFromClass/leaveToClass/leaveActiveClass离开动画的 from / to / active 类undefinedoptions指令为pMotionOptions完整的MotionOptions配置对象{}指令形式还暴露了完整的事件输出pMotionOnBeforeEnter、pMotionOnEnter、pMotionOnAfterEnter、pMotionOnEnterCancelled、pMotionOnBeforeLeave、pMotionOnLeave、pMotionOnAfterLeave等便于在动画各阶段挂接回调motion.directive.ts。此外动画阶段类遵循 Vue 风格的命名约定[name]-enter、[name]-enter-active、[name]-enter-to、[name]-leave、[name]-leave-active、[name]-leave-to与primeuix/motion的createMotion配合使用源码见 motion.directive.ts。2.4 内置 CSS 动画类参考原生 CSS 动画通过样式类 keyframes 组合实现.{classname}-enter-active与.{classname}-leave-active指定动画名称、时长和缓动函数。你既可以全局覆盖默认动画类影响所有组件也可以给单个组件添加作用域类来独立修改其动画。各组件对应的内置动画类可参考 animations 文档下表为关键组件清单组件进入类离开类Accordion / Panel / Fieldset / Stepper / PanelMenu.p-collapsible-enter-active.p-collapsible-leave-activeAutoComplete / CascadeSelect / ColorPicker / ConfirmPopup / ContextMenu / DatePicker / Menu / MultiSelect / Password / Select / TieredMenu / TreeSelect.p-anchored-overlay-enter-active.p-anchored-overlay-leave-activeDialog.p-dialog-enter-active.p-dialog-leave-activeDrawer.p-drawer-enter-active.p-drawer-leave-activeGalleria.p-galleria-enter-active.p-galleria-leave-activeImage.p-image-original-enter-active.p-image-original-leave-activeMessage.p-message-enter-active.p-message-leave-activeModal Masks.p-overlay-mask-enter-active.p-overlay-mask-leave-activeToast.p-toast-message-enter-active.p-toast-message-leave-active如需禁用或减弱个别动画可通过调整动画时长实现详见动画文档的 Disable 一节。三、v21 弃用清单Deprecationsv21 标记弃用的项目如下表均计划在 v22 中移除API弃用版本替代方案移除版本showTransitionOptionsv21原生 CSS 动画motionOptions等v22hideTransitionOptionsv21原生 CSS 动画motionOptions等v22指令型 PT 属性名如ptInputTextv21PT 后缀命名如pInputTextPTv22contextMenuSelectionMode的joint模式v21使用separate模式适用于 Tree、TreeTable、Tablev223.1 指令型 PT 属性重命名ptInputText→pInputTextPT为统一 PassThrough 命名规范v21 将指令上的 PT 属性名从ptInputText这类前缀式改成了pInputTextPT后缀式。源码证据见 inputtext.ts/** * Used to pass attributes to DOM elements inside the InputText component. * deprecated use pInputTextPT instead. */ ptInputText inputInputTextPassThrough(); /** * Used to pass attributes to DOM elements inside the InputText component. */ pInputTextPT inputInputTextPassThrough();实际读取逻辑也兼容了两者this.ptInputText() || this.pInputTextPT()。升级建议将代码中的ptInputText等旧名直接替换为pInputTextPT并在 v22 之前完成迁移。3.2contextMenuSelectionMode移除joint模式contextMenuSelectionMode用于定义右键菜单选择行为separate独立模式上下文菜单更新独立的contextMenuSelection属性joint联合模式与行选择共用同一个selection属性开启行选择时右键选择会与行选择联动。v21 起joint模式被弃用v22 将彻底移除统一采用separate。该属性涉及 Table、Tree、TreeTable 三个组件源码中的默认值并不一致升级时请特别核对table.ts默认separatetree.ts默认jointtreetable.ts默认separate两种模式的分支逻辑可分别查看 table.ts 与 treetable.tsseparate模式只更新contextMenuSelectionjoint模式则写入selection并触发selectionChange同时也会同步更新contextMenuSelection。相关行为在 tree.spec.ts、treetable.spec.ts 中均有测试用例覆盖。升级建议将 Tree 中显式指定的contextMenuSelectionModejoint改为separateTable / TreeTable 默认即separate无需改动并调整依赖“右键即选中行”的业务逻辑。四、v21 移除项Removalsv21没有任何 API 被移除。关于计划在 v22 中移除的 API 清单请参考 v20 迁移文档的弃用章节例如primeng/themes→primeuix/themes、pTemplate→ 模板引用变量、CamelCase 选择器 → Kebab case、styleClass→class等建议在 v21 阶段就着手迁移这些已被弃用的 API。五、v21 新特性亮点Whats NewPrimeNG v21 是 PrimeTek 产品愿景的一次重大推进主要亮点如下PassThrough attributesPT 属性增强定制通过每个组件内置的pt属性直接访问底层 DOM 元素自由施加样式、aria、data-*或自定义属性与事件监听实现“Your Components, Not Ours”的定制哲学。PT 对象可在组件级或全局providePrimeNG的pt选项定义组件级优先级更高还支持生命周期钩子hooks、子组件pc前缀命名与ptOptions合并策略mergeSections/mergeProps详见 PassThrough 文档。Unstyled Mode无样式模式完全移除设计令牌的 CSS 变量及其规则集只保留核心功能与无障碍支持配合 Tailwind CSS PassThrough 实现完全自由的样式控制。可通过providePrimeNG({ unstyled: true })全局开启或对单个组件使用unstyled属性示例见 unstyled 文档。现代 CSS 动画Modern CSS-based animations即本文第二节所述的核心变更动画体系全面基于 CSS 实现。provideAnimationsAsync可安全移除由于动画已不再依赖angular/animations应用中已弃用的provideAnimationsAsync提供者可以且建议移除从而减小打包体积、简化引导配置。初始 Zoneless 支持v21 开始支持 Angular 的 Zoneless 变更检测以提升运行时性能。仓库 showcase 自身已在 app.config.ts 中使用provideZonelessChangeDetection()且大量组件测试如 accordion.spec.ts也通过provideZonelessChangeDetection()运行可作为实践参考。AI 增强文档面向开发者体验的 AI 辅助文档改进。六、升级注意事项primeuix依赖版本检查升级 v21 时请确保内部包版本满足要求内部包primeuix/styles和primeuix/themes版本应为2.0.2 或更高。全新安装时这些包会自动更新。如果你在升级后发现视觉效果或动画异常请优先检查这两个包的版本是否过旧。从 v20 起PrimeNG 已迁移到 PrimeUIX 共享主题体系组件样式来自primeuix/styles设计令牌主题预设来自primeuix/themes相关说明见 v20 迁移文档。七、升级检查清单全局搜索代码中的showTransitionOptions/hideTransitionOptions改用motionOptions或 CSS 动画类定制全局搜索ptInputText等指令型 PT 旧命名替换为pInputTextPT后缀命名检查 Tree / TreeTable / Table 的contextMenuSelectionMode移除joint模式的使用移除已弃用的provideAnimationsAsync以及angular/animations相关导入确认primeuix/styles与primeuix/themes不低于 2.0.2必要时重新安装依赖如需 Zoneless 优化参照 app.config.ts 在应用配置中加入provideZonelessChangeDetection()顺带核对 v20 迁移文档 中计划于 v22 移除的弃用 API尽早迁移。按照以上步骤完成迁移后即可平滑享受 v21 带来的 CSS 动画体系、PassThrough 深度定制、Unstyled 模式与 Zoneless 性能提升。【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考