表格

我们封装了 Table 组件、baTable 类、baTableApi 类、表格顶部菜单 组件等，以方便快速生成和制作表格。

TIP

我们提供了一个表格开发示例模块，内含大量表格使用、编程式操作的实际示例，欢迎下载体验。

Table 组件

Table 组件位于 \src\components\table，我们基于 el-table 封装了该组件，所以 el-table 的所有事件属性都是可以直接在 Table 组件上使用的，部分属性可能失效，比如 el-table 的 size，这是因为 Table 组件拥有一些默认的 css 样式。

组件属性

属性名	注释	值
pagination	是否显示底部分页组件	boolean
...	其他 el-table 的属性可以直接使用	-

组件方法与事件

方法名/项目	注释	参数
getRef	获取内部 `el-table` 的 `ref`，然后就可以使用 el-table 的所有方法	-
各类事件	单双击、勾选、hover、右击等事件 `el-table` 均以自带，请转到 el-table 事件文档	-

组件插槽

插槽名	注释	子标签
neck	表格头与表格主体中间区域	任意
columnPrepend	通过此插槽在 `baTable` 类中定义的列之前插入列	el-table-column
columnAppend	通过此插槽在 `baTable` 类中定义的列之后插入列	el-table-column
footer	表格底部区域	任意
任意	列使用 `render:slot, slotName:插槽名称` 来使用 `slot` 渲染	任意

TIP

Table 组件和下方的 baTable 类是搭配使用的，baTable 类为表格提供数据，并可以响应表格组件的各种事件，组件的使用示例，也请参考下方 baTable 类的示例。

baTable 表格管家类

此类代码位于：\src\utils\baTable.ts
我们在类里面封装好了一个表格应有的 属性 和 方法，预设了 查看前、查看后、编辑前 等钩子

TIP

此类非常强大和重要，我们在表格管家类的深度理解一节对这一点进行了特别说明

使用示例

以下为基本使用示例，实际使用表格非常灵活，请发挥您的想象力；baTable 类支持的属性在表格所有可用属性有介绍，您还可以直接查阅 src\utils\baTable.ts 文件代码（有注释，不知道有哪些属性可用时，可直接查看 ts 的类型定义）

scripttemplatepopupForm.vue

<script setup lang="ts">
import Table from '/@/components/table/index.vue' // 导入 Table 组件
import baTableClass from '/@/utils/baTable' // 导入 baTable 类
import { baTableApi } from '/@/api/common' // 导入表格 api 方法生成器类
import { defaultOptButtons } from '/@/components/table' // 导入默认表格操作按钮数据:拖拽排序、编辑、删除按钮等

const tableRef = ref()

// 直接实例化 baTableClass 并传递各种参数
const baTable = new baTableClass(
    new baTableApi('/admin/user.user/'), // 一个 api 类的实例，快速生成一个控制器的 增、删、改、查、排序 接口的请求方法
    {
        // 表格列定义
        column: [
            { type: 'selection', align: 'center', operator: false },
            { label: 'ID', prop: 'id', align: 'center', operator: 'LIKE', operatorPlaceholder: '模糊查询', width: 70 },
            { label: '用户名', prop: 'username', align: 'center', operator: 'LIKE', operatorPlaceholder: '模糊查询' },
            // ...
            {
                label: '操作',
                align: 'center',
                width: '100',
                render: 'buttons',
                // 操作按钮传递的只是一个按钮配置数组，你也可以在渲染前对数组配置进行修改
                buttons: defaultOptButtons(['edit', 'delete']),
                operator: false,
            },
        ],
        // 不允许双击编辑的列的 prop
        dblClickNotEditColumn: [undefined],
        // ...属性很多，请参考本文下方的表格全部可用属性，或翻阅源代码（有注释）
    },
)

// 实例化表格后，将 baTable 的实例提供给上下文
provide('baTable', baTable)

// 相当于表格的 onMounted，也可以在页面的 onMounted 时执行
baTable.mount()

// 获取数据，可以在页面的 onMounted 时执行，也可以比如先请求一个API，再执行获取数据
baTable.getData()!.then(() => {
    // 查看请求完毕（已获取到表格数据）
    baTable.initSort() // 初始化默认排序（如果需要）
    baTable.dragSort() // 初始化拖拽排序（如果需要）
})
</script>

vue

<template>
    <!-- 可以直接在标签上使用 el-table 的属性和事件 -->
    <Table ref="tableRef">
        <template #columnPrepend>
            <el-table-column prop="prepend" label="第一个列" width="180" />
        </template>

        <!-- baTableClass 实例中定义的表格列会渲染在此处 -->
    </Table>

    <PopupForm />
</template>

vue

<!-- 独立的表单组件，以便二次开发 -->
<!-- 表格表单组件，表单项组件（FormItem）文档：https://doc.buildadmin.com/senior/web/formItem.html -->

<template>
    <!-- 对话框表单 -->
    <!-- 建议使用 Prettier 格式化代码 -->
    <!-- el-form 内可以混用 el-form-item、FormItem、ba-input 等输入组件 -->
    <el-dialog
        class="ba-operate-dialog"
        :close-on-click-modal="false"
        :model-value="['Add', 'Edit'].includes(baTable.form.operate!)"
        @close="baTable.toggleForm"
        width="50%"
    >
        <template #header>
            <div class="title" v-drag="['.ba-operate-dialog', '.el-dialog__header']" v-zoom="'.ba-operate-dialog'">
                {{ baTable.form.operate ? t(baTable.form.operate) : '' }}
            </div>
        </template>
        <el-scrollbar v-loading="baTable.form.loading" class="ba-table-form-scrollbar">
            <div
                class="ba-operate-form"
                :class="'ba-' + baTable.form.operate + '-form'"
                :style="config.layout.shrink ? '' : 'width: calc(100% - ' + baTable.form.labelWidth! / 2 + 'px)'"
            >
                <el-form
                    v-if="!baTable.form.loading"
                    ref="formRef"
                    @submit.prevent=""
                    @keyup.enter="baTable.onSubmit(formRef)"
                    :model="baTable.form.items"
                    :label-position="config.layout.shrink ? 'top' : 'right'"
                    :label-width="baTable.form.labelWidth + 'px'"
                    :rules="rules"
                >
                    <FormItem
                        :label="t('test.string')"
                        type="string"
                        v-model="baTable.form.items!.string"
                        prop="string"
                        :placeholder="t('Please input field', { field: t('test.string') })"
                    />
                </el-form>
            </div>
        </el-scrollbar>
        <template #footer>
            <div :style="'width: calc(100% - ' + baTable.form.labelWidth! / 1.8 + 'px)'">
                <el-button @click="baTable.toggleForm()">{{ t('Cancel') }}</el-button>
                <el-button v-blur :loading="baTable.form.submitLoading" @click="baTable.onSubmit(formRef)" type="primary">
                    {{ baTable.form.operateIds && baTable.form.operateIds.length > 1 ? t('Save and edit next item') : t('Save') }}
                </el-button>
            </div>
        </template>
    </el-dialog>
</template>

<script setup lang="ts">
import type { FormInstance, FormItemRule } from 'element-plus'
import { inject, reactive, ref } from 'vue'
import { useI18n } from 'vue-i18n'
import FormItem from '/@/components/formItem/index.vue'
import { useConfig } from '/@/stores/config'
import type baTableClass from '/@/utils/baTable'
import { buildValidatorData } from '/@/utils/validate'

const config = useConfig()
const formRef = ref<FormInstance>()
const baTable = inject('baTable') as baTableClass

const { t } = useI18n()

const rules: Partial<Record<string, FormItemRule[]>> = reactive({})
</script>

<style scoped lang="scss"></style>

表格列

此处特指实例化表格管家类（new baTable）时定义的列（column）数据，您还可以使用表格组件的插槽渲染列。

import baTableClass from '/@/utils/baTable'
import { baTableApi } from '/@/api/common'

const baTable = new baTableClass(new baTableApi('table controller url'), {
    // 表格列数据，其中 type、align、operator 等称为列属性，所有可用属性可在下方查阅
    column: [
        { type: 'selection', align: 'center', operator: false },
    ]
})

表格列的可用属性

表格列属性 TS 类型定义内置单元格渲染器公共搜索操作符支持的值

interface TableColumn extends Partial<TableColumnCtx<TableRow>> {
    // 是否于表格显示此列
    show?: boolean
    // 渲染器组件名，即 \src\components\table\fieldRender\ 中的组件之一，也可以查看 TableRenderer 类型定义
    render?: TableRenderer
    // 值替换数据（字典数据），同时用于单元格渲染时和作为公共搜索下拉框数据，格式如：{ open: '开', close: '关', disable: '已禁用' }
    replaceValue?: Record<string, any>

    // render=slot 时，slot 的名称
    slotName?: string
    // render=customRender 时，要渲染的组件或已注册组件名称的字符串
    customRender?: string | Component
    // render=customTemplate 时，自定义渲染 html，应谨慎使用：请返回 html 内容，务必确保返回内容是 xss 安全的
    customTemplate?: (row: TableRow, field: TableColumn, value: any, column: TableColumnCtx<TableRow>, index: number) => string
    // 渲染前对字段值的预处理函数（对 el-table 的 formatter 扩展）
    formatter?: (row: TableRow, column: TableColumnCtx<TableRow>, cellValue: any, index: number) => any

    /**
     * 自定义单元格渲染属性（比如单元格渲染器内部的 tag、button 组件的属性，设计上不仅是组件属性，也可以自定义其他渲染相关属性）
     * 直接定义对应组件的属性 object，或使用一个函数返回组件属性 object
     */
    customRenderAttr?: {
        tag?: TableContextDataFun<TagProps>
        icon?: TableContextDataFun<InstanceType<typeof Icon>['$props']>
        image?: TableContextDataFun<ImageProps>
        switch?: TableContextDataFun<SwitchProps>
        tooltip?: TableContextDataFun<ElTooltipProps>
        [key: string]: any
    }

    // render=tag 时，el-tag 组件的 effect
    effect?: TagProps['effect']
    // render=tag 时，el-tag 组件的 size
    size?: TagProps['size']
    // render=url 时，链接的打开方式
    target?: '_blank' | '_self'
    // render=datetime 时，时间日期的格式化方式，字母可以自由组合:y=年,m=月,d=日,h=时,M=分,s=秒，默认：yyyy-mm-dd hh:MM:ss
    timeFormat?: string
    // render=buttons 时，操作按钮数组
    buttons?: OptButton[]

    /**
     * 单元格渲染器需要的其他任意自定义数据
     * 1. render=tag 时，可单独指定每个不同的值 tag 的 type 属性 { open: 'success', close: 'info', disable: 'danger' }
     */
    custom?: any

    // 默认值（单元格值为 undefined,null,'' 时取默认值，仅使用了 render 时有效）
    default?: any
    // 是否允许动态控制字段是否显示，默认为 true
    enableColumnDisplayControl?: boolean
    // 单元格渲染组件的 key，默认将根据列配置等属性自动生成（此 key 值改变时单元格将自动重新渲染）
    getRenderKey?: (row: TableRow, field: TableColumn, column: TableColumnCtx<TableRow>, index: number) => string

    // 公共搜索操作符，默认值为 = ，值为 false 禁用此字段公共搜索，支持的操作符见下类型定义
    operator?: boolean | OperatorStr
    // 公共搜索框的 placeholder
    operatorPlaceholder?: string | string[]
    // 公共搜索渲染方式，render=tag|switch 时公共搜索也会渲染为下拉，数字会渲染为范围筛选，时间渲染为时间选择器等
    comSearchRender?: 'remoteSelect' | 'select' | 'date' | 'customRender' | 'slot'
    // 公共搜索自定义组件/函数渲染
    comSearchCustomRender?: string | Component
    // 公共搜索自定义渲染为 slot 时，slot 的名称
    comSearchSlotName?: string
    // 公共搜索自定义渲染时，外层 el-col 的属性（仅 customRender、slot 支持）
    comSearchColAttr?: Partial<ColProps>
    // 公共搜索是否显示字段的 label
    comSearchShowLabel?: boolean
    // 公共搜索渲染为远程下拉时，远程下拉组件的必要属性
    remote?: {
        pk?: string
        field?: string
        params?: anyObj
        multiple?: boolean
        remoteUrl: string
    }

    // 使用了 render 属性时，渲染前对字段值的预处理方法（即将废弃，请使用兼容 el-table 的 formatter 函数代替）
    renderFormatter?: (row: TableRow, field: TableColumn, value: any, column: TableColumnCtx<TableRow>, index: number) => any
    // 渲染为 url 时的点击事件（即将废弃，请使用 el-table 的 @cell-click 或单元格自定义渲染代替）
    click?: (row: TableRow, field: TableColumn, value: any, column: TableColumnCtx<TableRow>, index: number) => any
}

/**
 * 可用的表格单元格渲染器，以 ./src/components/table/fieldRender/ 目录中的文件名自动生成
 */
type TableRenderer =
    | 'buttons'
    | 'color'
    | 'customRender'
    | 'customTemplate'
    | 'datetime'
    | 'icon'
    | 'image'
    | 'images'
    | 'switch'
    | 'tag'
    | 'tags'
    | 'url'
    | 'slot'

type OperatorStr =
    | 'eq' // 等于，默认值
    | 'ne' // 不等于
    | 'gt' // 大于
    | 'egt' // 大于等于
    | 'lt' // 小于
    | 'elt' // 小于等于
    | 'LIKE'
    | 'NOT LIKE'
    | 'IN'
    | 'NOT IN'
    | 'RANGE' // 范围，将生成两个输入框 以输入最小值和最大值
    | 'NOT RANGE'
    | 'NULL' // 是否为NULL，将生成单个复选框
    | 'NOT NULL'
    | 'FIND_IN_SET'
    // 不推荐使用的，因为部分符号不利于网络传输
    | '='
    | '<>'
    | '>'
    | '>='
    | '<'
    | '<='

自定义单元格渲染

我们预设了一系列的单元格渲染方式 image、switch、tag...，若它们不能满足您的需求，我们提供了另外四种方案，最终方案实现了完全的自定义渲染能力。

方案一：渲染前格式化方案二：slot 渲染（推荐）方案三：组件渲染方案四：系统同级渲染器

import { TableColumnCtx } from 'element-plus'

// 在您使用预设的单元格渲染方案时（`switch|image|tag...`），可以在渲染前，通过函数对单元格值进行一次处理：
const baTable = new baTableClass(
    new baTableApi('admin/auth.Admin/'),
    {
        column: [
            {
                label: 'id',
                prop: 'id',
                render: 'tags',
                // >= v2.1.2 推荐直接使用 formatter，它是由 el-table-column 自带的，新版系统自定义的单元格渲染器也使用了它格式化
                formatter(row, column, cellValue, index) {
                    return cellValue + ' - 为该列所有值，加了个后缀'
                },
                // < v2.1.2 使用 renderFormatter
                renderFormatter: (row: TableRow, field: TableColumn, value: any, column: TableColumnCtx<TableRow>, index: number) => {
                    return value + ' - 为该列所有值，加了个后缀';
                }
            },
        ]
    }
)

vue

<!-- 此方案在 `BuildAdmin >= v2.0.0` 添加，实现了开发者最舒适的模式 -->
<template>
    <div class="default-main">
        <Table>
            <!-- 请注意 #test 它是自定义的插槽名称 -->
            <template #test>
                <!-- 在插槽内，您可以随意发挥，通常使用 el-table-column 组件 -->
                <el-table-column prop="username" label="用户名" width="180" />

                <!-- 还可以继续使用 el-table-column 组件本身的插槽 -->
                <el-table-column prop="id" label="ID" width="180">
                    <template #default="scope">
                        <b>{{ scope.row['id'] }}</b>
                        列宽度是：{{ scope.column.width }}
                    </template>
                </el-table-column>
            </template>
        </Table>
    </div>
</template>

<script setup lang="ts">
import baTableClass from '/@/utils/baTable'
const baTable = new baTableClass(
    new baTableApi('/admin/auth.Admin/'),
    {
        column: [
            // render: 'slot' 表示本列将使用 slot渲染
            // slotName: 'test' slot的名称
            { label: '管理员', render: 'slot', slotName: 'test', operator: 'LIKE' },
        ]
    }
)
// ...
</script>

import { h, resolveComponent } from 'vue'

// renderId 即自定义的组件，你也可以直接单独建立一个 vue 文件导入使用
// 自定义组件可以接受五个 props，分别是:renderValue=单元格值,renderRow=当前行数据,renderField=当前列数据,renderColumn=当前列上下文数据,renderIndex=当前行号
const renderId = {
    render(context: TableRenderPublicInstance) {
        console.log(context.$attrs.renderRow, context.$attrs.renderField, context.$attrs.renderValue, context.$attrs.renderColumn, context.$attrs.renderIndex)
        
        // 使用原生元素渲染，如`div、h1、a`等，以下演示了将 单元格值 直接通过h1标签进行渲染
        return h('h1', { class: 'id-h1' }, context.$attrs.renderValue)

        // 使用vue组件定义进行渲染（导入的组件）
        return h(Foo, {onClick: () => {}}, context.$attrs.renderValue)

        // 使用vue组件定义进行渲染（全局注册的组件）
        return h(resolveComponent('el-xxx'), context.$attrs.renderValue)
    },
}

const baTable = new baTableClass(
    new baTableApi('/admin/auth.admin/'),
    {
        // id 字段将使用渲染函数进行渲染
        column: [
            { label: 'id', prop: 'id', render: 'customRender', customRender: h(renderId) },
        ]
    }
)

// 自 v2.1.2 起，您可以直接建立 image、switch 等系统同级的单元格渲染器，全局使用
// 请查阅 /components/table/fieldRender/ 文件夹，其中的每个组件为一种单元格渲染器
// 组件名称即为渲染器名称，可直接将组件名于 baTable.column.render 配置使用
// 假设您参考已有渲染器建立了 /components/table/fieldRender/customRenderId.vue 组件，可如下，直接于 baTable.column 配置使用
// 建立了新的单元格渲染器后，重新执行 pnpm dev，系统还会自动更新可用渲染器的类型定义，以获得语法提示支持
// 此处不再提供渲染器内部的代码示例，因为系统已经自带了很多个定义好的，请直接复制文件->改名->修改->使用

const baTable = new baTableClass(
    new baTableApi('/admin/auth.admin/'),
    {
        column: [
            { label: 'id', prop: 'id', render: 'customRenderId' },
        ]
    }
)

自定义表格顶部按钮

有时您需要自定义表格顶部的按钮，请直接点击此处查看示例代码，或者您可以参考表格示例模块或 数据安全管理->数据回收站，我们在该管理功能内，通过插槽自定义了一个表格顶部的 还原 按钮（代码示例更完整）。

自定义表格行侧边按钮

表格行侧边的按钮组通过普通的 js 数组进行配置，所以自定义它非常容易，因为您只需对一个 js 数组进行增删改查操作；常用的按钮配置数组可通过 defaultOptButtons() 快速生成

import baTableClass from '/@/utils/baTable'
import { defaultOptButtons } from '/@/components/table'

// defaultOptButtons 函数返回常用按钮数据
let optBtn: OptButton[] = defaultOptButtons(['edit', 'delete'])

// 给第一个按钮加上点击事件
optBtn[0].click = (row: TableRow, field: TableColumn) => {
    console.log('点击了按钮')
}

// 自定义一个新的按钮
let newButton: OptButton[] = [
    {
        // 渲染方式:tipButton=带tip的按钮,confirmButton=带确认框的按钮,moveButton=移动按钮
        render: 'tipButton',
        // 按钮名称，将作为触发表格内事件（onTableAction）时的事件名
        name: 'info',
        // 鼠标 hover 时的提示，可使用多语言翻译 key，比如 user.group
        title: '详情',
        // 直接在按钮内显示的文字，title 有值时可为空，可使用多语言翻译 key，比如 user.group
        text: '详情',
        // 按钮类型，请参考 element plus 的按钮类型
        type: 'primary',
        // 按钮 icon
        icon: 'fa fa-search-plus',
        class: 'table-row-info',
        // 自定义点击事件
        click: (row: TableRow, field: TableColumn) => {},
        // 按钮是否显示，请返回布尔值
        display: (row: TableRow, field: TableColumn) => {
            return true
        },
        // 按钮是否禁用，请返回布尔值
        disabled: (row: TableRow, field: TableColumn) => {
            return false
        },
        // 自定义其他 el-button 属性
        attr: {}
        // 是否禁用 title 提示，此值通常由系统动态调整以确保提示的显示效果
        disabledTip: false,
    },
]

// 新按钮合入到默认的按钮数组
optBtn = newButton.concat(optBtn)

// 实例化 baTable
const baTable = new baTableClass(new baTableApi('table controller url'), {
    // 表格列数据
    column: [
        { type: 'selection', align: 'center', operator: false },
        {
            label: '操作',
            align: 'center',
            width: 120,
            // 表格列渲染为 buttons
            render: 'buttons',
            // 按钮数据为上面组装好的 optBtn
            buttons: optBtn,
            operator: false,
        },
    ],
})

provide('baTable', baTable)

若以上方案不能满足您的需求或任有疑惑，还可以参考表格示例模块和 数据安全管理->数据回收站，我们在该管理功能内，实例化 baTable 时定义了一个额外的表格侧边确认还原按钮。

表格操作前后置钩子

TIP

钩子不是事件，事件请参考 Element Plus 官方文档，如单击单元格、双击、勾选、鼠标 hover、右击、列宽度改变等事件 el-table 本身均以自带实现。

操作前置钩子操作后置钩子

// 前置钩子返回 false 可取消原操作

// 获取表格数据前的钩子
baTable.before.getData = () => {}
// 删除前的钩子
baTable.before.postDel = ({ ids }: { ids: string[] }) => {}
// 获取被编辑行数据前的钩子
baTable.before.getEditData = ({ id }: { id: string }) => {}
// 双击表格具体操作执行前钩子
baTable.before.onTableDblclick = ({ row, column }: { row: TableRow; column: TableColumn }) => {}
// 表单切换前钩子
baTable.before.toggleForm = ({ operate, operateIds }: { operate: string; operateIds: string[] }) => {}
// 表单提交前钩子
baTable.before.onSubmit = ({ formEl, operate, items }: { formEl: FormInstance | undefined; operate: string; items: anyObj }) => {}
// 表格内事件响应前钩子，event 有效值:selection-change=选中项改变,page-size-change=每页数量改变,current-page-change=翻页,sort-change=排序,edit=编辑,delete=删除,field-change=单元格值改变,com-search=公共搜索
baTable.before.onTableAction = ({ event, data }: { event: string; data: anyObj }) => {}
// 表格顶部菜单事件响应前钩子，event 有效值:refresh=刷新,edit=编辑,delete=删除,quick-search=快速查询,unfold=折叠/展开,change-show-column=调整列显示状态
baTable.before.onTableHeaderAction = ({ event, data }: { event: string; data: anyObj }) => {}
// 表格初始化前钩子
baTable.before.mount = () => {}

// getData 的别名
baTable.before.getIndex = () => {}
// getEditData 的别名
baTable.before.requestEdit = ({ id }: { id: string }) => {}

// 后置钩子均无需返回值

// 请求到表格数据后钩子，此时 baTable.table.data 已赋值
baTable.after.getData = ({ res }: { res: ApiResponse }) => {}
// 删除请求后钩子
baTable.after.postDel = ({ res }: { res: ApiResponse }) => {}
// 获取到编辑行数据后钩子，此时 baTable.form.items 已赋值
baTable.after.getEditData = ({ res }: { res: ApiResponse }) => {}
// 双击单元格操作执行后钩子
baTable.after.onTableDblclick = ({ row, column }: { row: TableRow; column: TableColumn }) => {}
// 表单切换后钩子
baTable.after.toggleForm = ({ operate, operateIds }: { operate: string; operateIds: string[] }) => {}
// 表单提交后钩子
baTable.after.onSubmit = ({ res }: { res: ApiResponse }) => {}
// 表格内事件响应后钩子，event 有效值:selection-change=选中项改变,page-size-change=每页数量改变,current-page-change=翻页,sort-change=排序,edit=编辑,delete=删除,
baTable.after.onTableAction = ({ event, data }: { event: string; data: anyObj }) => {}
// 表格顶部菜单事件响应后钩子，event 有效值:refresh=刷新,edit=编辑,delete=删除,quick-search=快速查询,unfold=折叠/展开,change-show-column=调整列显示状态
baTable.after.onTableHeaderAction = ({ event, data }: { event: string; data: anyObj }) => {}

// getData 的别名
baTable.after.getIndex = ({ res }: { res: ApiResponse }) => {}
// getEditData 的别名
baTable.after.requestEdit = ({ res }: { res: ApiResponse }) => {}

表格管家类的深度理解

以往很多小伙伴不能掌握 baTable 类的精髓，我们认为它没有一个正式的中文名称是决定性原因之一，现在问题已经解决。

类如其名，作为表格的管家：

你可以找它拿数据，比如 表格行数据、当前被编辑行的数据、公共搜索表单数据、快速搜索关键词、当前表单操作标识、加载状态、页码、每页显示数 等，几乎与表格相关的所有数据都能从这里拿到
你可以找它更新数据，你能拿到的数据自然也能直接修改，这些数据通常都具备响应性
你可以找它做操作，比如 刷新表格、发起公共/快速搜索、调整排序、分页、打开编辑表单 等
监控与拦截操作，几乎所有事件均可拦截或监控，比如 获取表格数据前后、获取编辑行数据前后、双击单元格前后、打开/提交表单、刷新、删除 等
随时待命，通过表格管理类你可以在代码任何位置对任意属性进行修改，类似状态商店，且该类通过 provide 提供给子级组件，你可以随时 inject，而无需自行传递（就像 popupForm.vue 中那样）
高度可定制化，您可以随时重写它的方法，添加自定义属性（方便数据随整个类在上下文中流通），甚至可以直接继承它写个新类
它是一个 js 类实例，但更是表格状态商店，是表格事件巴士，是万能入口与工具库，它是真正的好管家。

以下是一些使用示例：

示例一示例二示例三示例四

// 您可以先设置好一些表格属性，再获取表格数据
// 表格的所有可用属性，在本文下方可以寻找到，您也可以直接阅读源代码
const example1 = () => {
    baTable.table.filter.limit = 20
    baTable.table.filter.page = 2
    baTable.table.filter!.search = [{field:'status',val:'1',operator:'=',render:'tags'}]
    baTable.getData() // 或 baTable.getIndex()
}

// 数据加载完成后打开公共搜索
baTable.getData()?.then(() => {
    baTable.table.showComSearch = true
})

/**
 * 利用钩子在修改数据前对数据进行预处理
 * getEditData 为获取到编辑行数据后钩子（老版本此钩子名为 requestEdit）
 * @param object.res 为请求被编辑数据时，接口的完整响应数据
 */
baTable.after.getEditData = ({ res }) => {
    if (res.code == 1 && baTable.form.items) {
        // 将被编辑行的标题置空
        baTable.form.items.title = ''

        // 如果被编辑行没有图标，给定一个默认图标
        if (!baTable.form.items.icon) {
            baTable.form.items.icon = 'fa fa-circle-o'
        }
    }
}

import { auth } from '/@/utils/common'

// ... 略

// 重写表格内部验权方法
baTable.auth = (node) => {
    return auth({ name: '/admin/auth/group' })
}

// auth 是全局公共函数，它的文档请参考：https://doc.buildadmin.com/senior/web/utils.html
// baTable.auth 是表格内部鉴权方法，参数 node 是表格内部需要鉴权的节点，比如 add、edit、delete 等

表格所有可用属性

// 一般通过 baTable.table 访问

interface BaTable {
    /**
     * 表格数据，通过 baTable.getData 获取
     * 刷新数据可使用 baTable.onTableHeaderAction('refresh', { event: 'custom' })
     */
    data?: TableRow[]

    /**
     * 表格列定义
     */
    column: TableColumn[]

    /**
     * 获取表格数据时的过滤条件（含公共搜索、快速搜索、分页、排序等数据）
     * 公共搜索数据可使用 baTable.setComSearchData 和 baTable.getComSearchData 进行管理
     */
    filter?: {
        page?: number
        limit?: number
        order?: string
        quickSearch?: string
        // comSearchData 类型定义请参考旁边的 杂项 选项卡，数据示例直接于后台发起搜索从网络面板查看
        search?: comSearchData[]
        [key: string]: any
    }

    /**
     * 不需要双击编辑的字段，type=selection 的列为 undefined
     * 禁用全部列的双击编辑，可使用 ['all']
     */
    dblClickNotEditColumn?: (string | undefined)[]

    /**
     * 表格扩展数据，随意定义，以便一些自定义数据可以随 baTable 实例传递
     */
    extend?: anyObj

    // 表格 ref，通常在 页面 onMounted 时赋值，可选的
    ref?: typeof Table
    // 表格对应数据表的主键字段
    pk?: string
    // 路由 remark，后台菜单规则备注信息
    remark?: string | null
    // 表格加载状态
    loading?: boolean
    // 当前选中行
    selection?: TableRow[]
    // 数据总量
    total?: number
    // 默认排序字段和排序方式
    defaultOrder?: { prop: string; order: string }
    // 拖动排序限位字段，例如拖动行 pid=1，那么拖动目的行 pid 也需要为 1
    dragSortLimitField?: string
    // 接受 url 的 query 参数并自动触发公共搜索
    acceptQuery?: boolean
    // 显示公共搜索
    showComSearch?: boolean
    // 是否展开所有子项，树状表格专用属性
    expandAll?: boolean
    // 当前表格所在页面的路由 path
    routePath?: string
}

// 一般通过 baTable.form 访问

interface BaTableForm {
    /**
     * 当前表单项数据
     */
    items?: anyObj

    /**
     * 当前操作标识:Add=添加,Edit=编辑
     */
    operate?: string

    /**
     * 添加表单字段默认值，打开表单时会使用 cloneDeep 赋值给 this.form.items 对象
     */
    defaultItems?: anyObj

    /**
     * 表单扩展数据，可随意定义，以便一些自定义数据可以随 baTable 实例传递
     */
    extend?: anyObj

    // 表单 ref，实例化表格时通常无需传递
    ref?: FormInstance | undefined
    // 表单项 label 的宽度
    labelWidth?: number
    // 被操作数据ID，支持批量编辑:add=[0],edit=[1,2,n]
    operateIds?: string[]
    // 提交按钮状态
    submitLoading?: boolean
    // 表单加载状态
    loading?: boolean
}

// 一般通过 baTable.comSearch 访问

interface ComSearch {
    /** 表单项数据 */
    form: anyObj
    /** 字段搜索配置，搜索操作符（operator）、字段渲染方式（render）等 */
    fieldData: Map<string, any>
}

// 一般通过 baTable.table.column 访问

interface TableColumn extends Partial<TableColumnCtx<TableRow>> {
    // 是否于表格显示此列
    show?: boolean
    // 渲染器组件名，即 \src\components\table\fieldRender\ 中的组件之一，也可以查看 TableRenderer 类型定义
    render?: TableRenderer
    // 值替换数据（字典数据），同时用于单元格渲染时和作为公共搜索下拉框数据，格式如：{ open: '开', close: '关', disable: '已禁用' }
    replaceValue?: Record<string, any>

    // render=slot 时，slot 的名称
    slotName?: string
    // render=customRender 时，要渲染的组件或已注册组件名称的字符串
    customRender?: string | Component
    // render=customTemplate 时，自定义渲染 html，应谨慎使用：请返回 html 内容，务必确保返回内容是 xss 安全的
    customTemplate?: (row: TableRow, field: TableColumn, value: any, column: TableColumnCtx<TableRow>, index: number) => string
    // 渲染前对字段值的预处理函数（对 el-table 的 formatter 扩展）
    formatter?: (row: TableRow, column: TableColumnCtx<TableRow>, cellValue: any, index: number) => any

    /**
     * 自定义单元格渲染属性（比如单元格渲染器内部的 tag、button 组件的属性，设计上不仅是组件属性，也可以自定义其他渲染相关属性）
     * 直接定义对应组件的属性 object，或使用一个函数返回组件属性 object
     */
    customRenderAttr?: {
        tag?: TableContextDataFun<TagProps>
        icon?: TableContextDataFun<InstanceType<typeof Icon>['$props']>
        image?: TableContextDataFun<ImageProps>
        switch?: TableContextDataFun<SwitchProps>
        tooltip?: TableContextDataFun<ElTooltipProps>
        [key: string]: any
    }

    // render=tag 时，el-tag 组件的 effect
    effect?: TagProps['effect']
    // render=tag 时，el-tag 组件的 size
    size?: TagProps['size']
    // render=url 时，链接的打开方式
    target?: '_blank' | '_self'
    // render=datetime 时，时间日期的格式化方式，字母可以自由组合:y=年,m=月,d=日,h=时,M=分,s=秒，默认：yyyy-mm-dd hh:MM:ss
    timeFormat?: string
    // render=buttons 时，操作按钮数组
    buttons?: OptButton[]

    /**
     * 单元格渲染器需要的其他任意自定义数据
     * 1. render=tag 时，可单独指定每个不同的值 tag 的 type 属性 { open: 'success', close: 'info', disable: 'danger' }
     */
    custom?: any

    // 默认值（单元格值为 undefined,null,'' 时取默认值，仅使用了 render 时有效）
    default?: any
    // 是否允许动态控制字段是否显示，默认为 true
    enableColumnDisplayControl?: boolean
    // 单元格渲染组件的 key，默认将根据列配置等属性自动生成（此 key 值改变时单元格将自动重新渲染）
    getRenderKey?: (row: TableRow, field: TableColumn, column: TableColumnCtx<TableRow>, index: number) => string

    // 公共搜索操作符，默认值为 = ，值为 false 禁用此字段公共搜索，支持的操作符见下类型定义
    operator?: boolean | OperatorStr
    // 公共搜索框的 placeholder
    operatorPlaceholder?: string | string[]
    // 公共搜索渲染方式，render=tag|switch 时公共搜索也会渲染为下拉，数字会渲染为范围筛选，时间渲染为时间选择器等
    comSearchRender?: 'remoteSelect' | 'select' | 'date' | 'customRender' | 'slot'
    // 公共搜索自定义组件/函数渲染
    comSearchCustomRender?: string | Component
    // 公共搜索自定义渲染为 slot 时，slot 的名称
    comSearchSlotName?: string
    // 公共搜索自定义渲染时，外层 el-col 的属性（仅 customRender、slot 支持）
    comSearchColAttr?: Partial<ColProps>
    // 公共搜索是否显示字段的 label
    comSearchShowLabel?: boolean
    // 公共搜索渲染为远程下拉时，远程下拉组件的必要属性
    remote?: {
        pk?: string
        field?: string
        params?: anyObj
        multiple?: boolean
        remoteUrl: string
    }

    // 使用了 render 属性时，渲染前对字段值的预处理方法（即将废弃，请使用兼容 el-table 的 formatter 函数代替）
    renderFormatter?: (row: TableRow, field: TableColumn, value: any, column: TableColumnCtx<TableRow>, index: number) => any
    // 渲染为 url 时的点击事件（即将废弃，请使用 el-table 的 @cell-click 或单元格自定义渲染代替）
    click?: (row: TableRow, field: TableColumn, value: any, column: TableColumnCtx<TableRow>, index: number) => any
}

// 一般通过 baTable.table.filter!.search 访问

/**
 * 公共搜索事件返回的 Data
 */
interface comSearchData {
    field: string
    val: string | string[] | number | number[]
    operator: string
    render?: string
}

表格公共搜索

表格公共搜索是在实例化 baTable 时定义的，表格列的 render、operator、comSearchRender 属性共同参与公共搜索框的渲染。comSearchRender 支持 remoteSelect、select、date、customRender、slot，详细使用方法请直接查看下方示例代码。

公共搜索输入组件渲染示意表

render	operator	comSearchRender	公共搜索渲染
任意	`false`		不渲染
任意	`RANGE、NOT RANGE`		生成两个输入框（A和B），可输入`从A到B`的范围值
任意	`NULL、NOT NULL`		生成一个复选框，勾选则搜索值为`NULL、NOT NULL`的情况
datetime	`RANGE、NOT RANGE`		时间范围选择器
datetime	`=、>、<`等比较符号，请参考表格列的 `operator` 属性		时间选择器
tag	`=、>、<`等比较符号		生成下拉框，下拉列表定义请参考表格列的 `replaceValue`
switch	无需设定		生成下拉框: `1=开,0=关`，也可以通过设置表格列的 `replaceValue` 自定义值
任意	表格列的其他 `operator` 属性		生成普通字符串输入框
任意	`=、>、<` 等比较符号	remoteSelect	远程下拉
任意	`=、>、<` 等比较符号	select	下拉框
任意	无需设定	date	日期选择器（纯日期无时间）
datetime	`RANGE、NOT RANGE`	date	日期范围选择器（纯日期无时间）
任意	任意	customRender	自定义渲染组件，请参考下方示例

公共搜索配置示例代码

import baTableClass from '/@/utils/baTable'
import { baTableApi } from '/@/api/common'

const baTable = new baTableClass(new baTableApi('table controller url'), {
    // 定义表格列数据、同时定义公共搜索数据
    column: [
        // 关闭这个字段的公共搜索
        { type: 'selection', align: 'center', operator: false },
        // 此字段是模糊查找，并为公共搜索输入框设置了 placeholder
        { label: 'ID', prop: 'id', align: 'center', operator: 'LIKE', operatorPlaceholder: t('Fuzzy query'), width: 70 },
        // 此字段是图片，建议关闭公共搜索
        { label: '头像', prop: 'avatar', align: 'center', render: 'image', operator: false },
        // 此字段将生成一个下拉框选择进行搜索，拥有三个值
        {
            label: t('user.user.Gender'),
            prop: 'gender',
            align: 'center',
            render: 'tag',
            replaceValue: { '0': t('unknown'), '1': t('user.user.male'), '2': t('user.user.female') },
        },
        // 此字段将生成一个时间范围选择框，选择时间日期进行搜索
        { label: t('createtime'), prop: 'createtime', align: 'center', render: 'datetime', sortable: 'custom', operator: 'RANGE', width: 160 },
        // 此字段将生成一个日期范围选择框，选择日期进行搜索（请注意渲染还是 datetime 若需自定义单元格渲染请参考`表格列`一节）
        { label: t('updatetime'), prop: 'updatetime', align: 'center', render: 'datetime', sortable: 'custom', operator: 'RANGE', width: 160, comSearchRender: 'date' },
        // 另外一种在公共搜索渲染下拉框的办法
        {
            label: t('user.user.Gender'),
            prop: 'gender',
            align: 'center',
            comSearchRender: 'select',
            replaceValue: { '0': t('unknown'), '1': t('user.user.male'), '2': t('user.user.female') },
        },
        // 远程下拉选择框
        { label: '会员', prop: 'user_id', comSearchRender: 'remoteSelect', remote: {
            // 主键，下拉 value
            pk: 'id',
            // 字段，下拉 label
            field: 'username',
            // 远程接口URL
            // 比如想要获取 user(会员) 表的数据，后台`会员管理`控制器URL为`/index.php/admin/user.user/index`
            // 该URL地址通常等于对应后台管理功能的`查看`操作请求的URL
            remoteUrl: '/admin/user.user/index',
            // 额外的请求参数
            params: {},
        }},
    ]
})

自动获取表格筛选条件

有时您只需要带着一些筛选条件跳转到表格，并获取筛选后的数据，您可以直接参考会员管理->编辑会员资料->调整余额；我们在跳转到余额日志管理时，携带了 user_id 参数，该参数由于和表格字段对应，所以会自动获取到并作为公共搜索的筛选条件。

import router from '/@/router/index'

// 跳转到 user/moneyLog 页面，并携带 user_id 参数
router.push({
    name: 'user/moneyLog',
    query: {
        // user_id 字段存在于 user/moneyLog 页面表格的公共搜索中
        // user/moneyLog 页面内的表格公共搜索，会自动获取下列参数，如果存在，则自动填充并搜索
        user_id: baTable.form.items!.id,
    },
})

完全自定义公共搜索的渲染

方案一：使用slot渲染方案二：自定义组件渲染方案三：弃用表格自带的公共搜索

vue

// 此方案在 `BuildAdmin >= v2.0.0` 添加，实现了开发者最舒适的模式
<template>
    <div class="default-main">
        <TableHeader
            :buttons="['refresh', 'add', 'edit', 'delete', 'comSearch', 'quickSearch', 'columnDisplay']"
            :quick-search-placeholder="t('Quick search placeholder', { fields: t('auth.admin.username') + '/' + t('auth.admin.nickname') })"
        >
            <!-- 请注意 #test 它是自定义的插槽名称 -->
            <template #test>
                <!-- 在插槽内，您可以随意发挥，通常渲染一个输入框供用户输入内容 -->
                <!-- 输入组件的 v-model="baTable.comSearch.form[item.prop!]" 即可在baTable上下文获取用户输入的关键词 -->
                我是公共搜索的slot渲染内容
            </template>
        </TableHeader>

        <Table />
    </div>
</template>

<script setup lang="ts">
import baTableClass from '/@/utils/baTable'
const baTable = new baTableClass(
    new baTableApi('/admin/auth.Admin/'),
    {
        column: [
            // comSearchRender: 'slot' 表示本字段的公共搜索将使用 slot渲染
            // comSearchSlotName: 'test' slot的名称
            { label: '管理员', prop: 'username', operator: 'LIKE', comSearchRender:'slot', comSearchSlotName: 'test' },
        ]
    }
)
// ...
</script>

import { h, resolveComponent } from 'vue'

// searchId 即自定义的组件，你也可以直接单独建立一个 vue 文件导入使用
// 自定义组件可以接受三个 props，分别是:renderRow=当前行数据,renderField=当前列数据,renderValue=搜索框绑定值
const searchId = {
    render(context: TableRenderPublicInstance) {
        console.log(context.$attrs.renderRow, context.$attrs.renderField, context.$attrs.renderValue)
        
        // 使用原生元素渲染
        return h('input', { class: 'id-h1' }, context.$attrs.renderValue)

        // 使用vue组件定义进行渲染（全局注册的组件）
        return h(resolveComponent('el-input'), context.$attrs.renderValue)
    },
}

const baTable = new baTableClass(
    new baTableApi('/admin/auth.admin/'),
    {
        // id 字段的公共搜索将使用 searchId 组件进行渲染
        // 与单元格的完全自定义渲染只是属性名不同
        column: [
            { label: 'id', prop: 'id', comSearchRender: 'customRender', comSearchCustomRender: h(searchId) },
        ]
    }
)

vue


<!-- 1. 表格顶部菜单的 buttons 里边不要有 comSearch，表示不启用默认的公共搜索 -->
<TableHeader
    :buttons="['refresh', 'add', 'edit', 'delete', 'quickSearch', 'columnDisplay']"
    :quick-search-placeholder="t('Quick search placeholder', { fields: t('auth.admin.username') + '/' + t('auth.admin.nickname') })"
></TableHeader>

<!-- 2. 完整实现一个自定义的公共搜索组件并导入使用 -->
<!-- 3. 通过 `baTable.table.showComSearch` 来判断您自定义公共搜索组件的显示隐藏状态 -->
<ComSearch v-if="baTable.table.showComSearch"></ComSearch>

baTableApi 类

此类代码位于：\src\api\common.ts，它实现快速生成一个控制器的：增、删、改、查、排序 的操作 url 和请求方法，提供控制器的 url 即可。此类通常与 baTable 类搭配使用，若需单独定义 api 请求函数，可以直接在 \src\api 目录下定义，无需经过 baTableApi。

使用示例

vue

<script>
import { baTableApi } from '/@/api/common' // 导入表格api方法生成器

// 请注意，baTableApi 类的方法通常都是由 baTable 类来使用的，并不是在外部示例化一个 baTableApi 类使用，以下仅为方便读者理解它是什么

let baApi = new baTableApi('/admin/user.user/')
baApi.index({}) // 请求查看，参数为筛选条件，具体使用请参考baTable类
baApi.edit({}) // 请求编辑数据，参数为被编辑项id等
baApi.del({}) // 请求删除，参数为被删除数据的ids
// ...
</script>

表格顶部组件

TableHeader 组件内含有公共搜索和表头操作按钮，菜单按钮可以自动根据当前路由进行 鉴权，当前管理员无权限的按钮，则不会显示。

属性列表

属性名	注释
buttons	要显示的按钮数组，比如 `['refresh', 'add', 'comSearch']`，即表示于表格顶部显示 `刷新、添加、公共搜索` 按钮
quick-search-placeholder	快速搜索输入框的 `placeholder`

插槽列表

插槽名	注释
refreshPrepend	刷新按钮前插槽
refreshAppend	刷新按钮后插槽
—	此插槽内容将放置在组件内置的菜单按钮之后，可自定义表格顶部按钮等
quickSearchPrepend	快速搜索前插槽
任意	列配置中使用 `comSearchRender:'slot', comSearchSlotName: 插槽名称`来通过`slot`渲染公共搜索

支持的菜单按钮

菜单按钮	注释
refresh	刷新按钮
add	添加
edit	编辑
delete	删除
comSearch	公共搜索
quickSearch	快速搜索
columnDisplay	字段显示状态
unfold	展开/折叠，与 `baTable.table.expandAll` 属性关联

表格顶部菜单示例代码

src/views/backend/security/dataRecycleLog/index.vue 文件

vue

<template>
    <!-- buttons 属性定义了 TableHeader 本身支持的顶部按钮，仅需传递按钮名即可 -->
    <TableHeader
        :buttons="['refresh', 'add', 'edit', 'delete', 'comSearch', 'quickSearch', 'columnDisplay', 'unfold']"
        :quick-search-placeholder="t('Quick search placeholder', { fields: t('security.dataRecycleLog.Rule name') })"
    >
        <!-- 可以在此处以插槽的方式设置一些自定义按钮 -->
        
        <template #refreshPrepend>
            <!-- 刷新按钮前插槽内容 -->
        </template>

        <!-- 默认插槽 -->
        <template #default>
            <el-button v-blur :disabled="baTable.table.selection!.length > 0 ? false:true" class="table-header-operate" type="success">
                <Icon color="#ffffff" name="el-icon-RefreshRight" />
                <span class="table-header-operate-text">还原</span>
            </el-button>
        </template>

    </TableHeader>
</template>

<script>
import TableHeader from '/@/components/table/header/index.vue'
</script>

常见问题

如何在一个页面渲染两个表格？

由于表格数据来自 baTable 实例，并且通过 provide、inject 将整个实例传递给组件上下文，所以，两个表格不能共处于一个 vue 文件中，您可以另外建立 vue 文件，在其中写好新的表格，然后导入使用即可。

如何禁用列的双击编辑功能？

我们可以通过添加列的 prop 到 baTable 的 dblClickNotEditColumn数组 来禁用对应列的双击编辑功能，当我们想禁用全部列的双击编辑功能时只需要定义 dblClickNotEditColumn: ['all'] 即可。

表格 ​

Table 组件 ​

组件属性 ​

组件方法与事件 ​

组件插槽 ​

baTable 表格管家类 ​

使用示例 ​

表格列 ​

自定义单元格渲染 ​

自定义表格顶部按钮 ​

自定义表格行侧边按钮 ​

表格操作前后置钩子 ​

表格管家类的深度理解 ​

表格所有可用属性 ​

表格公共搜索 ​

公共搜索输入组件渲染示意表 ​

公共搜索配置示例代码 ​

自动获取表格筛选条件 ​

完全自定义公共搜索的渲染 ​

baTableApi 类 ​

使用示例 ​

表格顶部组件 ​

属性列表 ​

插槽列表 ​

支持的菜单按钮 ​

表格顶部菜单示例代码 ​

常见问题 ​

表格

Table 组件

组件属性

组件方法与事件

组件插槽

baTable 表格管家类

使用示例

表格列

自定义单元格渲染

自定义表格顶部按钮

自定义表格行侧边按钮

表格操作前后置钩子

表格管家类的深度理解

表格所有可用属性

表格公共搜索

公共搜索输入组件渲染示意表

公共搜索配置示例代码

自动获取表格筛选条件

完全自定义公共搜索的渲染

baTableApi 类

使用示例

表格顶部组件

属性列表

插槽列表

支持的菜单按钮

表格顶部菜单示例代码

常见问题