kt-template-admin/skills/references/components/business/table.md

KtTable 表格

当前项目表格统一使用 KtTable + Antdv Next Table + Vben Form。不要再引入旧表格适配器或额外表格依赖。

基础用法

import type { TableColumnType } from 'antdv-next';

import type { KtTableApi, KtTableButton } from '#/components/ktTable';

import { h } from 'vue';

import { Plus } from '@vben/icons';

import { KtTable, useKtTable } from '#/components/ktTable';

interface Row {
  id: string;
  name: string;
  status: number;
}

const columns: Array<TableColumnType<Row>> = [
  { dataIndex: 'name', key: 'name', title: '名称', width: 200 },
  { dataIndex: 'status', key: 'status', title: '状态', width: 100 },
];

const api: KtTableApi<Row> = {
  list: async (params) => {
    return await getListApi({
      page: params.pageNo,
      pageSize: params.pageSize,
      ...params,
    });
  },
};

const buttons: Array<KtTableButton<Row>> = [
  {
    icon: () => h(Plus, { class: 'kt-table__button-icon' }),
    key: 'create',
    label: '新增',
    onClick: onCreate,
    type: 'primary',
  },
];

const [registerTable, tableApi] = useKtTable<Row>({
  api,
  buttons,
  columns,
  rowActions,
});

<KtTable
  onRegister={registerTable}
  v-slots={{
    bodyCell: ({ column, record }) => {
      if (column.key === 'status') {
        return record.status === 1 ? '启用' : '停用';
      }
      return undefined;
    },
  }}
/>

搜索表单

const [registerTable] = useKtTable<Row>({
  api,
  columns,
  formOptions: {
    fieldMappingTime: [['createTime', ['startTime', 'endTime']]],
    labelInInput: true,
    schema: [
      { component: 'Input', fieldName: 'keyword', label: '关键词' },
      {
        component: 'Select',
        fieldName: 'status',
        label: '状态',
        componentProps: {
          allowClear: true,
          options: [
            { label: '启用', value: 1 },
            { label: '停用', value: 0 },
          ],
        },
      },
    ],
  },
});

操作按钮

按钮完全由业务页面注册，组件里不写死新增、编辑、删除等业务逻辑。

const rowActions = [
  {
    key: 'edit',
    label: '编辑',
    onClick: onEdit,
    permissionCodes: ['System:Role:Edit'],
  },
  {
    confirm: (row) => `确认删除「${row.name}」吗？`,
    danger: true,
    key: 'delete',
    label: '删除',
    onClick: onDelete,
    permissionCodes: ['System:Role:Delete'],
  },
];

可插拔模块

import { defineKtTableHook, defineKtTableModule } from '#/components/ktTable';

const requestLogger = defineKtTableHook<Row>({
  name: 'requestLogger',
  onBeforeFetch(params) {
    console.log(params);
  },
});

const statusModule = defineKtTableModule<Row>({
  columns: [{ dataIndex: 'status', key: 'status', title: '状态', width: 100 }],
  hooks: [requestLogger],
  name: 'statusModule',
});

const [registerTable] = useKtTable<Row>({
  columns,
  modules: [statusModule],
});

常用配置

属性	说明
api.list	远程数据接口，组件自动带分页和搜索参数
columns	Antdv Next TableColumnType[]
formOptions	Vben Form 搜索表单配置
buttons	表格头部按钮
rowActions	行操作按钮，超过可见数量自动折叠
statistics	行列级统计，固定在表格底部
showIndex	是否显示序号列，默认显示
showSelection	是否显示选择列
showPagination	是否显示分页
rowResizable	是否允许调整单行行高

约束

• 表格列使用 Antdv Next 原生 TableColumnType。
• 自定义单元格使用 bodyCell 插槽或页面内 TSX 渲染。
• 搜索表单必须使用 Vben Form，不在外部维护独立 searchValue。
• 业务按钮、权限码和请求逻辑都由页面通过 useKtTable 注册。