0.0.4

Development Guide 高级组件开发指南 ​

本文说明 高级组合组件在 uniboot-ui monorepo 中的定位、目录约定、本地开发与构建、与 文档站 联调方式，以及新增组件时的推荐流程。

TIP

安装与对外 API 说明以各组件文档为准；本页面向仓库贡献者与内部扩展维护者。

仓库定位 ​

  • 职责：在 uniboot-ui 的 U* 原子组件之上，提供 组合级能力（如 ProLayout、PageContainer、ProTable、LoginPage 等），语义对齐 Ant Design Pro 中常用子集。
  • 边界：高级组件源码位于 packages/components 下各子目录（如 pro-table/、pro-layout/），与原子组件同包维护，不依赖业务项目。
  • 发布：与 uniboot-ui 主包一并构建发布；业务侧 pnpm add uniboot-ui 即可 import { ProTable } from 'uniboot-ui'。

monorepo 目录关系 ​

text
uniboot-ui/
├── packages/
│   ├── components/           # 原子 U* 与高级组件源码
│   │   ├── index.ts          # 聚合导出
│   │   ├── button/
│   │   ├── pro-table/
│   │   └── pro-layout/
│   └── uniboot-ui/           # 对外 npm 包入口，re-export components
├── docs/                     # VitePress，含 zh-CN/component 文档与 examples
├── play/                     # 组件演练场
└── internal/build/           # 统一构建 → dist/uniboot-ui

依赖与代码流向 ​

mermaid
flowchart LR
  PCOM["packages/components"]
  PUI["packages/uniboot-ui"]
  DIST["dist/uniboot-ui"]
  PCOM --> PUI
  PUI --> DIST
  • 源码 import：高级组件内使用 @uniboot-ui/components、@uniboot-ui/hooks 等内部包，禁止 import from 'uniboot-ui'（避免与聚合出口循环依赖）。
  • 对外 import：import { ProTable } from 'uniboot-ui'。
  • echarts：仅 ProChart 需要；@uniboot-ui/components 将 echarts 标为 optional peer。

环境要求 ​

  • Node：>= 22（以根目录 package.json 的 engines 为准）。
  • 包管理：pnpm（packageManager 锁定版本）。

克隆与安装 ​

bash
cd uniboot-ui
pnpm install

目录与模块结构 ​

高级组件典型布局：

text
packages/components/
├── index.ts
├── pro-layout/
├── pro-table/
├── pro-descriptions/
└── query-filter/

新增高级组件子模块时：

  1. 在 packages/components/<模块名>/ 放置 *.vue、types.ts、index.ts。
  2. 在 packages/components/index.ts 增加 export * from './<模块名>'。
  3. 同步 docs/zh-CN/component/*.md 与 docs/examples/ 示例。
  4. 单测放在 <模块名>/__tests__/ 下，命名与现有高级组件一致（如 pro-table.test.tsx）。

常用命令 ​

命令说明
pnpm dev启动 play 演练场，联调组件与高级组件
pnpm test全量单测（含高级组件）
pnpm typecheck:web含 packages/components 的类型检查
pnpm build全量构建，产出 dist/uniboot-ui
pnpm docs:dev文档站开发，示例 import from 'uniboot-ui' 联调源码

按需解析（resolver） ​

ts
import {
  UnibootCombinedResolver,
  UnibootProComponentsResolver,
  UnibootUIResolver,
} from 'uniboot-ui/resolver'
  • UnibootProComponentsResolver：自动解析 ProTable、ProLayout 等。
  • UnibootCombinedResolver：同时注册 U* 与 Pro*。

与文档站联调 ​

  • 文档示例统一 import { ProTable } from 'uniboot-ui'。
  • Vite 已将 uniboot-ui 别名到 packages/uniboot-ui/index.ts，改源码后热更新。
  • 生产文档构建（DOC_ENV=production）在 pnpm build 之后使用 dist/uniboot-ui。

质量检查清单（提交前） ​

  • [ ] pnpm test 通过。
  • [ ] pnpm typecheck 无报错。
  • [ ] pnpm build 成功，dist/uniboot-ui/es/components/pro-table 等存在。
  • [ ] 若修改对外 API，同步更新 docs/zh-CN/component/*.md 与示例。

相关链接 ​