跳转到正文

样式规范 ​

组件库不能靠 scoped 做隔离,也不该把库前缀散落在几十个文件里。规则只有一条:所有类名和 CSS 变量都从 lib.config.ts 的 cssPrefix 派生,组件代码里不写死前缀。

源码用纯 CSS、SCSS 还是 Less,只在 pnpm bootstrap 问一次。发布物始终是 CSS,使用方不安装预处理器。

命名约定 ​

以 cssPrefix: 'pl'、组件 button 为例:

角色写法示例用途
Block<prefix>-<block>pl-button组件根节点
Block 变体<prefix>-<block>-<后缀>pl-button-group同族组件,例如按钮组
Element__<element>pl-button__content组件内部节点
Modifier--<modifier>pl-button--primary由 props 决定的外观分支
Stateis-<state>is-disabled临时状态,与 Block 组合
全局令牌--<prefix>-<name>--pl-color-primary跨组件复用的设计令牌
组件级变量--<prefix>-<block>-<name>--pl-button-bg只属于该组件的可覆盖变量

State 故意不带组件前缀。它描述的是「当前是什么状态」,配合 Block 使用即可定位:.pl-button.is-disabled。

前缀只有一个来源 ​

text
lib.config.ts (cssPrefix)
  └─ pnpm gen sync
       └─ packages/utils/src/css-prefix.ts  →  export const CSS_PREFIX = 'pl'
            └─ createNamespace() 的默认前缀

packages/utils/src/css-prefix.ts 带有 // generated by contract:sync 标记,不要手改。要换前缀就改 lib.config.ts,再执行 pnpm gen sync;pnpm bootstrap 初始化新库时会一并写好这两个文件,并把模板里 pl- 开头的类名批量改成新前缀。

createNamespace ​

ts
import { createNamespace } from '@internal/utils';

const ns = createNamespace('button');
方法返回
ns.b()pl-button
ns.b('group')pl-button-group
ns.e('content')pl-button__content
ns.m('primary')pl-button--primary
ns.be('group', 'item')pl-button-group__item
ns.em('icon', 'large')pl-button__icon--large
ns.is('disabled')is-disabled
ns.is('disabled', false)''
ns.cssVar('color-primary')--pl-color-primary
ns.cssVarBlock('bg')--pl-button-bg
ns.prefix / ns.block'pl' / 'button'

第二个参数可以显式指定前缀,例如 createNamespace('button', 'demo'),仅在测试或特殊子命名空间时才需要。

在组件里使用 ​

生成器产出的骨架已经接好命名空间,实现时继续往下加 element 和 modifier 即可:

vue
<script setup lang="ts">
import { createNamespace, cx } from '@internal/utils';

defineOptions({ name: 'PlButton' });

const props = withDefaults(defineProps<{ type?: 'primary' | 'default'; disabled?: boolean }>(), {
  type: 'default',
  disabled: false,
});

const ns = createNamespace('button');
</script>

<template>
  <button
    :class="cx(ns.b(), ns.m(props.type), ns.is('disabled', props.disabled))"
    :disabled="props.disabled"
  >
    <span :class="ns.e('content')">
      <slot />
    </span>
  </button>
</template>

ns.is() 在条件为 false 时返回空字符串,cx 会把它过滤掉;用数组绑定 :class="[ns.b(), ns.is('disabled', props.disabled)]" 也可以,Vue 同样会忽略空串。

样式怎么写 ​

CSS 读不到运行时变量,所以 <style> 里仍然写字面量类名,前缀必须与 cssPrefix 一致:

vue
<style>
.pl-button {
  background: var(--pl-button-bg, var(--pl-color-bg));
  border: 1px solid var(--pl-color-border);
}

.pl-button__content {
  display: inline-flex;
  gap: 4px;
}

.pl-button.is-disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
</style>

把组件级变量写成 var(--pl-button-bg, <默认值>),使用方就能只覆盖一个变量而不必和选择器权重较劲:

css
.checkout-page {
  --pl-button-bg: #f5f7fa;
}

令牌定义在 packages/core/styles/tokens.css,完整引入走 style.css,按需引入要单独引 @plinth/ui/tokens.css,见使用组件库。

CSS 预处理器 ​

基座出厂不装预处理器:模板依赖里没有 sass-embedded / sass / less,示例组件是纯 <style>。接不接、接 SCSS 还是 Less,只在 pnpm bootstrap 问一次。

选完之后基座会写好依赖和 lib.config.ts 的 preprocessor 字段;之后 pnpm gen component 读取该字段,带样式的骨架自动带上对应 lang。作者不必再手改 catalog 或各包 package.json。

初始化时选择 ​

交互式会问 CSS preprocessor。非交互:

bash
pnpm bootstrap --yes --name @acme/ui --prefix Ac --registry https://registry.npmjs.org/ --preprocessor none
pnpm bootstrap --yes --name @acme/ui --prefix Ac --registry https://registry.npmjs.org/ --preprocessor scss
pnpm bootstrap --yes --name @acme/ui --prefix Ac --registry https://registry.npmjs.org/ --preprocessor less

--preprocessor 默认 none。不要根据底层 UI 框架的源码语言来选:Ant Design Vue 用 Less、Antdv Next 用 CSS-in-JS、Element Plus 用 SCSS、TDesign 用 Less,只表示它们怎么构建;二开并不编译对方源码,主题桥接仍是 packages/core/styles/tokens.css。

选项写入 lib.config.ts依赖已有库组件之后 pnpm gen component --style
none(默认)preprocessor: 'none'不增依赖保持 <style><style>
scsspreprocessor: 'scss'catalog 增加 sass-embedded,并写入根目录、docs、playground、@internal/build、发布包<style> 改为 <style lang="scss"><style lang="scss">
lesspreprocessor: 'less'同上,包名换成 less<style lang="less"><style lang="less">

preprocessor 与 cssPrefix 一样,是唯一来源。pnpm gen component 不会再问预处理器。选了 scss 时不要再装一份纯 JS 的 sass,以免两个实现抢解析顺序。

生成组件 ​

bash
pnpm gen component date-picker --style

生成器只问组件名和是否带 <style>。若 bootstrap 选了 scss,骨架会是:

vue
<script setup lang="ts">
import { createNamespace } from '@internal/utils';

defineOptions({ name: 'PlDatePicker' });

const ns = createNamespace('date-picker');
</script>

<template>
  <div :class="ns.b()">
    <slot />
  </div>
</template>

<style lang="scss">
.pl-date-picker {
  color: var(--pl-color-text);
}
</style>

类名仍由 createNamespace 给出。可以在 SCSS / Less 里用 &__element 嵌套,编译结果必须仍是 .pl-date-picker__panel 这种 BEM 类名。也可以抽到同目录 .scss / .less 再 import;契约层会识别这些扩展名。

文档示例和 playground 属于应用代码,不受库组件的 lang 约束。

初始化之后改选择 ​

pnpm bootstrap 只能跑一次。若当时选了 none,后来才要 SCSS:

  1. 把 lib.config.ts 的 preprocessor 改成 'scss'。
  2. 在 pnpm-workspace.yaml 的 catalog: 增加 'sass-embedded': ^1.93.0(Less 则是 'less': ^4.4.0)。
  3. 在下列文件的 devDependencies 中写入 "sass-embedded": "catalog:"(Less 换成 less):
    • 根目录 package.json
    • docs/package.json
    • playground/package.json(若还保留 playground)
    • internal/build/package.json
    • packages/core/package.json
  4. 把 packages/components/**/*.vue 里无 lang 的 <style> 改成 <style lang="scss">。
  5. pnpm install && pnpm verify。

从 scss 换成 less(或反过来)时,同步替换包名和 lang,不要两个编译器并存。

硬性约束 ​

  • 不写 <style scoped>。隔离依靠前缀,理由见新增组件;packages/**/*.vue 上的 lint 规则会直接拦住。
  • 不写裸标签选择器(button {}、input {})和全局元素样式,所有规则都从自己的 Block 类名起步。
  • Element 只有一层。pl-button__content__icon 是错的,需要层级就新起一个 Block。
  • 不在 TS 或模板里手拼前缀字符串('pl-' + name、`pl-button--${type}`),一律走 createNamespace。
  • 不在预处理器里另写一套变量拼类名,也不用 Sass / Less 变量当主题 API。可覆盖值继续用 var(--pl-button-bg, <默认值>)。
  • 不把 .scss / .less 写进发布包的 exports,使用方只消费 CSS。
  • 二开第三方组件时同样从自己的 Block 往下写,不要输出全局 .ant-* / .el-* / .t-* 规则,详见 UI 框架。