a

docs/hooks-table使用检查.md

@@ -0,0 +1,103 @@
+# 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 })`。