PVQ-UI
 v1.2.10
Gitee

文档

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

库演进治理

PVQ-UI 库演进治理方案（随插件开发慢慢完善）

状态：治理规范（与《PVQ-UI组件库开发方案.md》配合，是后者的"持续运营"补充） 目标：让 pvq-ui 随 Plugin 后端/前端开发增量生长、越用越专业，同时不破坏存量插件。

1. 推荐方案（一句话）

版本化 CDN + 文档驱动增量贡献 + 组件分级（stable/experimental）+ 分层文件。 即在现有方案（CDN 单一源 + loader 收敛）之上，增加"版本维度"与"贡献流程"，使库能持续演进而不击穿存量。

2. 为什么"慢慢完善"必须版本化

现有方案 §3.1 的 CDN 路径已含 <版本> 占位、§3.2 已有 PVQ_UI_VERSION 常量——架构已埋伏笔。但"随插件慢慢完善"意味着库会持续变：

  • 若所有插件引用同一固定 URL（无版本），库一改就全站影响，存量插件随时可能被新改动击穿（风险高，违背"慢慢"）。
  • 版本化让每个插件锁定它开发时的库版本：存量不动 = 不被破坏；新插件用最新 = 立即享受新组件。视觉"统一"是渐进达成的，而非强制一次性。

结论：保留 loader 的 URL 单一源 + override 收敛机制，但每个插件显式锁定版本，override 只在"同版本冲突"时收敛，不强制跨版本降级。

3. 版本化 CDN 设计

  • 路径含版本：https://<CDN_BASE>/pvq-ui/v{MAJOR.MINOR.PATCH}/pvq-ui.css（及 -admin/-editor/-frontend/-js）。
  • latest 别名：.../pvq-ui/latest/... 指向当前最新版，供开发期 / 新插件快速试用。
  • 插件锁定版本：各插件的 pvq-ui-loader.php 调用时传入版本，如 PVQ_UI_Loader::enqueue(['admin'], '1.2.0')；不传则用常量 PVQ_UI_VERSION（默认 latest 或该插件锁定值）。
  • 内网站点：仍可用 PVQ_UI_URL 等常量覆盖为本地副本（现有方案 §3.4 不变）。
  • 语义化版本：
    • PATCH 修样式 bug / 微调，不破类。
    • MINOR 新增组件 / 新增修饰符 / 新增令牌（向后兼容，只加不删）。
    • MAJOR 破坏性改名 / 删类 / 改令牌语义（需文档说明迁移）。

4. 增量贡献流程（插件开发 → 库生长）

每次开发 / 迭代插件时，把"插件需求"变成"库的一次成长"：

  1. 先查组件总表（doc/模块文档/设计令牌与组件清单.md）。
    • 已存在且 stable → 直接引用。
    • 已存在但 experimental → 引用或锁定版本，注意可能调整。
    • 不存在 → 进入第 2 步。
  2. 先在库里实现该组件（顺序铁律）：
    • ① 在 doc/开发文档/ 或模块文档写/改组件条目（API、类名、令牌、示例）；
    • ② 写 CSS/JS（遵守 BEM 双横线、统一令牌、pvq- 动画前缀）；
    • ③ bump 版本号（MINOR），同步 CHANGELOG.md 与 readme.md（版本三处同步）；
    • ④ 构建上传 CDN 对应版本路径。
  3. 插件引用库组件，绝不自建通用组件副本。
  4. 防回潮校验：grep 确认该组件类在插件自有 CSS/HTML 中零残留定义。

这条流程把"每次写插件"都变成"库变专业一点"的机会，正好匹配你说的"随开发慢慢完善"。

5. 组件分级（stable / experimental）

在组件总表中标注每个组件的稳定级别：

  • stable：已成熟，承诺不破坏性改（仅可加修饰符 / 不删类）。新插件放心引用。
  • experimental：新提取 / 接口可能调整。文档标注，插件可引用但建议锁定版本。

库首版（wolai 提取的通用组件）即为 stable 基线；后续新提取的组件先标 experimental，经 1~2 个插件验证后转正。

6. 设计令牌演进规则（只加不删）

  • 新增语义色 / 尺寸 / 阴影 / 动画 → 追加新 --pvq-* 变量，不改既有变量语义、不删。
  • 令牌语义变更 / 删除只在 MAJOR 版本，且须在 CHANGELOG + 文档说明迁移路径。
  • 库的 :root 是默认令牌；pvq-wp 主题激活时的 --pvq-theme-* 映射由 pvq-wp 自行在作用域 override，库不依赖它。

7. 分层文件（场景隔离，避免 base 膨胀）

  • 现有四层：pvq-ui(base) / pvq-ui-admin / pvq-ui-editor / pvq-ui-frontend。
  • 新场景出现（如 media-library、block-toolbar、stats-dashboard）→ 新增 pvq-ui-<scene>.css，不塞进 base。
  • 插件只 enqueue 自己需要的层，控制体积。
  • 所有层共享 base 的 --pvq-* 令牌，保证跨场景风格一致。

8. 防回潮 / 一致性保障

  • 组件总表单一真源：doc/模块文档/设计令牌与组件清单.md 是库全部组件的唯一清单；任何"是不是已有"都查它。
  • 迁移后 grep 校验：已进库的类（如 .pvq-card、.pvq-btn--primary）在插件自有代码中零残留定义，避免与库双定义。
  • 插件审查点：新增/修改插件时检查"是否误建了通用组件副本"——若有，应回流到库而非留在插件。
  • 可选 CI：脚本校验插件 CSS 不含 .pvq-{btn,card,input,switch,tab,banner,stat,...} 的定义块（只允许引用）。

9. 文档驱动铁律（不变）

  • 任何组件新增 / 修改：先改 doc/开发文档/（或模块文档）→ 再改代码 → 最后同步 CHANGELOG.md 与 readme.md（版本三处同步；除非用户要求不更新版本号）。
  • 库自身的 CHANGELOG.md 记录每个组件何时加入、何时从 experimental 转为 stable。

10. 与《PVQ-UI组件库开发方案.md》的关系

文档 职责
PVQ-UI组件库开发方案.md 总纲：架构、loader、CDN、命名、迁移步骤
组件提取对照表.md 实施：三套现有组件 → 库单一实现的逐组件映射与择优
PVQ-UI项目规则.md 最高优先级权威规则：收敛散落铁律，冲突以它为准
PVQ-UI组件库调用手册.md 实操：插件如何调用库（复制 loader、enqueue、写组件、迁移、自检）
本文件 运营：库如何随插件开发持续演进、版本化、防回潮

五份互为引用，共同构成"唯一真源"。