企业官网建设流程全解析

PrimeNG v21 迁移指南：无破坏升级策略、CSS 动画迁移与弃用 API 处理

【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng

导读

本文是 PrimeNG（Angular 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/animations（animations）包，PrimeNG v21 将组件动画全面迁移到了原生 CSS 动画方案。这一迁移直接影响了 animations API 中的两个属性：

• showTransitionOptions
• hideTransitionOptions

2.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 = input<MotionOptions | undefined>(undefined);

2.3 新方案：motionOptions与p-motion/pMotion

如果你此前使用上述两个属性定制动画，请改用新的动画 API。仓库中新增的motion模块（packages/primeng/src/motion）提供了两种使用方式：

组件形式p-motion（motion.component.ts）和指令形式pMotion（motion.directive.ts），二者输入输出基本一致：

指令形式还暴露了完整的事件输出：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 文档，下表为关键组件清单：

如需禁用或减弱个别动画，可通过调整动画时长实现（详见动画文档的 Disable 一节）。

三、v21 弃用清单（Deprecations）

v21 标记弃用的项目如下表（均计划在 v22 中移除）：

3.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 = input<InputTextPassThrough>(); /** * Used to pass attributes to DOM elements inside the InputText component. */ pInputTextPT = input<InputTextPassThrough>();

实际读取逻辑也兼容了两者（this.ptInputText() || this.pInputTextPT()）。升级建议：将代码中的ptInputText等旧名直接替换为pInputTextPT，并在 v22 之前完成迁移。

3.2contextMenuSelectionMode：移除"joint"模式

contextMenuSelectionMode用于定义右键菜单选择行为：

• "separate"（独立模式）：上下文菜单更新独立的contextMenuSelection属性；
• "joint"（联合模式）：与行选择共用同一个selection属性，开启行选择时右键选择会与行选择联动。

v21 起"joint"模式被弃用，v22 将彻底移除，统一采用"separate"。该属性涉及 Table、Tree、TreeTable 三个组件，源码中的默认值并不一致，升级时请特别核对：

• table.ts：默认'separate'
• tree.ts：默认'joint'
• treetable.ts：默认'separate'

两种模式的分支逻辑可分别查看 table.ts 与 treetable.ts：separate模式只更新contextMenuSelection；joint模式则写入selection并触发selectionChange，同时也会同步更新contextMenuSelection。相关行为在 tree.spec.ts、treetable.spec.ts 中均有测试用例覆盖。

升级建议：将 Tree 中显式指定的contextMenuSelectionMode="joint"改为"separate"（Table / TreeTable 默认即separate，无需改动），并调整依赖“右键即选中行”的业务逻辑。

四、v21 移除项（Removals）

v21没有任何 API 被移除。关于计划在 v22 中移除的 API 清单，请参考 v20 迁移文档的弃用章节（例如@primeng/themes→@primeuix/themes、pTemplate→ 模板引用变量、CamelCase 选择器 → Kebab case、styleClass→class等），建议在 v21 阶段就着手迁移这些已被弃用的 API。

五、v21 新特性亮点（What's New）

PrimeNG v21 是 PrimeTek 产品愿景的一次重大推进，主要亮点如下：

1. PassThrough attributes（PT 属性）增强定制：通过每个组件内置的pt属性直接访问底层 DOM 元素，自由施加样式、aria、data-*或自定义属性与事件监听，实现“Your Components, Not Ours”的定制哲学。PT 对象可在组件级或全局（providePrimeNG的pt选项）定义，组件级优先级更高；还支持生命周期钩子（hooks）、子组件pc前缀命名与ptOptions合并策略（mergeSections/mergeProps），详见 PassThrough 文档。

2. Unstyled Mode（无样式模式）：完全移除设计令牌的 CSS 变量及其规则集，只保留核心功能与无障碍支持，配合 Tailwind CSS + PassThrough 实现完全自由的样式控制。可通过providePrimeNG({ unstyled: true })全局开启，或对单个组件使用unstyled属性，示例见 unstyled 文档。

3. 现代 CSS 动画（Modern CSS-based animations）：即本文第二节所述的核心变更，动画体系全面基于 CSS 实现。

4. provideAnimationsAsync可安全移除：由于动画已不再依赖@angular/animations，应用中已弃用的provideAnimationsAsync提供者可以（且建议）移除，从而减小打包体积、简化引导配置。

5. 初始 Zoneless 支持：v21 开始支持 Angular 的 Zoneless 变更检测，以提升运行时性能。仓库 showcase 自身已在 app.config.ts 中使用provideZonelessChangeDetection()，且大量组件测试（如 accordion.spec.ts）也通过provideZonelessChangeDetection()运行，可作为实践参考。

6. AI 增强文档：面向开发者体验的 AI 辅助文档改进。

六、升级注意事项：@primeuix依赖版本检查

升级 v21 时，请确保内部包版本满足要求：

内部包@primeuix/styles和@primeuix/themes版本应为2.0.2 或更高。全新安装时这些包会自动更新。

如果你在升级后发现视觉效果或动画异常，请优先检查这两个包的版本是否过旧。从 v20 起，PrimeNG 已迁移到 PrimeUIX 共享主题体系：组件样式来自@primeuix/styles，设计令牌主题预设来自@primeuix/themes（相关说明见 v20 迁移文档）。

七、升级检查清单

1. 全局搜索代码中的showTransitionOptions/hideTransitionOptions，改用motionOptions或 CSS 动画类定制；
2. 全局搜索ptInputText等指令型 PT 旧命名，替换为pInputTextPT后缀命名；
3. 检查 Tree / TreeTable / Table 的contextMenuSelectionMode，移除"joint"模式的使用；
4. 移除已弃用的provideAnimationsAsync（以及@angular/animations相关导入）；
5. 确认@primeuix/styles与@primeuix/themes不低于 2.0.2，必要时重新安装依赖；
6. 如需 Zoneless 优化，参照 app.config.ts 在应用配置中加入provideZonelessChangeDetection()；
7. 顺带核对 v20 迁移文档 中计划于 v22 移除的弃用 API，尽早迁移。

按照以上步骤完成迁移后，即可平滑享受 v21 带来的 CSS 动画体系、PassThrough 深度定制、Unstyled 模式与 Zoneless 性能提升。

【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng