@gx-design-vue/pro-table 0.2.0-alpha.8 → 0.2.0-alpha.9

package/dist/hooks/useFetchData.js

@@ -1,49 +1,78 @@
-import useDebounceFn from "./useDebounceFn.js";
-import { computed, onActivated, onDeactivated, onMounted, onUnmounted, ref, toRaw, unref, watch } from "vue";
-import { cloneDeep, deepMerge, getRandomNumber, getSortIndex, handleCurrentPage, isArray, isDeepEqualReact, isFunction, isObject, runFunction } from "@gx-design-vue/pro-utils";
-import { omit } from "es-toolkit";
+import { computed, onActivated, onDeactivated, onUnmounted, ref, toRaw, watch } from "vue";
+import { getRandomNumber, getSortIndex, handleCurrentPage, isArray, isFunction, isObject, merge } from "@gx-design-vue/pro-utils";
+import { useDebounceFn } from "@vueuse/core";
 //#region src/hooks/useFetchData.ts
-function useConfigFetchData(props) {
-	const rowKey = computed(() => props.rowKey);
-	const polling = computed(() => props.polling);
-	const debounceTime = computed(() => props.debounceTime);
-	const dataSource = computed(() => props.dataSource);
-	const autoRequest = computed(() => props.autoRequest);
-	return {
-		rowKey,
-		polling,
-		request: props.request,
-		postData: props.postData,
-		debounceTime,
-		dataSource,
-		autoRequest
-	};
-}
-function useFetchData({ rowKey, autoRequest, polling, request, postData, dataSource, waitRequest, debounceTime }, { params, columns, setLoading, setColumns, removeRowKeys, syncSelectedRows, defaultFormSearch, setPagination, pageInfo, paginationInfo, onRequestError, onBeforeSearchSubmit, hasCustomRender }, emit) {
-	const updateKey = ref("");
-	const umountRef = ref(false);
-	const pollingLoading = ref(false);
+const EMPTY_ARRAY = [];
+/**
+* 核心请求引擎。
+* 负责数据请求调度、分页状态、轮询、AbortController 中断、
+* loading 管理、数据转换、行操作、排序/筛选变更。
+*
+* 调度模型：所有请求入口（run/reload/handleTableChange/params 变化等）
+* 统一进入 dispatchFetch → debouncedFetch → fetchList。
+* 通过 requestId + AbortController 双重保证旧响应不回写。
+*/
+function useFetchData(config, action) {
+	const { rowKey, polling, pollingTime, request, postData, dataSource, immediate, waitRequest, autoRequest, debounceTime, params, defaultFormSearch, onLoadingChange, onRequestError, onBeforeSearchSubmit } = config;
+	const { pageInfo, paginationInfo, setPagination, setLoading, setColumns, removeRowKeys, syncSelectedRows, columns } = action;
 	const tableDataList = ref([]);
-	const pollingSetTimeRef = ref();
-	const abortRef = ref(null);
-	const requestFinally = (clear = false) => {
-		if (umountRef.value || clear) setLoading(false);
-		setPollingLoading(false);
-	};
-	const fetchList = async (props = {}) => {
-		const { pagination = {}, filters = {}, sorter = {}, removeKeys = [], isPolling = false, extra } = props;
+	const unmounted = ref(false);
+	const pollingTimer = ref(null);
+	const abortController = ref(null);
+	const requestId = ref("");
+	/** 通知外部 loading 状态变化（通过 onLoadingChange 回调） */
+	function notifyLoading(loadingState) {
+		if (onLoadingChange) onLoadingChange(loadingState);
+	}
+	function clearPollingTimer() {
+		if (pollingTimer.value != null) {
+			clearTimeout(pollingTimer.value);
+			pollingTimer.value = null;
+		}
+	}
+	function stopPolling() {
+		clearPollingTimer();
+	}
+	function schedulePolling(fetchParams) {
+		if (unmounted.value || !polling.value) return;
+		const interval = Math.max(pollingTime.value || 2e3, 2e3);
+		clearPollingTimer();
+		pollingTimer.value = setTimeout(() => {
+			dispatchFetch({
+				...fetchParams,
+				isPolling: true
+			});
+		}, interval);
+	}
+	function abortCurrent() {
+		abortController.value?.abort();
+		abortController.value = null;
+	}
+	/** 写入表格数据并同步 sortIndex，无 request 时同步 dataSource total */
+	function setTableDataList(list) {
+		tableDataList.value = getSortIndex(list, toRaw(pageInfo));
+		if (!request || !isFunction(request)) {
+			const total = list.length || 0;
+			if (total !== pageInfo.total) setPagination({ total });
+		}
+	}
+	/** 执行单次请求，处理参数合并、AbortController、轮询调度、错误处理 */
+	async function fetchList(fetchParams = {}) {
+		const { pagination: fetchPagination = {}, filters = {}, sorter = {}, removeKeys = [], isPolling = false, extra } = fetchParams;
 		if (!request || !isFunction(request)) return dataSource.value || [];
-		if (!isPolling) setLoading(true);
-		else setPollingLoading(true);
-		if (pagination && Object.keys(pagination).length) setPagination(pagination);
+		if (!isPolling) {
+			setLoading(true);
+			notifyLoading(true);
+		}
+		if (fetchPagination && Object.keys(fetchPagination).length) setPagination(fetchPagination);
 		try {
 			if (removeKeys.length) removeRowKeys(removeKeys);
-			const sorterList = isObject(sorter) ? Object.keys(sorter).length ? [sorter] : [] : sorter;
-			setColumns(unref(columns).map((item) => {
-				const row = sorterList.find((el) => (el?.columnKey || el?.field) === item.dataIndex);
+			const sorterList = isObject(sorter) && Object.keys(sorter).length ? [sorter] : isArray(sorter) ? sorter : [];
+			if (setColumns && columns) setColumns(columns.value.map((columnItem) => {
+				const matchedSorter = sorterList.find((sorterItem) => (sorterItem?.columnKey || sorterItem?.field) === columnItem.dataIndex);
 				return {
-					...item,
-					sortOrder: row?.order
+					...columnItem,
+					sortOrder: matchedSorter?.order
 				};
 			}));
 			let actionParams = {
@@ -51,9 +80,9 @@ function useFetchData({ rowKey, autoRequest, polling, request, postData, dataSou
 					pageSize: pageInfo.pageSize,
 					current: handleCurrentPage(toRaw(pageInfo), removeKeys.length)
 				},
-				...unref(defaultFormSearch),
-				...unref(params),
-				...props.params || {}
+				...toRaw(defaultFormSearch.value),
+				...toRaw(params.value),
+				...fetchParams.params || {}
 			};
 			if (onBeforeSearchSubmit && isFunction(onBeforeSearchSubmit)) actionParams = await onBeforeSearchSubmit({
 				params: actionParams,
@@ -61,98 +90,66 @@ function useFetchData({ rowKey, autoRequest, polling, request, postData, dataSou
 				filter: filters,
 				extra
 			});
-			let responseData = [];
-			const requestKey = `table_request_${getRandomNumber().uuid(10)}`;
-			updateKey.value = requestKey;
-			const response = await request?.({
-				params: cloneDeep(toRaw(actionParams)),
+			const currentRequestId = `table_request_${getRandomNumber().uuid(10)}`;
+			requestId.value = currentRequestId;
+			const controller = new AbortController();
+			abortController.value = controller;
+			const response = await request({
+				params: { ...actionParams },
 				sorter: sorterList,
 				filter: filters,
-				extra
+				extra,
+				signal: controller.signal
 			});
-			if (updateKey.value !== requestKey) return [];
+			if (requestId.value !== currentRequestId || controller.signal.aborted) return [];
 			if (response) {
 				const { success = true, data = [] } = response;
 				if (!success) return [];
-				responseData = typeof postData === "function" ? await postData?.(data) : data;
-				syncSelectedRows(responseData);
-				const total = response.total || responseData?.length || 0;
+				const responseData = typeof postData === "function" ? postData(data) : data;
+				const total = response.total || responseData.length || 0;
 				if (total !== pageInfo.total) setPagination({ total });
-				const preTableDataList = unref(tableDataList).map((item) => omit(item, ["sortIndex"]));
-				if (!isDeepEqualReact(responseData, preTableDataList)) {
-					setTableDataList(responseData);
-					return responseData;
-				}
-				return unref(tableDataList);
-			} else return [];
+				setTableDataList(responseData);
+				syncSelectedRows(responseData);
+				schedulePolling(fetchParams);
+				return responseData;
+			}
+			return [];
 		} catch (e) {
-			if (onRequestError === void 0) throw new Error(e);
-			if (tableDataList.value === void 0) setTableDataList([]);
-			onRequestError(e);
+			if (e.name === "AbortError") return [];
+			if (onRequestError) {
+				if (tableDataList.value === void 0) setTableDataList([]);
+				onRequestError(e);
+				return [];
+			}
+			throw e;
 		} finally {
-			requestFinally(true);
-		}
-		return [];
-	};
-	const fetchListDebounce = useDebounceFn(async (props = {}) => {
-		if (pollingSetTimeRef.value) clearTimeout(pollingSetTimeRef.value);
-		if (!request) return;
-		const abort = new AbortController();
-		abortRef.value = abort;
-		try {
-			const msg = await Promise.race([fetchList(props), new Promise((_, reject) => {
-				abortRef.value?.signal?.addEventListener?.("abort", () => {
-					reject("aborted");
-					fetchListDebounce.cancel();
-					requestFinally();
-				});
-			})]);
-			if (abort.signal.aborted) return;
-			const needPolling = runFunction(polling.value, msg);
-			if (needPolling && !umountRef.value) pollingSetTimeRef.value = setTimeout(() => {
-				fetchListDebounce.run({
-					...props,
-					isPolling: needPolling
-				});
-			}, Math.max(needPolling, 2e3));
-			return msg;
-		} catch (error) {
-			if (error === "aborted") return;
-			throw error;
+			if (!isPolling) {
+				setLoading(false);
+				notifyLoading(false);
+			}
 		}
-	}, debounceTime.value || 30);
-	const abortFetch = () => {
-		abortRef.value?.abort();
-		fetchListDebounce.cancel();
-		requestFinally();
-	};
-	onMounted(() => {
-		umountRef.value = false;
-	});
+	}
+	const debouncedFetch = useDebounceFn((fetchParams) => fetchList(fetchParams), () => debounceTime.value ?? 10);
+	/** 统一请求调度入口：先 abort 上一个请求，再 debounce 执行 */
+	function dispatchFetch(fetchParams = {}) {
+		abortCurrent();
+		debouncedFetch(fetchParams);
+	}
 	onActivated(() => {
-		umountRef.value = false;
+		unmounted.value = false;
 	});
 	onUnmounted(() => {
-		abortFetch();
-		umountRef.value = true;
-		clearTimeout(pollingSetTimeRef.value);
+		unmounted.value = true;
+		abortCurrent();
+		stopPolling();
 	});
 	onDeactivated(() => {
-		abortFetch();
-		umountRef.value = true;
-		clearTimeout(pollingSetTimeRef.value);
+		unmounted.value = true;
+		abortCurrent();
+		stopPolling();
 	});
-	watch(() => polling.value, () => {
-		if (waitRequest.value) return;
-		if (!polling.value) clearTimeout(pollingSetTimeRef.value);
-		else fetchListDebounce.run({ isPolling: true });
-	}, { immediate: true });
-	watch(() => waitRequest.value, () => {
-		if (waitRequest.value) setLoading(true);
-		else fetchListDebounce.run({ isPolling: false });
-	}, { immediate: true });
-	watch(() => dataSource.value, () => {
-		if (dataSource.value) setTableDataList(dataSource.value || []);
+	watch(() => dataSource.value, (source) => {
+		if (source && !isFunction(request)) setTableDataList(source);
 	}, {
 		deep: true,
 		immediate: true
@@ -161,59 +158,40 @@ function useFetchData({ rowKey, autoRequest, polling, request, postData, dataSou
 		if (waitRequest.value) return;
 		if (autoRequest.value) {
 			setPagination({ current: 1 });
-			fetchRunData();
+			dispatchFetch({ isPolling: false });
 		}
-	}, {
-		deep: true,
-		immediate: true
-	});
-	watch(() => defaultFormSearch.value, (val, old) => {
+	}, { deep: true });
+	watch(() => defaultFormSearch.value, (current, previous) => {
 		if (waitRequest.value) return;
-		if (!isDeepEqualReact(val, old)) {
+		if (current !== previous) {
 			setPagination({ current: 1 });
-			fetchRunData();
+			dispatchFetch({ isPolling: false });
 		}
-	}, {
-		deep: true,
-		immediate: true
+	}, { deep: true });
+	watch(() => polling.value, () => {
+		if (waitRequest.value) return;
+		if (!polling.value) stopPolling();
+		else dispatchFetch({ isPolling: true });
 	});
-	function fetchRunData() {
-		if (request) {
-			if (!polling.value) {
-				abortFetch();
-				fetchListDebounce.run({ isPolling: false });
-			}
-		} else setTableDataList(dataSource.value || []);
-	}
-	const getDataSourceRef = computed(() => {
-		if (hasCustomRender.value) return unref(tableDataList);
-		const viewColumns = columns.value.filter((column) => column.show || column.show === void 0);
-		if (!unref(tableDataList) || !viewColumns || viewColumns.length === 0) return [];
-		return unref(tableDataList);
+	watch(() => waitRequest.value, (waiting) => {
+		if (waiting) {
+			setLoading(true);
+			notifyLoading(true);
+		} else if (immediate.value) dispatchFetch({ isPolling: false });
 	});
-	const isTreeDataRef = computed(() => unref(tableDataList).some((item) => isArray(item.children) && item.children.length > 0));
-	function setPollingLoading(loading) {
-		pollingLoading.value = loading;
-	}
-	function handleTableChange(pagination, filters = {}, sorter = {}, extra) {
-		abortFetch();
-		fetchListDebounce.run({
-			pagination,
+	if (!waitRequest.value && immediate.value) dispatchFetch({ isPolling: false });
+	const isTreeDataRef = computed(() => tableDataList.value.some((item) => isArray(item.children) && item.children.length > 0));
+	function handleTableChange(paginationConfig, filters = {}, sorter = {}, extra) {
+		dispatchFetch({
+			pagination: paginationConfig,
 			filters,
 			sorter,
 			extra,
 			isPolling: false
 		});
 	}
-	function setTableDataList(list) {
-		const newData = getSortIndex(cloneDeep(list), toRaw(pageInfo));
-		tableDataList.value = newData;
-		if (!request || !isFunction(request)) {
-			const total = newData.length || 0;
-			if (total !== pageInfo.total) setPagination({ total });
-		}
-	}
-	const operateTableDataRow = (props) => {
+	/** 对表格数据行执行增删改操作（update/push/unshift/delete） */
+	function operateTableDataRow(props) {
 		const { key, row, value, type = "update" } = props;
 		const dataIndex = key ?? rowKey.value;
 		const recordValue = row?.[dataIndex] ?? value;
@@ -221,7 +199,7 @@ function useFetchData({ rowKey, autoRequest, polling, request, postData, dataSou
 		switch (type) {
 			case "update":
 				if (dataIndex && recordValue && row) tableDataList.value = tableDataList.value.map((item) => {
-					if (recordValue === item[dataIndex]) return deepMerge(item, row);
+					if (recordValue === item[dataIndex]) return merge({}, item, row);
 					return item;
 				});
 				break;
@@ -235,22 +213,29 @@ function useFetchData({ rowKey, autoRequest, polling, request, postData, dataSou
 				if (dataIndex) tableDataList.value = tableDataList.value.filter((item) => value !== item[dataIndex]);
 				break;
 		}
-	};
+	}
+	/** 手动触发请求，waitRequest=true 时跳过 */
+	function run(info) {
+		if (waitRequest.value) return;
+		if (request) dispatchFetch({
+			...info,
+			isPolling: false
+		});
+		else setTableDataList(dataSource.value || []);
+	}
+	/** reload 是 run 的别名 */
+	function reload(info) {
+		run(info);
+	}
 	return {
-		dataSource: getDataSourceRef,
+		dataSource: computed(() => tableDataList.value.length ? tableDataList.value : EMPTY_ARRAY),
 		isTreeDataRef,
 		setTableDataList,
 		operateTableDataRow,
 		handleTableChange,
-		run: async (info) => {
-			if (waitRequest.value) return;
-			if (request) await fetchListDebounce.run({
-				...info,
-				isPolling: false
-			});
-			else emit("reload");
-		}
+		run,
+		reload
 	};
 }
 //#endregion
-export { useConfigFetchData, useFetchData };
+export { useFetchData };

package/dist/hooks/useFitPage.d.ts

@@ -0,0 +1,19 @@
+import { BarExpose } from "../components/ScrollBar/Bar.js";
+import { ComputedRef, Ref } from "vue";
+
+//#region src/hooks/useFitPage.d.ts
+interface UseFitPageOptions {
+  fitPage: ComputedRef<boolean>;
+  cardEl: Ref<HTMLElement | undefined>;
+  prefixCls: ComputedRef<string>;
+}
+interface UseFitPageReturn {
+  scrollY: ComputedRef<number>;
+  overflowHidden: ComputedRef<boolean>;
+  fullPageClass: ComputedRef<string>;
+  scrollEl: Ref<HTMLElement | undefined>;
+  barRef: Ref<BarExpose | undefined>;
+}
+declare function useFitPage(options: UseFitPageOptions): UseFitPageReturn;
+//#endregion
+export { UseFitPageOptions, UseFitPageReturn, useFitPage };

package/dist/hooks/useFitPage.js

@@ -0,0 +1,90 @@
+import { useProvideScrollBarContext } from "../components/ScrollBar/context.js";
+import { computed, ref, watchEffect } from "vue";
+import { useElementSize, useMutationObserver, useResizeObserver, useScroll } from "@vueuse/core";
+import { onMountedOrActivated } from "@gx-design-vue/pro-hooks";
+//#region src/hooks/useFitPage.ts
+function queryChildElements(card, prefixCls, targets) {
+	targets.toolbarEl.value = card.querySelector(`.${prefixCls}-list-toolbar`) ?? void 0;
+	targets.headerEl.value = card.querySelector(".ant-table-header") ?? void 0;
+	targets.pageEl.value = card.querySelector(".ant-table-pagination") ?? void 0;
+	targets.scrollEl.value = card.querySelector(".ant-table-body") ?? void 0;
+	targets.bodyInnerEl.value = card.querySelector(".ant-table-body > table") ?? void 0;
+}
+function getElementBlockMargin(el) {
+	if (!el) return 0;
+	const style = getComputedStyle(el);
+	return (Number.parseFloat(style.marginTop) || 0) + (Number.parseFloat(style.marginBottom) || 0);
+}
+function useFitPage(options) {
+	const { fitPage, cardEl, prefixCls } = options;
+	const barRef = ref();
+	const toolbarEl = ref();
+	const headerEl = ref();
+	const pageEl = ref();
+	const scrollEl = ref();
+	const bodyInnerEl = ref();
+	const childRefs = {
+		toolbarEl,
+		headerEl,
+		pageEl,
+		scrollEl,
+		bodyInnerEl
+	};
+	const { height: cardHeight } = useElementSize(cardEl);
+	const { height: toolbarHeight } = useElementSize(toolbarEl);
+	const { height: headerHeight } = useElementSize(headerEl);
+	const { height: pageHeight } = useElementSize(pageEl);
+	const { height: bodyContentHeight } = useElementSize(bodyInnerEl);
+	useMutationObserver(cardEl, () => {
+		if (cardEl.value) queryChildElements(cardEl.value, prefixCls.value, childRefs);
+	}, {
+		childList: true,
+		subtree: true
+	});
+	onMountedOrActivated(() => {
+		if (cardEl.value) queryChildElements(cardEl.value, prefixCls.value, childRefs);
+	});
+	const toolbarMargin = computed(() => getElementBlockMargin(toolbarEl.value));
+	const pageMargin = computed(() => {
+		return getElementBlockMargin(pageEl.value);
+	});
+	const scrollY = computed(() => {
+		if (!cardEl.value || !fitPage.value) return 0;
+		const tableHeight = cardHeight.value - toolbarHeight.value - toolbarMargin.value - headerHeight.value - pageHeight.value - pageMargin.value;
+		return Math.max(0, tableHeight);
+	});
+	const overflowHidden = computed(() => {
+		if (!scrollY.value || !fitPage.value) return false;
+		return bodyContentHeight.value <= scrollY.value;
+	});
+	const fullPageClass = computed(() => {
+		return fitPage.value ? `${prefixCls.value}-full-page` : "";
+	});
+	watchEffect(() => {
+		if (!scrollEl.value) return;
+		if (fitPage.value && scrollY.value > 0) scrollEl.value.style.height = `${scrollY.value}px`;
+		else scrollEl.value.style.height = "";
+	});
+	useScroll(scrollEl, { onScroll: () => {
+		if (scrollEl.value) barRef.value?.handleScroll(scrollEl.value);
+	} });
+	useResizeObserver(scrollEl, () => {
+		barRef.value?.update();
+	});
+	useProvideScrollBarContext({
+		className: `${prefixCls.value}-scroll`,
+		tableHeaderHeight: headerHeight,
+		tableScrollYHeight: scrollY,
+		scrollbarElement: cardEl,
+		wrapElement: scrollEl
+	});
+	return {
+		scrollY,
+		overflowHidden,
+		fullPageClass,
+		scrollEl,
+		barRef
+	};
+}
+//#endregion
+export { useFitPage };

package/dist/hooks/useKeepAliveReload.d.ts

@@ -0,0 +1,21 @@
+import { ComputedRef, Ref } from "vue";
+
+//#region src/hooks/useKeepAliveReload.d.ts
+interface UseKeepAliveReloadOptions {
+  enabled: ComputedRef<boolean>;
+  reload: () => void;
+}
+interface UseKeepAliveReloadReturn {
+  hasActivated: Ref<boolean>;
+}
+/**
+ * 安全的 onActivated 包装：无组件实例时直接执行回调。
+ */
+declare function tryOnActivated(callback: () => void): void;
+/**
+ * Keep-alive 页面重新进入时触发数据请求。
+ * 首次激活仅标记状态，后续激活且 enabled 为 true 时调用 reload。
+ */
+declare function useKeepAliveReload(options: UseKeepAliveReloadOptions): UseKeepAliveReloadReturn;
+//#endregion
+export { UseKeepAliveReloadOptions, UseKeepAliveReloadReturn, tryOnActivated, useKeepAliveReload };

package/dist/hooks/useKeepAliveReload.js

@@ -0,0 +1,24 @@
+import { getCurrentInstance, nextTick, onActivated, ref } from "vue";
+//#region src/hooks/useKeepAliveReload.ts
+/**
+* 安全的 onActivated 包装：无组件实例时直接执行回调。
+*/
+function tryOnActivated(callback) {
+	if (getCurrentInstance()) onActivated(callback);
+	else nextTick(callback);
+}
+/**
+* Keep-alive 页面重新进入时触发数据请求。
+* 首次激活仅标记状态，后续激活且 enabled 为 true 时调用 reload。
+*/
+function useKeepAliveReload(options) {
+	const hasActivated = ref(false);
+	tryOnActivated(() => {
+		if (hasActivated.value) {
+			if (options.enabled.value) options.reload();
+		} else hasActivated.value = true;
+	});
+	return { hasActivated };
+}
+//#endregion
+export { tryOnActivated, useKeepAliveReload };

package/dist/hooks/useLoading.d.ts

@@ -1,10 +1,21 @@
-import { BaseTableProps } from "../props.js";
-import { Ref } from "vue";
+import { ComputedRef, Ref } from "vue";
 
 //#region src/hooks/useLoading.d.ts
-declare function useLoading(options: {
-  loading: Ref<BaseTableProps['loading']>;
-  onChange: (value: BaseTableProps['loading']) => void;
-}): [Ref<boolean>, (value: boolean) => void];
+interface UseLoadingOptions {
+  loading: ComputedRef<boolean | {
+    spinning?: boolean;
+  } | undefined>;
+  onChange?: (loading: boolean) => void;
+}
+interface UseLoadingReturn {
+  loading: Ref<boolean>;
+  setLoading: (value: boolean) => void;
+}
+/**
+ * Table loading 状态管理。
+ * 支持 boolean 和 SpinProps 对象两种 loading prop 形式，
+ * 内部始终维护 boolean 状态，外部 prop 变化时自动同步。
+ */
+declare function useLoading(options: UseLoadingOptions): UseLoadingReturn;
 //#endregion
-export { useLoading };
+export { UseLoadingOptions, UseLoadingReturn, useLoading };

package/dist/hooks/useLoading.js

@@ -1,18 +1,36 @@
 import { ref, watch } from "vue";
 import { isBoolean, isObject } from "@gx-design-vue/pro-utils";
 //#region src/hooks/useLoading.ts
+/** 从 boolean 或 SpinProps 对象中提取 spinning 状态 */
+function toSpinning(value, fallback = false) {
+	if (isBoolean(value)) return value;
+	if (isObject(value)) return value.spinning ?? fallback;
+	return fallback;
+}
+/**
+* Table loading 状态管理。
+* 支持 boolean 和 SpinProps 对象两种 loading prop 形式，
+* 内部始终维护 boolean 状态，外部 prop 变化时自动同步。
+*/
 function useLoading(options) {
-	const loading = ref(getStatus(options.loading.value));
-	watch(() => options.loading.value, (val) => {
-		loading.value = getStatus(val, loading.value);
+	const loading = ref(toSpinning(options.loading.value));
+	watch(() => options.loading.value, (propValue) => {
+		const next = toSpinning(propValue, loading.value);
+		if (next !== loading.value) {
+			loading.value = next;
+			options.onChange?.(next);
+		}
 	});
-	function getStatus(value, defaultValue = false) {
-		return isBoolean(value) ? value : isObject(value) ? value?.spinning ?? defaultValue : defaultValue;
-	}
 	function setLoading(value) {
-		loading.value = value;
+		if (loading.value !== value) {
+			loading.value = value;
+			options.onChange?.(value);
+		}
 	}
-	return [loading, setLoading];
+	return {
+		loading,
+		setLoading
+	};
 }
 //#endregion
 export { useLoading };

package/dist/hooks/usePagination.d.ts

@@ -1,18 +1,21 @@
-import { PageItemRender } from "../types/SlotsTypings.js";
-import { PageState, ProTablePagination, ProTableProps } from "../types/TableTypings.js";
+import { PageState, ProTablePagination, ProTablePaginationConfig } from "../interface.js";
 import { Ref } from "vue";
 
 //#region src/hooks/usePagination.d.ts
+/**
+ * 分页状态管理。
+ * 合并用户分页配置与默认值，分离 UI 分页展示与请求分页参数。
+ * setPagination 只同步 current/pageSize/total 到 requestPagination，避免 UI 字段污染请求参数。
+ */
 declare function usePagination({
-  pagination,
-  pageItemRender
+  pagination
 }: {
-  pagination: Ref<ProTableProps['pagination']>;
-  pageItemRender: PageItemRender;
+  pagination: Ref<ProTablePagination | undefined>;
 }): {
   paginationInfo: Ref<ProTablePagination | false>;
+  paginationAlign: Ref<'start' | 'center' | 'end'>;
   requestPagination: PageState;
-  setPagination: (info: Partial<ProTablePagination>) => void;
+  setPagination: (info: Partial<ProTablePaginationConfig>) => void;
 };
 //#endregion
 export { usePagination };