---
url: /docs/5.0/front/catch-table.md
---
# CatchTable 表格组件 - 高效动态数据表格解决方案

`CatchTable` 是一个专为 CatchAdmin Vue 应用设计的高性能表格组件，致力于简化后台管理系统中表格开发的复杂度。通过动态配置和模块化设计，CatchTable 能显著提升开发效率，提供完整的数据表格管理功能。

## CatchTable 基础用法与快速上手

创建一个功能完整的数据表格只需简单配置即可实现。以下以用户管理页面为实例，详细演示 CatchTable 组件的基础使用方法
![CatchAdmin 表格基础用法-laravel admin](https://image.catchadmin.com/202406130849406.png)
代码如下

```javascript
<catch-table
    :columns="[
      {
        type: 'selection'
      },
      {
        label: '用户昵称',
        prop: 'username'
      },
      {
        label: '创建时间',
        prop: 'created_at'
      },
      {
        type: 'operate',
        label: '操作',
        width: 200
      }
    ]"
    api="users"
  />
```

## CatchTable 按钮权限控制管理

CatchTable 提供完整的按钮权限管理功能。通过 `permission` 属性实现细粒度的权限控制，属性值格式为 `module.controller`（模块名.控制器名），请注意使用小写格式。以下是用户模块权限配置示例

```javascript
<catch-table permission='user.user' />
```

### CatchTable 内置操作方法 (Built-in Actions)

CatchTable 预定义了完整的 CRUD 操作方法，每个操作都对应后端控制器的特定方法：

* **export** - 数据导出功能，调用控制器的 `export` 方法
* **import** - 数据导入功能，调用控制器的 `import` 方法
* **store** - 数据新增功能，调用控制器的 `store` 方法
* **update** - 数据编辑功能，调用控制器的 `update` 方法
* **destroy** - 数据删除功能，调用控制器的 `destroy` 方法
* **restore** - 数据恢复功能，调用控制器的 `restore` 方法

## CatchTable 高级搜索功能配置

![CatchAdmin 表格搜索功能-laravel admin](https://image.catchadmin.com/202406130849989.png)

CatchTable 提供强大的搜索功能，通过配置 `search-form` 属性即可实现多条件组合查询。支持多种表单控件类型，满足各种业务场景的搜索需求

```javascript
<catch-table
    :columns="[
      {
        type: 'selection'
      },
      {
        label: '用户昵称',
        prop: 'username'
      },
      {
        label: '创建时间',
        prop: 'created_at'
      },
      {
        type: 'operate',
        label: '操作',
        width: 200
      }
    ]"
    api="users"
    :search-form="[
      {
        type: 'input',
        label: '用户名',
        name: 'username'
      },
      {
        type: 'input',
        label: '邮箱',
        name: 'email'
      }
    ]"
  />
```

ok，这样一个完整的表格页面就创建完成了。

### search 组件支持以下表单组件

* `input`
* `select`
* `input-number`
* `date`
* `datetime`
* `range`
* `tree`
* `remote-api-select`
* `remote-select`

#### Tree 组件特殊配置说明

`tree` 组件是基于下拉选择器的树形结构控件，专门用于处理具有层级关系的数据选择。由于 tree 组件通常需要从后端 API 动态获取数据，因此必须配置响应式数据源。以下是 tree 组件的标准配置方法：

```ts
// 首先在 setup 中设置 search 相关组件
<script lang="ts" setup>
  const categories = ref()
  const search = [
    {
      type: 'tree',
      label: '分类',
      name: 'category_id',
      options: categories,
      props: { value: 'id', label: 'name' }
    }
  ]
  // onMounted 获取数据
  onMounted(() => {
    http.get('cms/category').then(r => {
      categories.value = r.data.data
    })
  })
</script>

// 在 catch table 种设置 search 即可
<catch-table ref="table" :search="search"></catch-table>
```

#### 远程下拉

使用远程接口下拉组件，可以获取后台任何带有分页接口数据。如果没有分页，请使用 `select` 组件

```ts
<script lang="ts" setup>
  const categories = ref()
  const search = [
    {
      type: 'remote-api-select',
      label: '角色',
      name: 'role',
      props: {
        label: 'role_name',
        value: 'id',
        api: 'permissions/roles'
      }
    }
  ]
  // onMounted 获取数据
  onMounted(() => {
    http.get('cms/category').then(r => {
      categories.value = r.data.data
    })
  })
</script>
```

#### 范围搜索

这里使用时间范围选择，接口会使用 `start_at` 和 `end_at` 两个搜索参数

```ts
<script lang="ts" setup>
  const categories = ref()
  const search = [
    {
    type: 'range',
    label: '时间范围',
    children: [
      {
        type: 'datetime',
        name: 'start_at',
        label: '开始时间',
        placeholder: '请选择开始时间'
      },
      {
        type: 'datetime',
        name: 'end_at',
        label: '结束时间',
        placeholder: '请选择结束时间'
      }
    ]
  }
  ]
  // onMounted 获取数据
  onMounted(() => {
    http.get('cms/category').then(r => {
      categories.value = r.data.data
    })
  })
</script>

```

## 获取当前列表的搜索参数数据

```ts
import { useQueryStore } from '@/components/catchTable/useQueryStore'
const queryStore = useQueryStore()

// 这样你就可以获取当前列表的搜索参数数据了
console.log(queryStore.getTableQuery)
```

## CatchTable 数据新增功能实现

CatchTable 提供完整的 CRUD（增删改查）操作支持。数据新增功能通过 Vue 插槽（slot）机制实现，允许开发者自定义新增表单的界面和逻辑。以下演示如何在 CatchTable 中集成数据新增功能：

```javascript
<template>
    <catch-table
        :columns="[
        {
            type: 'selection'
        },
        {
            label: '用户昵称',
            prop: 'username'
        },
        {
            label: '创建时间',
            prop: 'created_at'
        },
        {
            type: 'operate',
            label: '操作',
            width: 200
        }
        ]"
        api="users"
        :search-form="[
        {
            type: 'input',
            label: '用户名',
            name: 'username'
        },
        {
            type: 'input',
            label: '邮箱',
            name: 'email'
        }
        ]"
    >
        <!-- 通过使用 dialog slot -->
        <template #dialog="row">
            <Create :primary="row?.id" :api="api" />
        </template>
    </catch-table>
  </template>
  <script lang="ts" setup>
       import Create from './create.vue
  </script>
```

这里需要注意两点的是，一般情况下 Create 组件都是由代码自动生成功能生成的

* `Create` 组件是自带 `primary` props 的，用于更新
* `Create` 组件是自带 `api` props 的，api 主要用于接口提交

### 弹窗关闭保持搜索条件

目前 CatchTable 内置了弹窗关闭保持搜索条件的功能，有时候翻页，例如翻页到第 10 页，修改数据，保存之后。会重置分页数据。如果需要保持搜索条件，可以
在 Create 组件中找到 `close` 方法。

```javascript
const closeDialog = inject('closeDialog') as Function
onMounted(() => {
  close(() => closeDialog(false)) // 设置为 false，就不会重置分页数据了
})
```

## CatchTable 回收站功能配置

CatchTable 内置数据回收站功能，支持软删除和数据恢复机制。启用回收站功能只需简单的配置即可：

```javascript
<catch-table :trash="true"/>
```

### 数据恢复

恢复功能需要添加一条路由才可以正常运行，例如用户管理(`UserController`)添加一条 `restore` 路由

```php
// 回收站恢复
Route::put('users/restore/{id}', [UserController::class, 'restore']);
```

:::warning
回收站数据的删除是强制删除，删除后数据将不可恢复
:::

## 隐藏分页

一般列表都是需要分页的，但是某种场景下，需要隐藏分页的话，可以使用下面的代码

```javascript
<catch-table :pagination="false"/>
```

## 树形表格

要使用树形表格，在 `catch-table` 中也是非常简单的，只需要

```javascript
<catch-table row-key='id' />
```

> {info}
> 注意在 `catchtable` 中，树形表格都是自动隐藏分页的

## 空数据显示的文本

如果表格没有数据，需要友好的提示的话，那么可以使用下面的代码，默认使用`暂无数据`

```javascript
<catch-table empty-text='暂无数据' />
```

## 隐藏操作

表格默认一个新增操作，如果不需要的话，可以使用

```javascript
<catch-table :operation="false"/>
```

## 隐藏表头

```javascript
<catch-table :showHeader="false"/>
```

## 隐藏工具栏

在表格右上角，有三个默认工具栏操作，分别是 `刷新`，`表格栏目`, `搜索`, 如果不需要的话，可以使用

```javascript
<catch-table :show-tools="false"/>
```

## 隐藏多选删除

```javascript
<catch-table :multiDelShow="false"/>
```

## 默认参数

有这么一个场景，例如后台的字典管理，每个字典都需要管理字典值。而每个字典值列表则需要字典的 ID。这个时候
每个请求列表的 api 都是需要默认参数 `字典ID`。这个时候就需要添加默认参数

```javascript
<catch-table :defualt-params="{ dic_id: 1}"/>
```

## 搜索设置默认参数

如果需要给搜索框设置某一个默认值，可以使用 `default` 属性，这样每次进入列表页面，都可以自带一个默认搜索参数了

```javascript
<catch-table :search-form="[
        {
            type: 'input',
            label: '用户名',
            name: 'username',
            default: 'admin'
        },
        ]"/>
```

## 默认选中

有时候表格需要默认选中一些数据，我们可以使用

```javascript
<catch-table :defaualtMultiSelection="[1,2,4]"/>

```

:::tip
目前使用表格数据的主键数据作为选中依据
:::

## Table 曝露方法

有一些需求可能需要直接操作表格的方法。目前表格对外有几个可以直接调用的方法，调用方法之前需要先设置 `table ref`，在获取整个`catchtable`对象 ref 之后，才可以使用

```vue
<!-- 设置 ref = 'catchtable' -->
<catch-table ref="catchtable" />
// js 代码 // ⚠️如果你对 vue 不熟悉的话，注意 ref="catchadmin" 这里 ref 的名称需要和 const [catchtable] 相同
<script lang="ts" setup>
import { ref } from 'vue'
// 获取 catable ref 对象之后，进行下面的操作
const catchtable = ref()
</script>
```

### 搜索

在某些操作之后，需要搜索刷新列表

```vue
<script lang="ts" setup>
import { ref } from 'vue'

const catchtable = ref()

catchtable.value.doSearch()
</script>
```

### 重置

在某些操作之后，需要重置列表，也可以叫做刷新吧

```vue
<script lang="ts" setup>
import { ref } from 'vue'

const catchtable = ref()

catchtable.value.reset()
</script>
```

### 打开弹出层

```vue
<script lang="ts" setup>
import { ref } from 'vue'

const catchtable = ref() // v 行数据 // 弹出层标题 catchtable.value.openDialog(v = null, dialogTitle: string = '')
</script>
```

### 关闭弹出层

```vue
<script lang="ts" setup>
import { ref } from 'vue'

const catchtable = ref()

catchtable.value.closeDialog()
</script>
```

### 删除

某些场景需要访问删除接口时候，就可以使用它

```vue
<script lang="ts" setup>
import {ref} from 'vue'

const catchtable = ref()

catchtable.value.del(api: string, id: any)
</script>
```

### 设置默认搜索参数

这个方法在某些特定场景下会有用到，比如一个表格列表的访问他的子列表，子列表需要父列表的某个条件才能访问到。这个时候就需要给子列表设置一个默认参数。`字典管理`列表就是一个很好的例子

```vue
<script lang="ts" setup>
import {ref} from 'vue'

const catchtable = ref()

catchtable.value.setDefaultParams(params: Object = {})
</script>
```

### 获取表格多选 ID

目前 `catchadmin` 已经内置了多选删除。如果需要做其他多选操作的时候，可以使用它获取多选数据

```vue
<script lang="ts" setup>
import { ref } from 'vue'

const catchtable = ref()

catchtable.value.getMultiSelectIds()
</script>
```

## 表格插槽

为了让表格更加灵活点，`catchtable` 内置了几个插槽，来让用户自定义操作

### 表格操作插槽

`catchtable` 默认只有新增操作，如果你需要添加其他的操作，那么你可以使用以下代码，新增表格的操作

```vue
<catch-table>
      <template #operation>
        <el-button>操作插槽</el-button>
      </template>
  </catch-table>
```

![CatchAdmin 表格操作插槽-laravel admin](https://image.catchadmin.com/202406130851032.png)

### 搜索和表格之间插槽

`catchtable` 提供了搜索和表格之间的插槽，可以用于自定义搜索和表格之间的内容

```vue
<catch-table>
      <template #middle>
        这里可以实现表格一些统计数据
      </template>
  </catch-table>
```

### 批量操作插槽

目前表格内置了`批量删除`操作。当表格需要额外的批量操作时，可以使用该插槽。

```vue
<catch-table>
     <template #multiOperate>
        <el-button>多选操作</el-button>
      </template>
  </catch-table>
```

光是这样的是不够的，还要获取批量选择 ID，请查看[获取表格多选 ID](#获取表格多选id)，获取到多选 ID 之后进行操作
![CatchAdmin 批量操作插槽-laravel admin](https://image.catchadmin.com/202406130852219.png)

### 栏目操作插槽

表格栏目支持`更新`和`删除`操作,如果还需要额外的操作，那么可以使用

```vue
// 通过 scope 你可以获取行数据
<catch-table>
  <template #operate="scope">
    <el-button>自定义栏目操作</el-button>
  </template>
</catch-table>
```

![CatchAdmin 栏目操作插槽-laravel admin](https://image.catchadmin.com/202406130852588.png)

### 弹窗插槽

弹窗插槽是每个表格都需要的，目前只服务于表单数据。

```vue
<catch-table>
  <template #dialog="row">
  // 这里的 Create 组件就是 Form 组件
    <Create :primary="row?.id" :api="api" />
  </template>
  </catch-table>
```

## 表格栏目

对于表格栏目，可以通过表格类型窥探一二。看下表格栏目是如何定义的

```js
export type columnType = 'expand' | 'selection' | 'index' | 'operate'
export type fixed = 'fiexed' | 'right' | 'left'
export interface Column {
  type?: columnType // 类型 expand select index
  label?: string
  prop?: string
  'min-width'?: string | number
  width?: number | string
  slot?: 'string'
  header: 'string' // 表头插槽名称
  align?: string
  fixed?: fixed
  sortable?: boolean | string
  'sort-method'?: Function
  'sort-by'?: Function
  resizable?: boolean
  'header-align'?: string
  'class-name'?: string
  selectable?: Function // function(row, index)
  show: boolean
  index?: number | Function // 如果设置了 type=index，可以通过传递 index 属性来自定义索引
  children?: Array<Column> // 多级表头
  filter?:Function,
  ellipsis?:boolean|number, // 当文字太多时，可以使用省略文字
  switch: false, // swith 字段状态切换
  // 操作
  update?: boolean, // 编辑操作
  destroy?: boolean // 删除操作
}
```

### 栏目类型

`type` 字段

* `expand` 展开类型，树形结构的表格，规定哪个栏目展开
* `selection` 多选类型，一般用于表格多选操作。一般都是用于主键字段
* `index` 可以自定义索引
* `operate` 最后一行操作栏目

### 栏目固定

`fiexed` 字段

* fixed 默认固定
* right 固定在右侧
* left 固定在左侧

### 插槽

如果栏目是需要自定义，那么肯定是需要用插槽这个功能。只需要设置 `slot` 字段，例如插槽名称设置为

```javascript
{
  label: '你好',
  slot: 'hello'
}
```

那么此时只需要在`catchtable`组件如下设置

```vue
<catch-table>
  <template #hello="scope">
    // 在这自定义栏目内容
  </template>
</catch-table>
```

### 格式化字段

有时候并不需要插槽，例如当后台的接口中的性别字段(gender)返回 1， 2。其中 1 代表男 2 代表女，这个时候需要实现格式化方法即可

```js
{
  label: '性别'，
  prop: 'gender',
  filter: (value) => {
    return value === 1 ? '男' : '女'
  }
}
```

### 自定义索引

当栏目的 type 设置成 `index` 时，则需要自定义索引，一般通过 `index` 来设置

```js
{
  type: 'index',
  prop: 'gender',
  index: () => {}
}
```

### 多级表头

当然，catchtable 也支持多集表头，只要一个简单的配置即可

```js
{
  prop: 'job_name',
  label: '岗位名称',
  children: [
    {
      prop: 'coding',
      label: '岗位编码'
    },
    {
      label: '状态',
      prop: 'status',
      switch: true,
      align: 'center'
    }
  ]
}
```

![CatchAdmin 多级表头-laravel admin](https://image.catchadmin.com/202406130854407.png)

### 字段太长，省略号

```js
{
    prop: 'description',
    label: '岗位描述',
    ellipsis: true // 添加该字段
},
```

### 字段状态切换

某些场景下，业务中只需要在表格中做某些字段的状态切换，这个时候就可以使用下面的代码

```javascript
{
    prop: 'status', // 设置字段，这里仅做演示
    label: '状态',
    switch: true // 添加该字段
},
```

`catchadmin`在后端通常使用 `enable` 方法做字段切换的路由, 你可以根据实际改动。代码如下

```php
public function enable($id, Request $request)
{
    return $this->model->toggleBy($id, $request->get('field'));
}
```

![CatchAdmin 字段状态切换-laravel admin](https://image.catchadmin.com/202406130855026.png)

### 图片预览

如果表格中需要进行图片预览，那么可以使用下面的配置，只需要使用 `image` 属性

```js
 {
    label: '内容',
    prop: 'content',
    image: true,
  },
```

如果你是想要预览，如果是单图的话，你需要使用 `filter` 转换成多图数组

```js
{
    label: '内容',
    prop: 'content',
    image: true,
    preview: true,
    filter: (value: any) => {
      return [value]
    }
  },

```

### 链接

如果表格中需要某个字段需要链接，那么可以使用下面的配置, 也是非常简单，只需要配置 `link` 属性

```js
{
    label: '链接',
    prop: 'url',
    link: true
  },
```

### 标签展示

如果表格中需要某个字段需要标签，那么可以使用下面的配置, 也是非常简单，只需要配置 `tags` 属性,单个标签

```js
 {
    label: '类型',
    prop: 'type',
    tags: true
  },
```

多个标签一般都是配合枚举值，`catchadmin` 枚举一般使用 number，并且从数字`1`开始，数组可以很好配合使用

```js
 {
    label: '类型',
    prop: 'type',
    tags: ['danger', 'info', 'success'],
    filter: (value: number) => {
      return value === 1 ? '轮播图' : value === 2 ? '友情链接' : '广告'
    }
  },
```

### 排序

某些场景下，业务中只需要在表格中做某个字段排序。通常来说，elementPlus 只是在前端列表单独一页排序，但是使用下面的代码，可以直接进行后端排序，不需要写任何一行代码，都是自动完成的

```js
{
  prop: 'sort',
  label: '排序',
  sortable: true
}
```

![CatchAdmin 表格排序-laravel admin](https://image.catchadmin.com/202406130856803.png)

### Mask 数据

某些时候，希望数据默认是以 `******` 这样的形式展示,那么你需要这么设置

```js
{
  prop: 'secret',
  label: '密钥',
  mask: true
}
```

![CatchAdmin 表格 Mask 数据-laravel admin](https://image.catchadmin.com/202410261739969.png)