# BaseTable

**Repository Path**: leheya/BaseTable

## Basic Information

- **Project Name**: BaseTable
- **Description**: 基于Elment Plus开源的表格组件。
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/leheya/BaseTable
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-04-05
- **Last Updated**: 2025-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BaseTable 组件

## 简介

BaseTable 是一个基于 Element Plus 的表格组件，提供了丰富的功能和灵活的配置，适用于各种业务场景。它支持数据展示、分页、搜索、排序、筛选、导出等常用功能，并且可以通过简单的配置实现复杂的表格操作。

## 目录

- [功能特点](#功能特点)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [使用方法](#使用方法)
- [属性配置](#属性配置)
- [事件](#事件)
- [列配置](#列配置)
- [插槽](#插槽)
- [扩展功能](#扩展功能)
- [常见问题](#常见问题)

## 功能特点

- ✅ 基于 Element Plus，UI 风格统一
- ✅ 支持服务端分页、排序、搜索
- ✅ 支持表格数据行展开
- ✅ 内置操作列（编辑、删除等）
- ✅ 支持导出数据为 Excel
- ✅ 支持自定义表格列渲染
- ✅ 内置搜索与重置功能
- ✅ 表格内容自适应高度
- ✅ 支持多选功能
- ✅ 支持自定义操作按钮
- ✅ 支持虚拟化数据处理
- ✅ 支持高级过滤功能
- ✅ 支持基于路由的按钮权限控制

## 环境要求

### 必备条件

- **Node.js**: v16.0.0 或更高版本
- **npm**: v7.0.0 或更高版本

### 依赖版本

- **Vue**: 3.3.4 或更高版本
- **Element Plus**: 2.4.0 或更高版本
- **TypeScript**: 5.2.2 或更高版本
- **Vite**: 4.4.9 或更高版本

### 必需插件

1. **xlsx**: 用于Excel导出功能
2. **lodash-es**: 用于高级数据处理
3. **@element-plus/icons-vue**: 提供Element Plus图标支持

## 快速开始

### 安装项目

1. **克隆项目**

```bash
git clone https://github.com/yourusername/elmentpulstable.git
cd elmentpulstable
```

2. **安装依赖**

```bash
npm install
```

3. **安装额外插件**

如果遇到缺少依赖的情况，可以手动安装以下插件：

```bash
# 安装Excel导出功能所需的依赖
npm install xlsx --save

# 安装lodash-es（防抖、节流等工具函数）
npm install lodash-es --save

# 安装Element Plus图标
npm install @element-plus/icons-vue --save
```

4. **启动开发服务器**

```bash
npm run dev
```

5. **访问应用**

打开浏览器访问: `http://localhost:5173/`

### 项目目录结构

```
src/
├── components/
│   └── BaseTable/           # 表格组件
│       ├── index.vue        # 主组件
│       └── components/      # 子组件
│           ├── table/       # 表格核心
│           └── tableToolBar/ # 工具栏
├── utils/
│   └── exportUtils.ts       # 导出工具
├── views/
│   └── TableDemo.vue        # 使用示例
├── router/
│   └── index.ts             # 路由配置
├── App.vue                  # 应用入口
└── main.ts                  # 主文件
```

## 使用方法

### 基础用法

```vue
<template>
  <BaseTable 
    ref="tableRef"
    :table-data="tableData" 
    :total="total" 
    :loading="loading"
    :page-sizes="pageSizes" 
    :columns="columns" 
    showOperations 
    table_name="user_list"
    @search="handleSearch" 
    @reset="handleReset" 
    @add="handleAdd" 
    @edit="handleEdit" 
    @delete="handleDelete"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue'
import BaseTable from '@/components/table/index.vue'

// 表格数据
const tableData = ref([])
const total = ref(0)
const loading = ref(false)
const pageSizes = [10, 20, 50, 100]

// 表格列配置
const columns = ref([
  { prop: 'id', label: 'ID', width: 80 },
  { prop: 'name', label: '姓名', width: 120 },
  { prop: 'age', label: '年龄', width: 80 },
  { prop: 'address', label: '地址' }
])

// 事件处理
const handleSearch = (keyword) => {
  // 处理搜索逻辑
}

const handleReset = () => {
  // 处理重置逻辑
}

const handleAdd = () => {
  // 处理添加逻辑
}

const handleEdit = (row) => {
  // 处理编辑逻辑
}

const handleDelete = (row) => {
  // 处理删除逻辑
}

onMounted(async () => {
  // 初始化表格数据
  // 例如从API获取数据
})
</script>
```

### 与API集成示例

BaseTable组件可以与后端API服务无缝集成：

```vue
<script setup>
import { ref, onMounted } from 'vue'
import BaseTable from '@/components/table/index.vue'
import { publicApi, activeApi } from '@/api/allApi'

const tableData = ref([])
const total = ref(0)
const loading = ref(false)
const columns = ref([])

// 获取表格配置
const getColumns = async () => {
  try {
    const result = await publicApi.getPublicConfigList('active_basic')
    columns.value = result
  } catch (error) {
    console.error('获取列配置失败:', error)
  }
}

// 获取表格数据
const fetchData = async (page = 1, size = 10, keyword = '') => {
  loading.value = true
  try {
    const res = await activeApi.getActivityList({
      getstart: (page - 1) * size,
      getnumber: size,
      pars: keyword ? { keyword } : undefined
    })
    
    if (res && res.back && res.back.data) {
      tableData.value = res.back.data.list || []
      total.value = res.back.data.pagination.total || 0
    }
  } catch (error) {
    console.error('获取数据失败:', error)
  } finally {
    loading.value = false
  }
}

onMounted(async () => {
  await getColumns()
  fetchData()
})
</script>
```

## 属性配置

| 属性名 | 说明 | 类型 | 可选值 | 默认值 |
| --- | --- | --- | --- | --- |
| table-data | 表格数据 | Array | - | [] |
| columns | 表格列配置 | Array | - | [] |
| total | 数据总条数 | Number | - | 0 |
| loading | 加载状态 | Boolean | - | false |
| page-sizes | 每页显示条数选项 | Array | - | [10, 20, 30, 50] |
| current-page | 当前页码 | Number | - | 1 |
| page-size | 每页显示条数 | Number | - | 10 |
| showOperations | 是否显示操作列 | Boolean | - | false |
| table_name | 表格名称，用于识别表格，从而进行其他的权限配置 | String | - | '' |
| expandFields | 可展开字段配置 | Array | - | [] |
| expandable | 是否可展开行 | Boolean | - | false |
| placeholder | 搜索框占位符 | String | - | '请输入关键词搜索' |
| showDatePicker | 是否显示日期选择器 | Boolean | - | false |
| selectOptions | 状态筛选选项 | Array | - | [] |

## 事件

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| search | 点击搜索按钮时触发 | 搜索关键词 |
| reset | 点击重置按钮时触发 | - |
| add | 点击添加按钮时触发 | - |
| edit | 点击编辑按钮时触发 | 当前行数据 |
| delete | 点击删除按钮时触发 | 当前行数据 |
| export | 点击导出按钮时触发 | - |
| print | 点击打印按钮时触发 | - |
| row-click | 行点击事件 | 当前行数据 |
| selection-change | 选择项发生变化时触发 | 已选择的行数据数组 |
| select-change | 选项卡或选择器值变化时触发 | 选中的值 |
| date-change | 日期选择器值变化时触发 | 日期范围值 |
| virtual | 高级过滤按钮点击时触发 | - |
| load-all-data | 加载全部数据时触发（用于高级筛选/虚拟模式） | {limit: number} 限制加载的最大数据条数 |

## 列配置

columns 数组中每一项的配置：

```javascript
{
  prop: 'name',           // 字段名
  label: '姓名',           // 列标题
  width: 120,             // 列宽度
  type: 'text',           // 字段类型: text, image, button, click, number, status
  showOverflow: true,     // 是否显示省略号
  show: true,             // 是否显示该列
  sortable: true,         // 是否可排序
  formatter: Function     // 格式化函数
}
```

字段类型支持以下值：

- `text`: 普通文本（默认）
- `image`: 图片，会渲染为`<el-image>`
- `button`: 按钮，会渲染为`<el-button>`
- `click`: 可点击文本
- `number`: 数字类型，空值显示为0
- `status`: 状态类型，会渲染为`<el-tag>`

## 插槽

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义表格内容 |
| empty | 自定义空数据显示内容 |
| append | 表格尾部内容 |
| expand | 展开行内容 |
| header | 表格头部内容 |

## 扩展功能

### 表格数据导出

BaseTable 组件内置了导出功能，可以将表格数据导出为 Excel 文件。

```vue
<BaseTable 
  ref="tableRef"
  :table-data="tableData" 
  :columns="columns" 
  @export="handleExport"
/>
```

### 表格行展开

通过 `expandable` 和 `expandFields` 属性，可以实现表格行的展开功能。

```vue
<BaseTable 
  ref="tableRef"
  :table-data="tableData" 
  :columns="columns" 
  expandable
  :expandFields="['name', 'age', 'address']"
/>
```

### 自定义表格内容渲染

通过插槽可以自定义表格内容的渲染方式。

```vue
<BaseTable 
  ref="tableRef"
  :table-data="tableData" 
  :columns="columns"
>
  <template #name="{ row }">
    <el-tag>{{ row.name }}</el-tag>
  </template>
</BaseTable>
```

### 高级筛选功能

点击"高级筛选"按钮启用虚拟模式，可以对表格数据进行更复杂的筛选操作。

**重要说明**：
- 高级筛选实际上是基于虚拟化表格技术实现的，它会一次性加载所有数据到前端进行处理
- 默认限制加载最多10,000条记录，超过此数量可能会影响浏览器性能
- 适用于中小型数据集，大型数据集建议使用基本的分页筛选功能
- 启用高级筛选后，表格将不再使用分页，而是显示全部数据

```vue
<script setup>
const handleVirtual = () => {
  console.log('启用高级筛选')
  // 处理高级筛选逻辑
}
</script>
```

**底层实现**：
```javascript
// 在BaseTable组件中的实现
const toggleVirtualMode = () => {
  isVirtualMode.value = !isVirtualMode.value
  if (isVirtualMode.value) {
    // 在虚拟模式下加载所有数据（最多10000条）
    emit('load-all-data', { limit: 10000 })
  } else {
    // 切回分页模式，重新加载当前页数据
    emit('search', { keyword: '', page: props.currentPage, pageSize: props.pageSize })
  }
}
```

## 常见问题

### 1. 表格数据不显示

**问题描述**：配置了表格但没有数据显示。

**解决方案**：
- 确认 `tableData` 数组中有数据
- 检查控制台是否有错误信息
- 确认列配置的 `prop` 属性与数据字段匹配
- 确保在数据加载完成后将 `loading` 状态设置为 `false`

```javascript
// 正确的数据加载方式
const fetchData = () => {
  loading.value = true
  // 异步获取数据
  setTimeout(() => {
    tableData.value = [...yourData]
    loading.value = false
  }, 500)
}
```

### 2. 编辑按钮无法点击

**问题描述**：表格中的编辑按钮不触发事件。

**解决方案**：
- 确保路由配置中包含了 'edit' 按钮权限
- 检查是否正确实现了 `handleEdit` 方法
- 确认 `showOperations` 属性已设置为 `true`

```javascript
// router/index.ts 中的配置
{
  path: '/',
  component: TableDemo,
  meta: {
    buttons: ['add', 'edit', 'delete', 'export', 'print']
  }
}
```

### 3. 高级筛选功能不工作

**问题描述**：点击高级筛选按钮没有反应。

**解决方案**：
- 确保路由配置中包含了 'virtual' 按钮权限
- 检查是否正确实现了 `handleVirtual` 方法
- 确认事件绑定正确：`@virtual="handleVirtual"`

```javascript
// 确保路由配置中包含 'virtual'
{
  path: '/',
  component: TableDemo,
  meta: {
    buttons: ['add', 'edit', 'delete', 'export', 'print', 'virtual']
  }
}
```

### 4. 导出功能报错

**问题描述**：点击导出按钮时出现 "Cannot find module 'xlsx'" 错误。

**解决方案**：
- 安装 xlsx 依赖：`npm install xlsx --save`
- 确保 utils/exportUtils.ts 文件存在
- 确保正确导入 exportToExcel 函数

```javascript
// 正确的导入方式
import { exportToExcel } from '../utils/exportUtils'

const handleExport = () => {
  exportToExcel(tableData.value, 'export-filename')
}
```

### 5. 浏览器兼容性问题

**问题描述**：在某些浏览器中表格功能异常。

**解决方案**：
- 确保使用现代浏览器：Chrome 80+, Firefox 72+, Safari 13+, Edge 80+
- 如果需要支持旧浏览器，请添加相应的 polyfill

### 6. 表格列宽度自适应问题

**问题描述**：表格列宽度不合理或显示异常。

**解决方案**：
- 为固定宽度的列设置明确的 `width` 属性
- 最后一列可以不设置宽度，让其自动占满剩余空间
- 对于可能内容过长的列，设置 `showOverflow: true`

```javascript
const columns = ref([
  { prop: 'id', label: 'ID', width: 80 },          // 固定宽度
  { prop: 'name', label: '姓名', width: 120 },     // 固定宽度
  { prop: 'email', label: '邮箱', width: 220, showOverflow: true }, // 内容可能长，显示省略号
  { prop: 'address', label: '地址' }               // 自适应宽度
])
```

### 7. 高级筛选性能问题

**问题描述**：启用高级筛选后，浏览器变得卡顿或响应缓慢。

**解决方案**：
- 高级筛选功能会一次加载所有数据（默认上限10,000条），对于大量数据会影响性能
- 减少加载的数据量：修改 `handleLoadAllData` 方法中的 `limit` 参数
- 对于超过3,000条的数据集，建议使用普通分页模式
- 如果必须使用高级筛选，考虑在服务端实现预筛选，减少返回的数据量

```javascript
// 自定义数据加载上限
const handleVirtual = () => {
  // 将上限设置为较小的值以提高性能
  emit('load-all-data', { limit: 3000 })
}
```

## 浏览器兼容性

本组件已在以下浏览器进行测试：

- Chrome 80+
- Firefox 72+
- Safari 13+
- Edge 80+

不支持 Internet Explorer 11 及更早版本。

## 版本信息

- 当前版本: 0.1.0
- 最后更新: 2023-04-15

如需了解更多信息，或报告bug，请访问项目GitHub页面。

## 构建与部署

### 构建项目

项目可以使用以下命令构建生产版本：

```bash
# 不进行类型检查的构建（推荐）
npm run build

# 进行类型检查的构建（可能在某些环境下报错）
npm run build:check
```

构建后的文件会生成在 `dist` 目录下，可以部署到任何静态文件服务器。

### 常见构建问题

#### 1. vue-tsc 类型检查错误

**问题描述**：使用 `vue-tsc && vite build` 命令构建时出现以下错误：

```
Search string not found: "/supportedTSExtensions = .*(?=;)/"
```

**解决方案**：
- 使用不带类型检查的构建命令：`npm run build`
- 如果需要类型检查，可以先单独运行 `vue-tsc --noEmit`，然后再执行 `vite build`
- 更新 vue-tsc 版本：`npm install vue-tsc@latest --save-dev`

#### 2. 打包文件过大警告

**问题描述**：构建时出现文件过大的警告：

```
(!) Some chunks are larger than 500 kBs after minification.
```

**解决方案**：
- 使用动态导入拆分代码块：`import('./moduleName.js')`
- 在 vite.config.ts 中配置手动分块：

```javascript
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'element-plus': ['element-plus'],
          'lodash': ['lodash-es'],
        }
      }
    },
    chunkSizeWarningLimit: 1000, // 提高警告阈值（单位：KB）
  }
})
```

### 部署建议

构建后的 BaseTable 组件可以部署到以下环境：

1. **静态文件服务器**：Nginx、Apache 等
2. **CDN 服务**：阿里云 OSS、腾讯云 COS 等
3. **页面托管服务**：GitHub Pages、Vercel、Netlify 等

部署示例（Nginx）：

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        root /path/to/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}
```

日期选择器提供了便捷的快捷方式，包括"最近一周"、"最近一个月"和"最近三个月"。