stk-table-vue 1.2.2 → 1.2.4

package/lib/{Dropdown-D40QlY91.js → Dropdown-D_9cB0rD.js}

@@ -1,12 +1,12 @@
 /**
  * name: stk-table-vue
- * version: v1.2.2
+ * version: v1.2.4
  * 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-g_qwf6BE.js";
+import { t as StkTable_default } from "./StkTable-CVcmlZi9.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;
@@ -115,7 +115,9 @@ var Dropdown_default = /* @__PURE__ */ defineComponent({
 		}
 		function handleClear() {
 			checkedTempValueSet.clear();
-			confirm();
+			options.value.forEach((opt) => opt.selected = false);
+			onConfirmFn([]);
+			hide();
 		}
 		__expose({
 			visible,

package/lib/{StkTable-g_qwf6BE.js → StkTable-CVcmlZi9.js}

@@ -1,6 +1,6 @@
 /**
  * name: stk-table-vue
- * version: v1.2.2
+ * version: v1.2.4
  * 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) {
 	/**
@@ -1547,7 +1557,7 @@ function useFixedCol(props, colKeyGen, getFixedColPosition, tableHeaders, tableH
 				}
 				if (showShadow) classList.push("fixed-cell--shadow");
 				if (fixed === "right" && fixedBorderLeftColsValue.includes(col)) classList.push("fixed-cell--border-left");
-				colMap.set(colKeyFn(col), classList);
+				colMap.set(colKeyFn(col), classList.join(" "));
 			}
 		}
 		return colMap;
@@ -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);
@@ -4654,6 +4675,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();

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/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/stk-table-vue.js

@@ -1,12 +1,12 @@
 /**
  * name: stk-table-vue
- * version: v1.2.2
+ * version: v1.2.4
  * 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-g_qwf6BE.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-CVcmlZi9.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-D40QlY91.js").then((module) => module.default)).mount(div);
+		DropdownIns = createApp(await import("./Dropdown-D_9cB0rD.js").then((module) => module.default)).mount(div);
 	}
 	return DropdownIns;
 }

package/lib/style.css

@@ -1,6 +1,6 @@
 /**
  * name: stk-table-vue
- * version: v1.2.2
+ * version: v1.2.4
  * 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.2",
+  "version": "1.2.4",
   "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';

package/src/StkTable/custom-cells/FilterCell/Dropdown/index.vue

@@ -146,7 +146,9 @@ function setTheme(t: 'light' | 'dark') {
 
 function handleClear() {
     checkedTempValueSet.clear();
-    confirm();
+    options.value.forEach(opt => (opt.selected = false));
+    onConfirmFn([]);
+    hide();
 }
 
 defineExpose({ visible, show, hide, setTheme });

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,

package/src/StkTable/useFixedCol.ts

@@ -59,7 +59,7 @@ export function useFixedCol<DT extends Record<string, any>>(
                 if (fixed === 'right' && fixedBorderLeftColsValue.includes(col)) {
                     classList.push('fixed-cell--border-left');
                 }
-                colMap.set(colKeyFn(col), classList);
+                colMap.set(colKeyFn(col), classList.join(' '));
             }
         }
         return colMap;

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

@@ -192,8 +192,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
         );
     });