# hooks/table 使用方法检查

## 一、useTable 源码要点（`src/hooks/table.ts`）

### 1. 入参 `BasicTableProps`

| 属性            | 类型                            | 默认值                                     | 说明                               |
| --------------- | ------------------------------- | ------------------------------------------ | ---------------------------------- |
| `createdIsNeed` | `boolean`                       | **true**                                   | 是否在 `onMounted` 时自动请求列表  |
| `isPage`        | `boolean`                       | true                                       | 是否分页                           |
| `queryForm`     | `any`                           | `{}`                                       | 查询条件，会合并到请求参数         |
| `pageList`      | `(...arg: any) => Promise<any>` | -                                          | **必填**，分页接口方法             |
| `props`         | `object`                        | `{ item: 'records', totalCount: 'total' }` | 列表/总数的数据路径                |
| `validate`      | `Function`                      | -                                          | 请求前校验，不通过则不请求         |
| `onLoaded`      | `Function`                      | -                                          | 请求成功、写入 `dataList` 后的回调 |
| `onCascaded`    | `Function`                      | -                                          | 级联回调                           |
| `pagination`    | `Pagination`                    | 见源码                                     | 分页配置                           |

### 2. 内部逻辑

- **请求参数**：`query()` 调用 `state.pageList({ ...state.queryForm, current, size, descs, ascs })`。
- **响应处理**：用 `state.props.item`、`state.props.totalCount` 从 `res.data` 取列表和总数，写入 `state.dataList`、`state.pagination.total`。
- **首次加载**：在 **hooks 内部的 `onMounted`** 里，若 `state.createdIsNeed === true` 则执行一次 `query()`。
- **注意**：`useTable` **不 return state**，调用方需要自己持有一份 `state`（通常用 `reactive`）并传给 `useTable(state)`，表格数据、分页、loading 都写在这份 `state` 上。

### 3. 返回值

```ts
{
	getDataList, // (refresh?: any) => void，默认重置到第 1 页再请求；getDataList(false) 不重置页码
		currentChangeHandle, // 页码变化时调用
		sizeChangeHandle, // 每页条数变化时调用
		sortChangeHandle, // 排序变化时调用（若表格支持 sortable="custom"）
		tableStyle, // { cellStyle, headerCellStyle }
		downBlobFile; // 下载文件
}
```

---

## 二、推荐用法（与 search-form 配合）

### 1. 定义 state 并传入 useTable

```ts
import { BasicTableProps, useTable } from '/@/hooks/table';

const search = reactive({ deptCode: '', realName: '', teacherNo: '' });

const state = reactive<BasicTableProps>({
	queryForm: search, // 与 search-form 的 :model 同一对象
	pageList: fetchList, // 或自定义方法合并额外参数
	// createdIsNeed 不写则默认为 true，首屏自动请求
});

const { getDataList, currentChangeHandle, sizeChangeHandle, tableStyle } = useTable(state);
```

- **state 由调用方定义并传入**，不要在解构时期望 `useTable` 返回 `state`（源码未返回）。

### 2. 模板绑定

- 表格：`:data="state.dataList"`、`v-loading="state.loading"`，`tableStyle` 用于 `cell-style` / `header-cell-style`。
- 分页：`v-bind="state.pagination"` 或分别绑定 `current`/`size`/`total`，事件用 `@current-change="currentChangeHandle"`、`@size-change="sizeChangeHandle"`。

### 3. 查询 / 重置 / 刷新

- 点击「查询」：先更新 `search`（或额外参数），再 `getDataList()`（会回到第 1 页）。
- 重置：清空 `search`（及 ref 里的额外参数），可选 `searchFormRef?.resetFields()`，再 `getDataList()`。
- 只刷新当前页：`getDataList(false)`。

### 4. 与 createdIsNeed 的关系

- **createdIsNeed: true（默认）**：hooks 内部 onMounted 会自动调一次 `query()`，**页面里不需要再在 onMounted 里调 getDataList()**，否则会重复请求。
- **createdIsNeed: false**：不在挂载时请求，需要自己在合适时机（例如 onMounted 或某个条件满足后）调用 `getDataList()`。

---

## 三、professionaltitlerelation/index.vue 检查结果

| 检查项                                                           | 状态 | 说明                                                   |
| ---------------------------------------------------------------- | ---- | ------------------------------------------------------ |
| queryForm 使用 search                                            | ✅   | 与 search-form 的 model 一致                           |
| pageList 返回结构                                                | ✅   | 返回 `{ data: { records, total } }`，与默认 props 一致 |
| createdIsNeed                                                    | ✅   | 未配置即默认 true，首屏由 useTable 自动请求            |
| onMounted 不重复请求                                             | ✅   | 仅 `loadDictData()`，未再调 getDataList                |
| 表格绑定 state.dataList / state.loading                          | ✅   | 正确                                                   |
| 分页绑定 state.pagination + currentChangeHandle/sizeChangeHandle | ✅   | 正确                                                   |
| 查询 handleFilter → getDataList()                                | ✅   | 正确                                                   |
| 重置 resetQuery → 清空 search + getDataList()                    | ✅   | 正确                                                   |
| 删除/审核后 getDataList()                                        | ✅   | 正确                                                   |
| tableStyle 用于 el-table                                         | ✅   | 正确                                                   |

**结论**：当前 `professionaltitlerelation/index.vue` 对 hooks/table 的使用符合上述规范，无需修改。

---

## 四、常见注意点

1. **不要从 useTable 解构 state**：源码未返回 state，应自己在页面里 `const state = reactive<BasicTableProps>({...})` 并传给 `useTable(state)`。
2. **文档中若写 `const { state } = useTable(state)`**：属于文档笔误，实际应使用调用方定义的 `state`。
3. **自定义 pageList 时**：返回结构需与 `props` 一致，默认即 `res.data.records`、`res.data.total`；若后端字段不同，可同时配置 `props: { item: 'xxx', totalCount: 'yyy' }`。
4. **需要额外请求参数时**：在 `pageList` 里对入参做合并，例如 `return await fetchList({ ...queryParams, ...params.value })`。
