# 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 })`。