PVQ-UI 组件库调用手册（插件实操）

状态：使用指南（插件开发者速查） 适用：任何要调用 pvq-ui 的 PVQ 插件（新插件 / 存量迁移） 关联：《PVQ-UI项目规则.md》（铁律）、《PVQ-UI组件库开发方案.md》（架构）、《库演进治理方案.md》（版本化）

1. 一句话流程

*复制 loader → 一行 enqueue → 直接写 `.pvq-` BEM 类 → 自身 CSS 只写插件专有样式。**

不要自己注册库句柄、不要复制库 CSS、不要自造通用组件。

2. 接入步骤（新插件）

2.1 复制 loader

把 pvq-ui 仓库里的 pvq-ui-loader.php 复制到插件 includes/ 目录（或任意合适位置）。这是唯一需要"复制"的文件，其余全走 CDN。

2.2 一行 enqueue

在插件的 admin_enqueue_scripts / enqueue_block_editor_assets / wp_enqueue_scripts 钩子里：

require_once __DIR__ . '/includes/pvq-ui-loader.php';

// 后台场景（最常用）
PVQ_UI_Loader::enqueue( array( 'admin' ), '1.2.0' );   // 第二个参数锁定版本

// 块编辑器场景
PVQ_UI_Loader::enqueue( array( 'editor' ), '1.2.0' );

// 前端场景
PVQ_UI_Loader::enqueue( array( 'frontend' ), '1.2.0' );

// 多场景一次性
PVQ_UI_Loader::enqueue( array( 'admin', 'frontend' ), '1.2.0' );

// 选择器 Select / 删除二次确认需 1.2.0+（逻辑随 pvq-ui.js 发布），低于此版本不生效

• 第一个参数 $scenes：需要哪些层就传哪些（admin / editor / frontend）。base 层 pvq-ui 会自动随依赖加载，无需手动传。
• 第二个参数 $version：锁定库版本。不传则用常量 PVQ_UI_VERSION（默认 latest 或该插件锁定值）。强烈建议显式传版本，使存量不被新库击穿（见《库演进治理方案》§2）。

2.3 自身 CSS 声明依赖

插件自己的样式要"站在库肩上"，声明依赖即可：

wp_enqueue_style(
    'my-plugin-admin',
    plugins_url( 'assets/css/admin.css', __FILE__ ),
    array( 'pvq-ui', 'pvq-ui-admin' ), // 依赖库，不复制库样式
    MY_PLUGIN_VER
);

2.4 直接写组件

在 PHP 渲染的 HTML / 模板里，直接用库提供的 .pvq-* 类，无需任何额外注册：

<div class="pvq-card">
  <div class="pvq-card__header">
    <span class="pvq-card__icon pvq-card__icon--primary"><i class="fas fa-cog"></i></span>
    <div>
      <h3 class="pvq-card__title">连接设置</h3>
      <p class="pvq-card__desc">配置你的账号信息</p>
    </div>
  </div>
  <div class="pvq-card__action">
    <button class="pvq-btn pvq-btn--primary">保存</button>
  </div>
</div>

图标用 FontAwesome class（如 fas fa-cog），loader 已保证 font-awesome 句柄注册。

3. 场景与层对照

4. 常用组件速查（仅列类名，完整 API 见组件总表）

完整清单与示例以 doc/模块文档/设计令牌与组件清单.md 为准。

• 按钮：.pvq-btn .pvq-btn--primary/--secondary/--danger/--warning/--ghost .pvq-btn--sm/--icon .pvq-btn-group（破坏性操作加 data-pvq-confirm 二次确认，见 §4.2）

• 卡片：.pvq-card .pvq-card__header/__icon/__icon--primary/__title/__desc/__action

• 表单：.pvq-field .pvq-field__label .pvq-field__help .pvq-input .pvq-input__wrap .pvq-input__wrap--has-icon .pvq-input__icon .pvq-input__toggle

• 开关（语义化，纯 CSS）：

  <label class="pvq-switch">
    <input type="checkbox" class="pvq-switch__input" checked>
    <span class="pvq-switch__slider"></span>
  </label>

• 选项卡 + 磁吸滑块（胶囊 pill）：.pvq-tabs .pvq-tabs__slider .pvq-tab .pvq-tab--active .pvq-tab__icon .pvq-tab-content .pvq-tab-content--active（容器/tab/滑块全圆角 999px，width:fit-content 紧凑；形态细节见《设计令牌与组件清单.md》Tabs 条目）

• 状态横幅：.pvq-banner .pvq-banner--success/danger/warning/info .pvq-banner__dot

• 状态指示：.pvq-status .pvq-status--success/warning/error .pvq-status__dot

• 统计：.pvq-stat-grid .pvq-stat .pvq-stat__value .pvq-stat__label

• 帮助：.pvq-help .pvq-help__icon .pvq-help__title .pvq-help__text

• 范围：.pvq-range .pvq-range__group .pvq-range__value .pvq-range__labels

• 其它：.pvq-divider .pvq-spinner .pvq-alert .pvq-alert--success/error/loading .pvq-meta-list .pvq-meta-list__row/__key/__value

• 选择器 Select（1.1.2 新增，experimental）：

  <div class="pvq-select">
    <select name="threads_sync_settings[mode]">
      <option value="auto">自动同步</option>
      <option value="manual" selected>手动同步</option>
      <option value="off" disabled>关闭（维护中）</option>
    </select>
  </div>

  详见下方 §4.1 完整调用接口。

5. JS 交互（无需你写，库已委托）

pvq-ui.js 已用事件委托处理以下交互，插件只监听自定义事件即可：

严禁在插件里写 inline onclick / onkeydown 调库组件；一律用 data-* + 委托 / 原生事件。

4.1 选择器 Select 调用接口（1.1.2 新增 · experimental）

完整 API 以 doc/模块文档/设计令牌与组件清单.md「选择器 Select」条目为准。下方是插件调用的实操契约。

4.1.1 调用前提

1. 版本必须 ≥ 1.1.2（选择器逻辑随 pvq-ui.js 发布，旧版无此功能）：

   PVQ_UI_Loader::enqueue( array( 'admin' ), '1.2.0' ); // 后台场景；selector 逻辑随 base 自动加载

   pvq-ui.js 在所有场景的 enqueue() 里都会被 wp_enqueue_script('pvq-ui') 带出，无需单独 enqueue JS。

2. 插件不复制、不重写任何下拉 JS/CSS；选择器纯靠写 HTML 类自动生效。

4.1.2 HTML 契约（必须这样写）

<div class="pvq-select">
  <select name="your_form[field]">            <!-- ① 原生 select 必须保留，且 name 照常 -->
    <option value="a">选项 A</option>
    <option value="b" selected>选项 B</option> <!-- ② selected 决定初始显示 -->
    <option value="c" disabled>选项 C（禁用）</option> <!-- ③ disabled 自动识别 -->
  </select>
</div>

• 类名唯一要求：外层包一个 .pvq-select，里面放一个原生 <select>。
• 原生 <select> 仅视觉隐藏、DOM 仍在 → 表单照常提交，WP 里 $_POST['your_form']['field'] 正常拿到值。.pvq-select 可放进 .pvq-field 内做行布局（见展示页）。
• 不要手写 .pvq-select__trigger / .pvq-select__dropdown / .pvq-select__option —— 这些由库 JS 自动生成（触发器生成在 .pvq-select 内，下拉面板挂在 <body>）。

4.1.3 自动初始化（无需你调用）

• pvq-ui.js 在 DOMContentLoaded 时自动扫描文档内所有 .pvq-select 并增强；已初始化的打 data-pvqSelectInit="1" 标记，重复扫描不会重复渲染（幂等）。
• 因此静态 HTML 写完即生效，你不需要在插件 JS 里调任何初始化函数。

4.1.4 取值方式（两种，任选）

• 表单原生提交：name 已挂在原生 select 上，随 <form> 提交自动带值（与旧 jQuery 版完全一致）。
• JS 监听变更：监听原生 select 的 change 事件即可（库在选中时会 dispatchEvent(new Event('change'))）：

  document.querySelector('select[name="your_form[field]"]')
    .addEventListener('change', function (e) {
      console.log('当前值：', e.target.value);
    });

4.1.5 动态内容（AJAX 注入后重挂）

若 select 是 AJAX 后来插入 DOM 的，注入后调一次即可：

if (window.PVQUI && window.PVQUI.initSelects) { window.PVQUI.initSelects(); }

（已初始化的会跳过，未初始化的会被接管。）

4.1.6 交互能力清单（库已内置，无需插件写）

开/关、箭头翻转、空间不足自动向上弹（flip）、右边界贴合、滚动/缩放重定位、键盘（Enter/Space 切换、ArrowDown 打开、方向键移动高亮、Enter 选中、Esc 关闭）、点击外部关闭、同时只开一个、选中同步原生 select 并派发 change、禁用项不可选。

4.1.7 可访问性现状（experimental 边界，知悉即可）

已含 role="button"/aria-haspopup/aria-expanded/aria-selected + 键盘高亮 --active。完整 listbox/option 方向键语义化聚焦留待 stable，不影响键盘可用性与表单提交。

4.1.8 threads 迁移配方（存量替换 .pvq-ts-*）

旧 threads 用 pvqSelect($sel)（jQuery）把原生 select 改成 .pvq-ts-* 结构。改用库后：

Before（旧，勿保留）：

<!-- PHP 渲染原生 select -->
<select name="threads_sync_settings[mode]">…</select>

// admin.js（删）
$('select[name="threads_sync_settings[mode]"]').each(function(){ pvqSelect($(this)); });

After（新）：

<div class="pvq-select">
  <select name="threads_sync_settings[mode]">…</select>
</div>

// functions.php / 加载点：仅一行 enqueue，无自定义下拉 JS
require_once __DIR__ . '/includes/pvq-ui-loader.php';
PVQ_UI_Loader::enqueue( array( 'admin' ), '1.2.0' );

旧 .pvq-ts-* 的 CSS/JS 建议先保留（改名或注释），迁移出问题时可即时切回；确认无回归后再删。另见《库演进治理方案》防回潮。

4.2 删除按钮二次确认（1.2.0 新增 · stable）

完整 API 以 doc/模块文档/设计令牌与组件清单.md「删除按钮二次确认」条目为准。下方是插件调用的实操契约。

4.2.1 调用前提

1. 版本必须 ≥ 1.2.0（二次确认逻辑随 pvq-ui.js 发布）：

   PVQ_UI_Loader::enqueue( array( 'admin' ), '1.2.0' );

   pvq-ui.js 在所有场景的 enqueue() 里都会被 wp_enqueue_script('pvq-ui') 带出，无需单独 enqueue JS。

2. 删除按钮视觉复用 .pvq-btn--danger + fa-trash；二次确认是*纯 `data-` 增强**，无需插件写任何 JS。

4.2.2 HTML 契约

<button class="pvq-btn pvq-btn--danger" data-pvq-confirm="确定删除该项？">
  <i class="fas fa-trash"></i> 删除
</button>

• 仅多一个 data-pvq-confirm 属性（值为确认态显示的文案）；其余按普通按钮写。
• 图标-only / 小号变体同样可用：.pvq-btn--danger.pvq-btn--icon[data-pvq-confirm="确定？"]、.pvq-btn--danger.pvq-btn--sm。

4.2.3 行为契约（库已内置，无需插件写）

1. 首次点击：仅进入确认态——按钮变实色危险红（.pvq-btn--armed）+ 文案替换为确认语，不触发任何原行为（不提交表单、不跑插件 handler）。
2. 确认态内再次点击：恢复外观并放行原行为（表单提交 / 插件自有 click 监听照常）。
3. 超时（3s）/ Esc / 点击页面其它处：自动取消恢复原样。
4. WordPress：按钮在 <form> 内（如 upload.php）时，库在捕获阶段 preventDefault，不会整页重载；第二次点击才放行。

4.2.4 插件要做的

• 无需监听、无需初始化；把真正删除逻辑挂在按钮原本的 click / 表单提交上即可（二次确认由库透明拦截首次点击）。
• 严禁为二次确认写 inline onclick；一律靠 data-pvq-confirm + 库委托。

6. 内网站点 / 本地副本覆盖

若站点无法访问公共 CDN，用常量把库指向本地副本（在 wp-config.php 或插件最早执行处定义）：

define( 'PVQ_UI_URL',        'https://内网域名/pvq-ui/v1.2.0/pvq-ui.css' );
define( 'PVQ_UI_ADMIN_URL',  'https://内网域名/pvq-ui/v1.2.0/pvq-ui-admin.css' );
define( 'PVQ_UI_EDITOR_URL', 'https://内网域名/pvq-ui/v1.2.0/pvq-ui-editor.css' );
define( 'PVQ_UI_FRONT_URL',  'https://内网域名/pvq-ui/v1.2.0/pvq-ui-frontend.css' );
define( 'PVQ_UI_VERSION',    '1.2.0' );

loader 用 defined() 守卫，仅当未定义时才用内置默认值——所以站点的覆盖优先。

如需完全关闭 loader 的版本收敛，可 define('PVQ_UI_NO_CONVERGE', true);。

7. 存量插件迁移（wolai / pvq-wp / threads）

对照《PVQ-UI组件库开发方案.md》§9 与《组件提取对照表.md》§6 映射表：

1. 复制 pvq-ui-loader.php，改三个 enqueue 点为 PVQ_UI_Loader::enqueue(...)。
2. 删插件自有 CSS 中已进库的通用类 + :root 令牌；保留插件专有类（如 .pvq-wolai-*），硬编码色值改为 --pvq-*。
3. HTML 旧类全量改新 BEM 名（注意旧类多为双类组合，勿当单类替换）。
4. 剥离所有 inline handler（§5）。
5. grep 校验：已进库的类在插件 CSS/HTML 中零残留定义（防回潮）。
6. 同步 CHANGELOG / readme / 组件总表。

8. 自检清单（提交插件前）

• [ ] 只复制了 pvq-ui-loader.php，没有复制任何库 CSS/JS
• [ ] 调用了 PVQ_UI_Loader::enqueue(...) 且显式传了版本
• [ ] 自身 CSS 声明了对 pvq-ui / pvq-ui-<场景> 的依赖
• [ ] HTML 只用 .pvq-* BEM 类，没有自建通用组件
• [ ] 无 inline onclick / onkeydown
• [ ] 颜色 / 圆角 / 阴影均用 --pvq-* 令牌，无硬编码
• [ ] 迁移插件已完成 grep 防回潮校验