stk-table-vue 1.2.3 → 1.2.5

package/lib/{Dropdown-B2dzC5D3.js → Dropdown-C4c7Nmgf.js}

@@ -1,12 +1,12 @@
 /**
  * name: stk-table-vue
- * version: v1.2.3
+ * version: v1.2.5
  * 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-DFh1B-f9.js";
+import { t as StkTable_default } from "./StkTable-CzktjLlV.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-DFh1B-f9.js → StkTable-CzktjLlV.js}

@@ -1,6 +1,6 @@
 /**
  * name: stk-table-vue
- * version: v1.2.3
+ * version: v1.2.5
  * description: High performance realtime virtual table for vue3 and vue2.7
  * author: japlus
  * homepage: https://ja-plus.github.io/stk-table-vue/
@@ -323,9 +323,19 @@ var MY_FN_NAME = "stkName";
 //#endregion
 //#region src/StkTable/features/useAreaSelection.ts
 /**
-* 单元格区域选择功能
-* 支持鼠标拖拽选择、键盘导航、复制粘贴等功能
+* 单元格区域选择功能（Excel 式交互）。
+* 支持鼠标拖拽选择、键盘导航（方向键/Tab/Shift+Tab，Ctrl 多选、Shift 扩选）、复制到剪贴板。
 * en: Cell area selection feature with mouse drag, keyboard navigation, copy-paste, etc.
+*
+* 分区说明：
+* - 选区状态：锚点 begin / 终点 end、选区集合、是否正在拖拽选中（isAreaSelecting）。
+* - 鼠标交互：mousedown 起锚、mousemove 扩展选区、拖拽靠近容器边缘时自动滚动（EDGE_ZONE/SCROLL_SPEED_MAX）。
+* - 键盘交互：方向键/Tab 移动选区（见 useKeyboardArrowScroll 联动）、Ctrl 切换多选、Shift 扩选。
+* - 复制：通过 formatCellForClipboard 回调（若配置了 customCell 应自定义）生成剪贴板文本。
+* - 选区转换：单元格的可见/数据坐标通过 getRowIndex/getColumnIndex、cellKeyGen/colKeyGen 与
+*   虚拟滚动(虚拟窗口裁剪)和列宽缓存(getCalculatedColWidth)相互换算。
+*
+* 对外返回：选区配置/状态、选区范围读写(setAreaSelection/getAreaSelection)、复制处理、选择/取消等。
 */
 function useAreaSelectionImpl(props, emits, tableContainerRef, dataSourceCopy, tableHeaderLast, colKeyGen, cellKeyGen, scrollTo, virtualScroll, virtualScrollX, getRowIndex, getColumnIndex) {
 	/**
@@ -3039,6 +3049,17 @@ function useSorter(props, emits, colKeyGen, tableHeaderLast, dataSourceCopy, ini
 /**
 * Table Columns Processing Hook
 * Handles multi-level header processing and column flattening
+*
+* 核心职责：
+* - 将用户传入的 `columns`（可能含 children 多级表头）摊平为「按层级划分」的二维数组 `tableHeaders`，
+*   每层是同一行的 th 集合；同时生成 `tableHeadersForCalc`（复制 rowSpan 位置）用于固定列计算。
+* - 为每个列补充私有元数据（@private 字段）：
+*   - __P__    父列引用（双向链表）
+*   - __LF_S__ / __LF_E__  该列在叶子列中的起止索引，用于多级表头横向虚拟滚动
+*   - __W__    计算宽度（子列累加 / 叶子列取配置宽度）
+*   - __R_SP__ / __C_SP__  th 的 rowSpan / colSpan
+* - 在 relative 模式（isRelativeMode）下，固定列不再用 sticky，而是重排到左右两侧。
+* - 叶子列宽度是 X 轴虚拟滚动的依据（getColWidth）。
 */
 function useTableColumns(virtualX, isRelativeMode) {
 	/**
@@ -3717,7 +3738,7 @@ function useVirtualScroll(props, tableContainerRef, trRef, dataSourceCopy, table
 		return (dataSourceCopyValue.length - startIndex - virtual_dataSourcePart.value.length) * rowHeight;
 	});
 	const virtualX_on = computed(() => {
-		return props.virtualX && tableHeaderLast.value.reduce((sum, col) => sum += getCalculatedColWidth(col), 0) > virtualScrollX.value.containerWidth + 100;
+		return props.virtualX && tableHeaderLast.value.reduce((sum, col) => sum += getCalculatedColWidth(col), 0) > virtualScrollX.value.containerWidth;
 	});
 	/** 是否多级表头 */
 	const isMultiLevelHeader = computed(() => tableHeaders.value.length > 1);
@@ -4072,6 +4093,7 @@ function useVirtualScroll(props, tableContainerRef, trRef, dataSourceCopy, table
  /** fix： 滚动条不在顶部时，表格数据变少，导致滚动条位置有误 */
 		scrollTop = maxScrollTop;
 		assignVs(virtualScroll, {
+			rowHeight,
 			containerHeight,
 			pageSize,
 			scrollHeight
@@ -4654,6 +4676,36 @@ var StkTable_default = /* @__PURE__ */ defineComponent({
 	],
 	setup(__props, { expose: __expose, emit: __emit }) {
 		/**
+		* StkTable 主组件（Vue 3 / Vue 2.7）
+		*
+		* 这是一个超大的核心组件文件，约 1800+ 行。理解它时请按以下「分区地图」定位：
+		*
+		* 1. 顶部（template 261 行前）
+		*    渲染结构：滚动容器 + 原生 <table>。包括 colgroup（固定模式列宽）、thead（多级表头、
+		*    sticky 固定）、tbody（虚拟滚动 tr / 空 td 定位）、tfoot（汇总行）、自定义滚动条容器。
+		*    通过 CSS 类（如 virtual / virtual-x / area-selection / theme 等）联动对应 hook 状态。
+		*
+		* 2. script setup（270 行起）
+		*    - props 定义：全部配置项，即公共 API（对应 types/index.ts 与文档 table-props.md）。
+		*    - 大量 useXxx hooks 的组装：本文件只做「装配」，具体逻辑在对应 hook 中。
+		*
+		* 3. 核心 hook 与职责（均在 src/StkTable/use*.ts）：
+		*    - useVirtualScroll     XY 轴虚拟滚动（可视区裁剪、占位 tr/th 定位、scroll 计算）
+		*    - useTableColumns      列配置归一化 / 多级表头展开为叶子列
+		*    - useFixedCol/useFixedStyle/getFixedColPosition  固定列 sticky/relative 定位
+		*    - useSorter/useTableColumns.sort  排序（本地/远端、多列）
+		*    - useColResize/useThDrag/useTrDrag  列宽调整 / 表头拖拽 / 行拖拽
+		*    - useMergeCells/useMaxRowSpan  单元格合并与最大行跨
+		*    - useRowExpand/useTree  展开行 / 树形
+		*    - useHighlight         单元格/行高亮（Web Animations API 或 css）
+		*    - useAreaSelection (features/)  区域选取（Excel 式键盘操作）
+		*    - useScrollbar/useScrollRowByRow/useWheeling  自定义滚动条 / 按行滚动 / 滚轮
+		*    - useAutoResize        容器尺寸自动适配
+		*
+		* 4. expose：对外暴露的实例方法（对应文档 expose.md），供 ref 调用。
+		*
+		* 注意：此文件与 vue2.7 兼容，props 不可抽离到独立文件（见下方注释），修改时注意不要破坏兼容性。
+		*
 		* @author japlus
 		*/
 		const stkTableId = createStkTableId();
@@ -4902,7 +4954,21 @@ var StkTable_default = /* @__PURE__ */ defineComponent({
 		watch(() => props.virtual, () => {
 			nextTick(initVirtualScrollY);
 		});
-		watch(() => props.rowHeight, initVirtualScrollY);
+		/**
+		* 行高类配置变化后重算虚拟滚动几何。
+		* 合并为一个 watcher：同一 tick 内多项同时变化只重算一次。
+		* 必须无参调用 initVirtualScrollY（其首参是虚拟滚动容器高度，不能把行高值传入），
+		* 且需 nextTick 等新的 --row-height / 表头行高等样式应用到 DOM 后再测量。
+		*
+		* 监听值拼接为单个原始值（字符串）而非返回数组：getter 返回数组时每次求值都是新数组，
+		* 身份比较必然变化，父组件传入内联对象字面量（如 :expand-config="{ height: 40 }"，官方示例即如此写法）
+		* 会让本 watcher 在父组件每次重渲染时误触发；展开行/变高大表下误触发一次会连带行高树 O(n) 重建
+		* （实测 50K 行每次父重渲染多付 ~10ms）。拼接为原始值后仅在值真正变化时触发，且兼容 Vue 2.7。
+		*/
+		watch(() => {
+			var _props$expandConfig;
+			return `${props.rowHeight}|${props.headerRowHeight}|${props.footerRowHeight}|${(_props$expandConfig = props.expandConfig) === null || _props$expandConfig === void 0 ? void 0 : _props$expandConfig.height}`;
+		}, () => nextTick(initVirtualScrollY));
 		watch(() => props.virtualX, () => {
 			handleDealColumns();
 			nextTick(() => {
@@ -5117,7 +5183,7 @@ var StkTable_default = /* @__PURE__ */ defineComponent({
 			return col.title || "";
 		}
 		function getTRProps(row, index) {
-			var _props$expandConfig;
+			var _props$expandConfig2;
 			const rowIndex = getAbsoluteRowIndex(index);
 			const rowKey = rowKeyGen(row);
 			const classList = [
@@ -5134,9 +5200,9 @@ var StkTable_default = /* @__PURE__ */ defineComponent({
 				class: classList.filter(Boolean).join(" "),
 				style: null
 			};
-			if ((row === null || row === void 0 ? void 0 : row.__EXP_R__) && props.virtual && ((_props$expandConfig = props.expandConfig) === null || _props$expandConfig === void 0 ? void 0 : _props$expandConfig.height)) {
-				var _props$expandConfig2;
-				result.style = `--row-height: ${(_props$expandConfig2 = props.expandConfig) === null || _props$expandConfig2 === void 0 ? void 0 : _props$expandConfig2.height}px`;
+			if ((row === null || row === void 0 ? void 0 : row.__EXP_R__) && props.virtual && ((_props$expandConfig2 = props.expandConfig) === null || _props$expandConfig2 === void 0 ? void 0 : _props$expandConfig2.height)) {
+				var _props$expandConfig3;
+				result.style = `--row-height: ${(_props$expandConfig3 = props.expandConfig) === null || _props$expandConfig3 === void 0 ? void 0 : _props$expandConfig3.height}px`;
 			}
 			return result;
 		}

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

@@ -20,6 +20,7 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
     /**
      * 行高
      * - `props.autoRowHeight` 为 `true` 时，将表示为期望行高，用于计算。不再影响实际行高。
+     * - 支持动态修改，修改后自动重算可视区行数与滚动高度，并与 `--row-height` 保持同步。
      */
     rowHeight?: number;
     /**
@@ -35,9 +36,15 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
      * @deprecated
      */
     rowCurrentRevokable?: boolean;
-    /** 表头行高。default = rowHeight */
+    /**
+     * 表头行高。default = rowHeight
+     * - 支持动态修改，表头占用的表体行数（pageSize）随之重算。
+     */
     headerRowHeight?: number | string;
-    /** 表尾行高。default = rowHeight */
+    /**
+     * 表尾行高。default = rowHeight
+     * - 支持动态修改。表尾行悬浮于滚动区底部，不计入虚拟滚动的总高度。
+     */
     footerRowHeight?: number | string;
     /** 虚拟滚动 */
     virtual?: boolean;
@@ -510,6 +517,7 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
     /**
      * 行高
      * - `props.autoRowHeight` 为 `true` 时，将表示为期望行高，用于计算。不再影响实际行高。
+     * - 支持动态修改，修改后自动重算可视区行数与滚动高度，并与 `--row-height` 保持同步。
      */
     rowHeight?: number;
     /**
@@ -525,9 +533,15 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
      * @deprecated
      */
     rowCurrentRevokable?: boolean;
-    /** 表头行高。default = rowHeight */
+    /**
+     * 表头行高。default = rowHeight
+     * - 支持动态修改，表头占用的表体行数（pageSize）随之重算。
+     */
     headerRowHeight?: number | string;
-    /** 表尾行高。default = rowHeight */
+    /**
+     * 表尾行高。default = rowHeight
+     * - 支持动态修改。表尾行悬浮于滚动区底部，不计入虚拟滚动的总高度。
+     */
     footerRowHeight?: number | string;
     /** 虚拟滚动 */
     virtual?: boolean;

package/lib/src/StkTable/features/useAreaSelection.d.ts

@@ -3,9 +3,19 @@ import { AreaSelectionConfig, AreaSelectionRange, CellKeyGen, ColKeyGen, StkTabl
 import { VirtualScrollStore, VirtualScrollXStore } from '../useVirtualScroll';
 
 /**
- * 单元格区域选择功能
- * 支持鼠标拖拽选择、键盘导航、复制粘贴等功能
+ * 单元格区域选择功能（Excel 式交互）。
+ * 支持鼠标拖拽选择、键盘导航（方向键/Tab/Shift+Tab，Ctrl 多选、Shift 扩选）、复制到剪贴板。
  * en: Cell area selection feature with mouse drag, keyboard navigation, copy-paste, etc.
+ *
+ * 分区说明：
+ * - 选区状态：锚点 begin / 终点 end、选区集合、是否正在拖拽选中（isAreaSelecting）。
+ * - 鼠标交互：mousedown 起锚、mousemove 扩展选区、拖拽靠近容器边缘时自动滚动（EDGE_ZONE/SCROLL_SPEED_MAX）。
+ * - 键盘交互：方向键/Tab 移动选区（见 useKeyboardArrowScroll 联动）、Ctrl 切换多选、Shift 扩选。
+ * - 复制：通过 formatCellForClipboard 回调（若配置了 customCell 应自定义）生成剪贴板文本。
+ * - 选区转换：单元格的可见/数据坐标通过 getRowIndex/getColumnIndex、cellKeyGen/colKeyGen 与
+ *   虚拟滚动(虚拟窗口裁剪)和列宽缓存(getCalculatedColWidth)相互换算。
+ *
+ * 对外返回：选区配置/状态、选区范围读写(setAreaSelection/getAreaSelection)、复制处理、选择/取消等。
  */
 declare function useAreaSelectionImpl<DT extends Record<string, any>>(props: any, emits: any, tableContainerRef: Ref<HTMLDivElement | undefined>, dataSourceCopy: ShallowRef<DT[]>, tableHeaderLast: ShallowRef<StkTableColumn<DT>[]>, colKeyGen: ColKeyGen, cellKeyGen: CellKeyGen, scrollTo: (top: number | null, left: number | null) => void, virtualScroll: Ref<VirtualScrollStore>, virtualScrollX: Ref<VirtualScrollXStore>, getRowIndex: (row: DT) => number, getColumnIndex: (col: StkTableColumn<DT>) => number): {
     config: import('vue').ComputedRef<AreaSelectionConfig>;

package/lib/src/StkTable/types/index.d.ts

@@ -297,7 +297,10 @@ export type SeqConfig = {
 };
 /** Configuration options for the expand column  */
 export type ExpandConfig = {
-    /** worked in virtual mode */
+    /**
+     * worked in virtual mode
+     * 展开行的行高，支持动态修改（修改后行高累计与虚拟滚动会一同重算）
+     */
     height?: number;
 };
 /** drag row config */

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

@@ -4,5 +4,16 @@ import { PrivateRowDT, PrivateStkTableColumn, StkTableColumn } from './types';
 /**
  * Table Columns Processing Hook
  * Handles multi-level header processing and column flattening
+ *
+ * 核心职责：
+ * - 将用户传入的 `columns`（可能含 children 多级表头）摊平为「按层级划分」的二维数组 `tableHeaders`，
+ *   每层是同一行的 th 集合；同时生成 `tableHeadersForCalc`（复制 rowSpan 位置）用于固定列计算。
+ * - 为每个列补充私有元数据（@private 字段）：
+ *   - __P__    父列引用（双向链表）
+ *   - __LF_S__ / __LF_E__  该列在叶子列中的起止索引，用于多级表头横向虚拟滚动
+ *   - __W__    计算宽度（子列累加 / 叶子列取配置宽度）
+ *   - __R_SP__ / __C_SP__  th 的 rowSpan / colSpan
+ * - 在 relative 模式（isRelativeMode）下，固定列不再用 sticky，而是重排到左右两侧。
+ * - 叶子列宽度是 X 轴虚拟滚动的依据（getColWidth）。
  */
 export declare function useTableColumns<DT extends Record<string, any>>(virtualX: boolean, isRelativeMode: Ref<boolean>): readonly [import('vue').ShallowRef<PrivateStkTableColumn<PrivateRowDT>[][], PrivateStkTableColumn<PrivateRowDT>[][]>, import('vue').ShallowRef<PrivateStkTableColumn<PrivateRowDT>[][], PrivateStkTableColumn<PrivateRowDT>[][]>, (columns: StkTableColumn<DT>[]) => void];

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

@@ -13,7 +13,12 @@ export type VirtualScrollStore = {
     startIndex: number;
     /** 数组结束位置 */
     endIndex: number;
-    /** 行高 */
+    /**
+     * 基准行高（px）。
+     * 由 initVirtualScrollY 随 props.rowHeight 同步（模板中的 --row-height 亦取此值，二者同源），
+     * 因此行高配置动态变化后此处不会是旧快照。
+     * 仅记录统一基准行高：变高模式（autoRowHeight）与展开行的行级高度不写入此字段。
+     */
     rowHeight: number;
     /** 表格定位上边距 */
     offsetTop: number;

package/lib/stk-table-vue.js

@@ -1,12 +1,12 @@
 /**
  * name: stk-table-vue
- * version: v1.2.3
+ * version: v1.2.5
  * 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-DFh1B-f9.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-CzktjLlV.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-B2dzC5D3.js").then((module) => module.default)).mount(div);
+		DropdownIns = createApp(await import("./Dropdown-C4c7Nmgf.js").then((module) => module.default)).mount(div);
 	}
 	return DropdownIns;
 }

package/lib/style.css

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stk-table-vue",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "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/StkTable.vue

@@ -302,6 +302,36 @@ export default {
 
 <script setup lang="ts">
 /**
+ * StkTable 主组件（Vue 3 / Vue 2.7）
+ *
+ * 这是一个超大的核心组件文件，约 1800+ 行。理解它时请按以下「分区地图」定位：
+ *
+ * 1. 顶部（template 261 行前）
+ *    渲染结构：滚动容器 + 原生 <table>。包括 colgroup（固定模式列宽）、thead（多级表头、
+ *    sticky 固定）、tbody（虚拟滚动 tr / 空 td 定位）、tfoot（汇总行）、自定义滚动条容器。
+ *    通过 CSS 类（如 virtual / virtual-x / area-selection / theme 等）联动对应 hook 状态。
+ *
+ * 2. script setup（270 行起）
+ *    - props 定义：全部配置项，即公共 API（对应 types/index.ts 与文档 table-props.md）。
+ *    - 大量 useXxx hooks 的组装：本文件只做「装配」，具体逻辑在对应 hook 中。
+ *
+ * 3. 核心 hook 与职责（均在 src/StkTable/use*.ts）：
+ *    - useVirtualScroll     XY 轴虚拟滚动（可视区裁剪、占位 tr/th 定位、scroll 计算）
+ *    - useTableColumns      列配置归一化 / 多级表头展开为叶子列
+ *    - useFixedCol/useFixedStyle/getFixedColPosition  固定列 sticky/relative 定位
+ *    - useSorter/useTableColumns.sort  排序（本地/远端、多列）
+ *    - useColResize/useThDrag/useTrDrag  列宽调整 / 表头拖拽 / 行拖拽
+ *    - useMergeCells/useMaxRowSpan  单元格合并与最大行跨
+ *    - useRowExpand/useTree  展开行 / 树形
+ *    - useHighlight         单元格/行高亮（Web Animations API 或 css）
+ *    - useAreaSelection (features/)  区域选取（Excel 式键盘操作）
+ *    - useScrollbar/useScrollRowByRow/useWheeling  自定义滚动条 / 按行滚动 / 滚轮
+ *    - useAutoResize        容器尺寸自动适配
+ *
+ * 4. expose：对外暴露的实例方法（对应文档 expose.md），供 ref 调用。
+ *
+ * 注意：此文件与 vue2.7 兼容，props 不可抽离到独立文件（见下方注释），修改时注意不要破坏兼容性。
+ *
  * @author japlus
  */
 import { computed, nextTick, onMounted, provide, ref, shallowRef, toRaw, toRef, watch } from 'vue';
@@ -400,6 +430,7 @@ const props = withDefaults(
         /**
          * 行高
          * - `props.autoRowHeight` 为 `true` 时，将表示为期望行高，用于计算。不再影响实际行高。
+         * - 支持动态修改，修改后自动重算可视区行数与滚动高度，并与 `--row-height` 保持同步。
          */
         rowHeight?: number;
         /**
@@ -415,9 +446,15 @@ const props = withDefaults(
          * @deprecated
          */
         rowCurrentRevokable?: boolean;
-        /** 表头行高。default = rowHeight */
+        /**
+         * 表头行高。default = rowHeight
+         * - 支持动态修改，表头占用的表体行数（pageSize）随之重算。
+         */
         headerRowHeight?: number | string;
-        /** 表尾行高。default = rowHeight */
+        /**
+         * 表尾行高。default = rowHeight
+         * - 支持动态修改。表尾行悬浮于滚动区底部，不计入虚拟滚动的总高度。
+         */
         footerRowHeight?: number | string;
         /** 虚拟滚动 */
         virtual?: boolean;
@@ -1184,7 +1221,21 @@ watch(
     },
 );
 
-watch(() => props.rowHeight, initVirtualScrollY);
+/**
+ * 行高类配置变化后重算虚拟滚动几何。
+ * 合并为一个 watcher：同一 tick 内多项同时变化只重算一次。
+ * 必须无参调用 initVirtualScrollY（其首参是虚拟滚动容器高度，不能把行高值传入），
+ * 且需 nextTick 等新的 --row-height / 表头行高等样式应用到 DOM 后再测量。
+ *
+ * 监听值拼接为单个原始值（字符串）而非返回数组：getter 返回数组时每次求值都是新数组，
+ * 身份比较必然变化，父组件传入内联对象字面量（如 :expand-config="{ height: 40 }"，官方示例即如此写法）
+ * 会让本 watcher 在父组件每次重渲染时误触发；展开行/变高大表下误触发一次会连带行高树 O(n) 重建
+ * （实测 50K 行每次父重渲染多付 ~10ms）。拼接为原始值后仅在值真正变化时触发，且兼容 Vue 2.7。
+ */
+watch(
+    () => `${props.rowHeight}|${props.headerRowHeight}|${props.footerRowHeight}|${props.expandConfig?.height}`,
+    () => nextTick(initVirtualScrollY),
+);
 
 watch(
     () => props.virtualX,

package/src/StkTable/features/useAreaSelection.ts

@@ -15,9 +15,19 @@ import { getCalculatedColWidth } from '../utils/constRefUtils';
 import { MY_FN_NAME } from './const';
 
 /**
- * 单元格区域选择功能
- * 支持鼠标拖拽选择、键盘导航、复制粘贴等功能
+ * 单元格区域选择功能（Excel 式交互）。
+ * 支持鼠标拖拽选择、键盘导航（方向键/Tab/Shift+Tab，Ctrl 多选、Shift 扩选）、复制到剪贴板。
  * en: Cell area selection feature with mouse drag, keyboard navigation, copy-paste, etc.
+ *
+ * 分区说明：
+ * - 选区状态：锚点 begin / 终点 end、选区集合、是否正在拖拽选中（isAreaSelecting）。
+ * - 鼠标交互：mousedown 起锚、mousemove 扩展选区、拖拽靠近容器边缘时自动滚动（EDGE_ZONE/SCROLL_SPEED_MAX）。
+ * - 键盘交互：方向键/Tab 移动选区（见 useKeyboardArrowScroll 联动）、Ctrl 切换多选、Shift 扩选。
+ * - 复制：通过 formatCellForClipboard 回调（若配置了 customCell 应自定义）生成剪贴板文本。
+ * - 选区转换：单元格的可见/数据坐标通过 getRowIndex/getColumnIndex、cellKeyGen/colKeyGen 与
+ *   虚拟滚动(虚拟窗口裁剪)和列宽缓存(getCalculatedColWidth)相互换算。
+ *
+ * 对外返回：选区配置/状态、选区范围读写(setAreaSelection/getAreaSelection)、复制处理、选择/取消等。
  */
 function useAreaSelectionImpl<DT extends Record<string, any>>(
     props: any,
@@ -1017,6 +1027,7 @@ function useAreaSelectionImpl<DT extends Record<string, any>>(
         const isScrollRowByRow = props.scrollRowByRow;
 
         // 计算目标行的位置（基于虚拟滚动数据）
+        // vs.rowHeight 由 initVirtualScrollY 随 props.rowHeight 同步，动态改行高后此处即新值
         const rowHeight = vs.rowHeight;
         const targetRowTop = rowIndex * rowHeight;
         const targetRowBottom = targetRowTop + rowHeight;

package/src/StkTable/types/index.ts

@@ -314,7 +314,10 @@ export type SeqConfig = {
 
 /** Configuration options for the expand column  */
 export type ExpandConfig = {
-    /** worked in virtual mode */
+    /**
+     * worked in virtual mode
+     * 展开行的行高，支持动态修改（修改后行高累计与虚拟滚动会一同重算）
+     */
     height?: number;
 };
 

package/src/StkTable/useTableColumns.ts

@@ -6,6 +6,17 @@ import { howDeepTheHeader } from './utils/index';
 /**
  * Table Columns Processing Hook
  * Handles multi-level header processing and column flattening
+ *
+ * 核心职责：
+ * - 将用户传入的 `columns`（可能含 children 多级表头）摊平为「按层级划分」的二维数组 `tableHeaders`，
+ *   每层是同一行的 th 集合；同时生成 `tableHeadersForCalc`（复制 rowSpan 位置）用于固定列计算。
+ * - 为每个列补充私有元数据（@private 字段）：
+ *   - __P__    父列引用（双向链表）
+ *   - __LF_S__ / __LF_E__  该列在叶子列中的起止索引，用于多级表头横向虚拟滚动
+ *   - __W__    计算宽度（子列累加 / 叶子列取配置宽度）
+ *   - __R_SP__ / __C_SP__  th 的 rowSpan / colSpan
+ * - 在 relative 模式（isRelativeMode）下，固定列不再用 sticky，而是重排到左右两侧。
+ * - 叶子列宽度是 X 轴虚拟滚动的依据（getColWidth）。
  */
 export function useTableColumns<DT extends Record<string, any>>(virtualX: boolean, isRelativeMode: Ref<boolean>) {
     /**

package/src/StkTable/useVirtualScroll.ts

@@ -17,7 +17,12 @@ export type VirtualScrollStore = {
     startIndex: number;
     /** 数组结束位置 */
     endIndex: number;
-    /** 行高 */
+    /**
+     * 基准行高（px）。
+     * 由 initVirtualScrollY 随 props.rowHeight 同步（模板中的 --row-height 亦取此值，二者同源），
+     * 因此行高配置动态变化后此处不会是旧快照。
+     * 仅记录统一基准行高：变高模式（autoRowHeight）与展开行的行级高度不写入此字段。
+     */
     rowHeight: number;
     /** 表格定位上边距 */
     offsetTop: number;
@@ -192,8 +197,7 @@ export function useVirtualScroll(
 
     const virtualX_on = computed(() => {
         return (
-            props.virtualX &&
-            tableHeaderLast.value.reduce((sum, col) => (sum += getCalculatedColWidth(col)), 0) > virtualScrollX.value.containerWidth + 100
+            props.virtualX && tableHeaderLast.value.reduce((sum, col) => (sum += getCalculatedColWidth(col)), 0) > virtualScrollX.value.containerWidth
         );
     });
 
@@ -603,7 +607,9 @@ export function useVirtualScroll(
             /** fix： 滚动条不在顶部时，表格数据变少，导致滚动条位置有误 */
             scrollTop = maxScrollTop;
         }
-        assignVs(virtualScroll, { containerHeight, pageSize, scrollHeight });
+        // rowHeight 必须随 props.rowHeight 变化同步：模板的 --row-height 与 SRBR/区域选取均读此字段，
+        // 若只在 shallowRef 初始化时求值一次，改行高后会出现「计算已用新行高、渲染仍是旧行高」的不一致。
+        assignVs(virtualScroll, { rowHeight, containerHeight, pageSize, scrollHeight });
         updateVirtualScrollY(scrollTop);
     }