# el-table-wrapper

**Repository Path**: tigersss/el-table-wrapper

## Basic Information

- **Project Name**: el-table-wrapper
- **Description**: 基于el-table二次封装的表格组件：组件继承了搜索栏、表格设置、表格、分页
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-09-18
- **Last Updated**: 2026-01-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TableWrapper

`version: 1.0.2`

#### 基于Element Plus `el-table` 实现的表格组件，内部集成了搜索栏目、表格、分页、表格设置等功能

## 基础用法

#### 当`table-wrapper`元素中注入`columns`和`load-api`后，页面即可显示数据。`columns`中配置需要显示的列，`load-api`为数据加载的api接口

![](./src/components/TableWrapper/.images/table-simple.jpg)

````html
<template>
  <!-- 列表 -->
  <TableWrapper 
    title="录像列表" 
    :columns="columns" 
    :load-api="mockApi" 
    ref="tableRef"
  >
  </TableWrapper>
</template>

<script setup lang="ts">
// 引入组件
import { TableWrapper } from '@/components/TableWrapper'
// 引入mock api（用于联调前的前端页面开发阶段，使用静态假数据填充列表）
import { TableMockApi } from '@/components/TableWrapper/tool'
// 引入依赖
import { dateFormatter } from '@/utils/formatTime'
import { TableWrapperColumn, TableWrapperRowItems, TableWrapperSearch } from '@/components/TableWrapper/types'

const tableRef = ref()
// 列表的列
const columns: TableWrapperColumn[] = [
  { label: '通道名称', prop: 'name', width: 150 },
  { label: '所属区域', prop: 'area', width: 150 },
  { label: '录像时长', prop: 'duration', minWidth: 150 },
  { label: '开始时间', prop: 'startTime', width: 180, formatter: dateFormatter },
  { label: '结束时间', prop: 'endTime', width: 180, formatter: dateFormatter },
  { label: '操作人', prop: 'createUser', width: 120},
  { label: '创建时间', prop: 'createTime', width: 180, formatter: dateFormatter }
]
  
const mockApi = TableMockApi(
  [
    {id: 1, name: '通道1', area: '区域1', duration: '00:01:00', startTime: 1617246435000, endTime: 1617246435000, createUser: 'admin', createTime: 1617246435000},
    {id: 2, name: '通道2', area: '区域2', duration: '00:02:00', startTime: 1617246435000, endTime: 1617246435000, createUser: 'admin', createTime: 1617246435000},
    {id: 3, name: '通道3', area: '区域3', duration: '00:03:00', startTime: 1617246435000, endTime: 1617246435000, createUser: 'admin', createTime: 1617246435000},
  ]
)
</script>
````

## 带操作按钮的表格

#### 给`table-wrapper`传入`actions`，指定操作列

![](./src/components/TableWrapper/.images/table-actions.jpg)

````html
<template>
  <!-- 列表 -->
  <TableWrapper 
    title="录像列表" 
    :columns="columns" 
    :load-api="mockApi" 
    :actions="tableActions"
    ref="tableRef"
  >
  </TableWrapper>
</template>
<script setup lang="ts">
// ... 此处省略部分基础用法代码

//详情
const viewItem = (row: any) => {
  // 打开详情查看弹窗
}

//删除
const deleteItem = async (row: any) => {
  await message.confirm('确认删除该录像文件？')
  message.success('删除成功')
}

// 下载
const downloadItem = async (row: any) => {
  await message.confirm('确定要下载录像文件吗？', '下载')
  message.success('文件已开始下载，请关注浏览器下载任务')
}
const tableActions = [
  {
    name: '详情',
    handler: viewItem
  },
  {
    name: '下载',
    handler: downloadItem,
    // 这里还可以指定，个别的数据才有下载按钮
    display: row => {
      row.status == 1
    }
  },
  {
    name: '删除',
    handler: deleteItem,
    // 这里还可以指定，个别的数据禁用删除
    disabled: row => {
      row.status != 1
    }
  }
]
</script>
````

## 带搜索栏的表格

#### 给`table-wrapper`传入`search-parameters`，指定需要搜索的条件。

![](./src/components/TableWrapper/.images/table-search.jpg)

````html
<template>
  <!-- 列表 -->
  <TableWrapper 
    title="录像列表" 
    :columns="columns" 
    :load-api="mockApi" 
    :search-parameters="queryParams"
    ref="tableRef"
  >
  </TableWrapper>
</template>
<script setup lang="ts">
// ... 此处省略部分基础用法代码

// 搜索条件
const queryParams: TableWrapperSearch[] = [
  { label: '通道名称', prop: 'name', type: 'input' },
  { label: '所属区域', prop: 'area', type: 'select', options: [{label: '区域一', value: 1}] },
   {prop: 'demo2', label: '动态获取的下拉选', type: 'select', options: [], width: 300}
]

onMounted(() => {
  // 动态获取下拉选数据
  setTimeout(() => {
    // 假设这是接口返回的数据
    const resData = [
      {label: '选项1', value: '1'},
      {label: '选项2', value: '2'}
    ]
    tableRef.value.updateSearchBar('demo2', {
      options: resData
    })
  }, 300)
})
</script>
````

## 带新增、导入、导出、批量删除等按钮的表格

#### 想要使用以上按钮时，给`table-wrapper`传入`show-add-button`、`show-import-button`、`show-export-button`, `show-batch-delete`。点击后，它们分别会触发`on-add`、`on-import`、`on-export`、`on-batch-delete`事件。

> 当然，如果你需要使用其他的按钮，类似于“批量删除”，可以使用`toolbar-right`插槽来实现。

![](./src/components/TableWrapper/.images/table-buttons.jpg)

````html
<template>
  <!-- 列表 -->
  <TableWrapper 
    title="录像列表" 
    :columns="columns" 
    :load-api="mockApi" 
    show-add-button
    show-import-button
    show-export-button
    show-column-check
    show-batch-delete
    @on-add="onAdd"
    @on-import="onImport"
    @on-export="onExport"
    @on-batch-delete="deleteBatch"
    ref="tableRef"
  >
  </TableWrapper>
</template>
<script setup lang="ts">
// ... 此处省略部分基础用法代码

const onAdd = () => {
  console.log('点击了新增')
}

const onImport = () => {
  console.log('点击了导入')
}

const onExport = () => {
  console.log('点击了导出')
}

const deleteBatch = (rows: any[]) => {
    console.log(`点击了删除${rows.length}条数据`)
}
</script>
````

## TableWrapper API

#### TableWrapper属性

| 属性名                | 说明           |     类型     |    默认值     | 补充说明                                       |
|:-------------------|:-------------|:----------:|:----------:|:-------------------------------------------|
| title              | 表格标题         |  `string`  |     -      | -                                          |
| columns            | 表格展示列配置      |  `Array`   |     []     | 配置项说明查看下方`TableWrapperColumn`类说明           |
| show-add-button    | 是否展示添加按钮     | `boolean`  |   false    | -                                          |
| show-index         | 是否展示序号列      | `boolean`  |   false    | -                                          |
| show-export-button | 是否展示导出按钮     | `boolean`  |   false    | -                                          |
| show-import-button | 是否展示导入按钮     | `boolean`  |   false    | -                                          |
| show-batch-delete  | 是否展示批量删除按钮   | `boolean`  |   false    | -                                          |
| show-column-check  | 是否展示勾选列      | `boolean`  |   false    | -                                          |
| actions            | 表格操作按钮       |  `Array`   |     []     | 配置项说明查看下方`TableWrapperActions`类说明          |
| load-api           | 加载数据的方法      | `Function` | 空Promise函数 | 直接传入api中配置的方法                              |
| export-api         | 导出excel的方法   | `Function` | 空Promise函数 | 直接传入api中配置的方法                              |
| search-parameters  | 搜索栏配置        |  `Array`   |     []     | 配置项说明查看下方`TableWrapperSearch`类说明           |
| default-parameters  | 默认查询参数        |  `object`   |     -     |                   |
| use-search-button  | 搜索栏中是否展示搜索按钮 | `boolean`  |    true    | 搜索条件区域显示搜索按钮后，输入搜索条件时不再触发条件筛选，点击搜索才会触发条件筛选 |
| tree-props         | 树形结构字段配置     |  `object`  |     -      | 用法同el-table的tree-props                     |
| row-key            | 行数据的 Key     |  `string`  |     id     | 用法同el-table的row-key                        |
| settable           | 是否开启表格设置功能   | `boolean`  |    true    | 可以设置表格的显示风格、密度及列设置等                        |
| enable-pagination  | 是否开启分页功能   | `boolean`  |    true    |                         |
| table-formatter  | 列表数据格式化方法   | `Function`  |    -    |                         |
| search-formatter  | 查询参数格式化方法   | `Function`  |    -    |                         |

> TableWrapper属性中，相关配置类说明

**`TableWrapperColumn`表格列配置类**

| 字段                  | 类型                 | 是否必传                                                            | 说明                                              |
|:--------------------|:-------------------|:----------------------------------------------------------------|:------------------------------------------------|
| label               | `string`           | √                                                               | 列显示名                                            |
| prop                | `string`           | √                                                               | 列字段名                                            |
| displayType         | `normal`           | `tag` / `img` / `switch` / `dict` / `option`/`slot` | 展示类型                                            |
| width               | `string`/`number`  |                                                                 | 列宽度                                             |
| min-width           | `string`/`number`  |                                                                 | 列最小宽度 （用法同width）                                |
| sortable            | `string`/`boolean` |                                                                 | 是否支持排序（用法可参考el-table）                           |
| fixed               | `string`/`boolean` |                                                                 | 是否固定列（用法可参考el-table）                            |
| formatter           | `Function`         |                                                                 | 列数据展示的格式化方法（例如时间格式的显示格式化）                       |
| showOverflowTooltip | `boolean`          |                                                                 | 是否支持超出隐藏省略...展示                                 |
| dict                | `string`           |                                                                 | 数据字典字段（需要配合dict @/utils/dict工具类使用）              |
| dictIsPoint         | `boolean`          |                                                                 | 数据字典的UI风格是否为小圆点类型（只有传入dict时有效）                  |
| options             | `Array`            |                                                                 | 常量型数据字典（直接传入一个数据列表，适用于简单的字典类型，例如：状态 => 0启用，1停用） |
| disabled            | `boolean`          |                                                                 | 当展示类型为switch时，是否允许开关点击                          |
| textProp            | `string`           |                                                                 | 当display为imgText时，指定用来展示文字的字段                   |
| imgProp             | `string`           |                                                                 | 当display为imgText时，指定用来展示图片的字段                   |
| slotName            | `string`           |                                                                 | 当display为slot时，指定插槽名称                           |


**`TableWrapperActions`表格操作按钮配置类**

| 字段       | 类型         | 是否必传 | 说明                                                             |
|:---------|:-----------|:-----|:---------------------------------------------------------------|
| name     | `string`   | √    | 按钮显示的名字                                                        |
| type     | `string`   |      | 按钮显示的类型，可选值有primary、success、warning、danger、info，如果不传默认为primary |
| handler  | `Function` | √    | 操作按钮点击后执行的方法   (row: any, button: any) => void                 |
| display  | `Function` |      | 控制按钮是否显示    (row?: any) => boolean                             |
| disabled | `Function` |      | 控制按钮是否禁用  (row?: any) => boolean                               |


**`TableWrapperSearch`搜索栏配置类**

| 字段           | 类型                                             | 是否必传 | 说明                                                                                    |
|:-------------|:-----------------------------------------------|:-----|:--------------------------------------------------------------------------------------|
| type         | `string`                                       | √    | 搜索栏目的类型，可选值有：select、treeSelect、input、datetimerange、daterange、datetime、date                       |
| label        | `string`                                       | √    | 搜索栏的名字                                                                                |
| prop         | `string`                                       | √    | 搜索栏目的字段名                                                                              |
| placeholder  | `string`                                       |      | 搜索栏目输入提示文字                                                                            |
| defaultValue | `string`/`number`/`string[]`/`number[]`        |      | 搜索栏目的默认值（重置搜索条件后也会恢复该值）                                                               |
| value        | `string`/`number`/`string[]`/`number[]`        |      | 搜索栏目的v-model值                                                                         |
| width        | `string`/`number`                              |      | 搜索项DOM元素宽度（搜索项的宽度是固定的，如果有label内容过长的搜索像，建议传入合适的width）（注意，传入`string`类型时需要带上单位，例如：100px） |
| options      | `{ label: string, value: string \| number }[]` |      | 下拉选的选项（仅当type为select时有效）                                                              |
| treeData      | `Array`                             |      | type为treeSelect时的展示数据（仅type为treeSelect时有效）                                                              |
| checkStrictly | `boolean`                           |      | 在显示复选框的情况下，是否严格的遵循父子不互相关联的做法，默认为 false（仅type为treeSelect时有效）                                             |
| multiple      | `boolean`                           |      | 是否多选（仅type为treeSelect时有效）                                                                               |
| nodeKey       | `string`                            |      | 每个树节点用来作为唯一标识的属性，整棵树应该是唯一的（仅type为treeSelect时有效）                                                         |
| defaultProps  | `{children: string, label: string}` |      | 配置选项（仅type为treeSelect时有效）                                                                               |


<br>

#### TableWrapper 事件
| 事件名             | 说明         | 参数                                                |
|:----------------|:-----------|:--------------------------------------------------|
| pagination      | 页码切换事件     | `object` { pageNo: `number`, pageSize: `number` } |
| on-add          | 新增按钮点击事件   | -                                                 |
| on-export       | 导出按钮点击事件   | -                                                 |
| on-import       | 导入按钮点击事件   | -                                                 |
| on-batch-delete | 批量删除按钮点击事件 | `[]`                                              |
| loading         | 表格数据加载中事件   | `object`当前查询参数                             |
| loaded          | 表格数据加载完成事件 | `[]`当前页数据                                                 |

<br>

#### TableWrapper 插槽
| 插槽名           | 说明                   |
|:--------------|:---------------------|
| default       | 默认插槽，用法示例：查看详情、编辑等弹窗 |
| toolbar-left  | 表格按钮左侧插槽   |
| toolbar-right | 表格按钮右侧插槽             |
| column        | 表格数据底部插槽             |

<br>

#### TableWrapper Exposes
| 方法名              | 说明                        | 参数                                    |
|:-----------------|:--------------------------|:--------------------------------------|
| refresh          | 刷新表格数据，常用于删除或编辑、新增数据后刷新列表 | `object`{ clear: `boolean` } 是否重置搜索条件 |
| getSelectionRows | 获取表格选中的行                  | -                                     |
| updateSearchBar  | 更新搜索栏目配置（例如下拉选内容）         | `string`, `object`(参考TableWrapperSearch配置类)                                     |
| getTableList | 获取表格当前页数据                 | -                                     |
| startLoading | 手动设置表格为加载中状态              | -                                     |
| endLoading | 手动关闭表格加载中状态               | -                                     |


<br>

# TableRowDrawer

`version: 1.0.1`
#### 基于Element Plus `el-drawer` 实现的抽屉弹窗，用于展示表格行的详情，或编辑、新增

## 基础用法，查看详情
#### 当`table-row-drawer`元素中注入`items`后，调用组件的`openDetail(data: any)`或`open(null, { editable: false })`方法即可显示抽屉弹窗。

![](./src/components/TableWrapper/.images/drawer_detail.jpg)

````html
<template>
    <TableRowDrawer title="数据桥接" :items="detailColumns" ref="drawerRef"/>
</template>

<script setup lang="ts">
import { TableRowDrawer } from '@/components/TableRowDrawer'
import { TableWrapperRowItems } from '@/components/TableWrapper/types'

const drawerRef = ref()

const statusOptions = [
    {label: '启用', value: 0},
    {label: '停用', value: 1}
]
// 详情列
const detailColumns: TableWrapperRowItems[] = [
    {prop: 'name', label: '连接器名称', type: 'input', required: true},
    {prop: 'type', label: '类型', type: 'select', required: true},
    {prop: 'direction', label: '桥接方向', type: 'select', required: true},
    {prop: 'status', label: '生效状态', type: 'radio', required: true, value: 0, options: statusOptions}
]

const openDetail = (row: any) => {
    drawerRef.value.openDetail(row)
    // 或者  drawerRef.value.open(row, {editable: false})
}
</script>
````

## 编辑或新增

#### 当`table-row-drawer`元素中注入`items`后，调用组件的`openEdit(data: any)`方法或`open(data: any, { editable: true })`即可显示编辑或新增的抽屉弹窗。data参数为当前行的数据，若为新增数据，则data为`null`。`title`会根据编辑或新增自适应

![](./src/components/TableWrapper/.images/drawer_edit.jpg)

````html
<template>
    <TableRowDrawer title="数据桥接" :items="detailColumns" ref="drawerRef"/>
</template>

<script setup lang="ts">
// ... 此处省略部分基础用法代码

// 编辑
const openEdit = (row: any) => {
    drawerRef.value.openDetail(row)
    // 或者  drawerRef.value.open(row, {editable: true})
}

// 新增
const addItem = () => {
    drawerRef.value.openDetail(null)
    // 或者  drawerRef.value.open(null, {editable: true})
}
</script>
````

## 自定义内容

#### `table-row-drawer`传入`custom`属性后，会开启自定义内容模式，此时`items`属性将无效，`title`也不再根据不通的模式自适应，自定义内容将由`default`插槽填充。

![](./src/components/TableWrapper/.images/drawer_custom.jpg)

````html
<template>
    <TableRowDrawer title="自定义窗口" :custom="true" ref="drawerRef">
        <em>自定义内容</em>
    </TableRowDrawer>
</template>

<script setup lang="ts">
// ... 此处省略部分基础用法代码

// 打开窗口
const open = () => {
    // 自定义内容模式下，open、openEdit、openDetail三个方法的效果是等同的
    drawerRef.value.open()
}
</script>
````

## TableRowDrawer API

#### TableRowDrawer属性

| 属性名          | 说明       |        类型         |  默认值  | 补充说明                                                                                   |
|:-------------|:---------|:-----------------:|:-----:|:---------------------------------------------------------------------------------------|
| title        | 窗口标题     |     `string`      |   -   | 窗口标题会根据查看、新增或详情自适应。例如：传入title="用户"时，查看时标题为用户详情，编辑时标题为编辑用户，新增为新增用户（注意：custom模式下除外）      |
| label-size   | label长度  |     `number`      |   4   | 仅用于查看详情时的label长度控制                                                                     |
| items        | 对象字段配置   |     `object`      |  {}   | 配置项参考下方`TableWrapperRowItems`类说明                                                       |
| id-key       | 对象主键字段名  |     `string`      |  id   | 用于编辑或查看详情时，绑定对象唯一主键                                                                    |
| custom       | 是否为自定义内容 |     `boolean`     | false | 开启后，使用插槽填充内容，`items`将无关紧要，`title`的值将不在自适应，适用于需要在弹窗中展示个性化内容的场景                          |
| show-confirm | 是否展示确认按钮 |     `boolean`     | false | 仅用于custom模式，custom为false的情况下，确认按钮的显示隐藏是根据详情或编辑自动调整的                                    |
| block-close  | 是否阻止窗口关闭 |     `boolean`     | false | 仅用于custom模式，判断窗口是否阻止关闭，阻止关闭的情况下，需要监听before-close事件，调用done()方法关闭                        |
| size         | 是否阻止窗口关闭 | `number`/`string` |  30%  | Drawer 窗体的大小, 当使用 `number` 类型时, 以像素为单位, 当使用 `string` 类型时, 请传入 'x%', 否则便会以 number 类型解释  |


> TableRowDrawer属性中，相关配置类说明

**`TableWrapperRowItems`对象字段配置类**

| 字段            | 类型                                  | 是否必传 | 说明                                                                                                                                                                     |
|:--------------|:------------------------------------|:-----|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| prop          | `string`                            | √    | 字段名                                                                                                                                                                    |
| label         | `string`                            | √    | 字段含义（字段显示在页面上的名）                                                                                                                                                       |
| value         | `string`/`number`                   |      | 字段值                                                                                                                                                                    |
| type          | `string`                            |      | 字段的类型（用于新增或编辑模式），可选值`select`/`treeSelect`/`input`/`datetimerange`/`daterange`/`datetime`/`date`/`radio`/`uploadImg`/`uploadFile`/`uploadVideo`/`markdowneditor`/`data` |
| disabled      | `boolean`                           |      | 是否禁用（用于新增或编辑模式）                                                                                                                                                        |
| immutable     | `boolean`                           |      | 传入true时，表示该字段编辑时不可修改（用于新增或编辑模式）                                                                                                                                        |
| formatter     | `Function`                          |      | 字段展示的格式化方法（例如时间格式的显示格式化，仅用于查看详情时）                                                                                                                                      |
| options       | `Array`                             |      | 下拉选时的选项 （用于新增或编辑模式）， 填充类型 `{ label: string, value: string \| number }[]`                                                                                               |
| required      | `boolean`                           |      | 是否必填（用于新增或编辑模式）                                                                                                                                                        |
| min           | `number`                            |      | 最小值（仅type为inputNumber时有效）                                                                                                                                              |
| max           | `number`                            |      | 最大值（仅type为inputNumber时有效）                                                                                                                                              |
| maxlength     | `string`/`number`                   |      | 字符最大输入长度（仅type为input或textarea时有效）                                                                                                                                      |
| treeData      | `Array`                             |      | type为treeSelect时的展示数据（仅type为treeSelect时有效）                                                                                                                             |
| checkStrictly | `boolean`                           |      | 在显示复选框的情况下，是否严格的遵循父子不互相关联的做法，默认为 false（仅type为treeSelect时有效）                                                                                                            |
| multiple      | `boolean`                           |      | 是否多选（仅type为treeSelect时有效）                                                                                                                                              |
| nodeKey       | `string`                            |      | 每个树节点用来作为唯一标识的属性，整棵树应该是唯一的（仅type为treeSelect时有效）                                                                                                                        |
| defaultProps  | `{children: string, label: string}` |      | 配置选项（仅type为treeSelect时有效）                                                                                                                                              |


<br>

#### TableRowDrawer 事件
| 事件名          | 说明         | 参数                                        | 补充说明                                                  |
|:-------------|:-----------|:------------------------------------------|:------------------------------------------------------|
| confirm      | 窗口确认按钮点击事件 | `object`{ data: `any`, done: `Function` } | `data`为编辑或新增时的对象，`done`为关闭弹窗方法，需要调用`done()`方法才可关闭窗口   |
| before-close | 窗口关闭前事件    | `Funcion`                                 | 仅用于custom模式，需要指定`block-close`为 `true`才会生效，用法同ElDrawer |

<br>

#### TableRowDrawer 插槽
| 插槽名     | 说明                                                        |
|:--------|:----------------------------------------------------------|
| default | 默认插槽，通常用于结合指定`custom`为true使用（如果不传入custom="true"，窗口标题会自适应） |
| buttons | 底部按钮插槽，位于关闭按钮一栏                                           |

<br>

#### TableRowDrawer Exposes
| 方法名        | 说明         | 参数                                               | 补充说明                                                                                              |
|:-----------|:-----------|:-------------------------------------------------|:--------------------------------------------------------------------------------------------------|
| open       | 开启窗口       | `object`{ data: `any`, { editable: `boolean` }}。 | 该方法一共接收两个参数，参数1为需要编辑或查看的对象（如果是新增可以传`null`或不传），参数2也是一个对象，对象目前只有一个属性edit，类型为Boolean，用于指定是查看详情还是编辑新增 |
| openDetail | 开启查看详情窗口   | `object`{ data: `any` }                          | 效果等同于 `open(data, {editable: false})`                                                             |
| openEdit   | 开启编辑或新增窗口  | `object`{ data: `any` }                          | 效果等同于 `open(data, {editable: true})`                                                              |
| loading    | 打开加载中状态的窗口 | `object`{ data: `any` }                          | 一般用于编辑或查看时，调用接口获取数据前调用                                                                            |
| update    | 更新配置信息  | `string`, `object` |例如：drawerRef.value.update('parentId', {treeData: [{ id: 0, name: '根节点', children: list }]}) |

**注意：自定义内容内容模式（custom为true）下，open、openEdit、openDetail三个方法的效果是等同的**