主题
新增组件
组件、文档、分包入口和类型声明由同一份文件系统契约连接。请使用生成器创建骨架,不要手动复制旧组件。
1. 选择名称
- 输入不带组件前缀的名称,例如
date-picker - 使用 kebab-case 目录名
- 公开组件名由配置自动拼接,例如
Pl+date-picker→PlDatePicker - 不要使用
_或.开头的目录,它们不会进入组件契约
2. 生成骨架
bash
pnpm gen component交互模式会询问组件名和是否包含 <style>。样式语言不在这里问:它来自 lib.config.ts 的 preprocessor(pnpm bootstrap 时选定,none / scss / less)。也可以非交互执行:
bash
pnpm gen component date-picker --style
# 或
pnpm gen component date-picker --no-style生成器会创建:
text
packages/components/date-picker/
date-picker.vue
index.ts
docs/components/date-picker/
index.md
demo/basic.vue随后自动执行契约同步。pnpm gen sync 每次都会重写整套生成文件:
packages/components/index.ts:组件桶文件packages/hooks/src/index.ts:组合式函数桶文件packages/core/component.ts:安装器与具名导出packages/core/resolver-map.ts:resolver 用的组件表internal/build/src/generated-entries.ts:分包构建入口packages/utils/src/css-prefix.ts:由lib.config.ts的cssPrefix派生typings/global.d.ts:模板里的全局组件类型
3. 实现组件
组件至少要具备:
- 稳定、明确的 props 和 emits 类型
- props、emits 和
defineSlots每个成员都有 JSDoc 说明 - 符合组件前缀的
defineOptions({ name }) - 原生语义和键盘可访问性
- 通过设计令牌表达的颜色、边框和间距,不在业务组件里硬编码品牌值
- 由
createNamespace派生的类名,不手写库前缀
入口文件必须保留具名导出,契约层依靠它识别公开组件:
ts
export { default } from './date-picker.vue';
export { default as PlDatePicker } from './date-picker.vue';3.1 IDE 提示从 JSDoc 来
pnpm build 会用 vue-component-meta 读取组件的类型和 JSDoc,生成随包发布的 dist/web-types.json(JetBrains)和 dist/tags.json / dist/attributes.json(Vetur)。类型、默认值、字符串字面量可选值会自动提取,说明文字只能来自 JSDoc,没写注释的成员在 IDE 里就只有类型:
ts
const props = withDefaults(
defineProps<{
/** 尺寸 */
size?: 'small' | 'large';
}>(),
{ size: 'small' },
);
const emit = defineEmits<{
/** 选中日期变化时触发 */
change: [value: string];
}>();
defineSlots<{
/** 面板底部的额外内容 */
footer?: () => unknown;
}>();要废弃某个 prop、事件或插槽时,在它的 JSDoc 里加 @deprecated,并写明替代方案。JetBrains IDE 会给它加删除线,Vetur 的提示里则以「已废弃」开头;事件的 @deprecated 同样写在 defineEmits 的成员注释上:
ts
defineProps<{
/**
* 旧的尺寸写法
* @deprecated 改用 `size`
*/
scale?: 'small' | 'large';
}>();lib.config.ts 设置 docsUrl 后,提示里还会带上指向 <docsUrl>/components/<seg>/ 的文档链接。
3.2 类名与样式约定
模板里的类名全部由 createNamespace 派生,库前缀只在 lib.config.ts 中配置一次,完整约定见样式规范:
vue
<script setup lang="ts">
import { createNamespace } from '@internal/utils';
const ns = createNamespace('date-picker');
</script>
<template>
<div :class="[ns.b(), ns.is('open', visible)]">
<div :class="ns.e('panel')" />
</div>
</template>组件库里的 <style> 一律不加 scoped,包括封装第三方组件的二开组件。隔离依靠 CSS 前缀约定,而不是编译期哈希。lang 不要手写:它来自 lib.config.ts 的 preprocessor。bootstrap 选了 scss 时,生成器产出的是 <style lang="scss">(less 同理);下面按 none 写出厂形态:
vue
<style>
.pl-date-picker {
color: var(--pl-color-text);
}
.pl-date-picker__panel {
border: 1px solid var(--pl-color-border);
}
</style>原因有三个:
scoped会生成data-v-*哈希属性,哈希随构建变化,使用方无法据此写稳定的覆盖规则scoped选择器无法命中子组件和第三方组件内部结构,二开组件只能退化成写一堆:deep()- 分包构建下每个组件的 CSS 已经随自己的 JS 入口注入,作用范围本来就是按组件切分的
因此所有类名都必须带库前缀(例如 pl-),并避免裸标签选择器和全局元素样式。packages/**/*.vue 上开启了 vue/enforce-style-attribute,写了 scoped 会直接 lint 报错。
基座出厂不装 Less 或 SCSS。作者在 pnpm bootstrap 时选择 none / scss / less,生成器按 lib.config.ts 写出对应 lang。详见样式规范。
文档示例和 playground 属于应用代码,不受此约束,可以继续用 scoped 隔离示例自己的排版样式。
4. 添加测试
生成器不会替你猜业务行为,请在组件目录中新增 date-picker.test.ts。优先覆盖:
- 默认渲染与插槽
- 关键 props
- 用户交互和 emits
- disabled、空数据等边界状态
ts
import { mount } from '@vue/test-utils';
import { describe, expect, it } from 'vitest';
import DatePicker from './date-picker.vue';
describe('PlDatePicker', () => {
it('renders', () => {
const wrapper = mount(DatePicker);
expect(wrapper.exists()).toBe(true);
});
});5. 写文档
docs/components/date-picker/index.md 至少包含:
- 组件用途与不适用场景
- 一个最小可运行示例
- props、events 和 slots 说明
- 容易误用的边界条件
示例组件放在同目录的 demo/ 中。文档侧边栏根据 frontmatter 自动生成:
yaml
---
title: 日期选择器
group: 表单组件
order: 20
---6. 本地验收
bash
pnpm dev
pnpm dev:docs
pnpm verify检查 playground 中的交互、文档站中的示例和 API,再以 pnpm verify 收口。
删除组件
- 删除
packages/components/<seg>/ - 删除
docs/components/<seg>/ - 运行
pnpm gen sync - 运行
pnpm verify
不要手动编辑带有 // generated by contract:sync 标记的文件。新增组件后,无需额外编辑导出文件,pnpm verify 应当直接通过。