primevue-skilld

PrimeVue ([email protected])

版本 5.0.1，准备好的源文件为 input/source/package.json。面向 Vue 3 的 UI 组件库。 文档：https://primevue.dev（组件页面位于 https://primevue.dev/<name>，例如 https://primevue.dev/inputtags/）。

v5 关键事实

1. 需要许可证密钥。 v5 采用 PrimeUI 双重许可证（免费 Community 版或付费 Commercial 版）。安装插件时，将密钥作为 license 字符串选项传入。许可证验证离线进行；缺少、无效或过期的密钥可能会显示许可证提示（input/source/LICENSE.md）。
2. 与 v4 相比没有破坏性公共 API 变更，详见官方迁移指南（https://primevue.dev/migration/v5/）。已弃用的 v4 API 在 v5 中仍可使用，并会在 v6 中移除。编写新代码时，请使用 v5 变更 中的替代方案。
3. 根字体基准为 16px。 v5 假定文档根字体大小为 16px；v4 假定为 14px。每个预设都提供 -compat 变体以适配 14px 布局，并维护至 2027 年 6 月（https://primevue.dev/theming/styled/）。
4. 配置插件。 使用 app.use 安装一次。primevue/config 的默认导出也会作为 Config 从包根目录重新导出（input/source/index.mjs:139）。

设置

// main.js
import { createApp } from 'vue';
import PrimeVue from 'primevue/config'; // or: import { Config } from 'primevue'
import Aura from '@primeuix/themes/aura';
import App from './App.vue';

const app = createApp(App);
app.use(PrimeVue, {
    license: '<your PrimeUI license key>',
    ripple: true, // optional, disabled by default
    theme: {
        preset: Aura,
        options: {
            darkModeSelector: '.app-dark' // default is 'system'
        }
    }
});

详情：主题选项、本地化、无样式模式、Nuxt 模块、自动导入，请参阅设置。

导入模式

<script setup>
// Tree-shakeable subpath imports (package.json exports map "./*")
import Button from 'primevue/button';
import Select from 'primevue/select';
// Style classes for a component (design token CSS)
import SelectStyle from 'primevue/select/style';
</script>

• 也可以从根目录导入 from 'primevue'，它会导出所有组件、样式、服务和组合式函数（input/source/index.mjs）。
• 图标：SVG 图标组件来自 @primeicons/vue（input/source/package.json 中的依赖 ^8.0.0）。@primevue/icons 包在 v5 中已弃用。

黄金法则

• 新代码绝不使用已弃用的组件。 在 v5 中已弃用（将在 v6 中移除）：MultiSelect、Galleria、Image、ColorPicker、ImageCompare、ScrollPanel、Password、InputMask（组件）、PanelMenu、Chart、Editor、带有 multiple 的 AutoComplete、由 value 驱动的 Carousel、scrollable Tabs。请使用 v5 变更 中的替代方案表。
• 按钮使用默认插槽组合内容。 label、icon、iconPos、iconClass、badge、badgeClass、badgeSeverity、loading、loadingIcon 属性自 v5.0.0 起均已弃用（input/source/button/index.d.ts）。
• 优先使用复合组件，而非由属性驱动的模板：Tabs/TabList/Tab/TabPanels/TabPanel、Accordion/AccordionPanel/AccordionHeader/AccordionContent、Stepper 系列、Sidebar 系列、Gallery 系列、Carousel 系列。活动状态通过 v-model:value 绑定（Accordion 的 activeIndex 属性和事件已在 v5 中移除）。
• 覆盖层基于 Teleport：设置 appendTo="body"（默认值）或 "self"；大多数覆盖层组件都接受 overlayStyle/overlayClass（panel* 属性已在 v5 中移除）。
• 优先使用设计令牌，而非 CSS 覆盖：使用 dt 属性设置作用域令牌，并通过 definePreset 自定义预设，而不是使用 :deep() 或样式类（https://primevue.dev/theming/styled/）。

常见任务

按钮（插槽组合）

<Button severity="contrast" size="small">
    <i class="pi pi-check" />
    <span>Confirm</span>
    <Badge value="2" />
</Button>

插槽中的图标顺序取代 iconPos；使用 disabled 和自定义加载指示器，而不是 loading。

多选（替代 MultiSelect）

<Select v-model="selectedCities" multiple :options="cities" optionLabel="name" fluid />

Select 上的 multiple（“指定后允许选择多个值”，input/source/select/index.d.ts）。

标签输入（替代多选 AutoComplete）

<InputTags v-model="tags" typeahead :suggestions="suggestions" @complete="search" delimiter="," />

关键属性：max、allowDuplicate、addOnBlur、addOnPaste、addOnTab、delimiter（字符串或 RegExp）。触发 add、remove、option-select、complete 事件（input/source/inputtags/index.d.ts）。

Toast 服务

// main.js: app.use(ToastService)
import { useToast } from 'primevue/usetoast';
const toast = useToast();
toast.add({ severity: 'info', summary: 'Saved', life: 3000 });

服务方法：add、remove、removeGroup、removeAllGroups（input/source/toastservice/index.d.ts）。ConfirmationService + useConfirm 以及 DialogService + useDialog（动态对话框）也采用相同模式。

Mask 指令（替代 InputMask 组件）

<InputText v-mask="{ mask: '99-9999', unmask: true }" v-model="value" />

选项：mask、slotChar（默认值 _）、autoClear（默认值为 true）、unmask、接收 { value, rawValue } 的 onChange（input/source/mask/index.d.ts）。

应用侧边栏（复合组件）

<SidebarLayout>
    <SidebarAside>
        <SidebarHeader>…</SidebarHeader>
        <SidebarContent>
            <SidebarGroup>
                <SidebarGroupLabel>Admin</SidebarGroupLabel>
                <SidebarGroupContent>
                    <SidebarMenu>
                        <SidebarMenuItem><SidebarMenuButton>Users</SidebarMenuButton></SidebarMenuItem>
                    </SidebarMenu>
                </SidebarGroupContent>
            </SidebarGroup>
        </SidebarContent>
        <SidebarFooter>…</SidebarFooter>
    </SidebarAside>
    <SidebarMain><RouterView /></SidebarMain>
</SidebarLayout>

Sidebar 在 SidebarLayout 内使用时需要唯一的 id；支持 side、variant（sidebar|floating|inset）、collapsible（offcanvas|icon|none）、v-model:open、openOnHover、overlay、width（input/source/sidebar/index.d.ts）。完整部件列表见组件。

表单字段

• FloatLabel、IftaLabel（字段内标签）或普通的 Label。
• 使用 <Fluid> 包裹区域，即可让输入框铺满宽度，而不必在每个字段上设置 fluid。
• 任意输入组件上的 invalid 属性都会启用错误样式；通过 @primevue/forms 管理验证状态（独立的软件包，https://primevue.dev/forms/）。

DataTable 性能

设置 dataKey 后，对于大型数据集，应将 expandedRows 绑定到对象（{ '1004': true }），而不是行对象数组，以实现 O(1) 查找（官方 DataTable 文档）。使用 stateStorage + stateKey 持久化用户偏好。

参考资料

• 设置与配置：安装、许可证、主题预设、深色模式、本地化、无样式模式、Nuxt。
• v5 变更与迁移：包含替代方案的弃用和移除列表。
• 组件与替代方案：复合组件系列、新增的 v5 组件、服务、实用工具。