primeng-developer

PrimeNG 开发指南

与 angular-developer 配套使用——该技能提供 Angular 基础知识（信号、DI、路由、表单、SSR、无障碍功能）。本技能专注于 PrimeNG 的特性。建议同时安装两者，以获得最佳体验。

兼容性

• 跟踪版本： PrimeNG 22.1.3（发布于 2026-10-20），以及 @primeuix/themes 和 @primeuix/styles 的 3.x 版本（当前为 3.0.2）。PrimeNG 与 Angular 的主版本保持一致，因此 v22 需要 Angular v22（从 22.1 起，peer 依赖为 @angular/core@^22.1.0；在 22.0.x 中为 ^22.0.0）。
• 适用项目： PrimeNG v18 → v22 项目。本技能的参考资料包含 migration.md，涵盖 v18 组件重命名（Calendar→DatePicker、Dropdown→Select 等）以及 v21→v22 的移除项，因此 v18-v21 项目也可以使用本技能，但主题和部分组件 API 可能存在偏差。与本技能最匹配的是 v22。
• v21 → v22： v22 与 Angular 22 对齐，并升级至 @primeuix/themes/@primeuix/styles v3；同时**最终移除（删除）**了早期版本中标记为“将在 v22 中移除”的 API，包括 @primeng/themes 导入路径、pTemplate、styleClass、showTransitionOptions/hideTransitionOptions、驼峰式选择器，以及 pButton 的图标/标签属性等。应视为这些 API 已不存在，而不只是已弃用。请参阅 migration.md。
• v22.0 → v22.1： 没有破坏性变更。22.1 新增了用于微前端和嵌入式小组件的实验性 withIsolation() 功能（primeng/isolation）、p-select 上的 filterMessage / selectionMessage / emptySelectionMessage 输入属性、p-tree 上的 filteredNodes 模型，并将 Angular peer 依赖提升至 ^22.1.0。还需注意，v22 的组件按根字体大小为 16px 进行尺寸设计；根字体仍为 14px 的应用应使用 -compat 预设（参阅 theming.md）。请参阅 migration.md。
• 文档域名： 官方文档已从 primeng.org 迁移至 primeng.dev（旧链接会通过 301 重定向）。
• Angular： 需要 v18 或更高版本（PrimeNG v22 需要 v22）。PrimeNG 组件从 v18 起采用独立组件。本技能假定使用独立组件、控制流（@if / @for）和基于信号的 API。
• Tailwind： v3 或 v4，并使用 tailwindcss-primeui 插件（可选，用于无样式模式）。
• 不支持： PrimeNG v17 及更低版本（采用基于 prime.css 的不同主题模型）、Angular v17 及更低版本（NgModule 模式）。

如果项目使用的 PrimeNG 版本低于 v18，请引导用户查阅 PrimeNG v17 文档，并拒绝在 v17 项目中生成 v18 及更高版本的模式，这些模式无法编译。

1. 提供指导前，务必先检查项目的 PrimeNG 版本。PrimeNG v18 引入了主要组件重命名（Calendar→DatePicker、Dropdown→Select、InputSwitch→ToggleSwitch、OverlayPanel→Popover、Sidebar→Drawer）和新的设计令牌主题系统。package.json 是权威依据；如有疑问，请先查阅该文件，再推荐 API。请参阅 migration.md。

2. 添加组件前，先确认项目使用的主题模式：

   • 如果导入了 @primeuix/themes 并配置了 providePrimeNG({ theme: ... }) → 有样式模式（默认）。
   • 如果在 providePrimeNG 中设置了 unstyled: true，或项目使用了 tailwindcss-primeui → 无样式模式。
   • 两种模式的自定义方式有本质区别。请参阅 styled-vs-unstyled.md。

3. 组件从 v18 起采用独立组件。务必导入独立类（例如从 'primeng/button' 导入 Button），不要使用旧版 *Module。为保持向后兼容，仍会导出旧版模块，但不应在新代码中使用。

4. 生成 PrimeNG 代码后，运行 ng build 检查编译错误。AI 最常见的错误有：（a）从 @primeng/themes 而非 @primeuix/themes 导入（已弃用的路径）；（b）在 v18 至 v20 项目中忘记调用 provideAnimationsAsync()（PrimeNG v21+ 使用原生 CSS 动画，不再需要它）；（c）在 v18 重命名组件后，仍使用 v17 的组件名称（Calendar、Dropdown、OverlayPanel、Sidebar、InputSwitch）；（d）在组件上写 styleClass="…"，该写法自 v20 起已弃用，应改用原生的 class="…"（或 [class] / [ngClass]）；（e）在以独立方式导入的组件中写 pTemplate="item"，除非导入 SharedModule（或重新导出它的 TableModule 等 *Module），否则 PrimeTemplate 指令不在作用域内，因此模板不会注册，组件会渲染出空行，且不会出现构建错误或控制台错误。应改用模板引用（<ng-template #item>、#content、#header 等），每个 v21 组件都会直接查询这些引用。请参阅 setup.md 和 migration.md。

PrimeNG 架构：有样式、无样式和 PassThrough

PrimeNG 以编译后的形式随 node_modules 一同提供，没有复制源码的 CLI。自定义可通过以下三种递进方式实现：

• 设计令牌（有样式模式）：通过 definePreset(Aura, {...}) 在预设级别覆盖主题变量。适用于大多数主题需求。请参阅 theming.md。
• PassThrough（pt）：逐组件的属性，可向任意内部 DOM 区域注入类和属性。有样式和无样式模式均适用。设计令牌无法满足需求时使用。请参阅 passthrough.md。
• 无样式模式：彻底移除 PrimeNG 的样式，并提供自己的样式（通常通过 tailwindcss-primeui 使用 Tailwind）。适用于已有设计系统的团队。请参阅 styled-vs-unstyled.md。

默认使用带 Aura 预设的有样式模式。 需要覆盖特定内部区域时使用 PassThrough。只有在项目决定采用 Tailwind 驱动的设计系统时，才使用无样式模式。

安装与主题设置

• 设置：安装 primeng @primeuix/themes @primeuix/styles，配置 providePrimeNG()（v18 至 v20 中还需配置 provideAnimationsAsync()），并了解常见问题。请阅读 setup.md
• 主题设置：Aura / Lara / Nora / Material 预设、设计令牌、暗色模式、definePreset 覆盖、运行时切换预设、CSS 图层顺序。请阅读 theming.md
• 有样式与无样式：何时使用各模式、Tailwind v4 与 tailwindcss-primeui 的集成、Volt UI 参考模式。请阅读 styled-vs-unstyled.md
• PassThrough：pt API、providePrimeNG 中的全局 pt、嵌套组件前缀（pcBadge）、ptOptions.mergeSections 和 mergeProps。请阅读 passthrough.md

组件

PrimeNG 按类别提供了 80 多个组件。每个类别文件都介绍组件 API、常见模式和注意事项。

• 表单控件：AutoComplete、CascadeSelect、Checkbox、ColorPicker、DatePicker、Editor、FloatLabel、IconField、IftaLabel、InputMask、InputNumber、InputOtp、InputText、Knob、Listbox、MultiSelect、Password、RadioButton、Rating、Select、SelectButton、Slider、Textarea、ToggleButton、ToggleSwitch、TreeSelect。阅读 form-controls.md
• 按钮：Button、SpeedDial、SplitButton。阅读 buttons.md
• 叠加层：ConfirmDialog、ConfirmPopup、Dialog、Drawer、DynamicDialog、Popover、Toast、Tooltip。阅读 overlays.md
• 布局：Accordion、BlockUI、Card、Divider、Fieldset、Panel、Scroller（VirtualScroller）、ScrollTop、Splitter、Stepper、Tabs、Toolbar。阅读 layout.md
• 数据展示：Carousel、DataView、Galleria、OrderList、Paginator、PickList、Table、Timeline、Tree、TreeTable。阅读 data-display.md
• 显示：Avatar、Badge、Chip、Image、Inplace、Message、MeterGroup、OverlayBadge、ProgressBar、ProgressSpinner、Ripple、Skeleton、Tag、Terminal。阅读 display.md
• 菜单：Breadcrumb、ContextMenu、Dock、MegaMenu、Menu、MenuBar、PanelMenu、TieredMenu。阅读 menus.md

表单集成

• 表单：将 PrimeNG 表单组件连接到 ReactiveForms 或 Signal Forms，使用 [invalid] 属性（v20+）替代 .ng-invalid.ng-dirty，ControlValueAccessor 模式，以及验证状态的显示。阅读 forms.md

无障碍

• 无障碍：内置符合 WCAG 2.1 AA 标准的支持、p-sr-only 实用类、各组件的 ARIA 规范、键盘导航和焦点管理。阅读 accessibility.md

迁移

• 迁移：v18 组件重命名（Calendar→DatePicker 等）、已弃用的 API、使用 [invalid] 属性替代 .ng-invalid.ng-dirty，以及用设计令牌系统替代旧版 SCSS 主题。阅读 migration.md