# BasicTable 表格

:::tip 说明
`BasicTable` 位于 `src/components/Table/src/Table.vue`，基于 ElementPlus 的 `el-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
<BasicTable
    :columns="columns"
    :request="loadDataTable"
    :row-key="(row) => row.id"
    ref="tableRef"
    :actionColumn="actionColumn"
    @selection-change="onSelectionChange"
>
    <template #tableTitle>
        <el-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">添加岗位</el-button>
    </template>
</BasicTable>
```

## 列定义

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

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

import { h } from 'vue';
import { ElTag } from 'element-plus';

export const columns = [
    { type: 'selection' },
    { label: 'ID', prop: 'id', fixed: 'left', width: 50 },
    { label: '岗位名称', prop: 'name', minWidth: 100 },
    {
        label: '岗位状态',
        prop: 'status',
        minWidth: 100,
        render(record) {
            return h(
                ElTag,
                { type: record.row.status == 1 ? 'success' : 'danger' },
                { default: () => (record.row.status == 1 ? '正常' : '停用') },
            );
        },
    },
    { label: '排序', prop: 'sort', minWidth: 100 },
    { label: '创建人', prop: 'createUser', minWidth: 100 },
    { label: '创建时间', prop: 'createTime', width: 180 },
];
```

### 列配置项

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

`render` 函数中 `record.row` 是行数据，`record.$index` 是行索引。

## 数据请求

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

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

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

## 操作列

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

```typescript
import { TableAction } from '@/components/Table';

const actionColumn = reactive({
    width: 200,
    label: '操作',
    prop: 'action',
    fixed: 'right',
    render(record) {
        return h(TableAction, {
            style: 'button',
            actions: [
                {
                    label: '编辑',
                    icon: 'Edit',
                    type: 'warning',
                    onClick: handleEdit.bind(null, record),
                    auth: ['sys:position:update'],  // 权限节点
                },
                {
                    label: '删除',
                    icon: 'Delete',
                    type: 'danger',
                    onClick: handleDelete.bind(null, record),
                    auth: ['sys:position:delete'],  // 权限节点
                },
            ],
        });
    },
});
```

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

## 多选

通过 `selection-change` 事件获取选中行：

```typescript
const selectionData = ref([]);

function onSelectionChange(value) {
    selectionData.value = value;
}

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

    await confirm('确定要删除？');
    record ? await positionDelete(record.row.id) : await positionBatchDelete(ids);
    message('删除成功');
    reloadTable();
}
```

## 刷新表格

通过 ref 调用 `reload` 或 `reloadTable` 方法：

```typescript
const tableRef = ref();

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

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

## 表格工具栏

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

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

通过 `showTableSetting` 和 `tableSetting` 属性控制：

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

## 搜索表单联动

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

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

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

const [register, {}] = useForm({
    labelWidth: 80,
    layout: 'horizontal',
    colProps: { span: 6 } as ColProps,
    submitOnReset: true,
    schemas,  // querySchemas.ts 中定义
});

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

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

// 数据请求：合并表单参数和分页参数
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 |

:::tip 温馨提示
BasicTable 内部自动处理分页参数（pageNo/pageSize），调用方只需提供请求函数。操作列的权限控制通过 `TableAction` 的 `auth` 属性实现，与后端 `@permission_required` 对应。`render` 函数使用 Vue 的 `h()` 函数创建虚拟 DOM。
:::

## 总结

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