BasicTable 表格

说明

BasicTable 位于 src/components/Table/src/Table.vue，基于 NaiveUI 的 n-data-table 二次封装，提供列定义、数据请求、分页、操作列、多选、全屏、密度调整、列设置等能力。

组件架构

src/components/Table/
├── src/
│ ├── Table.vue            # 主组件
│ ├── props.ts             # 属性定义
│ ├── types/table.ts       # 类型定义
│ ├── hooks/
│ │ ├── useLoading.ts      # loading 状态
│ │ ├── useColumns.ts      # 列管理
│ │ ├── useDataSource.ts   # 数据源管理
│ │ ├── usePagination.ts   # 分页管理
│ │ └── useTableContext.ts # 表格上下文
│ └── components/
│ ├── Render.tsx           # 渲染函数组件
│ └── settings/
│ └── ColumnSetting.vue    # 列设置面板
├── index.ts               # 导出 TableAction 等
└── src/TableAction.vue    # 操作列按钮组件

基本用法

<BasicTable
    :columns="columns"
    :request="loadDataTable"
    :row-key="(row) => row.id"
    ref="tableRef"
    :actionColumn="actionColumn"
    @update:checked-row-keys="onCheckedRow"
>
    <template #tableTitle>
        <n-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">
            <template #icon><n-icon><PlusOutlined /></n-icon></template>
            添加岗位
        </n-button>
    </template>
</BasicTable>

列定义

columns 定义表格列，支持 render 函数自定义渲染：

// src/views/system/position/columns.ts

import { h } from 'vue';
import { NTag } from 'naive-ui';

export const columns = [
    { type: 'selection', width: 50, fixed: 'left' },
    { title: 'ID', key: 'id', fixed: 'left', width: 50 },
    { title: '岗位名称', key: 'name', width: 100 },
    {
        title: '岗位状态',
        key: 'status',
        width: 100,
        render(record) {
            return h(
                NTag,
                {
                    style: { marginRight: '6px' },
                    bordered: false,
                    type: record.status == 1 ? 'success' : 'error',
                },
                { default: () => (record.status == 1 ? '正常' : '停用') },
            );
        },
    },
    { title: '排序', key: 'sort', width: 100 },
    { title: '创建人', key: 'createUser', width: 100 },
    { title: '创建时间', key: 'createTime', width: 180 },
];

列配置项

属性	类型	说明
key	string	字段名
title	string	列标题
width	number	固定宽度
minWidth	number	最小宽度
type	string	列类型：selection / index
fixed	string	固定列：left / right
render	function	自定义渲染函数，接收 { row, column, index }
isSlot	boolean	是否使用插槽渲染
ellipsis	boolean	是否溢出省略

render 函数中 record 直接是行数据对象，通过 record.key 访问字段值。

数据请求

request 属性传入数据请求函数，组件自动管理分页和 loading：

const loadDataTable = async (res: any) => {
    const result = await getPositionList({ ...formParams, ...res });
    return result;  // 返回 { data, count } 结构
};

内部通过 useDataSource Hook 实现：自动传入 pageNo、pageSize 参数，自动设置 total，自动管理 loading 状态。

操作列

actionColumn 使用 TableAction 组件渲染行操作按钮，支持权限控制：

import { TableAction } from '@/components/Table';
import { renderIcon } from '@/utils';
import { FormOutlined, DeleteOutlined } from '@vicons/antd';

const actionColumn = reactive({
    width: 200,
    title: '操作',
    align: 'center',
    key: 'action',
    fixed: 'right',
    render(record) {
        return h(TableAction as any, {
            style: 'button',
            actions: [
                {
                    label: '编辑',
                    icon: renderIcon(FormOutlined),
                    type: 'info',
                    onClick: handleEdit.bind(null, record),
                    auth: ['sys:position:update'],  // 权限节点
                },
                {
                    label: '删除',
                    icon: renderIcon(DeleteOutlined),
                    type: 'error',
                    onClick: handleDelete.bind(null, record),
                    auth: ['sys:position:delete'],  // 权限节点
                },
            ],
        });
    },
});

TableAction 的 auth 属性接受权限数组，内部通过 usePermission Hook 检查，无权限时自动隐藏按钮。

多选

通过 update:checked-row-keys 事件获取选中行：

const rowKeys = ref([]);

function onCheckedRow(keys) {
    rowKeys.value = keys;
}

// 批量删除
async function handleDelete(record) {
    let ids = [];
    if (!record) {
        ids = rowKeys.value;
    }

    dialog.warning({
        title: '提示',
        content: '确定要删除？',
        positiveText: '确定',
        negativeText: '取消',
        onPositiveClick: async () => {
            record?.id ? await positionDelete(record.id) : await positionBatchDelete(ids);
            message.success('删除成功');
            reloadTable();
        },
    });
}

刷新表格

通过 ref 调用 reload 或 reloadTable 方法：

const basicTableRef = ref();

// 刷新到第一页
function reloadTable(noRefresh = '') {
    basicTableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
}

// 操作成功后刷新
const handleAdd = async () => {
    await positionAdd(data);
    message.success('操作成功');
    reloadTable();
};

表格工具栏

BasicTable 内置右侧工具栏，支持：

• 刷新按钮（redo）
• 密度切换（small / default / large）
• 列设置面板（ColumnSetting）
• 全屏切换
• 斑马纹开关

通过 showTableSetting 和 tableSetting 属性控制：

<BasicTable
    :showTableSetting="true"
    :tableSetting="{ redo: true, size: true, setting: true, fullscreen: true, striped: true }"
/>

搜索表单联动

列表页中 BasicForm 和 BasicTable 的典型联动模式：

// src/views/system/position/index.vue

const formParams = reactive({ name: '', status: '' });

const [register, {}] = useForm({
    labelWidth: 80,
    gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
    submitOnReset: true,
    schemas,  // querySchemas.ts 中定义
});

// 表单提交：更新查询参数，刷新表格
function handleSubmit(values: Recordable) {
    for (const key in formParams) { formParams[key] = ''; }
    for (const key in values) { formParams[key] = values[key]; }
    reloadTable();
}

// 表单重置：清空查询参数，刷新表格
function handleReset(values: Recordable) {
    for (const key in formParams) { formParams[key] = ''; }
    for (const key in values) { formParams[key] = values[key]; }
    reloadTable();
}

// 数据请求：合并表单参数和分页参数
const loadDataTable = async (res: any) => {
    const result = await getPositionList({ ...formParams, ...res });
    return result;
};

defineExpose

组件通过 defineExpose 暴露的方法：

方法	说明
reload(opt?)	刷新表格（可指定 pageNo）
restReload()	重置后刷新
reloadTable(opt?)	刷新表格（清空选中行）
clearSelection()	清空多选
getDataSource()	获取当前数据源
setTableData(data)	设置表格数据
setColumns(columns)	设置列
setLoading(loading)	设置 loading

温馨提示

BasicTable 内部自动处理分页参数（pageNo/pageSize），调用方只需提供请求函数。操作列的权限控制通过 TableAction 的 auth 属性实现，与后端 @permission_required 对应。render 函数使用 Vue 的 h() 函数创建虚拟 DOM，直接接收行数据对象，通过 record.key 访问字段值。

总结

BasicTable 封装了列定义（含 render 函数自定义渲染）、数据请求（自动分页和 loading）、操作列（TableAction + 权限控制）、多选、全屏、密度、列设置等表格常用能力。通过 columns 配置化定义列（使用 title/key 而非 label/prop），request 函数自动管理数据加载，actionColumn 配置操作按钮。