primevue-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

primefaces/primevue

primevue

primefaces/primevue

primevue

Version: 4.5.4 (Dec 2025) Deps: @primeuix/styled@^0.7.4, @primeuix/utils@^0.6.2, @primeuix/styles@^2.0.2, @primevue/core@4.5.4, @primevue/icons@4.5.4 Tags: v2-stable: 2.10.4 (Dec 2023), v3-stable: 3.53.1 (Dec 2024), latest: 4.5.4 (Dec 2025)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • Releases — changelog, breaking changes, new APIs

**版本：**4.5.4（2025年12月） 依赖：@primeuix/styled@^0.7.4、@primeuix/utils@^0.6.2、@primeuix/styles@^2.0.2、@primevue/core@4.5.4、@primevue/icons@4.5.4 **标签版本：**v2-stable: 2.10.4（2023年12月）、v3-stable: 3.53.1（2024年12月）、latest: 4.5.4（2025年12月）

参考资源：文档 — API参考、使用指南 • GitHub问题 — 问题反馈、解决方案、边缘场景 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes — prioritize recent major/minor releases.

BREAKING:
```
Calendar
```
renamed to
```
DatePicker
```
— v3 component renamed to
```
DatePicker
```
in v4 source
BREAKING:
```
Dropdown
```
renamed to
```
Select
```
— v3 component renamed to
```
Select
```
in v4 source
BREAKING:
```
Sidebar
```
renamed to
```
Drawer
```
— v3 component renamed to
```
Drawer
```
in v4 source
BREAKING:
```
OverlayPanel
```
renamed to
```
Popover
```
— v3 component renamed to
```
Popover
```
in v4 source
BREAKING:
```
InputSwitch
```
renamed to
```
ToggleSwitch
```
— v3 component renamed to
```
ToggleSwitch
```
in v4 source
BREAKING:
```
TabView
```
replaced by
```
Tabs
```
— new component structure using
```
TabList
```
,
```
Tab
```
,
```
TabPanels
```
, and
```
TabPanel
```
source
BREAKING:
```
Steps
```
replaced by
```
Stepper
```
— new component structure using
```
StepList
```
,
```
Step
```
,
```
StepPanels
```
, and
```
StepPanel
```
source
BREAKING:
```
Accordion
```
reimplementation — now uses
```
AccordionPanel
```
,
```
AccordionHeader
```
, and
```
AccordionContent
```
components source
BREAKING:
```
v-model:value
```
— v4 uses
```
v-model:value
```
for active state in
```
Tabs
```
,
```
Accordion
```
, and
```
Stepper
```
instead of
```
v-model
```
source
DEPRECATED:
```
inputStyle
```
— property replaced by
```
inputVariant
```
(values: 'filled' | 'outlined') source
NEW:
```
@primevue/forms
```
— new dedicated package for advanced form management and validation source
NEW:
```
Fluid
```
component — layout component that makes descendants span full width source
NEW:
```
IconField
```
&
```
InputIcon
```
— new components to wrap inputs and icons for decorative purposes source
NEW:
```
useId
```
&
```
useAttrSelector
```
— new core composables for unique ID generation and attribute selectors source

Also changed:

DataTable

showClearButton

default is

false

(v4.3.0) ·

IftaLabel

new component for in-field labels ·

Checkbox

added

indeterminate

state ·

OverlayBadge

new component replaces

Badge

directive ·

InlineMessage

component deprecated ·

iconPosition

removed from

IconField

warning

property renamed to

warn

Drawer

added

before-hide

emit (v4.3.0)

本节记录特定版本的API变更——优先关注近期的主版本/次版本更新。

破坏性变更：
```
Calendar
```
重命名为
```
DatePicker
```
——v3版本的该组件在v4中更名为
```
DatePicker
```
来源
破坏性变更：
```
Dropdown
```
重命名为
```
Select
```
——v3版本的该组件在v4中更名为
```
Select
```
来源
破坏性变更：
```
Sidebar
```
重命名为
```
Drawer
```
——v3版本的该组件在v4中更名为
```
Drawer
```
来源
破坏性变更：
```
OverlayPanel
```
重命名为
```
Popover
```
——v3版本的该组件在v4中更名为
```
Popover
```
来源
破坏性变更：
```
InputSwitch
```
重命名为
```
ToggleSwitch
```
——v3版本的该组件在v4中更名为
```
ToggleSwitch
```
来源
破坏性变更：
```
TabView
```
被
```
Tabs
```
替代 ——新组件结构使用
```
TabList
```
、
```
Tab
```
、
```
TabPanels
```
和
```
TabPanel
```
来源
破坏性变更：
```
Steps
```
被
```
Stepper
```
替代 ——新组件结构使用
```
StepList
```
、
```
Step
```
、
```
StepPanels
```
和
```
StepPanel
```
来源
破坏性变更：
```
Accordion
```
重新实现 ——现在使用
```
AccordionPanel
```
、
```
AccordionHeader
```
和
```
AccordionContent
```
组件来源
破坏性变更：
```
v-model:value
```
——v4版本在
```
Tabs
```
、
```
Accordion
```
和
```
Stepper
```
中使用
```
v-model:value
```
控制激活状态，替代原有的
```
v-model
```
来源
已废弃：
```
inputStyle
```
——该属性被
```
inputVariant
```
替代（可选值：'filled' | 'outlined'）来源
新增功能：
```
@primevue/forms
```
——用于高级表单管理和验证的专属新包来源
新增组件：
```
Fluid
```
——使子元素撑满宽度的布局组件来源
新增组件：
```
IconField
```
&
```
InputIcon
```
——用于包裹输入框和图标以实现装饰效果的新组件来源
新增组合式函数：
```
useId
```
&
```
useAttrSelector
```
——用于生成唯一ID和属性选择器的核心新组合式函数来源

其他变更：

DataTable

的

showClearButton

默认值改为

false

（v4.3.0）·新增

IftaLabel

组件用于字段内标签·

Checkbox

新增

indeterminate

状态·

OverlayBadge

新组件替代

Badge

指令·

InlineMessage

组件已废弃·

IconField

移除

iconPosition

属性·

warning

属性重命名为

warn

Drawer

新增

before-hide

事件（v4.3.0）

Best Practices

最佳实践

Use the
```
Fluid
```
component as a wrapper for bulk application of full-width styles to inputs instead of adding the
```
fluid
```
prop to every individual field for cleaner and more maintainable templates source

vue

<Fluid>
    <div class="grid grid-cols-2 gap-4">
        <InputText placeholder="Full Width" />
        <DatePicker placeholder="Full Width" />
        <Select placeholder="Full Width" />
    </div>
</Fluid>

In Stepper vertical layouts, always wrap
```
Step
```
and
```
StepPanel
```
inside a
```
StepItem
```
component to ensure correct structure and connection between headers and content source
Use
```
asChild
```
and
```
v-slot
```
on components like
```
Step
```
or
```
Tab
```
to implement headless mode for full UI control while retaining PrimeVue's built-in accessibility logic source

vue

<Step v-slot="{ activateCallback, value, a11yAttrs }" asChild :value="1">
    <button @click="activateCallback" v-bind="a11yAttrs.header">
        Step {{ value }}
    </button>
</Step>

For performant row expansion in
```
DataTable
```
with large datasets, use an object for
```
expandedRows
```
combined with
```
dataKey
```
instead of an array of row objects source

// Preferred (O(1) lookup)
const expandedRows = ref({ '1004': true, '1005': true });

// In template
<DataTable v-model:expandedRows="expandedRows" dataKey="id">

Enable automatic user preference persistence (sorting, filtering, paging) in
```
DataTable
```
using
```
stateStorage
```
and
```
stateKey
```
to improve UX across page visits source
Add a
```
delay
```
to
```
VirtualScroller
```
to throttle rendering during rapid scrolling, significantly improving UI responsiveness for extremely large lists source

vue

<VirtualScroller :items="items" :itemSize="50" :delay="250">
    <template v-slot:item="{ item }">{{ item }}</template>
</VirtualScroller>

Implement semantic navigation menus by using
```
Tabs
```
without
```
TabPanels
```
and combining it with
```
router-link
```
for accessible, state-aware top or side bars source
Always wrap inputs and icons with
```
IconField
```
and
```
InputIcon
```
to ensure correct positioning and styling, supporting both leading and trailing icon placements source

vue

<IconField>
    <InputIcon class="pi pi-search" />
    <InputText placeholder="Search" />
</IconField>

Use
```
IftaLabel
```
for modern, top-aligned in-field labels that visually integrate with the input and handle validation states automatically source
Leverage the built-in
```
DataTable
```
context menu integration to provide row-specific actions without manual event listener management or custom positioning logic source

vue

<ContextMenu ref="cm" :model="menuModel" />
<DataTable :value="products" contextMenu @row-contextmenu="onRowContextMenu">

使用
```
Fluid
```
组件作为容器，批量为输入框应用全宽样式，而非为每个单独字段添加
```
fluid
```
属性，以此获得更简洁、更易维护的模板来源

vue

<Fluid>
    <div class="grid grid-cols-2 gap-4">
        <InputText placeholder="Full Width" />
        <DatePicker placeholder="Full Width" />
        <Select placeholder="Full Width" />
    </div>
</Fluid>

在垂直布局的Stepper中，务必将
```
Step
```
和
```
StepPanel
```
包裹在
```
StepItem
```
组件内，以确保头部和内容之间的结构正确且关联正常来源
在
```
Step
```
或
```
Tab
```
等组件上使用
```
asChild
```
和
```
v-slot
```
实现无头模式，在完全控制UI的同时保留PrimeVue内置的无障碍访问逻辑来源

vue

<Step v-slot="{ activateCallback, value, a11yAttrs }" asChild :value="1">
    <button @click="activateCallback" v-bind="a11yAttrs.header">
        Step {{ value }}
    </button>
</Step>

针对包含大量数据的
```
DataTable
```
实现高性能行展开功能，使用对象类型的
```
expandedRows
```
结合
```
dataKey
```
，而非行对象数组来源

// 推荐方案（O(1)查找效率）
const expandedRows = ref({ '1004': true, '1005': true });

// 模板中使用
<DataTable v-model:expandedRows="expandedRows" dataKey="id">

在
```
DataTable
```
中启用
```
stateStorage
```
和
```
stateKey
```
，实现用户偏好（排序、筛选、分页）的自动持久化，提升跨页面访问的用户体验来源
为
```
VirtualScroller
```
添加
```
delay
```
属性，在快速滚动时限制渲染频率，显著提升超大型列表的UI响应速度来源

vue

<VirtualScroller :items="items" :itemSize="50" :delay="250">
    <template v-slot:item="{ item }">{{ item }}</template>
</VirtualScroller>

通过使用不带
```
TabPanels
```
的
```
Tabs
```
并结合
```
router-link
```
实现语义化导航菜单，打造具备无障碍访问能力、状态感知的顶部或侧边栏来源
务必使用
```
IconField
```
和
```
InputIcon
```
包裹输入框和图标，确保图标定位和样式正确，支持前置和后置图标两种布局来源

vue

<IconField>
    <InputIcon class="pi pi-search" />
    <InputText placeholder="Search" />
</IconField>

使用
```
IftaLabel
```
实现现代化的顶部对齐字段内标签，其可与输入框视觉整合并自动处理验证状态来源
利用
```
DataTable
```
内置的右键菜单集成，提供行级专属操作，无需手动管理事件监听器或自定义定位逻辑来源

vue

<ContextMenu ref="cm" :model="menuModel" />
<DataTable :value="products" contextMenu @row-contextmenu="onRowContextMenu">