# getListApi Mixin 使用文档

## 概述

getListApi 是一个 Vue mixin，提供列表页面的通用功能，包括数据获取、分页、搜索、导出等功能。特别针对日期范围选择器进行了优化，支持灵活配置单个或多个日期范围选择器。

## 功能特性

- 自动处理列表数据获取和分页
- 支持搜索和重置功能
- 支持数据导出功能
- 灵活处理日期范围选择器参数
- 支持多选操作

## 数据属性

| 属性名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| loading | Boolean | false | 数据加载状态 |
| multipleSelection | Array | [] | 多选选中的数据 |
| search | Object | {} | 搜索参数 |
| queryParams | Object | {pageNum: 1, pageSize: 10} | 分页参数 |
| total | Number | 0 | 数据总条数 |
| dataList | Array | [] | 列表数据 |
| showSearch | Boolean | true | 控制搜索栏显示/隐藏 |
| dateTimeNum | Number | 0 | 日期范围查询参数个数 |
| dateRangeMapping | Object | {} | 日期范围字段映射配置 |

## 方法

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| getList | - | Promise | 获取列表数据 |
| handleQuery | - | - | 执行搜索 |
| resetQuery | - | - | 重置搜索条件 |
| handleExport | - | - | 导出数据 |
| selectionChange | selection | - | 多选变更处理 |
| processDateRangeParams | params | Object | 处理日期范围参数 |

## 使用方法

### 1. 基础使用

```javascript
// 在组件中引入并使用 mixin
import getListApi from '@/mixins/getListApi'

export default {
  mixins: [getListApi],
  data() {
    return {
      // 定义列表数据获取接口
      listURL: yourApiFunction
    }
  }
}
```

### 2. 配置日期范围选择器

#### 不使用日期范围选择器
```javascript
data() {
  return {
    // 不定义 dateRangeMapping 或设为空对象
    dateRangeMapping: {},
    listURL: yourApiFunction
  }
}
```

#### 使用单个日期范围选择器
```javascript
data() {
  return {
    // 日期范围字段映射配置
    dateRangeMapping: {
      // 日期范围字段名: { start: 开始时间字段名, end: 结束时间字段名 }
      createTime: { start: 'beginTime', end: 'endTime' }
    },
    listURL: yourApiFunction
  }
}
```

#### 使用多个日期范围选择器
```javascript
data() {
  return {
    // 支持多个日期范围字段配置
    dateRangeMapping: {
      createTime: { start: 'createTimeStart', end: 'createTimeEnd' },
      updateTime: { start: 'updateTimeStart', end: 'updateTimeEnd' }
    },
    listURL: yourApiFunction
  }
}
```

### 3. 模板使用示例

```vue
<template>
  <div>
    <!-- 搜索区域 -->
    <el-form :model="search" label-width="100px">
      <!-- 普通搜索字段 -->
      <el-form-item label="用户名">
        <el-input v-model="search.userName" />
      </el-form-item>
      
      <!-- 日期范围选择器 -->
      <el-form-item label="创建时间">
        <el-date-picker
          v-model="search.createTime"
          type="daterange"
          range-separator="至"
          start-placeholder="开始日期"
          end-placeholder="结束日期"
          value-format="yyyy-MM-dd"
        />
      </el-form-item>
    </el-form>
    
    <!-- 表格数据 -->
    <el-table
      v-loading="loading"
      :data="dataList"
      @selection-change="selectionChange"
    >
      <!-- 表格列定义 -->
    </el-table>
    
    <!-- 分页 -->
    <pagination
      v-show="total > 0"
      :total="total"
      :page.sync="queryParams.pageNum"
      :limit.sync="queryParams.pageSize"
      @pagination="getList"
    />
  </div>
</template>
```

### 4. 请求参数处理流程

当使用日期范围选择器时，数据流处理如下：

1. 用户在页面上选择日期范围：`search.createTime = ['2023-01-01', '2023-12-31']`
2. 点击搜索时，调用 handleQuery 方法
3. handleQuery 调用 getList
4. getList 调用 processDateRangeParams 处理参数
5. 根据 dateRangeMapping 配置，将日期范围拆分为独立参数：
   ```javascript
   // 处理前
   {
     createTime: ['2023-01-01', '2023-12-31'],
     userName: 'test'
   }
   
   // 处理后
   {
     beginTime: '2023-01-01',
     endTime: '2023-12-31',
     userName: 'test'
   }
   ```
6. 将处理后的参数发送给后端接口

### 5. 导出功能使用

```javascript
data() {
  return {
    // 导出配置
    exportObj: {
      url: '/api/export',  // 导出接口地址
      name: '用户列表'      // 导出文件名前缀
    },
    dateRangeMapping: {
      createTime: { start: 'beginTime', end: 'endTime' }
    },
    listURL: yourApiFunction
  }
}
```

### 6. 完整示例

```javascript
import getListApi from '@/mixins/getListApi'

export default {
  mixins: [getListApi],
  
  data() {
    return {
      // 配置日期范围映射
      dateRangeMapping: {
        createTime: { start: 'beginTime', end: 'endTime' }
      },
      
      // 导出配置
      exportObj: {
        url: '/api/user/export',
        name: '用户列表'
      },
      
      // 列表数据获取接口
      listURL: getUserList
    }
  },
  
  methods: {
    // 可以覆盖或扩展 mixin 中的方法
    async getList() {
      // 添加额外的处理逻辑
      console.log('准备获取列表数据')
      
      // 调用 mixin 中的方法
      await this.$options.mixins[0].methods.getList.call(this)
      
      console.log('列表数据获取完成')
    }
  }
}
```

## 注意事项

1. 必须在组件中定义 listURL 属性，指定获取列表数据的接口函数
2. 如需使用导出功能，需要定义 exportObj 对象
3. 日期范围选择器的值必须是包含两个元素的数组格式 `[startDate, endDate]`
4. dateRangeMapping 配置是可选的，如果不使用日期范围选择器可以不配置