zan-ui-vue3

纯组件库

组件二次封装，内部维护状态，场景化变体

❤️‍🩹 1.提高项目开发质量和效率；2. 迭代成为知识库并形成整体解决方案；3. 全链路测试规范(包含业务)

技术栈

• UI库: element plus https://element-plus.org/en-US/
• 组件管理: storyBook https://storybook.js.org/
• 样式: tailwind https://tailwindcss.com/
• 图标库: lucide https://lucide.dev/
• 框架: vue3 https://vuejs.org/
• 构建工具: vite
• 工具函数: vueuse https://vueuse.org/、lodash-es https://lodash.com/
• 编码语言: typescript https://www.typescriptlang.org/

规范

• UI库采用element plus进行二次封装
• 命名采用zi 前缀 (包含组件和css变量等)， 如: ZiText (组件名称), —zi-primary-color: #FFF; （样式名称）, 如无其他特殊样式设置，样式采用tailwind 编写
• 组件主文件名统一大写驼峰命名, 如: Filter.vue，采用工具生成，参考: 准备->快速创建组件部分说明
• 单元测试仅测试二次封装部分
• 组件中使用的图标限定只能使用预设图标
• 特殊需求引入的第三方模块，需由团队确认后方可使用；如: 拖拽、裁剪等库

项目结构

ui-vue3                            # 组件库
├── README.md
├── index.ts                       # 入口文件
├── src
│   ├── components                 # 基础组件
│   │   ├── Text                   # 文本组件
│   │   │   ├── Text.stories.ts    # 预览、单测、文档配置文件
│   │   │   ├── index.ts           # 组件入口文件
│   │   │   ├── Text.d.ts          # 类型文件
│   │   │   └── Text.vue           # 组件文件
│   │   └── index.ts
│   ├── composites                 # 组合组件
│   │   ├── Filter
│   │   │   ├── Filter.ts
│   │   │   └── Filter.vue
│   │   └── Tool
│   │       ├── Tool.ts
│   │       └── Tool.vue
│   ├── features                   # 功能组件
│   └── utils
├── tsconfig.json
└── vite.config.ts

准备

快速创建

标准组件范式的文件

# 进入 ui-vue3 目录
# button 为自定义组件名称
# components 为组件类型，可选 components|composites|features|resources

# Mac
pnpm gen button components

# windows
pnpm gen:win button components

启动开发环境

# 进入目录
cd packages/ui-vue3

pnpm dev

发布

文档

pnpm publish:story

组件

pnpm publish:components

开发流程

根据方案稿，编写组件用例；完成用例编写后再进行组件开发工作，最后对封装物进行卡点测试(如当一个组件提了可选择一系列样式时，仅随机测试一个选项是否符合预期)

用例 最重要

通过生成工具生成后，相应目录下将存在一个xx.stories.ts文件，然后进行测试用例相关编写; 约定每个stories都包含名为默认的测试用例，用例名称尽量用最简短的词描述测试行为，如：文字溢出自动文字提示 → 溢出提示

export const Normal: Story = {
  name: '默认',
  args: {},
}

export const Style: Story = {
  name: '样式',
  args: {},
}

export const One: Story = {
  name: '单按钮',
  args: {},
}

export const Max: Story = {
  name: '多按钮显示限制',
  args: {},
}

组件编码

满足方案稿要求，确保功能、用户体验和视觉效果符合预期；封装之前仔细阅读element plus文档说明避免冗余；组件结构严格按照工具生成规范

Filter.vue         # 组件
Filter.type.ts     # 类型
Filter.consts.ts   # 固定值
Filter.stories.ts  # 用例、测试、文档
index.ts           # 导出

组件内部依赖引用

// ✅ 正确, 内部引入方式
import { ZiText } from '../ZiText'

// ❌ 错误, 外部引入方式
import { ZiText } from '@/components'

单元、UI测试

确保测试覆盖全部用例，严格执行，才能满足知识库的建设

• 单元测试主要测试内部模块功能完整、可用性; 单元测试文件名格式为xx.test.ts ，参考: packages/ui-vue3/src/utils/tests/format.test.ts
• UI测试主要测试用例是否符合预期，确保组件后期维护过程中稳定性； 参考: packages/ui-vue3/src/components/Dialog/Dialog.stories.ts

🍕 基础组件 components

⚠️ 采用tailwind设置样式，封装参考element plus的props、methods等风格和规范

名称	类型	用例	说明
文本	text	1.前置图标;2.后置tooltip;3.内容行数、大小、颜色;4.复制
输入框	input	1.外部前后置插槽;2.内容格式化;3.append自定义插槽(可设置外边距);4.外部后置tooltip、popover	x
选择框	select
日期	date
开关	switch
单选	radio
复选	checkbox
图标	icon		x
图片	image
上传	upload
按钮	button		x
链接	link		x
提示	tooltip
悬浮展示框	popover
表单	form
表格	table		x
对话框	dialog		x
tab	tab

🥪 组合组件 composites

定义

• 表单
  • 过滤器 - 提供筛选条件
  • 工具栏 - 实现简单条件筛选
  • 常规表单 - 单多列布局，提供校验模块
  • schema定义，预设布局、交互、校验
• 表格
  • 常规
  • 复合(订单)
  • 嵌套
  • schema定义
• 区域联动
• 交互
  • 查询表格弹框
  • 提交表单确认弹框
  • 简单查询
  • 简单日期选择
• 展示
  • 文字
  • 排版模块

🍩 资源组件 resources

• 用户
• 商品
• 地址
• 物流

🥙 功能组件 features

• 地址区块选择 - 设置物流运费模板等场景