# 纯组件库

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

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

</aside>

# 技术栈

- UI库: element plus [https://element-plus.org/en-US/](https://element-plus.org/en-US/)
- 组件管理: storyBook [https://storybook.js.org/](https://storybook.js.org/)
- 样式: tailwind [https://tailwindcss.com/](https://tailwindcss.com/)
- 图标库: lucide [https://lucide.dev/](https://lucide.dev/)
- 框架: vue3 [https://vuejs.org/](https://vuejs.org/)
- 构建工具: vite
- 工具函数: vueuse [https://vueuse.org/](https://vueuse.org/)、lodash-es [https://lodash.com/](https://lodash.com/)
- 编码语言: typescript [https://www.typescriptlang.org/](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
```

# 准备

## 快速创建

标准组件范式的文件

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

# Mac
pnpm gen button components

# windows
pnpm gen:win button components
```

## 启动开发环境

```bash
# 进入目录
cd packages/ui-vue3

pnpm dev
```

## 发布

### 文档

```shell
pnpm publish:story
```

### 组件

```shell
pnpm publish:components
```

# 开发流程

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

## 用例 `最重要`

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

```tsx
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文档说明避免冗余；组件结构严格按照工具生成规范

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

### 组件内部依赖引用

```tsx
// ✅ 正确, 内部引入方式
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

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

</aside>

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

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