纯组件库

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

技术栈

• 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/
• 异步状态管理: tanStack/vue-query
• 构建工具: 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 '@/components'

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

单元、UI测试

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

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

🍕 基础组件 components

| 名称 | 类型 | 用例 | 说明 | | ---------- | -------- | ----------------------------------------------------------------------------------------- | ---- | | 文本 | 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

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