school-developer/docs/hooks-table使用检查.md

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. 返回值

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

---

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

1. 定义 state 并传入 useTable

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