stk-table-vue 1.0.4 → 1.1.0

package/lib/{Dropdown-D7PIq_F7.js → Dropdown-DknXtT1A.js}

@@ -1,12 +1,12 @@
 /**
  * name: stk-table-vue
- * version: v1.0.4
+ * version: v1.1.0
  * description: High performance realtime virtual table for vue3 and vue2.7
  * author: japlus
  * homepage: https://ja-plus.github.io/stk-table-vue/
  * license: MIT
  */
-import { t as StkTable_default } from "./StkTable-DuT_ezDm.js";
+import { t as StkTable_default } from "./StkTable-6OMgH-gT.js";
 import { createElementBlock, createElementVNode, createVNode, defineComponent, h, nextTick, normalizeClass, normalizeStyle, onMounted, onUnmounted, openBlock, reactive, ref, withModifiers } from "vue";
 //#region src/StkTable/custom-cells/FilterCell/Dropdown/index.vue?vue&type=script&setup=true&lang.ts
 var DROPDOWN_DEFAULT_WIDTH = 300;

package/lib/{StkTable-DuT_ezDm.js → StkTable-6OMgH-gT.js}

@@ -1,6 +1,6 @@
 /**
  * name: stk-table-vue
- * version: v1.0.4
+ * version: v1.1.0
  * description: High performance realtime virtual table for vue3 and vue2.7
  * author: japlus
  * homepage: https://ja-plus.github.io/stk-table-vue/
@@ -2931,6 +2931,7 @@ function useTree(props, dataSourceCopy, rowKeyGen, emits, onDataSourceChange) {
 	* @param option.expand expand or collapse
 	* @param option.all expand all descendants
 	* @param option.level expand to the nth level
+	* @param option.parents expand/collapse all ancestors of the given row, the target row itself is also expanded if it has children
 	* @param option.silent if set true, not emit `toggle-tree-expand`, default:false
 	*/
 	function privateSetTreeExpand(row, option) {
@@ -2978,11 +2979,55 @@ function useTree(props, dataSourceCopy, rowKeyGen, emits, onDataSourceChange) {
 		onDataSourceChange();
 	}
 	function setTreeExpand(row, option) {
+		if (option === null || option === void 0 ? void 0 : option.parents) {
+			var _target$children;
+			const rowKeyOrRow = Array.isArray(row) ? row[0] : row;
+			const rowKey = typeof rowKeyOrRow === "string" || typeof rowKeyOrRow === "number" ? rowKeyOrRow : rowKeyGen(rowKeyOrRow);
+			const path = findPath(props.dataSource || [], rowKey);
+			if (!path) {
+				console.warn("treeExpandRow failed.rowKey:", rowKey);
+				return;
+			}
+			const expanded = (option === null || option === void 0 ? void 0 : option.expand) !== false;
+			const target = path[path.length - 1];
+			const keys = path.slice(0, -1).map((it) => rowKeyGen(it));
+			if (expanded && ((_target$children = target.children) === null || _target$children === void 0 ? void 0 : _target$children.length)) keys.push(rowKeyGen(target));
+			if (!keys.length) return;
+			if (!expanded) keys.reverse();
+			privateSetTreeExpand(keys, {
+				expand: expanded,
+				isClick: false
+			});
+			return;
+		}
 		privateSetTreeExpand(row, {
 			...option,
 			isClick: false
 		});
 	}
+	/**
+	* 在原始树形数据中查找目标节点，返回从根节点到目标节点的完整路径（含目标节点自身）
+	* en: Find target node in raw tree data, return the full path from root to target node (target included)
+	* @returns full path including target, or null if target not found
+	*/
+	function findPath(data, targetKey) {
+		const path = [];
+		function dfs(list) {
+			for (const item of list) {
+				if (rowKeyGen(item) === targetKey) {
+					path.push(item);
+					return true;
+				}
+				if (item.children) {
+					path.push(item);
+					if (dfs(item.children)) return true;
+					path.pop();
+				}
+			}
+			return false;
+		}
+		return dfs(data) ? path : null;
+	}
 	function setNodeExpanded(row, expanded, level, parent) {
 		row.__T_EXP__ = expanded;
 		if (level !== void 0) row.__T_LV__ = level;
@@ -3104,6 +3149,12 @@ function useColWidthCache(getColWidth) {
 /** vue2 优化滚动回收延时 */
 var VUE2_SCROLL_TIMEOUT_MS = 200;
 /**
+* 合并单元格可视范围修正的最大迭代次数。
+* 合法（不重叠）的合并配置最多 2 轮即收敛（1 轮扩展 + 1 轮验证）；
+* 此上限仅针对重叠合并区域等病态配置兜底，防止修正循环过长。
+*/
+var MAX_MERGE_RANGE_EXPAND_ITERATIONS = 8;
+/**
 * virtual scroll
 * @returns
 */
@@ -3162,20 +3213,145 @@ function useVirtualScroll(props, tableContainerRef, trRef, dataSourceCopy, table
 	/** 是否多级表头 */
 	const isMultiLevelHeader = computed(() => tableHeaders.value.length > 1);
 	/**
+	* 需要参与可视范围修正的合并列集合。仅依赖 tableHeaderLast（columns 变化），
+	* 缓存后避免在数据更新、纵向滚动换窗等高频调用 buildColMergeRange 时重复收集。
+	* 无需修正时返回 null。
+	*/
+	const virtualX_mergeColsInfo = computed(() => {
+		const headers = tableHeaderLast.value;
+		const headerLength = headers.length;
+		let maxColIndex = headerLength;
+		const mergeCols = [];
+		for (let i = 0; i < headerLength; i++) {
+			const col = headers[i];
+			if (maxColIndex === headerLength && col.fixed === "right") maxColIndex = i;
+			if (col.mergeCells && !col.fixed) mergeCols.push({
+				col,
+				index: i
+			});
+		}
+		if (!mergeCols.length || !maxColIndex) return null;
+		return {
+			headerLength,
+			maxColIndex,
+			mergeCols
+		};
+	});
+	/**
+	* 收集行集合中的列合并（colspan）区间
+	* @param rows 行数据
+	* @param rowIndexBase mergeCells 入参 rowIndex 的起始值
+	*/
+	function buildColMergeRange(rows, rowIndexBase) {
+		const mergeColsInfo = virtualX_mergeColsInfo.value;
+		if (!mergeColsInfo) return null;
+		const { headerLength, maxColIndex, mergeCols } = mergeColsInfo;
+		const leftReach = new Int32Array(headerLength).fill(-1);
+		const rightEnd = new Int32Array(headerLength);
+		for (let r = 0; r < rows.length; r++) {
+			const row = rows[r];
+			for (let m = 0; m < mergeCols.length; m++) {
+				const { col, index } = mergeCols[m];
+				if (index >= maxColIndex) break;
+				const { colspan = 1 } = col.mergeCells({
+					row,
+					col,
+					rowIndex: rowIndexBase + r,
+					colIndex: index
+				}) || {};
+				if (colspan > 1) {
+					const end = Math.min(index + colspan, maxColIndex);
+					for (let c = index; c < end; c++) {
+						if (leftReach[c] === -1 || index < leftReach[c]) leftReach[c] = index;
+						if (end > rightEnd[c]) rightEnd[c] = end;
+					}
+				}
+			}
+		}
+		return {
+			leftReach,
+			rightEnd
+		};
+	}
+	/**
+	* 全量数据的列合并覆盖信息（懒计算）。
+	* 仅在 Y 虚拟滚动未开启（可视行即全量数据）且被消费时才遍历全量数据；
+	* 依赖 dataSourceCopy 与 columns，数据/列变化时自动重算。
+	* virtual + virtualX 模式下消费方走可视行分支，本 computed 直接返回 null，
+	* 避免 O(rows × mergeCols) 的全量 mergeCells 调用浪费。
+	*/
+	const virtualX_colMergeRangeFull = computed(() => {
+		if (!virtualX_on.value || virtual_on.value) return null;
+		return buildColMergeRange(dataSourceCopy.value, 0);
+	});
+	/**
+	* virtual-x 列合并覆盖信息。
+	* Y 虚拟滚动开启时仅计算可视行（rowIndex 与渲染时 mergeCells 入参保持一致）；
+	* 否则使用全量数据懒计算缓存（此时可视行即全量数据）。
+	*/
+	const virtualX_colMergeRange = computed(() => {
+		if (!virtualX_on.value) return null;
+		if (virtual_on.value) return buildColMergeRange(virtual_dataSourcePart.value, 0);
+		return virtualX_colMergeRangeFull.value;
+	});
+	/**
+	* 经列合并修正后的可视列范围。
+	* 合并单元格的锚点列可能已滚出可视区（但合并区域仍覆盖可视列），
+	* 也可能合并区域超出可视区右边界，需要将范围扩展到能完整渲染合并单元格。
+	*/
+	const virtualX_colRange = computed(() => {
+		let { startIndex, endIndex } = virtualScrollX.value;
+		const mergeRange = virtualX_colMergeRange.value;
+		if (mergeRange) {
+			const { leftReach, rightEnd } = mergeRange;
+			const len = leftReach.length;
+			for (let k = 0; k < MAX_MERGE_RANGE_EXPAND_ITERATIONS; k++) {
+				let newStart = startIndex;
+				let newEnd = endIndex;
+				const loopEnd = Math.min(endIndex, len);
+				for (let i = Math.max(0, startIndex); i < loopEnd; i++) {
+					const reach = leftReach[i];
+					if (reach > -1 && reach < newStart) newStart = reach;
+					if (rightEnd[i] > newEnd) newEnd = rightEnd[i];
+				}
+				if (newStart === startIndex && newEnd === endIndex) break;
+				startIndex = newStart;
+				endIndex = newEnd;
+			}
+		}
+		return {
+			startIndex,
+			endIndex
+		};
+	});
+	/**
 	* 多级表头横向虚拟滚动参数：以顶层列组为单位计算开始/结束位置。
 	* - 只有整个顶层组完全滚出视口时才移除（避免 colSpan 变化导致抖动）。
 	* - 单级表头时退化为与 tbody 相同的参数。
+	* - 范围基于列合并修正后的 virtualX_colRange，保证合并单元格完整渲染。
 	*/
 	const theadVirtualX = computed(() => {
-		if (!virtualX_on.value || !isMultiLevelHeader.value) return {
-			startIndex: virtualScrollX.value.startIndex,
-			endIndex: virtualScrollX.value.endIndex,
-			offsetLeft: virtualScrollX.value.offsetLeft
-		};
-		const { scrollLeft, containerWidth } = virtualScrollX.value;
+		if (!virtualX_on.value) {
+			const { startIndex, endIndex, offsetLeft } = virtualScrollX.value;
+			return {
+				startIndex,
+				endIndex,
+				offsetLeft
+			};
+		}
+		const { startIndex, endIndex } = virtualX_colRange.value;
+		if (!isMultiLevelHeader.value) {
+			const { nonFixedCols } = getColWidthCache(tableHeaderLast.value);
+			const found = binarySearch(nonFixedCols, (mid) => nonFixedCols[mid].index < startIndex ? -1 : 1);
+			return {
+				startIndex,
+				endIndex,
+				offsetLeft: found > 0 ? nonFixedCols[found - 1].cumWidth : 0
+			};
+		}
 		const topLevelCols = tableHeaders.value[0];
 		const totalLeafCount = tableHeaderLast.value.length;
-		let theadStartIndex = 0;
+		let theadStartIndex = totalLeafCount;
 		let theadEndIndex = totalLeafCount;
 		let theadOffsetLeft = 0;
 		let cumLeft = 0;
@@ -3183,21 +3359,21 @@ function useVirtualScroll(props, tableContainerRef, trRef, dataSourceCopy, table
 		for (let i = 0, len = topLevelCols.length; i < len; i++) {
 			const col = topLevelCols[i];
 			if (col.fixed === "left" || col.fixed === "right") continue;
+			const groupStart = col.__LF_S__ ?? 0;
+			const groupEnd = col.__LF_E__ ?? groupStart + 1;
 			const groupWidth = col.__W__ || getCalculatedColWidth(col);
-			const groupRight = cumLeft + groupWidth;
-			if (!foundStart && groupRight > scrollLeft) {
+			if (!foundStart && groupEnd > startIndex) {
 				foundStart = true;
-				theadStartIndex = col.__LF_S__ ?? 0;
+				theadStartIndex = groupStart;
 				theadOffsetLeft = cumLeft;
 			}
-			cumLeft = groupRight;
-			theadEndIndex = col.__LF_E__ ?? totalLeafCount;
-			if (foundStart && groupRight >= scrollLeft + containerWidth) break;
-		}
-		if (!foundStart) {
-			theadStartIndex = totalLeafCount;
-			theadOffsetLeft = cumLeft;
+			if (foundStart) {
+				if (groupStart >= endIndex) break;
+				theadEndIndex = groupEnd;
+			}
+			cumLeft += groupWidth;
 		}
+		if (!foundStart) theadOffsetLeft = cumLeft;
 		return {
 			startIndex: theadStartIndex,
 			endIndex: theadEndIndex,
@@ -3207,7 +3383,7 @@ function useVirtualScroll(props, tableContainerRef, trRef, dataSourceCopy, table
 	const virtualX_columnPart = computed(() => {
 		const tableHeaderLastValue = tableHeaderLast.value;
 		if (virtualX_on.value) {
-			const { startIndex, endIndex } = virtualScrollX.value;
+			const { startIndex, endIndex } = virtualX_colRange.value;
 			const maxIndex = tableHeaderLastValue.length;
 			const validEndIndex = Math.min(endIndex, maxIndex);
 			const validStartIndex = Math.min(startIndex, maxIndex);
@@ -3275,7 +3451,7 @@ function useVirtualScroll(props, tableContainerRef, trRef, dataSourceCopy, table
 	});
 	const virtualX_offsetRight = computed(() => {
 		if (!virtualX_on.value) return 0;
-		const endIndex = isMultiLevelHeader.value ? theadVirtualX.value.endIndex : virtualScrollX.value.endIndex;
+		const endIndex = isMultiLevelHeader.value ? theadVirtualX.value.endIndex : virtualX_colRange.value.endIndex;
 		let width = 0;
 		const tableHeaderLastValue = tableHeaderLast.value;
 		for (let i = endIndex; i < tableHeaderLastValue.length; i++) {

package/lib/src/StkTable/StkTable.vue.d.ts

@@ -383,6 +383,7 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
         expand?: boolean;
         all?: boolean;
         level?: number;
+        parents?: boolean;
     }) => void;
     /**
      * 获取拖选选中的单元格信息

package/lib/src/StkTable/useTree.d.ts

@@ -24,6 +24,12 @@ type SetTreeExpandOption = {
      * @version 1.0.4
      */
     level?: number;
+    /**
+     * 将传入 row 视为目标子节点，展开/收起其所有父节点；展开时若目标行自身有子节点则一并展开
+     * en: Treat the given row as a target child, expand/collapse all its ancestors. The target row itself is also expanded when expanding if it has children
+     * @version 1.1.0
+     */
+    parents?: boolean;
 };
 export declare function useTree(props: any, dataSourceCopy: ShallowRef<DT[]>, rowKeyGen: RowKeyGen, emits: any, onDataSourceChange: () => void): readonly [(row: DT, col: any) => void, (row: (UniqKey | DT) | (UniqKey | DT)[], option?: SetTreeExpandOption) => void, (data: DT[]) => DT[]];
 export {};

package/lib/stk-table-vue.js

@@ -1,12 +1,12 @@
 /**
  * name: stk-table-vue
- * version: v1.0.4
+ * version: v1.1.0
  * description: High performance realtime virtual table for vue3 and vue2.7
  * author: japlus
  * homepage: https://ja-plus.github.io/stk-table-vue/
  * license: MIT
  */
-import { a as insertToOrderedArray, i as binarySearch, n as registerFeature, o as strCompare, r as useAreaSelection, s as tableSort, t as StkTable_default } from "./StkTable-DuT_ezDm.js";
+import { a as insertToOrderedArray, i as binarySearch, n as registerFeature, o as strCompare, r as useAreaSelection, s as tableSort, t as StkTable_default } from "./StkTable-6OMgH-gT.js";
 import { Fragment, computed, createApp, createBlock, createElementBlock, createElementVNode, createTextVNode, defineComponent, getCurrentInstance, h, markRaw, nextTick, normalizeClass, openBlock, ref, renderSlot, resolveDynamicComponent, toDisplayString, watch, withModifiers } from "vue";
 //#region src/StkTable/custom-cells/FilterCell/Dropdown/index.ts
 var DropdownIns = null;
@@ -15,7 +15,7 @@ async function getDropdownIns() {
 		const div = document.createElement("div");
 		div.classList.add("stk-filter-dropdown-wrapper");
 		document.body.appendChild(div);
-		DropdownIns = createApp(await import("./Dropdown-D7PIq_F7.js").then((module) => module.default)).mount(div);
+		DropdownIns = createApp(await import("./Dropdown-DknXtT1A.js").then((module) => module.default)).mount(div);
 	}
 	return DropdownIns;
 }

package/lib/style.css

@@ -1,6 +1,6 @@
 /**
  * name: stk-table-vue
- * version: v1.0.4
+ * version: v1.1.0
  * description: High performance realtime virtual table for vue3 and vue2.7
  * author: japlus
  * homepage: https://ja-plus.github.io/stk-table-vue/

package/lib/test/setTreeExpandParents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/test/virtualXMerge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stk-table-vue",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "High performance realtime virtual table for vue3 and vue2.7",
   "main": "./lib/stk-table-vue.js",
   "types": "./lib/src/StkTable/index.d.ts",

package/src/StkTable/useTree.ts

@@ -23,6 +23,12 @@ type SetTreeExpandOption = {
      * @version 1.0.4
      */
     level?: number;
+    /**
+     * 将传入 row 视为目标子节点，展开/收起其所有父节点；展开时若目标行自身有子节点则一并展开
+     * en: Treat the given row as a target child, expand/collapse all its ancestors. The target row itself is also expanded when expanding if it has children
+     * @version 1.1.0
+     */
+    parents?: boolean;
 };
 
 export function useTree(props: any, dataSourceCopy: ShallowRef<DT[]>, rowKeyGen: RowKeyGen, emits: any, onDataSourceChange: () => void) {
@@ -42,6 +48,7 @@ export function useTree(props: any, dataSourceCopy: ShallowRef<DT[]>, rowKeyGen:
      * @param option.expand expand or collapse
      * @param option.all expand all descendants
      * @param option.level expand to the nth level
+     * @param option.parents expand/collapse all ancestors of the given row, the target row itself is also expanded if it has children
      * @param option.silent if set true, not emit `toggle-tree-expand`, default:false
      */
     function privateSetTreeExpand(row: (UniqKey | DT) | (UniqKey | DT)[], option: SetTreeExpandOption & { col?: any; isClick: boolean }) {
@@ -102,9 +109,54 @@ export function useTree(props: any, dataSourceCopy: ShallowRef<DT[]>, rowKeyGen:
     }
 
     function setTreeExpand(row: (UniqKey | DT) | (UniqKey | DT)[], option?: SetTreeExpandOption) {
+        if (option?.parents) {
+            const rowKeyOrRow = Array.isArray(row) ? row[0] : row;
+            const rowKey = typeof rowKeyOrRow === 'string' || typeof rowKeyOrRow === 'number' ? rowKeyOrRow : rowKeyGen(rowKeyOrRow);
+            const path = findPath(props.dataSource || [], rowKey);
+            if (!path) {
+                console.warn('treeExpandRow failed.rowKey:', rowKey);
+                return;
+            }
+            const expanded = option?.expand !== false;
+            const target = path[path.length - 1];
+            const keys = path.slice(0, -1).map(it => rowKeyGen(it));
+            // 展开时若目标行自身有子节点则一并展开；收起时仅处理父节点，目标行自身状态不变
+            // en: when expanding, also expand the target row itself if it has children; when collapsing, only ancestors are handled
+            if (expanded && target.children?.length) keys.push(rowKeyGen(target));
+            if (!keys.length) return;
+            // 展开时从根到目标逐级展开；收起时逆序处理，避免先折叠根节点导致其余节点从可见数据中移除而查找失败
+            // en: expand from root to target; collapse in reverse order, otherwise collapsing the root first removes the rest nodes from visible data
+            if (!expanded) keys.reverse();
+            privateSetTreeExpand(keys, { expand: expanded, isClick: false });
+            return;
+        }
         privateSetTreeExpand(row, { ...option, isClick: false });
     }
 
+    /**
+     * 在原始树形数据中查找目标节点，返回从根节点到目标节点的完整路径（含目标节点自身）
+     * en: Find target node in raw tree data, return the full path from root to target node (target included)
+     * @returns full path including target, or null if target not found
+     */
+    function findPath(data: DT[], targetKey: UniqKey): DT[] | null {
+        const path: DT[] = [];
+        function dfs(list: DT[]): boolean {
+            for (const item of list) {
+                if (rowKeyGen(item) === targetKey) {
+                    path.push(item);
+                    return true;
+                }
+                if (item.children) {
+                    path.push(item);
+                    if (dfs(item.children)) return true;
+                    path.pop();
+                }
+            }
+            return false;
+        }
+        return dfs(data) ? path : null;
+    }
+
     function setNodeExpanded(row: DT, expanded: boolean, level?: number, parent?: DT) {
         row.__T_EXP__ = expanded;
         if (level !== void 0) {

package/src/StkTable/useVirtualScroll.ts

@@ -85,6 +85,13 @@ function useColWidthCache<T extends { fixed?: StkTableColumn<PrivateRowDT>['fixe
 /** vue2 优化滚动回收延时 */
 const VUE2_SCROLL_TIMEOUT_MS = 200;
 
+/**
+ * 合并单元格可视范围修正的最大迭代次数。
+ * 合法（不重叠）的合并配置最多 2 轮即收敛（1 轮扩展 + 1 轮验证）；
+ * 此上限仅针对重叠合并区域等病态配置兜底，防止修正循环过长。
+ */
+const MAX_MERGE_RANGE_EXPAND_ITERATIONS = 8;
+
 /**
  * virtual scroll
  * @returns
@@ -170,24 +177,138 @@ export function useVirtualScroll(
     /** 是否多级表头 */
     const isMultiLevelHeader = computed(() => tableHeaders.value.length > 1);
 
+    /**
+     * 需要参与可视范围修正的合并列集合。仅依赖 tableHeaderLast（columns 变化），
+     * 缓存后避免在数据更新、纵向滚动换窗等高频调用 buildColMergeRange 时重复收集。
+     * 无需修正时返回 null。
+     */
+    const virtualX_mergeColsInfo = computed(() => {
+        const headers = tableHeaderLast.value;
+        const headerLength = headers.length;
+        // 右固定列始终渲染在可视区末尾，不参与主可视区合并修正
+        let maxColIndex = headerLength;
+        const mergeCols: { col: PrivateStkTableColumn<PrivateRowDT>; index: number }[] = [];
+        for (let i = 0; i < headerLength; i++) {
+            const col = headers[i];
+            if (maxColIndex === headerLength && col.fixed === 'right') maxColIndex = i;
+            // 固定列始终渲染，不需要修正可视范围
+            if (col.mergeCells && !col.fixed) mergeCols.push({ col, index: i });
+        }
+        if (!mergeCols.length || !maxColIndex) return null;
+        return { headerLength, maxColIndex, mergeCols };
+    });
+
+    /**
+     * 收集行集合中的列合并（colspan）区间
+     * @param rows 行数据
+     * @param rowIndexBase mergeCells 入参 rowIndex 的起始值
+     */
+    function buildColMergeRange(rows: PrivateRowDT[], rowIndexBase: number) {
+        const mergeColsInfo = virtualX_mergeColsInfo.value;
+        if (!mergeColsInfo) return null;
+        const { headerLength, maxColIndex, mergeCols } = mergeColsInfo;
+
+        const leftReach = new Int32Array(headerLength).fill(-1);
+        const rightEnd = new Int32Array(headerLength);
+        for (let r = 0; r < rows.length; r++) {
+            const row = rows[r];
+            for (let m = 0; m < mergeCols.length; m++) {
+                const { col, index } = mergeCols[m];
+                if (index >= maxColIndex) break;
+                const { colspan = 1 } = col.mergeCells!({ row, col, rowIndex: rowIndexBase + r, colIndex: index }) || {};
+                if (colspan > 1) {
+                    const end = Math.min(index + colspan, maxColIndex);
+                    for (let c = index; c < end; c++) {
+                        if (leftReach[c] === -1 || index < leftReach[c]) leftReach[c] = index;
+                        if (end > rightEnd[c]) rightEnd[c] = end;
+                    }
+                }
+            }
+        }
+        return { leftReach, rightEnd };
+    }
+
+    /**
+     * 全量数据的列合并覆盖信息（懒计算）。
+     * 仅在 Y 虚拟滚动未开启（可视行即全量数据）且被消费时才遍历全量数据；
+     * 依赖 dataSourceCopy 与 columns，数据/列变化时自动重算。
+     * virtual + virtualX 模式下消费方走可视行分支，本 computed 直接返回 null，
+     * 避免 O(rows × mergeCols) 的全量 mergeCells 调用浪费。
+     */
+    const virtualX_colMergeRangeFull = computed(() => {
+        if (!virtualX_on.value || virtual_on.value) return null;
+        return buildColMergeRange(dataSourceCopy.value, 0);
+    });
+
+    /**
+     * virtual-x 列合并覆盖信息。
+     * Y 虚拟滚动开启时仅计算可视行（rowIndex 与渲染时 mergeCells 入参保持一致）；
+     * 否则使用全量数据懒计算缓存（此时可视行即全量数据）。
+     */
+    const virtualX_colMergeRange = computed(() => {
+        if (!virtualX_on.value) return null;
+        if (virtual_on.value) {
+            return buildColMergeRange(virtual_dataSourcePart.value, 0);
+        }
+        return virtualX_colMergeRangeFull.value;
+    });
+
+    /**
+     * 经列合并修正后的可视列范围。
+     * 合并单元格的锚点列可能已滚出可视区（但合并区域仍覆盖可视列），
+     * 也可能合并区域超出可视区右边界，需要将范围扩展到能完整渲染合并单元格。
+     */
+    const virtualX_colRange = computed(() => {
+        let { startIndex, endIndex } = virtualScrollX.value;
+        const mergeRange = virtualX_colMergeRange.value;
+        if (mergeRange) {
+            const { leftReach, rightEnd } = mergeRange;
+            const len = leftReach.length;
+            // 扩展后的范围可能引入新的合并单元格，迭代直到稳定（合法配置最多 2 轮，上限兜底病态配置）
+            for (let k = 0; k < MAX_MERGE_RANGE_EXPAND_ITERATIONS; k++) {
+                let newStart = startIndex;
+                let newEnd = endIndex;
+                const loopEnd = Math.min(endIndex, len);
+                for (let i = Math.max(0, startIndex); i < loopEnd; i++) {
+                    const reach = leftReach[i];
+                    if (reach > -1 && reach < newStart) newStart = reach;
+                    if (rightEnd[i] > newEnd) newEnd = rightEnd[i];
+                }
+                if (newStart === startIndex && newEnd === endIndex) break;
+                startIndex = newStart;
+                endIndex = newEnd;
+            }
+        }
+        return { startIndex, endIndex };
+    });
+
     /**
      * 多级表头横向虚拟滚动参数：以顶层列组为单位计算开始/结束位置。
      * - 只有整个顶层组完全滚出视口时才移除（避免 colSpan 变化导致抖动）。
      * - 单级表头时退化为与 tbody 相同的参数。
+     * - 范围基于列合并修正后的 virtualX_colRange，保证合并单元格完整渲染。
      */
     const theadVirtualX = computed(() => {
-        if (!virtualX_on.value || !isMultiLevelHeader.value) {
-            return {
-                startIndex: virtualScrollX.value.startIndex,
-                endIndex: virtualScrollX.value.endIndex,
-                offsetLeft: virtualScrollX.value.offsetLeft,
-            };
+        if (!virtualX_on.value) {
+            const { startIndex, endIndex, offsetLeft } = virtualScrollX.value;
+            return { startIndex, endIndex, offsetLeft };
         }
-        const { scrollLeft, containerWidth } = virtualScrollX.value;
+
+        const { startIndex, endIndex } = virtualX_colRange.value;
+
+        if (!isMultiLevelHeader.value) {
+            // 单级表头：offsetLeft 为起始列之前所有非固定列宽度之和
+            const { nonFixedCols } = getColWidthCache(tableHeaderLast.value);
+            const found = binarySearch(nonFixedCols, mid => (nonFixedCols[mid].index < startIndex ? -1 : 1));
+            const offsetLeft = found > 0 ? nonFixedCols[found - 1].cumWidth : 0;
+            return { startIndex, endIndex, offsetLeft };
+        }
+
+        // 多级表头：保留与修正后可视范围有交集的顶层列组
         const topLevelCols = tableHeaders.value[0];
         const totalLeafCount = tableHeaderLast.value.length;
 
-        let theadStartIndex = 0;
+        let theadStartIndex = totalLeafCount;
         let theadEndIndex = totalLeafCount;
         let theadOffsetLeft = 0;
         let cumLeft = 0;
@@ -197,25 +318,23 @@ export function useVirtualScroll(
             const col = topLevelCols[i];
             if (col.fixed === 'left' || col.fixed === 'right') continue;
 
+            const groupStart = col.__LF_S__ ?? 0;
+            const groupEnd = col.__LF_E__ ?? groupStart + 1;
             const groupWidth = col.__W__ || getCalculatedColWidth(col);
-            const groupRight = cumLeft + groupWidth;
 
-            if (!foundStart && groupRight > scrollLeft) {
+            if (!foundStart && groupEnd > startIndex) {
                 foundStart = true;
-                theadStartIndex = col.__LF_S__ ?? 0;
+                theadStartIndex = groupStart;
                 theadOffsetLeft = cumLeft;
             }
-            cumLeft = groupRight;
-
-            theadEndIndex = col.__LF_E__ ?? totalLeafCount;
-            if (foundStart && groupRight >= scrollLeft + containerWidth) {
-                // find end
-                break;
+            if (foundStart) {
+                if (groupStart >= endIndex) break;
+                theadEndIndex = groupEnd;
             }
+            cumLeft += groupWidth;
         }
 
         if (!foundStart) {
-            theadStartIndex = totalLeafCount;
             theadOffsetLeft = cumLeft;
         }
 
@@ -225,7 +344,8 @@ export function useVirtualScroll(
     const virtualX_columnPart = computed(() => {
         const tableHeaderLastValue = tableHeaderLast.value;
         if (virtualX_on.value) {
-            const { startIndex, endIndex } = virtualScrollX.value;
+            // 使用列合并修正后的可视范围
+            const { startIndex, endIndex } = virtualX_colRange.value;
             // 将索引钳制到列数组范围内，防止列数减少时越界
             const maxIndex = tableHeaderLastValue.length;
             const validEndIndex = Math.min(endIndex, maxIndex);
@@ -324,8 +444,8 @@ export function useVirtualScroll(
 
     const virtualX_offsetRight = computed(() => {
         if (!virtualX_on.value) return 0;
-        // 多级表头使用 theadEndIndex，单级使用 body endIndex
-        const endIndex = isMultiLevelHeader.value ? theadVirtualX.value.endIndex : virtualScrollX.value.endIndex;
+        // 多级表头使用 theadEndIndex，单级使用列合并修正后的 endIndex
+        const endIndex = isMultiLevelHeader.value ? theadVirtualX.value.endIndex : virtualX_colRange.value.endIndex;
         let width = 0;
         const tableHeaderLastValue = tableHeaderLast.value;
         for (let i = endIndex; i < tableHeaderLastValue.length; i++) {