主题
快速开始
本页面向第一次接触此仓库的开发者。完成后,你会启动本地环境、修改示例组件,并知道一次组件变更如何通过验证。
还没有初始化仓库?
如果仓库中仍然存在 pnpm bootstrap,请先按照根目录 README.md 完成一次性初始化,再回到这里。初始化会设置包名、组件前缀、注册地址、UI 框架,以及 CSS 预处理器(none / scss / less)。预处理器选完后,pnpm gen component 会按 lib.config.ts 写出对应的 <style lang>。
环境准备
- Node.js
>= 20.19 - pnpm
>= 10 - Git
bash
node -v
pnpm -v
git --version此仓库只允许使用 pnpm。第一次拉取代码后安装依赖:
bash
pnpm install启动开发环境
组件开发通常同时使用两个入口:
bash
# 启动 playground,适合快速调试组件
pnpm dev
# 启动 VitePress,检查文档与示例
pnpm dev:docs终端会打印本地访问地址。两个命令需要分别占用一个终端。
认识示例代码
仓库预置了最小的 PlButton 和 useToggle,用于证明整条链路可用:
packages/components/button/:组件源码与单元测试packages/hooks/src/use-toggle/:组合式函数源码docs/components/button/:组件文档和可运行示例docs/hooks/use-toggle/:组合式函数文档
它们是实验品,不代表业务设计规范。建立自己的组件库后,可以改写或删除。
新增第一个组件
bash
pnpm gen component例如输入 date-picker。组件前缀由 lib.config.ts 的 componentPrefix 决定,不要在输入时重复写 Pl。样式语言由同一份配置里的 preprocessor 决定:bootstrap 选了 scss 或 less 时,生成的 SFC 会带上对应 lang;选 none 则是纯 <style>。
生成器会创建源码、文档和示例,并自动同步公开导出、resolver 和全局类型。随后:
- 在
packages/components/date-picker/date-picker.vue实现组件。 - 新建
date-picker.test.ts,覆盖最重要的交互和边界。 - 在
docs/components/date-picker/index.md写清用途、示例和 API。 - 在 playground 中调试,在文档站中检查示例。
完整规范见新增组件。
提交前验证
bash
pnpm verify该命令会依次执行:
- TypeScript 与 Vue 类型检查
- ESLint
- Vitest
- 源码与生成契约的一致性检查
- 文档覆盖检查
- 发布包构建与包结构检查
只有全部通过,才说明这次变更具备进入主分支的基本条件。