PVQ-UI
 v1.2.10
Gitee

文档

PVQ-UI 的开发方案、项目规则、组件清单与调用方法。文档为代码唯一真源，本页直接渲染仓库中的真实 Markdown。

项目规则

PVQ-UI 项目规则（单一权威版）

状态：规范（最高优先级，覆盖各文档中零散的同类表述） 适用：所有 pvq-ui 仓库的修改、以及任何消费 pvq-ui 的 PVQ 插件 关联：《PVQ-UI组件库开发方案.md》（架构总纲）、《组件提取对照表.md》（实施映射）、《库演进治理方案.md》（持续运营）、《PVQ-UI组件库调用手册.md》（插件实操）

0. 这份文档的地位

本仓库此前散落多处"铁律"（总纲 §12、演进方案 §9、Agent 记忆中的项目铁律等）。此文档是这些规则的收敛点：凡与本文冲突，以本文为准。

任何人对本仓库动手前，先读本文 + 调用手册。

1. 文档铁律（最高优先级）

来源：项目级铁律 + 总纲 §12 + 演进 §9

  1. 先文档 → 再代码 → 最后同步版本号。任何功能新增 / 修复 / 调整，都要先更新 doc/开发文档/（或 doc/模块文档/），再根据文档改代码，最后同步 CHANGELOG.md 与 readme.md。
  2. 文档是唯一真源（Single Source of Truth）：代码必须服从文档，文档也要反映代码。两者长期不一致视为缺陷。
  3. 版本三处同步：库版本号（PVQ_UI_VERSION 常量 / CDN 路径 / package 或 readme 版本字段）与 CHANGELOG.md、模块文档里的组件稳定性标记，必须保持一致。
  4. 用户豁免：用户明确要求"不更新版本号"时，第 3 条可暂缓，但第 1、2 条仍生效。

2. 单一真源与防回潮规则

来源：总纲 §2 + 演进 §8

  1. 通用组件只存在于 pvq-ui。插件不得自带通用组件副本（按钮 / 卡片 / 输入 / 开关 / 选项卡 / 横幅 / 统计 / 帮助 / 范围 / 分隔 / 转圈 / 状态指示等）。
  2. 已进库的类在插件自有代码中零残留定义。迁移 / 改造后必须 grep 校验：如 .pvq-card、.pvq-btn--primary 等在插件 CSS/HTML 中不得再被 @规则 定义（只可引用）。
  3. 组件清单唯一真源（JSON）：site/inc/components.json 是库全部组件的机器可读唯一真源（组件 id / 名称 / 层 / 稳定性 / 示例 HTML）。官网画廊（site/inc/gallery.php）数据驱动，遍历该 JSON 自动生成侧边栏与预览——新增组件只需在 JSON 加一条，画廊自动出现，杜绝手抄三遍漂移。模块文档 doc/模块文档/设计令牌与组件清单.md 是同一清单的人类可读 API 说明，引用 JSON、不再手抄示例；判断"某组件是否已存在"以 JSON 为准。
  4. 令牌只加不删：新增 --pvq-* 令牌追加即可；语义变更 / 删除只发生在 MAJOR 版本，且须在 CHANGELOG + 文档说明迁移路径。

3. 命名与编码规则

来源：总纲 §2.4 + §6、提取对照表 §3

  1. BEM 双横线：pvq-{block} / pvq-{block}__{element} / pvq-{block}--{modifier}。禁止单横线修饰符（如 .pvq-wp-btn-primary）。
  2. *类前缀统一 `.pvq-**：禁止.pvq-wp-、.pvq-ts-` 等插件专属前缀污染库。
  3. @keyframes 统一 pvq- 前缀（如 pvq-spin / pvq-pulse），禁止 pvqWp* / pvq-ts* 等。
  4. 设计令牌优先：组件中颜色 / 圆角 / 阴影 / 动画一律用 --pvq-* 变量，禁止硬编码色值（内网站点主题 override 时再覆盖变量）。
  5. 库不假设主题变量存在：库是纯令牌提供方；pvq-wp 激活主题时的 --pvq-theme-* 映射由它自行在作用域 override。
  6. JS 交互原生 + 事件委托：pvq-ui.js 用原生 JS、委托监听，禁止 jQuery 依赖、禁止 inline onclick / onkeydown；库只管"视觉 + 派发事件"，表单值同步等交给插件监听后处理。

4. 版本化规则（支持"随开发慢慢完善"）

来源：演进 §3

  1. 语义化版本：MAJOR.MINOR.PATCH
    • PATCH：修样式 bug / 微调，不破坏类名。
    • MINOR：新增组件 / 新增修饰符 / 新增令牌（向后兼容，只加不删）。
    • MAJOR：破坏性改名 / 删类 / 改令牌语义（须文档说明迁移）。
  2. CDN 路径含版本：https://<CDN_BASE>/pvq-ui/v{MAJOR.MINOR.PATCH}/pvq-ui.css（及 -admin/-editor/-frontend/-js）。提供 latest 别名供开发期试用。
  3. 插件锁定版本：调用 PVQ_UI_Loader::enqueue( $scenes, $version ) 时显式传版本；存量不强制降级，新插件用最新，视觉渐进统一。
  4. override 收敛幂等：loader 内置收敛只解决"同版本冲突"，多次挂载幂等；默认开启，可被 PVQ_UI_NO_CONVERGE 关闭。

5. 组件分级规则

来源：演进 §5

  1. stable：成熟、承诺不破坏性改（仅可加修饰符 / 不删类）。新插件放心引用。
  2. experimental：新提取 / 接口可能调整。文档标注，引用建议锁定版本。
  3. 首版基线（wolai 提取的通用组件）即 stable；后续新提取先 experimental，经 1~2 个插件验证后转正。

6. 文件分层规则

来源：总纲 §3.1 + 演进 §7

  1. 四固定层：pvq-ui(base) / pvq-ui-admin / pvq-ui-editor / pvq-ui-frontend。
  2. 新场景 → 新增 pvq-ui-<scene>.css，不塞进 base。
  3. 所有层共享 base 的 --pvq-* 令牌，跨场景风格一致。
  4. 组件视觉依赖 FontAwesome：loader 保证 font-awesome 句柄注册，pvq-ui-admin 声明对其依赖。

7. 消费方接入规则

来源：总纲 §8/§10 + 调用手册

  1. 每个插件只需：复制 pvq-ui-loader.php → require_once → PVQ_UI_Loader::enqueue(...)。不得各写一份收敛 / 注册逻辑。
  2. 插件自身样式声明对 pvq-ui / pvq-ui-<场景> 的依赖，不复制库样式。
  3. 内网站点可用 PVQ_UI_URL 等常量覆盖为本地副本。

8. 提交 / 同步纪律

  1. 改动前先确认文档已更新（§1）。
  2. 改动后：bump 版本（§4）→ 同步 CHANGELOG.md（含组件加入 / stable 转正记录）→ 同步组件总表稳定性标记 → 同步 readme.md。
  3. 迁移插件时：按总纲 §9 步骤，最后做 grep 防回潮校验（§2.2）。

9. 违规处理

  • 发现插件自建通用组件副本 → 回流到库（先文档、后代码），删插件副本，grep 校验。
  • 发现 inline handler / 非 BEM 命名 / 硬编码色值 → 改造时一并修正，不新增债务。
  • 发现版本号三处不一致 → 立即对齐。