school-developer/docs/useTable与search-form兼容说明.md

useTable 与 search-form 组件兼容使用说明

概述

useTable Hook 完全兼容自定义 <search-form> 组件。只需要将搜索表单的数据对象作为 queryForm 传入即可。

兼容原理

1. search-form 组件：只是一个表单包装器，接收 model prop 绑定到内部的 el-form
2. useTable Hook：接收 queryForm 对象，会自动将其合并到 API 请求参数中
3. 两者配合：将 search-form 的 model 对象作为 useTable 的 queryForm 传入即可

改造示例

当前代码（手动管理）

<template>
	<!-- 搜索表单 -->
	<search-form v-show="showSearch" :model="search" ref="searchFormRef" @keyup-enter="handleFilter(search)">
		<!-- 表单项 -->
	</search-form>

	<!-- 表格 -->
	<el-table :data="tableData" v-loading="tableLoading">
		<!-- 表格列 -->
	</el-table>

	<!-- 分页 -->
	<pagination :current="page.currentPage" :size="page.pageSize" :total="page.total" @currentChange="currentChange" @sizeChange="handleSizeChange" />
</template>

<script setup lang="ts">
const search = reactive({
	deptCode: '',
	realName: '',
	teacherNo: '',
	// ... 其他字段
});

const tableData = ref([]);
const tableLoading = ref(false);
const page = reactive({
	currentPage: 1,
	pageSize: 10,
	total: 0,
});
const params = ref<any>({});

// 手动实现数据加载
const getList = (page: any) => {
	tableLoading.value = true;
	fetchList(
		Object.assign(
			{
				current: page.currentPage,
				size: page.pageSize,
			},
			params.value
		)
	).then((response: any) => {
		tableData.value = response.data.record.records;
		page.total = response.data.record.total;
		tableLoading.value = false;
	});
};

// 手动实现分页
const currentChange = (val: number) => {
	page.currentPage = val;
	getList(page);
};

const handleSizeChange = (val: number) => {
	page.pageSize = val;
	page.currentPage = 1;
	getList(page);
};

// 查询
const handleFilter = (param: any) => {
	params.value = { ...param };
	page.currentPage = 1;
	getList(page);
};

onMounted(() => {
	getList(page);
});
</script>

改造后代码（使用 useTable）

<template>
	<!-- 搜索表单 - 保持不变 -->
	<search-form v-show="showSearch" :model="search" ref="searchFormRef" @keyup-enter="handleFilter(search)">
		<!-- 表单项 -->
	</search-form>

	<!-- 表格 - 使用 state.dataList 和 state.loading -->
	<el-table :data="state.dataList" v-loading="state.loading" :cell-style="tableStyle.cellStyle" :header-cell-style="tableStyle.headerCellStyle">
		<!-- 表格列 -->
	</el-table>

	<!-- 分页 - 使用 state.pagination -->
	<pagination
		:current="state.pagination.current"
		:size="state.pagination.size"
		:total="state.pagination.total"
		@currentChange="currentChangeHandle"
		@sizeChange="sizeChangeHandle"
	/>
</template>

<script setup lang="ts">
import { BasicTableProps, useTable } from '/@/hooks/table';
import { fetchList } from '/@/api/professional/teacherbase';

// 搜索表单数据 - 保持不变
const search = reactive({
	deptCode: '',
	realName: '',
	teacherNo: '',
	// ... 其他字段
});

// 额外参数（如 flag 等）
const params = ref<any>({});

// 配置 useTable
const state: BasicTableProps = reactive<BasicTableProps>({
	// 将 search 对象作为 queryForm
	queryForm: search,

	// 自定义 pageList 方法，合并额外参数
	pageList: async (queryParams: any) => {
		// 合并 search 和 params 中的额外参数
		return await fetchList({
			...queryParams,
			...params.value,
		});
	},

	// 数据属性映射（根据后端返回结构调整）
	props: {
		item: 'record.records', // 数据列表路径
		totalCount: 'record.total', // 总数字段路径
	},

	// 数据加载完成后的回调
	onLoaded: async (state) => {
		// 数据转换逻辑
		state.dataList = convertDictData(state.dataList);

		// 其他处理逻辑（如 auditAll）
		// ...
	},
});

// 使用 useTable Hook
const { getDataList, currentChangeHandle, sizeChangeHandle, tableStyle, state } = useTable(state);

// 查询方法 - 简化
const handleFilter = (param: any) => {
	// 更新额外参数
	params.value = { ...param };
	// 调用 getDataList 刷新数据（会自动跳转到第一页）
	getDataList();
};

// 重置查询
const resetQuery = () => {
	searchFormRef.value?.formRef?.resetFields();
	// 重置 search 对象
	Object.keys(search).forEach((key) => {
		search[key] = '';
	});
	params.value = {};
	getDataList();
};

// 其他需要刷新表格的地方
const handelQuickSeach = (val: any) => {
	params.value.flag = val;
	getDataList(); // 使用 getDataList 替代 getList(page)
};

const updateInoutFlag = (row: any, val: any) => {
	const updateParams = { teacherNo: row.teacherNo, inoutFlag: val };
	messageBox.confirm('确认操作?').then(() => {
		updateInout(updateParams).then((res: any) => {
			message.success('修改成功');
			getDataList(false); // 刷新但保持当前页
		});
	});
};

// 数据转换函数（保持不变）
const convertDictData = (records: any[]) => {
	// ... 转换逻辑
	return records;
};
</script>

关键改造点

1. 导入 useTable

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

2. 配置 state

const state: BasicTableProps = reactive<BasicTableProps>({
	queryForm: search, // 将 search 对象作为 queryForm
	pageList: fetchList, // 或自定义方法
	props: {
		item: 'record.records',
		totalCount: 'record.total',
	},
});

3. 处理额外参数

如果查询时需要额外的参数（如 params.value.flag），有两种方式：

方式一：自定义 pageList 方法（推荐）

const params = ref<any>({});

const state: BasicTableProps = reactive<BasicTableProps>({
	queryForm: search,
	pageList: async (queryParams: any) => {
		// 合并额外参数
		return await fetchList({
			...queryParams,
			...params.value, // 合并额外参数
		});
	},
});

方式二：在 onLoaded 中处理

const state: BasicTableProps = reactive<BasicTableProps>({
	queryForm: search,
	pageList: fetchList,
	onLoaded: async (state) => {
		// 可以在这里处理数据转换等逻辑
	},
});

4. 替换数据引用

原代码	改造后
tableData	state.dataList
tableLoading	state.loading
page.currentPage	state.pagination.current
page.pageSize	state.pagination.size
page.total	state.pagination.total

5. 替换方法调用

原代码	改造后
getList(page)	getDataList() 或 getDataList(false)
currentChange(val)	currentChangeHandle(val)
handleSizeChange(val)	sizeChangeHandle(val)

6. 处理数据转换

如果需要在数据加载后进行转换，使用 onLoaded 回调：

const state: BasicTableProps = reactive<BasicTableProps>({
	queryForm: search,
	pageList: fetchList,
	onLoaded: async (state) => {
		// 字典数据转换
		state.dataList = convertDictData(state.dataList);

		// 处理 auditAll 等逻辑
		// 注意：需要在 API 响应中获取，或通过其他方式处理
	},
});

完整改造示例（针对当前页面）

// 1. 导入 useTable
import { BasicTableProps, useTable } from '/@/hooks/table';

// 2. 搜索表单数据（保持不变）
const search = reactive({
	deptCode: '',
	secDeptCode: '',
	tied: '',
	realName: '',
	teacherNo: '',
	retireDate: '',
	pfTitleId: '',
	stationDutyLevelId: '',
	politicsStatus: '',
	teacherCate: '',
	inoutFlag: '',
});

// 3. 额外参数（用于 flag 等）
const params = ref<any>({});

// 4. 配置 useTable
const state: BasicTableProps = reactive<BasicTableProps>({
	queryForm: search, // 将 search 作为 queryForm

	// 自定义 pageList，合并额外参数
	pageList: async (queryParams: any) => {
		// 合并 search 和 params
		const mergedParams = {
			...queryParams,
			...params.value,
			tied: search.tied, // 如果需要特殊处理
		};
		return await fetchList(mergedParams);
	},

	// 数据属性映射
	props: {
		item: 'record.records',
		totalCount: 'record.total',
	},

	// 数据加载完成回调
	onLoaded: async (state) => {
		// 字典数据转换
		state.dataList = convertDictData(state.dataList);

		// 注意：auditAll 需要从 API 响应中获取
		// 如果 API 返回在 response.data.auditAll，需要特殊处理
	},
});

// 5. 使用 useTable
const { getDataList, currentChangeHandle, sizeChangeHandle, tableStyle, state } = useTable(state);

// 6. 查询方法（简化）
const handleFilter = (param: any) => {
	params.value = { ...param };
	getDataList(); // 自动跳转到第一页
};

// 7. 重置查询
const resetQuery = () => {
	searchFormRef.value?.formRef?.resetFields();
	Object.keys(search).forEach((key) => {
		search[key] = '';
	});
	params.value = {};
	getDataList();
};

// 8. 快速查询
const handelQuickSeach = (val: any) => {
	params.value.flag = val;
	getDataList();
};

// 9. 其他需要刷新的地方
const updateInoutFlag = (row: any, val: any) => {
	const updateParams = { teacherNo: row.teacherNo, inoutFlag: val };
	messageBox.confirm('确认操作?').then(() => {
		updateInout(updateParams).then((res: any) => {
			message.success('修改成功');
			getDataList(false); // 保持当前页
		});
	});
};

注意事项

1. API 响应结构

如果 API 返回结构是 response.data.record.records，需要配置 props：

props: {
  item: 'record.records',
  totalCount: 'record.total'
}

2. 额外参数处理

如果查询时需要额外的参数（不在 search 对象中），使用自定义 pageList 方法合并：

pageList: async (queryParams: any) => {
	return await fetchList({
		...queryParams,
		...params.value, // 额外参数
		// 或其他特殊参数
	});
};

3. 数据转换

如果需要在数据加载后进行转换，使用 onLoaded 回调：

onLoaded: async (state) => {
	state.dataList = convertDictData(state.dataList);
};

4. 特殊响应字段

如果 API 响应中有特殊字段（如 auditAll），需要在 onLoaded 中处理，或者自定义 pageList 方法：

pageList: async (queryParams: any) => {
	const response = await fetchList({
		...queryParams,
		...params.value,
	});

	// 处理特殊字段
	if (response.data.auditAll == '0') {
		auditAll.value = false;
	} else {
		auditAll.value = true;
	}

	return response;
};

5. 初始化数据加载

useTable 默认会在 onMounted 时自动加载数据。如果不需要自动加载，设置：

const state: BasicTableProps = reactive<BasicTableProps>({
	queryForm: search,
	pageList: fetchList,
	createdIsNeed: false, // 禁用自动加载
});

// 手动调用
onMounted(() => {
	init();
	loadSearchDictData();
	getDataList(); // 手动加载
});

优势总结

使用 useTable 后：

1. ✅ 代码量减少：不需要手动管理 tableData、tableLoading、page
2. ✅ 自动状态管理：loading、分页、数据自动管理
3. ✅ 统一方法：getDataList() 统一刷新数据
4. ✅ 兼容性好：完全兼容自定义 search-form 组件
5. ✅ 灵活扩展：支持自定义 pageList、onLoaded 等回调

总结

useTable 完全兼容自定义 <search-form> 组件，只需要：

1. 将 search 对象作为 queryForm 传入
2. 使用 state.dataList、state.loading、state.pagination 替代手动管理的状态
3. 使用 getDataList() 替代 getList(page)
4. 使用 currentChangeHandle、sizeChangeHandle 替代手动分页方法

如果有额外参数或特殊处理，使用自定义 pageList 方法或 onLoaded 回调即可。