` 可使内部组件撑满宽度；v4 中改为在组件上使用 `fluid` prop：
```vue
```
**4\. Dark Mode 与 SSR 水合不匹配**
Nuxt 3 中使用 `darkModeSelector: '.dark'` 并配合 `@nuxtjs/color-mode` 时，确保服务端和客户端的初始类名一致，否则会出现 Hydration Mismatch。
**5\. DataTable 懒加载 totalRecords 必须提前设置**
`lazy: true` 时，分页器需要 `totalRecords` 才能计算页数。初始加载时应在获取第一页数据的同时设置 `totalRecords`。
**6\. Tooltip 指令注册**
使用 `v-tooltip` 前需注册：
```typescript
import Tooltip from 'primevue/tooltip'
app.directive('tooltip', Tooltip)
// 或在 Nuxt 中通过 directives 配置自动注册
```
---
## 最佳实践
**选用 Unstyled 模式 + Tailwind，而非 Styled 模式**：PrimeVue v4 的 Unstyled 模式（`unstyled: true`）允许完全自定义样式，配合 `tailwindcss-primeui` 插件可以用 Tailwind 类名控制组件外观，避免主题覆盖战。Styled 模式适合快速原型，Unstyled 模式适合需要严格设计系统的项目。
**使用 `PassThrough` API 为单个组件实例添加 class，而非全局覆盖 CSS**：通过 `:pt` prop 可以精确控制组件内部 DOM 节点的类名，比写全局 CSS 选择器更可预期且不影响其他组件实例。
```vue
```
**DataTable 分页用受控模式（`:rows` \+ `@page`），而非非受控**：非受控模式下，分页状态由组件内部管理，无法与 URL、路由或外部状态同步。受控模式将 `first`、`rows` 状态提升到外部，便于持久化和服务端分页。
**表单组件与 Vee-Validate 或 Vue-Formkit 集成时，使用 `v-bind` 传递错误状态而非包装层**：PrimeVue v4 的表单组件接受 `invalid` prop，直接绑定校验库的错误状态即可，无需额外包装组件。
```vue
{{ errors.email }}
```
**图标使用 `primeicons` 类名时检查版本兼容性**：PrimeIcons 在大版本更新时会重命名部分图标（如 `pi-home` → `pi-house`），升级后应全量搜索项目中的 `pi-` 类名进行核对。
---
## 常见陷阱
### 陷阱：Styled 模式下自定义 CSS 被覆盖
**现象：** 通过全局 CSS 修改 DataTable 行高或颜色，在开发环境生效，生产构建后失效；或某些状态（hover、selected）样式无法覆盖。
**原因：** PrimeVue Styled 模式的主题 CSS 使用了较高特异性的选择器，全局 `class` 覆盖时特异性不够；生产构建中 CSS 加载顺序可能与开发环境不同。
**解决：** 升级到 Unstyled 模式使用 PT API 控制样式；或用 `:deep()` 穿透 Scoped CSS；或在主题 CSS 后引入自定义 CSS 以保证顺序。
```vue
```
### 陷阱：`v-model` 在 Dialog 内的组件数据不同步
**现象：** Dialog 打开后修改了表单数据，关闭再打开时，数据没有重置或显示了上次的值。
**原因：** Dialog 组件默认在关闭时不销毁内部 DOM（仅隐藏），Vue 组件状态保留，下次打开时仍是上次的值。
**解决：** 使用 `:visible` 控制显隐时，在 `@hide` 事件中手动重置表单数据；或使用 `v-if` 替代 `v-show` 控制 Dialog，每次打开都重新挂载组件。
```vue
