Skip to content

CSS_API.md

Latest commit

 

History

History
137 lines (98 loc) · 5.8 KB

CSS_API.md

File metadata and controls

137 lines (98 loc) · 5.8 KB
Raw

WPUIE CSS API

本文定义 Web Pixel UI Engine（WPUIE）的 CSS 公共 API。它是后续 CSS 重构、示例和组件文档的命名依据。

当前仓库中的部分选择器仍然属于历史 API。本次只确定目标规范，不立即删除旧选择器；迁移工作需要在补齐测试和兼容策略后单独进行。

设计原则

  • CSS 负责视觉表现，HTML 负责语义和原生行为。
  • 视觉变体使用 class，真实状态优先使用原生属性、伪类和 ARIA 状态。
  • 所有新的公共 class 使用 pui- 命名空间。
  • 不发布无命名空间的通用 class，也不使用纯视觉自定义 HTML 属性。
  • CSS 变量是主题和组件定制的主要入口。
  • JavaScript 可以增强交互，但不改变 CSS-only 用户的基础用法。

Class 命名

.pui 是一个特殊的基础启用 class，用于原生 HTML 控件的 WPUIE 样式入口。除此之外，公共 class 都以 pui- 开头。

用途 命名形式 示例
原生控件基础样式 .pui button.pui
组件 .pui-{component} .pui-btn、.pui-dialog
可复用视觉变体 .pui-{variant} .pui-primary、.pui-success
组件专属变体 .pui-{component}-{variant} .pui-btn-compact
组件状态 .pui-is-{state} .pui-is-loading、.pui-is-open
明确的视觉工具类 .pui-{property}-{value} .pui-border-2

命名选择遵循以下规则：

  1. 能跨多个组件复用的视觉能力使用 .pui-{variant}，例如颜色主题和边框风格。
  2. 只适用于一个组件的能力使用 .pui-{component}-{variant}，避免产生含义过宽的公共 class。
  3. 状态 class 只用于自定义组件或 JavaScript 管理的状态；原生控件优先使用 :disabled、:checked、:read-only 等原生状态。
  4. 工具类只在有明确、稳定的使用场景时增加，不把每个 CSS 属性都暴露成 class。
  5. 同一种能力只保留一种推荐写法，不同时维护多个等价的公共 class。

推荐示例

<button class="pui pui-primary pui-border-2">
  Save
</button>

<a class="pui-btn pui-success" href="/save">
  Save
</a>

<div class="pui-dialog pui-is-open" role="dialog" aria-modal="true">
  Content
</div>

上面的 class 只表达视觉或组件实现。真实的禁用、选中、展开等语义仍然应该写在 HTML 属性上：

<button class="pui pui-primary" disabled>Save</button>
<details class="pui-details" open>...</details>

HTML 属性职责

应保留为原生语义

以下属性表达 HTML 或无障碍语义，不应被视觉 class 替代：

  • disabled、checked、selected、open、required、readonly；
  • aria-expanded、aria-selected、aria-checked、aria-disabled 等真实的 ARIA 状态；
  • 原生元素本身定义的属性，例如 type、name、value 和合法的 size。

CSS 应根据这些属性或伪类绘制状态。JavaScript 更新状态时，也必须同步更新对应的 DOM 属性或 ARIA 状态。

不作为视觉 API

size、bsize、fill、animation、inline、at-after 等仅用于改变外观的自定义属性不作为新的公共 API。它们应逐步迁移到带 pui- 前缀的 class 或 CSS 变量。

data-pui-* 只用于 JavaScript 初始化、内部协议或调试信息，不作为主要视觉配置入口。文档中的视觉示例不应依赖它们。

CSS 变量

公共 CSS 变量统一使用 --pui- 前缀：

:root {
  --pui-primary: #209cee;
  --pui-primary-hover: #108de0;
  --pui-primary-shadow: #006bb3;
}

.my-button {
  --pui-btn-background: var(--pui-primary);
  --pui-btn-border-width: 4px;
}
  • 主题 token 使用 --pui-{token}；
  • 组件公开参数使用 --pui-{component}-{property}；
  • 未加 pui 命名空间的自定义属性不应作为公共定制接口；
  • 实现内部变量不保证兼容，不能写入组件文档或示例。

CSS 变量用于连续值和主题值，例如颜色、尺寸、间距、边框宽度。离散的视觉选择使用 class，例如 pui-primary 和 pui-border-2。

选择器范围

新的公共样式应满足以下约束：

  • 组件样式必须由明确的 WPUIE class 进入，例如 .pui-dialog 或 button.pui；
  • 不使用裸的 input[type=checkbox]、button 等全局选择器改变未启用 WPUIE 的原生控件；
  • 原生状态选择器可以组合在组件 class 后面，例如 .pui-dialog[open]；
  • 组件内部实现应尽量降低选择器层级，并通过 Cascade Layers 管理覆盖顺序。

旧 API 迁移方向

旧 API 在过渡期可以保留兼容选择器，但新文档、测试和示例只使用以下目标写法：

旧写法 目标写法
.primary、.success、.warning、.error .pui-primary、.pui-success、.pui-warning、.pui-error
.inline .pui-inline
.fill .pui-fill 或对应组件的 pui-{component}-fill
.at-after .pui-at-after
.animation .pui-animation
.resizer、.resizer2 .pui-resizer、.pui-resizer-2
bsize="1"、bsize="2" .pui-border-1、.pui-border-2
视觉上的 .disabled 原生 disabled，或自定义组件的 .pui-is-disabled

迁移时应先增加新选择器和回归测试，再决定旧写法的弃用周期。不能在没有兼容说明的情况下直接改变已有 class 的含义。

最小验收标准

CSS API 的第一版实现至少应满足：

  • 新增的公共 class 全部带 pui- 前缀；
  • 文档和示例不依赖无命名空间的视觉 class 或自定义视觉属性；
  • 原生控件在未添加 WPUIE class 时保持浏览器默认样式；
  • disabled、checked、open 等真实状态仍由 HTML/ARIA 表达；
  • 主题和组件可调参数均有稳定的 --pui-* 入口；
  • 新旧 API 的兼容选择器有明确测试覆盖。