vue-dd-ui/COMPONENTS.md

基于 Element UI 二次封装的 Vue.js 组件库，提供17个精心设计的组件和70+工具函数

# 组件详细文档

本文档详细介绍了 Vue DD UI 组件库中所有组件的使用方法。

## 目录

- [基础组件](#基础组件)
  - [dd-button 按钮](#dd-button-按钮)
  - [dd-icon 图标](#dd-icon-图标)
- [表单组件](#表单组件)
  - [dd-form 动态表单](#dd-form-动态表单)
  - [dd-debounce 防抖组件](#dd-debounce-防抖组件)
  - [dd-select-icon 图标选择器](#dd-select-icon-图标选择器)
- [数据展示](#数据展示)
  - [dd-list 增强列表](#dd-list-增强列表)
  - [dd-fold-card 折叠卡片](#dd-fold-card-折叠卡片)
- [工具函数](#工具函数)
  - [日期工具](#日期工具)
  - [数组工具](#数组工具)
  - [验证工具](#验证工具)

---

## 基础组件

### dd-button 按钮

基于 Element UI Button 组件增强，支持更多业务场景。

#### 基础用法

```vue
<template>
  <div>
    <!-- 基础按钮 -->
    <dd-button label="默认按钮" @click="handleClick" />

    <!-- 不同类型 -->
    <dd-button label="主要按钮" type="primary" @click="handleClick" />
    <dd-button label="成功按钮" type="success" @click="handleClick" />
    <dd-button label="警告按钮" type="warning" @click="handleClick" />
    <dd-button label="危险按钮" type="danger" @click="handleClick" />

    <!-- 带图标 -->
    <dd-button label="搜索" icon="search" type="primary" @click="handleClick" />

    <!-- 文件上传按钮 -->
    <dd-button
      label="导入Excel"
      button-mode="import"
      accept=".xls,.xlsx"
      @click="handleFileUpload"
    />
  </div>
</template>

<script>
  export default {
    methods: {
      handleClick(data) {
        console.log("按钮点击:", data);
      },
      handleFileUpload(data) {
        console.log("文件上传:", data.file);
      },
    },
  };
</script>
```

#### API

##### Props

| 参数       | 说明                   | 类型    | 可选值                                   | 默认值     |
| ---------- | ---------------------- | ------- | ---------------------------------------- | ---------- |
| label      | 按钮文字               | String  | —                                        | —          |
| type       | 按钮类型               | String  | primary/success/warning/danger/info/text | default    |
| icon       | 图标名称               | String  | —                                        | —          |
| loading    | 加载状态               | Boolean | —                                        | false      |
| buttonMode | 按钮模式               | String  | default/import                           | default    |
| accept     | 文件类型(仅upload模式) | String  | —                                        | .xls,.xlsx |

##### Events

| 事件名 | 说明     | 参数                  |
| ------ | -------- | --------------------- |
| click  | 点击事件 | { code, label, file } |

---

### dd-icon 图标

图标组件，基于自定义字体图标。

#### 基础用法

```vue
<template>
  <div>
    <dd-icon icon="search" :size="16" />
    <dd-icon icon="user" :size="20" />
    <dd-icon icon="setting" :size="24" />
  </div>
</template>
```

#### API

##### Props

| 参数 | 说明     | 类型   | 默认值 |
| ---- | -------- | ------ | ------ |
| icon | 图标编码 | String | —      |
| size | 图标大小 | Number | 12     |

---

## 表单组件

### dd-form 动态表单

强大的动态表单组件，支持多种表单控件类型。

#### 基础用法

```vue
<template>
  <dd-form
    ref="form"
    :items="formItems"
    :loading="loading"
    @click="handleFormClick"
    @change="handleFormChange"
  />
</template>

<script>
  export default {
    data() {
      return {
        loading: false,
        formItems: [
          {
            type: "input",
            key: "name",
            label: "姓名",
            placeholder: "请输入姓名",
            rules: [{ required: true, message: "请输入姓名" }],
          },
          {
            type: "select",
            key: "gender",
            label: "性别",
            options: [
              { key: "1", value: "男" },
              { key: "2", value: "女" },
            ],
          },
          {
            type: "date",
            key: "birthday",
            label: "出生日期",
            valueFormat: "yyyy-MM-dd",
          },
        ],
      };
    },
    methods: {
      handleFormClick(data) {
        if (data.code === "BtnSearch") {
          const formData = this.$refs.form.getValue();
          console.log("表单数据:", formData);
        }
      },
      handleFormChange(key, value) {
        console.log("字段变化:", key, value);
      },
    },
  };
</script>
```

#### 支持的表单控件类型

| 类型        | 说明     | 示例     |
| ----------- | -------- | -------- |
| input       | 输入框   | 文本输入 |
| number      | 数字输入 | 年龄输入 |
| select      | 下拉选择 | 状态选择 |
| radio       | 单选框   | 性别选择 |
| checkbox    | 复选框   | 兴趣选择 |
| date        | 日期选择 | 生日选择 |
| datetime    | 日期时间 | 预约时间 |
| cascader    | 级联选择 | 地区选择 |
| switch      | 开关     | 启用状态 |
| slider      | 滑块     | 评分     |
| rate        | 评分     | 商品评价 |
| upload      | 上传     | 文件上传 |
| selecttree  | 树选择   | 部门选择 |
| selectpopup | 弹窗选择 | 用户选择 |

---

### dd-debounce 防抖组件

防抖容器组件，防止用户频繁操作。

#### 基础用法

```vue
<template>
  <dd-debounce :time="500">
    <dd-button label="防抖按钮" @click="handleClick" />
    <dd-button label="另一个按钮" @click="handleClick2" />
  </dd-debounce>
</template>

<script>
  export default {
    methods: {
      handleClick() {
        console.log("防抖点击1");
      },
      handleClick2() {
        console.log("防抖点击2");
      },
    },
  };
</script>
```

---

## 数据展示

### dd-list 增强列表

基于 Element Table 的增强列表组件，集成搜索、分页、操作等功能。

#### 基础用法

```vue
<template>
  <dd-list
    ref="list"
    :search-items="searchItems"
    :list-items="listItems"
    :list-buttons="listButtons"
    :data-load="loadData"
    @btnClick="handleBtnClick"
  />
</template>

<script>
  export default {
    data() {
      return {
        searchItems: [
          {
            type: "input",
            key: "name",
            label: "姓名",
            placeholder: "请输入姓名",
          },
          {
            type: "select",
            key: "status",
            label: "状态",
            options: [
              { key: "1", value: "启用" },
              { key: "0", value: "禁用" },
            ],
          },
        ],
        listItems: [
          { prop: "name", label: "姓名", width: 120 },
          { prop: "age", label: "年龄", width: 80 },
          { prop: "email", label: "邮箱", minWidth: 200 },
          {
            prop: "status",
            label: "状态",
            width: 100,
            options: [
              { key: "1", value: "启用" },
              { key: "0", value: "禁用" },
            ],
          },
        ],
        listButtons: [
          { code: "add", label: "新增", type: "primary", icon: "plus" },
          { code: "edit", label: "编辑", type: "text" },
          { code: "delete", label: "删除", type: "text" },
        ],
      };
    },
    methods: {
      loadData(vue, params) {
        // 模拟接口请求
        return new Promise(resolve => {
          setTimeout(() => {
            resolve({
              datas: [
                {
                  id: 1,
                  name: "张三",
                  age: 25,
                  email: "zhang@example.com",
                  status: "1",
                },
                {
                  id: 2,
                  name: "李四",
                  age: 30,
                  email: "li@example.com",
                  status: "0",
                },
              ],
              total: 2,
            });
          }, 1000);
        });
      },
      handleBtnClick(data) {
        console.log("按钮点击:", data);
        if (data.code === "add") {
          // 新增逻辑
        } else if (data.code === "edit") {
          // 编辑逻辑
          console.log("编辑行数据:", data.row);
        }
      },
    },
  };
</script>
```

#### 高级功能

##### 虚拟滚动

处理大数据量时启用虚拟滚动：

```vue
<dd-list
  :use-virtual="true"
  :height="400"
  page-type="no"
  :data-load="bigDataLoad"
/>
```

##### 树形数据

显示树形结构数据：

```vue
<dd-list
  :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
  :data-load="treeDataLoad"
/>
```

---

## 工具函数

### 日期工具

```javascript
// 格式化日期
this.$ddDateUtil.format(new Date(), "YYYY-MM-DD HH:mm:ss");

// 获取当前日期
this.$ddDateUtil.getNowDay("YYYY-MM-DD");

// 获取本周开始时间
this.$ddDateUtil.getStartDayOfWeek();

// 获取本月开始时间
this.$ddDateUtil.getStartDayOfMonth();

// 获取日期范围
this.$ddDateUtil.getAllDate("2023-01-01", "2023-01-07");
```

### 数组工具

```javascript
// 数组去重
this.$ddUnique([1, 1, 2, 3]); // [1, 2, 3]

// 数组排序
this.$ddOrderBy(users, "age", "desc");

// 数组分组
this.$ddGroupBy(users, user => user.department);

// 集合运算
this.$ddUnion([1, 2], [2, 3]); // 并集: [1, 2, 3]
this.$ddIntersect([1, 2], [2, 3]); // 交集: [2]
this.$ddMinus([1, 2], [2, 3]); // 差集: [1]
```

### 验证工具

```javascript
// 邮箱验证
this.$ddValidate.isEmail("user@example.com"); // true

// 手机号验证
this.$ddValidate.isPhone("13800138000"); // true

// 身份证验证
this.$ddValidate.isIdCard("身份证号"); // true

// 数字验证
this.$ddValidate.isNumber("123"); // true

// 中文验证
this.$ddValidate.isChina("中文"); // true
```

更多组件和工具函数的详细用法，请参考原有文档或查看源代码示例。