# BasicTable 表格
:::tip 说明
`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 # 操作列按钮组件
```
## 基本用法
```vue
新建
```
## 列定义
`columns` 定义表格列，支持 `render` 函数自定义渲染：
```typescript
// 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 | 固定宽度 |
| `type` | string | 列类型：`selection` / `index` |
| `fixed` | string | 固定列：`left` / `right` |
| `render` | function | 自定义渲染函数，直接接收行数据 `record` |
| `ellipsis` | boolean | 是否溢出省略 |
:::warning render 回调说明
NaiveUI 表格的 `render` 回调直接接收行数据对象 `record`，无需通过 `record.row` 访问。
:::
## 数据请求
`request` 属性传入数据请求函数，组件自动管理分页和 loading：
```typescript
const loadDataTable = async (res) => {
rowKeys.value = [];
const result = await getPositionList({ ...formParams, ...res });
return result; // 返回 { data, count } 结构
};
```
内部通过 `useDataSource` Hook 实现：自动传入 `pageNo`、`pageSize` 参数，自动设置 `total`，自动管理 loading 状态。
## 操作列
`actionColumn` 使用 `TableAction` 组件渲染行操作按钮，支持权限控制：
```typescript
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 检查，无权限时自动隐藏按钮。图标通过 `renderIcon` 工具函数包装 `@vicons/antd` 图标组件。
## 多选
通过 `@update:checked-row-keys` 事件获取选中行：
```typescript
const rowKeys = ref([]);
function onCheckedRow(keys) {
rowKeys.value = keys;
}
// 批量删除
async function handleDelete(record) {
dialog.warning({
title: '提示',
content: '确定要删除？',
positiveText: '确定',
negativeText: '取消',
onPositiveClick: async () => {
record.id ? await positionDelete(record.id) : await positionBatchDelete(rowKeys.value);
message.success('删除成功');
reloadTable();
},
});
}
```
## 刷新表格
通过 ref 调用 `reload` 或 `reloadTable` 方法：
```typescript
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` 属性控制：
```vue
```
## 搜索表单联动
列表页中 BasicForm 和 BasicTable 的典型联动模式：
```typescript
// src/views/system/position/index.vue
const formParams = reactive({ name: '', status: '' });
const [register, {}] = useForm({
gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
labelWidth: 80,
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) => {
rowKeys.value = [];
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 |
:::tip 温馨提示
BasicTable 内部自动处理分页参数（pageNo/pageSize），调用方只需提供请求函数。操作列的权限控制通过 `TableAction` 的 `auth` 属性实现，与后端 `@permission_required` 对应。`render` 函数使用 Vue 的 `h()` 函数创建虚拟 DOM。NaiveUI 表格的 `render` 回调直接接收行数据，无需通过 `record.row` 访问。
:::
## 总结
BasicTable 封装了列定义（含 `render` 函数自定义渲染）、数据请求（自动分页和 loading）、操作列（`TableAction` + 权限控制）、多选、全屏、密度、列设置等表格常用能力。通过 `columns` 配置化定义列（使用 `title`/`key`），`request` 函数自动管理数据加载，`actionColumn` 配置操作按钮。多选事件使用 `@update:checked-row-keys`，删除确认使用 NaiveUI 的 `useDialog`。