104 lines
5.1 KiB
Markdown
104 lines
5.1 KiB
Markdown
# 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 })`。
|