npm package: @leiyin/v-data-table
Description: Base on element-ui, supports pagination, tree data structure, custom search, custom operation column
Author: leiyin
Latest version: 1.0.2

# @leiyin/v-data-table

一个基于 **Vue 3 + Element Plus** 的配置化数据表格组件，集成了查询表单、分页、工具栏和复杂的列配置功能。

---

## ✨ 特性

- 🚀 **配置驱动**：通过 JSON 配置快速生成表格列和搜索表单。
- 🔍 **集成搜索**：内置基于 `@leiyin/v-form-renderer` 的搜索表单，支持自动触发查询。
- 📡 **自动数据请求**：只需提供 `dataRequest` 函数，组件自动处理 Loading 状态、分页参数和数据回显。
- 🧩 **灵活列配置**：支持多级表头、自定义渲染（Formatter/VNode）、操作列按钮配置。
- 💾 **状态保持**：支持跨页勾选保持 (`persistSelection`)，单选多选操作。
- 🛠 **内置工具栏**：支持列显隐设置、密度调整，提供顶部和左侧工具栏插槽。

---

## 📦 安装

```bash
pnpm add @leiyin/v-data-table
# 依赖 element-plus 和 @leiyin/v-form-renderer
```

---

## 🚀 快速开始

```vue
<template>
  <VDataTable
    :data-request="fetchData"
    :columns="columns"
    :search-form="searchConfig"
  >
    <!-- 工具栏插槽示例 -->
    <template #tool-fl>
      <el-button type="primary">新增用户</el-button>
    </template>
  </VDataTable>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { VDataTable } from '@leiyin/v-data-table'
import type { TableColumn, SearchFormContent } from '@leiyin/v-data-table'

// 1. 定义表格列
const columns = ref<TableColumn[]>([
  { type: 'selection', width: 50 },
  { type: 'index', label: '#', width: 60 },
  { prop: 'name', label: '姓名', minWidth: 120 },
  { 
    prop: 'role', 
    label: '角色', 
    formatter: (row) => row.role === 'admin' ? '管理员' : '用户' 
  },
  {
    prop: 'operation',
    label: '操作',
    width: 200,
    // 动态生成按钮
    setBtns: (row) => [
      { label: '编辑', handler: () => handleEdit(row) },
      { label: '删除', hide: row.role === 'admin', handler: () => handleDelete(row), className: 'text-red-500' }
    ]
  }
])

// 2. 定义搜索表单 (基于 @leiyin/v-form-renderer)
const searchConfig = ref<SearchFormContent[]>([
  { type: 'input', label: '姓名', prop: 'name' },
  { 
    type: 'select', 
    label: '状态', 
    prop: 'status',
    options: [
      { label: '启用', value: 1 },
      { label: '禁用', value: 0 }
    ]
  }
])

// 3. 数据请求函数
const fetchData = async (params) => {
  // params 包含: page, size, ...searchForm字段
  console.log('Request params:', params)
  
  // 模拟接口请求
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({
        list: [
          { id: 1, name: 'Alice', role: 'admin', status: 1 },
          { id: 2, name: 'Bob', role: 'user', status: 0 }
        ],
        total: 100
      })
    }, 500)
  })
}

const handleEdit = (row) => console.log('Edit', row)
const handleDelete = (row) => console.log('Delete', row)
</script>
```

---

## 📖 API 文档

### Props

| 属性名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| dataRequest | `(params) => Promise<any>` | - | 数据请求函数，需返回包含 `list` 和 `total` 的对象（字段名可通过 `content`/`totalContent` 配置） |
| columns | `TableColumn[]` | `[]` | 表格列配置 |
| searchForm | `SearchFormContent[]` | `[]` | 搜索表单配置 |
| enablePagination | `Boolean` | `true` | 是否显示分页 |
| defaultSize | `Number` | `20` | 默认每页条数 |
| customQuery | `Object` | `{}` | 请求时的额外固定参数 |
| id | `String` | `'id'` | 数据主键 Key，用于跨页勾选等 |
| persistSelection | `Boolean` | `false` | 是否开启跨页勾选保持 |
| isSingleSelect | `Boolean` | `false` | 是否开启单选模式 |
| hideTool | `Boolean` | `false` | 是否隐藏工具栏 |
| immediate | `Boolean` | `true` | 是否在挂载时立即请求数据 |
| dataSource | `Array` | `null` | 静态数据源（当不使用 `dataRequest` 时使用） |
| tableAttrs | `Object` | `{}` | 透传给 Element Plus Table 的属性 |
| content | `String[]` | `['list']` | 响应数据中列表数据的路径 |
| totalContent | `String` | `'total'` | 响应数据中总条数的路径 |
| tablebScene | `String` | `''` | 表格唯一标识，用于保存筛选条件等状态 |
| summaryMethod | `Function` | - | 自定义合计行方法 |
| spanMethod | `Function` | - | 自定义合并行方法 |

### TableColumn 配置

继承自 Element Plus `TableColumn`，额外支持：

| 属性名 | 类型 | 说明 |
| --- | --- | --- |
| setBtns | `(row, index) => TableColumnBtn[]` | 仅当 `prop` 为 `'operation'` 时生效，配置操作列按钮 |
| columns | `TableColumn[]` | 用于配置多级表头 |
| formatter | `Function` | 支持返回 VNode 或 String |

### Slots

| 插槽名 | 参数 | 说明 |
| --- | --- | --- |
| tool-top | `{ selected, resData }` | 顶部工具栏区域（搜索栏下方，表格上方） |
| tool-fl | `{ selected, resData, requsetDto }` | 表格左上角工具栏（常用于放置“新建”等操作） |

### Events

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| search | 搜索表单提交时触发 | `(params: any)` |