niuma-ui 1.3.8 → 2.0.0

package/dist/components/table/src/composables/useRsTableInteraction.d.ts

@@ -0,0 +1,145 @@
+/**
+ * RsTable 行/列交互：排序点击、列拖拽排序、行选/展开、行拖拽封装。
+ *
+ * 性能约定：
+ * - 不引入对 data 的 deep watch
+ * - rowKeyFor 走 Engine 的 rowKeyByIndex 缓存，避免热路径重复 resolve
+ */
+import { type Ref } from 'vue';
+import { type RsTableRowDragTrigger, type RsTableRowDropMode } from '../utils/table-drag';
+import { type RsTableColumn, type RsTableRowData, type RsTableRowEntry, type RsTableRowKey, type RsTableSelectionType, type RsTableSortOrder, type RsTableSortState, type RsTableTreeConfig, type RsTableTreeNodeIndex, type RsTableRowDropPosition } from '../utils/table-utils';
+export interface UseRsTableInteractionOptions<T extends RsTableRowData> {
+    multiSort: () => boolean;
+    maxSort: () => number | undefined;
+    columnDraggable: () => boolean;
+    selectable: () => boolean;
+    selectionType: () => RsTableSelectionType;
+    rowSelectable?: (row: T, index: number) => boolean;
+    rowDraggable: () => boolean;
+    rowDragTrigger: () => RsTableRowDragTrigger;
+    rowDropMode: () => RsTableRowDropMode;
+    rowDraggableWhen?: (row: T, index: number) => boolean;
+    rowDropTargetWhen?: (row: T, index: number) => boolean;
+    canRowDrop?: (dragKeys: string[], dropKey: string) => boolean;
+    rowKey: () => RsTableRowKey<T> | undefined;
+    rowKeyByIndex: () => Map<number, string>;
+    selectedRowKeys: {
+        get: () => string[];
+        set: (keys: string[]) => void;
+    };
+    selectedKeySet: () => Set<string>;
+    selectableRowKeys: () => string[];
+    selectAllState: () => 'checked' | 'indeterminate' | 'unchecked';
+    expandedRowKeys: {
+        get: () => string[];
+        set: (keys: string[]) => void;
+    };
+    expandedKeySet: () => Set<string>;
+    treeMode: () => boolean;
+    treeCheckStrictly: () => boolean;
+    treeLazy: () => boolean;
+    treeChildrenField: () => string;
+    treeIsLeafField: () => string;
+    treeLoadingKeys: {
+        get: () => string[];
+        set: (keys: string[]) => void;
+    };
+    treeLoadingKeySet: () => Set<string>;
+    tableTreeNodeIndex: () => Map<string, RsTableTreeNodeIndex> | null;
+    treeConfig: () => RsTableTreeConfig<T> | undefined;
+    expandable: () => boolean;
+    rowExpandable?: (row: T, index: number) => boolean;
+    sortState: {
+        get: () => RsTableSortState | null;
+        set: (value: RsTableSortState | null) => void;
+    };
+    sortsState: {
+        get: () => RsTableSortState[];
+        set: (value: RsTableSortState[]) => void;
+    };
+    columnOrderState: {
+        get: () => string[];
+        set: (value: string[]) => void;
+    };
+    /** 行选时若正在编辑则不改选中 */
+    isEditingAny: () => boolean;
+    applyRowClickHighlight: (rowKey: string) => void;
+    onRowClickEmit: (row: T, index: number) => void;
+    onRowDblclickEmit: (row: T, index: number) => void;
+    onRowDragStartEmit: (dragKeys: string[], event: DragEvent) => void;
+    onRowDropEmit: (dragKeys: string[], dropKey: string, position: RsTableRowDropPosition) => void;
+}
+/**
+ * 表格交互 API（排序 / 列拖 / 行选展开 / 行拖）。
+ */
+export declare function useRsTableInteraction<T extends RsTableRowData>(options: UseRsTableInteractionOptions<T>): {
+    dragColumnKey: Ref<string | null, string | null>;
+    dropColumnKey: Ref<string | null, string | null>;
+    selectionAnchorKey: Ref<string | null, string | null>;
+    dragRowKeys: Ref<string[], string[]>;
+    dropRowTargetKey: Ref<string | null, string | null>;
+    dropRowPosition: Ref<RsTableRowDropPosition, RsTableRowDropPosition>;
+    rowKeyFor: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => string;
+    sortOrderFor: (key: string) => RsTableSortOrder;
+    sortPriorityFor: (key: string) => number;
+    sortIconName: (key: string) => string;
+    onHeaderClick: (column: RsTableColumn<T>) => void;
+    onColumnDragStart: (key: string, event: DragEvent) => void;
+    onColumnDragOver: (key: string, event: DragEvent) => void;
+    onColumnDrop: (key: string, event: DragEvent) => void;
+    onColumnDragEnd: () => void;
+    canSelectRow: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+    isRowSelected: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+    isRowIndeterminate: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+    onToggleRow: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => void;
+    onToggleSelectAll: () => void;
+    canExpandRow: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+    isRowExpanded: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+    treeDepthOf: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => number;
+    onToggleExpand: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => Promise<void>;
+    onRowClick: (entry: RsTableRowEntry<T>, event?: MouseEvent) => void;
+    onRowSelectMouseDown: (event: MouseEvent) => void;
+    onRowDblclick: (entry: RsTableRowEntry<T>, _event?: MouseEvent) => void;
+    onRowDragStart: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>, event: DragEvent) => void;
+    onRowDragOver: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>, event: DragEvent) => void;
+    onRowDragLeave: (event: DragEvent) => void;
+    onRowDrop: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>, event: DragEvent) => void;
+    onRowDragEnd: () => void;
+    isRowDropTarget: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+    isRowDragging: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+    canDragRow: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+    isRowDragByRow: (entry: Extract<RsTableRowEntry<T>, {
+        type: "row";
+    }>) => boolean;
+};
+export type RsTableInteractionApi<T extends RsTableRowData> = ReturnType<typeof useRsTableInteraction<T>>;

package/dist/components/table/src/composables/useRsTableInteraction.js

@@ -0,0 +1,249 @@
+import { getSortOrderForKey, getSortPriorityForKey, getTableTreeChildren, hasTableTreeChildren, isTableRowDisabled, reorderColumnKeys, resolveRowKey, resolveTableTreeCheckState, selectRowKeys, selectRowKeysByClick, toggleExpandedRowKeys, toggleMultiSortState, toggleSelectAll, toggleSortState, toggleTableTreeCheck } from "../utils/table-utils.js";
+import { createTableRowDragHandlers, createTableRowDragState } from "../utils/table-drag.js";
+import { ref } from "vue";
+//#region src/components/table/src/composables/useRsTableInteraction.ts
+/**
+* RsTable 行/列交互：排序点击、列拖拽排序、行选/展开、行拖拽封装。
+*
+* 性能约定：
+* - 不引入对 data 的 deep watch
+* - rowKeyFor 走 Engine 的 rowKeyByIndex 缓存，避免热路径重复 resolve
+*/
+/**
+* 表格交互 API（排序 / 列拖 / 行选展开 / 行拖）。
+*/
+function useRsTableInteraction(options) {
+	const dragColumnKey = ref(null);
+	const dropColumnKey = ref(null);
+	const selectionAnchorKey = ref(null);
+	const rowDragState = createTableRowDragState();
+	const { dragRowKeys, dropRowTargetKey, dropRowPosition } = rowDragState;
+	function rowKeyFor(entry) {
+		return options.rowKeyByIndex().get(entry.rowIndex) ?? entry.treeKey ?? resolveRowKey(entry.row, entry.rowIndex, options.rowKey());
+	}
+	function sortOrderFor(key) {
+		if (options.multiSort()) return getSortOrderForKey(options.sortsState.get(), key);
+		const sort = options.sortState.get();
+		return sort?.key === key ? sort.order : null;
+	}
+	function sortPriorityFor(key) {
+		if (!options.multiSort()) return 0;
+		return getSortPriorityForKey(options.sortsState.get(), key);
+	}
+	function sortIconName(key) {
+		const order = sortOrderFor(key);
+		if (order === "asc") return "arrow-up";
+		if (order === "desc") return "arrow-down";
+		return "arrow-up-down";
+	}
+	function onHeaderClick(column) {
+		if (!column.sortable) return;
+		if (options.multiSort()) {
+			options.sortsState.set(toggleMultiSortState(options.sortsState.get(), column.key, options.maxSort()));
+			return;
+		}
+		options.sortState.set(toggleSortState(options.sortState.get(), column.key));
+	}
+	function onColumnDragStart(key, event) {
+		if (!options.columnDraggable()) return;
+		dragColumnKey.value = key;
+		dropColumnKey.value = null;
+		if (!event.dataTransfer) return;
+		event.dataTransfer.setData("text/plain", key);
+		event.dataTransfer.effectAllowed = "move";
+	}
+	function onColumnDragOver(key, event) {
+		if (!options.columnDraggable() || !dragColumnKey.value) return;
+		if (dragColumnKey.value === key) {
+			if (dropColumnKey.value !== null) dropColumnKey.value = null;
+			return;
+		}
+		event.preventDefault();
+		if (dropColumnKey.value !== key) dropColumnKey.value = key;
+	}
+	function onColumnDrop(key, event) {
+		if (!options.columnDraggable() || !dragColumnKey.value) return;
+		event.preventDefault();
+		if (dragColumnKey.value === key) return;
+		options.columnOrderState.set(reorderColumnKeys(options.columnOrderState.get(), dragColumnKey.value, key));
+		dragColumnKey.value = null;
+		dropColumnKey.value = null;
+	}
+	function onColumnDragEnd() {
+		dragColumnKey.value = null;
+		dropColumnKey.value = null;
+	}
+	const isRowSelection = () => options.selectable() && options.selectionType() === "row";
+	function canSelectRow(entry) {
+		if (isTableRowDisabled(entry.row)) return false;
+		return options.rowSelectable ? options.rowSelectable(entry.row, entry.rowIndex) : true;
+	}
+	function isRowSelected(entry) {
+		const key = rowKeyFor(entry);
+		const index = options.tableTreeNodeIndex();
+		if (index && !options.treeCheckStrictly()) return resolveTableTreeCheckState(key, options.selectedKeySet(), index, false) === "checked";
+		return options.selectedKeySet().has(key);
+	}
+	function isRowIndeterminate(entry) {
+		const index = options.tableTreeNodeIndex();
+		if (!index || options.treeCheckStrictly()) return false;
+		return resolveTableTreeCheckState(rowKeyFor(entry), options.selectedKeySet(), index, false) === "indeterminate";
+	}
+	function onToggleRow(entry) {
+		if (!canSelectRow(entry)) return;
+		const key = rowKeyFor(entry);
+		const index = options.tableTreeNodeIndex();
+		if (index && !options.treeCheckStrictly() && options.selectionType() !== "radio") {
+			options.selectedRowKeys.set(toggleTableTreeCheck(key, options.selectedKeySet(), index, false));
+			return;
+		}
+		options.selectedRowKeys.set(selectRowKeys(options.selectedRowKeys.get(), key, options.selectionType()));
+	}
+	function onToggleSelectAll() {
+		const select = options.selectAllState() !== "checked";
+		options.selectedRowKeys.set(toggleSelectAll(options.selectedRowKeys.get(), options.selectableRowKeys(), select));
+	}
+	function canExpandRow(entry) {
+		if (options.treeMode()) {
+			if (entry.hasChildren != null) return entry.hasChildren;
+			return hasTableTreeChildren(entry.row, {
+				childrenField: options.treeChildrenField(),
+				isLeafField: options.treeIsLeafField(),
+				lazy: options.treeLazy()
+			});
+		}
+		if (!options.expandable()) return false;
+		if (options.rowExpandable) return options.rowExpandable(entry.row, entry.rowIndex);
+		return true;
+	}
+	function isRowExpanded(entry) {
+		return options.expandedKeySet().has(rowKeyFor(entry));
+	}
+	function treeDepthOf(entry) {
+		return entry.depth ?? 0;
+	}
+	async function onToggleExpand(entry) {
+		if (!canExpandRow(entry)) return;
+		const key = rowKeyFor(entry);
+		const expanding = !options.expandedKeySet().has(key);
+		const tree = options.treeConfig();
+		if (options.treeMode() && expanding && options.treeLazy() && tree?.loadData && getTableTreeChildren(entry.row, options.treeChildrenField()).length === 0) {
+			if (options.treeLoadingKeySet().has(key)) return;
+			options.treeLoadingKeys.set([...options.treeLoadingKeys.get(), key]);
+			try {
+				const loaded = await tree.loadData(entry.row, key);
+				if (Array.isArray(loaded)) entry.row[options.treeChildrenField()] = loaded;
+			} finally {
+				options.treeLoadingKeys.set(options.treeLoadingKeys.get().filter((item) => item !== key));
+			}
+		}
+		options.expandedRowKeys.set(toggleExpandedRowKeys(options.expandedRowKeys.get(), key));
+	}
+	function onRowClick(entry, event) {
+		if (entry.type !== "row") return;
+		const rowKey = rowKeyFor(entry);
+		if (isRowSelection() && canSelectRow(entry) && !options.isEditingAny()) {
+			const toggle = Boolean(event && (event.ctrlKey || event.metaKey));
+			const range = Boolean(event?.shiftKey);
+			options.selectedRowKeys.set(selectRowKeysByClick(options.selectedRowKeys.get(), rowKey, {
+				toggle,
+				range,
+				orderedKeys: options.selectableRowKeys(),
+				anchorKey: selectionAnchorKey.value
+			}));
+			if (!range) selectionAnchorKey.value = rowKey;
+			if (typeof window !== "undefined") window.getSelection()?.removeAllRanges();
+		}
+		options.applyRowClickHighlight(rowKey);
+		options.onRowClickEmit(entry.row, entry.rowIndex);
+	}
+	function onRowSelectMouseDown(event) {
+		if (!isRowSelection()) return;
+		if (event.shiftKey || event.ctrlKey || event.metaKey) event.preventDefault();
+	}
+	function onRowDblclick(entry, _event) {
+		if (entry.type !== "row") return;
+		options.onRowDblclickEmit(entry.row, entry.rowIndex);
+	}
+	const rowDrag = createTableRowDragHandlers({
+		state: rowDragState,
+		getRowDraggable: () => options.rowDraggable(),
+		getRowDragTrigger: () => options.rowDragTrigger(),
+		getRowDropMode: () => options.rowDropMode(),
+		rowDraggableWhen: options.rowDraggableWhen,
+		rowDropTargetWhen: options.rowDropTargetWhen,
+		canRowDrop: options.canRowDrop,
+		rowKeyFor: (row, index) => resolveRowKey(row, index, options.rowKey()),
+		isRowDisabled: isTableRowDisabled,
+		getSelectedKeys: () => options.selectedRowKeys.get(),
+		onDragStart: (dragKeys, event) => options.onRowDragStartEmit(dragKeys, event),
+		onDrop: (dragKeys, dropKey, position) => options.onRowDropEmit(dragKeys, dropKey, position)
+	});
+	function onRowDragStart(entry, event) {
+		rowDrag.onRowDragStart(entry.row, entry.rowIndex, event);
+	}
+	function onRowDragOver(entry, event) {
+		rowDrag.onRowDragOver(entry.row, entry.rowIndex, event);
+	}
+	function onRowDragLeave(event) {
+		rowDrag.onRowDragLeave(event);
+	}
+	function onRowDrop(entry, event) {
+		rowDrag.onRowDrop(entry.row, entry.rowIndex, event);
+	}
+	function onRowDragEnd() {
+		rowDrag.onRowDragEnd();
+	}
+	function isRowDropTarget(entry) {
+		return rowDrag.isRowDropTarget(rowKeyFor(entry));
+	}
+	function isRowDragging(entry) {
+		return rowDrag.isRowDragging(rowKeyFor(entry));
+	}
+	function canDragRow(entry) {
+		return rowDrag.canDragRow(entry.row, entry.rowIndex);
+	}
+	function isRowDragByRow(entry) {
+		return options.rowDraggable() && options.rowDragTrigger() === "row" && canDragRow(entry);
+	}
+	return {
+		dragColumnKey,
+		dropColumnKey,
+		selectionAnchorKey,
+		dragRowKeys,
+		dropRowTargetKey,
+		dropRowPosition,
+		rowKeyFor,
+		sortOrderFor,
+		sortPriorityFor,
+		sortIconName,
+		onHeaderClick,
+		onColumnDragStart,
+		onColumnDragOver,
+		onColumnDrop,
+		onColumnDragEnd,
+		canSelectRow,
+		isRowSelected,
+		isRowIndeterminate,
+		onToggleRow,
+		onToggleSelectAll,
+		canExpandRow,
+		isRowExpanded,
+		treeDepthOf,
+		onToggleExpand,
+		onRowClick,
+		onRowSelectMouseDown,
+		onRowDblclick,
+		onRowDragStart,
+		onRowDragOver,
+		onRowDragLeave,
+		onRowDrop,
+		onRowDragEnd,
+		isRowDropTarget,
+		isRowDragging,
+		canDragRow,
+		isRowDragByRow
+	};
+}
+//#endregion
+export { useRsTableInteraction };

package/dist/components/table/src/composables/useRsTableScrollHost.js

@@ -0,0 +1,42 @@
+import { isNearScrollBottom } from "../utils/table-utils.js";
+import { onActivated, onDeactivated, onMounted, ref, watch } from "vue";
+//#region src/components/table/src/composables/useRsTableScrollHost.ts
+/**
+* RsTable 滚动宿主生命周期 + 无限加载触底。
+*/
+/**
+* 绑定滚动生命周期与无限加载。
+*/
+function useRsTableScrollHost(options) {
+	const loadMoreLocked = ref(false);
+	onMounted(() => {
+		options.scheduleVirtualLayoutSync();
+		options.bindScrollElement(options.scrollContainerRef.value);
+	});
+	onActivated(() => {
+		options.scheduleVirtualLayoutSync();
+	});
+	onDeactivated(() => {
+		options.captureScrollFromDom();
+	});
+	function onScroll(event) {
+		options.hideCellTooltip();
+		const element = event.target;
+		if (options.infinite() && !options.loading() && !options.loadingMore() && options.hasMore() && !loadMoreLocked.value) {
+			if (isNearScrollBottom(element.scrollTop, element.scrollHeight, element.clientHeight, options.infiniteDistance())) {
+				loadMoreLocked.value = true;
+				options.onLoadMore();
+			}
+		}
+		options.onScrollFrame(element);
+	}
+	watch(() => [options.loadingMore(), options.hasMore()], ([loadingMore, hasMore]) => {
+		if (!loadingMore || !hasMore) loadMoreLocked.value = false;
+	});
+	return {
+		onScroll,
+		loadMoreLocked
+	};
+}
+//#endregion
+export { useRsTableScrollHost };

package/dist/components/table/src/composables/useRsTableScrollLayout.js

@@ -0,0 +1,195 @@
+import { computed, nextTick, onUnmounted, ref, watch } from "vue";
+//#region src/components/table/src/composables/useRsTableScrollLayout.ts
+/**
+* RsTable 滚动与视口布局：测量、节流同步、keep-alive / layoutActive 恢复。
+*
+* 职责边界：
+* - 做：scrollTop/Left、视口宽高、写回 DOM、ResizeObserver、RAF 节流滚动
+* - 不做：虚拟切片本身、无限加载业务判定（由调用方在 onScroll 钩子中处理）
+*/
+/** 统一读取 ComputedRef / getter */
+function read(source) {
+	return typeof source === "function" ? source() : source.value;
+}
+/**
+* 表格滚动容器与视口状态。
+*
+* @returns 滚动状态、视口尺寸、恢复/重置 API、bindScrollElement / onScrollFrame
+*/
+function useRsTableScrollLayout(options) {
+	const scrollTop = ref(0);
+	const scrollLeft = ref(0);
+	const scrollContainerRef = ref(null);
+	const measuredViewportHeight = ref(0);
+	const measuredViewportWidth = ref(0);
+	let viewportResizeObserver = null;
+	let preservedScrollTop = 0;
+	let preservedScrollLeft = 0;
+	let restoringScroll = false;
+	let restoreGeneration = 0;
+	let scrollRafId = 0;
+	const fallback = options.fallbackViewportHeight ?? 320;
+	/** 虚拟切片用视口高度：显式 height > 测量值 > DOM > fallback */
+	const viewportHeight = computed(() => {
+		const h = read(options.height);
+		if (typeof h === "number" && h > 0) return h;
+		if (typeof h === "string") {
+			const parsed = Number.parseInt(h, 10);
+			if (Number.isFinite(parsed) && parsed > 0 && !h.includes("%")) return parsed;
+		}
+		if (measuredViewportHeight.value > 0) return measuredViewportHeight.value;
+		const el = scrollContainerRef.value;
+		if (el && el.clientHeight > 0) return el.clientHeight;
+		return fallback;
+	});
+	function syncMeasuredViewportSize() {
+		const el = scrollContainerRef.value;
+		if (!el) return;
+		const nextH = el.clientHeight;
+		if (nextH > 0 && nextH !== measuredViewportHeight.value) measuredViewportHeight.value = nextH;
+		const nextW = el.clientWidth;
+		if (nextW > 0 && nextW !== measuredViewportWidth.value) measuredViewportWidth.value = nextW;
+	}
+	/**
+	* 失活前快照滚动。
+	* DOM 脱离文档后 scrollTop 常为 0——切勿用 0 覆盖 onScroll 已写入的位置。
+	*/
+	function captureScrollFromDom() {
+		const el = scrollContainerRef.value;
+		if (el) {
+			if (el.scrollTop > 0) scrollTop.value = el.scrollTop;
+			if (el.scrollLeft > 0) scrollLeft.value = el.scrollLeft;
+		}
+		if (scrollTop.value > 0) preservedScrollTop = scrollTop.value;
+		if (scrollLeft.value > 0) preservedScrollLeft = scrollLeft.value;
+	}
+	/** 将内部保存的滚动写回 DOM，并同步 reactive（驱动虚拟切片）。 */
+	function restoreScrollToDom() {
+		const el = scrollContainerRef.value;
+		if (!el) return;
+		syncMeasuredViewportSize();
+		const top = preservedScrollTop;
+		const left = preservedScrollLeft;
+		if (scrollTop.value !== top) scrollTop.value = top;
+		if (scrollLeft.value !== left) scrollLeft.value = left;
+		if (el.scrollTop !== top) el.scrollTop = top;
+		if (el.scrollLeft !== left) el.scrollLeft = left;
+	}
+	/**
+	* 布局稳定后多次写回滚动：keep-alive 切回首帧 clientHeight 常为 0，
+	* 需等 nextTick / rAF / 视口测稳后再设 scrollTop，否则会被浏览器钳成 0。
+	*/
+	function scheduleVirtualLayoutSync() {
+		restoreGeneration += 1;
+		const gen = restoreGeneration;
+		restoringScroll = true;
+		const apply = () => {
+			if (gen !== restoreGeneration) return;
+			restoreScrollToDom();
+		};
+		apply();
+		nextTick(() => {
+			apply();
+			requestAnimationFrame(() => {
+				apply();
+				requestAnimationFrame(() => {
+					apply();
+					if (gen === restoreGeneration) restoringScroll = false;
+				});
+			});
+		});
+	}
+	function resetScrollPosition() {
+		preservedScrollTop = 0;
+		preservedScrollLeft = 0;
+		scrollTop.value = 0;
+		scrollLeft.value = 0;
+		const el = scrollContainerRef.value;
+		if (el) {
+			el.scrollTop = 0;
+			el.scrollLeft = 0;
+		}
+		scheduleVirtualLayoutSync();
+	}
+	function isRestoringScroll() {
+		return restoringScroll;
+	}
+	/**
+	* RAF 节流写入滚动位置；恢复窗口内忽略伪 scrollTop=0。
+	* @returns true 表示本帧已调度或处于恢复中（调用方仍可先做无限加载判断）
+	*/
+	function onScrollFrame(element) {
+		if (scrollRafId) return;
+		scrollRafId = requestAnimationFrame(() => {
+			if (restoringScroll) {
+				scrollRafId = 0;
+				return;
+			}
+			scrollTop.value = element.scrollTop;
+			scrollLeft.value = element.scrollLeft;
+			preservedScrollTop = element.scrollTop;
+			preservedScrollLeft = element.scrollLeft;
+			scrollRafId = 0;
+		});
+	}
+	/**
+	* 绑定滚动容器 ResizeObserver：视口从 0→实高时补一次恢复写回。
+	*/
+	function bindScrollElement(el) {
+		viewportResizeObserver?.disconnect();
+		viewportResizeObserver = null;
+		if (!el || typeof ResizeObserver === "undefined") return;
+		viewportResizeObserver = new ResizeObserver(() => {
+			const prevH = measuredViewportHeight.value;
+			syncMeasuredViewportSize();
+			if (prevH === 0 && measuredViewportHeight.value > 0 && (preservedScrollTop > 0 || preservedScrollLeft > 0)) {
+				restoringScroll = true;
+				restoreScrollToDom();
+				requestAnimationFrame(() => {
+					restoringScroll = false;
+				});
+			}
+		});
+		viewportResizeObserver.observe(el);
+	}
+	function disposeScrollLayout() {
+		viewportResizeObserver?.disconnect();
+		viewportResizeObserver = null;
+		if (scrollRafId) {
+			cancelAnimationFrame(scrollRafId);
+			scrollRafId = 0;
+		}
+	}
+	watch(() => read(options.layoutActive), (active, prev) => {
+		if (active === false && prev !== false) captureScrollFromDom();
+	}, { flush: "sync" });
+	watch(() => read(options.layoutActive), (active) => {
+		if (active) scheduleVirtualLayoutSync();
+	}, { flush: "post" });
+	watch(() => read(options.viewKey), (_next, prev) => {
+		if (prev === void 0) return;
+		resetScrollPosition();
+	});
+	onUnmounted(() => {
+		disposeScrollLayout();
+	});
+	return {
+		scrollTop,
+		scrollLeft,
+		scrollContainerRef,
+		measuredViewportHeight,
+		measuredViewportWidth,
+		viewportHeight,
+		syncMeasuredViewportSize,
+		captureScrollFromDom,
+		restoreScrollToDom,
+		scheduleVirtualLayoutSync,
+		resetScrollPosition,
+		isRestoringScroll,
+		onScrollFrame,
+		bindScrollElement,
+		disposeScrollLayout
+	};
+}
+//#endregion
+export { useRsTableScrollLayout };

package/dist/components/table/src/composables/useRsTableSelectionSource.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 表格分析/图表数据源：viewRows + selectedRows → 稳定 sourceRows。
+ *
+ * 约定（便于柱状图/饼图等后期扩展）：
+ * - 有选中行时 sourceMode='selected'，图表跟随勾选
+ * - 无选中时回退 viewRows（筛选/排序后的业务行）
+ * - subscribe 仅在浅层引用变化时通知，不做 deep watch
+ */
+import { type ComputedRef, type Ref } from 'vue';
+import type { RsTableRowData } from '../utils/table-utils';
+export type RsTableAnalyticsSourceMode = 'selected' | 'view';
+/** 分析快照：图表 / 指标卡 / 服务端请求共用 */
+export interface RsTableAnalyticsSnapshot<T extends RsTableRowData = RsTableRowData> {
+    viewRows: readonly T[];
+    selectedRows: readonly T[];
+    sourceRows: readonly T[];
+    sourceMode: RsTableAnalyticsSourceMode;
+    selectedCount: number;
+    viewCount: number;
+}
+export interface UseRsTableSelectionSourceOptions<T extends RsTableRowData> {
+    viewRows: Ref<T[]> | ComputedRef<T[]>;
+    selectedRows?: Ref<T[]> | ComputedRef<T[]>;
+}
+/**
+ * 选中优先的分析数据源。
+ *
+ * @returns sourceRows / sourceMode / getSnapshot / subscribe
+ */
+export declare function useRsTableSelectionSource<T extends RsTableRowData>(options: UseRsTableSelectionSourceOptions<T>): {
+    viewRows: ComputedRef<T[]>;
+    selectedRows: ComputedRef<T[]>;
+    sourceRows: ComputedRef<T[]>;
+    sourceMode: ComputedRef<RsTableAnalyticsSourceMode>;
+    getSnapshot: () => RsTableAnalyticsSnapshot<T>;
+    subscribe: (listener: (snap: RsTableAnalyticsSnapshot<T>) => void) => () => void;
+};
+export type RsTableSelectionSourceApi<T extends RsTableRowData> = ReturnType<typeof useRsTableSelectionSource<T>>;