stk-table-vue 1.1.0 → 1.2.0-beta.2

package/README.md

@@ -25,7 +25,7 @@ Smooth performance with tens of thousands of rows. Designed for real-time data d
 - Cell highlighting with Animation API
 - Built-in custom cells: Filter, Editable, Checkbox, Number, Change
 - Column resize, header drag, row drag
-- Merge cells (virtual mode supported)
+- Merge cells (virtual mode, huge rowspan / colspan supported)
 - Custom scrollbar
 - Sortable & filterable
 - Theme support (dark / light)
@@ -182,7 +182,12 @@ const dataSource = [
 ```
 
 ## Compare
-Compare performance with other vue table [vue-table-compare](https://github.com/ja-plus/vue-table-compare)
+Compare performance with other vue table [vue-virtual-table-benchmark](https://github.com/ja-plus/vue-virtual-table-benchmark)
+
+[Benchmark Result Page](https://ja-plus.github.io/vue-virtual-table-benchmark/perf-report.html)
+
+## Changelog
+[CHANGELOG](CHANGELOG.md)
 
 
 ## License

package/lib/index-BDlBM6WX.js

@@ -0,0 +1,166 @@
+/**
+ * name: stk-table-vue
+ * version: v1.2.0-beta.2
+ * 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 { defineComponent, ref, reactive, h, onMounted, onUnmounted, createElementBlock, openBlock, withModifiers, normalizeStyle, normalizeClass, createVNode, createElementVNode, nextTick } from "vue";
+import { StkTable as _sfc_main$1 } from "./stk-table-vue.js";
+const DROPDOWN_DEFAULT_WIDTH = 300;
+const DROPDOWN_DEFAULT_HEIGHT = 400;
+const PADDING = 6;
+const _sfc_main = /* @__PURE__ */ defineComponent({
+  __name: "index",
+  setup(__props, { expose: __expose }) {
+    const theme = ref("light");
+    const checkedTempValueSet = reactive(/* @__PURE__ */ new Set());
+    const columns = ref([
+      {
+        title: "",
+        dataIndex: "value",
+        width: 30,
+        className: "stk-filter-dropdown-checkbox",
+        customCell: ({ row }) => h("input", {
+          type: "checkbox",
+          checked: checkedTempValueSet.has(row.value)
+        })
+      },
+      { title: "", dataIndex: "label" }
+    ]);
+    const visible = ref(false);
+    const position = ref({ x: 0, y: 0 });
+    const options = ref([]);
+    const dropdownEl = ref();
+    onMounted(() => {
+      document.addEventListener("click", handleClickOutside);
+    });
+    onUnmounted(() => {
+      document.removeEventListener("click", handleClickOutside);
+    });
+    let onConfirmFn;
+    function getDropdownSize() {
+      if (!dropdownEl.value) {
+        return [DROPDOWN_DEFAULT_WIDTH, DROPDOWN_DEFAULT_HEIGHT];
+      }
+      const rect = dropdownEl.value.getBoundingClientRect();
+      return [rect.width || DROPDOWN_DEFAULT_WIDTH, rect.height || DROPDOWN_DEFAULT_HEIGHT];
+    }
+    function calculatePosition(docPos) {
+      const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+      const scrollLeft = window.pageXOffset || document.documentElement.scrollLeft;
+      const viewportWidth = document.documentElement.clientWidth;
+      const viewportHeight = document.documentElement.clientHeight;
+      const [dropdownWidth, dropdownHeight] = getDropdownSize();
+      let finalX = docPos.x;
+      let finalY = docPos.y;
+      const relativeX = docPos.x - scrollLeft;
+      if (relativeX + dropdownWidth > viewportWidth - PADDING) {
+        finalX = viewportWidth - dropdownWidth - PADDING + scrollLeft;
+      }
+      const relativeY = docPos.y - scrollTop;
+      if (relativeY + dropdownHeight > viewportHeight - PADDING) {
+        const triggerHeight = docPos.height || 30;
+        if (relativeY - triggerHeight >= dropdownHeight + PADDING) {
+          finalY = docPos.y - triggerHeight - dropdownHeight - PADDING;
+        } else {
+          finalY = PADDING + scrollTop;
+        }
+      }
+      finalX = Math.max(PADDING + scrollLeft, finalX);
+      finalY = Math.max(PADDING + scrollTop, finalY);
+      return { x: finalX, y: finalY };
+    }
+    async function show(pos, opt, onConfirm) {
+      if (dropdownEl.value) {
+        dropdownEl.value.style.visibility = "hidden";
+      }
+      visible.value = true;
+      options.value = opt || [];
+      initChecked();
+      onConfirmFn = onConfirm;
+      await nextTick();
+      position.value = calculatePosition(pos);
+      if (dropdownEl.value) {
+        dropdownEl.value.style.visibility = "visible";
+      }
+    }
+    async function handleClickOutside(e) {
+      var _a;
+      if (!visible.value || ((_a = dropdownEl.value) == null ? void 0 : _a.contains(e.target))) return;
+      hide();
+    }
+    function initChecked() {
+      options.value.forEach((opt) => {
+        if (opt.selected) {
+          checkedTempValueSet.add(opt.value);
+        }
+      });
+    }
+    function updateChecked(checked, row) {
+      if (checked) {
+        checkedTempValueSet.add(row.value);
+      } else {
+        checkedTempValueSet.delete(row.value);
+      }
+    }
+    function confirm() {
+      options.value.forEach((opt) => opt.selected = checkedTempValueSet.has(opt.value));
+      onConfirmFn(Array.from(checkedTempValueSet));
+      hide();
+    }
+    function hide() {
+      visible.value = false;
+      options.value = [];
+      checkedTempValueSet.clear();
+    }
+    function handleRowClick(e, row) {
+      const selected = checkedTempValueSet.has(row.value);
+      updateChecked(!selected, row);
+    }
+    function setTheme(t) {
+      theme.value = t;
+    }
+    function handleClear() {
+      checkedTempValueSet.clear();
+      confirm();
+    }
+    __expose({ visible, show, hide, setTheme });
+    return (_ctx, _cache) => {
+      return openBlock(), createElementBlock("div", {
+        ref_key: "dropdownEl",
+        ref: dropdownEl,
+        class: normalizeClass(["stk-filter-dropdown", [`stk-filter-dropdown--${theme.value}`]]),
+        style: normalizeStyle({
+          top: position.value.y + "px",
+          left: position.value.x + "px",
+          display: visible.value ? void 0 : "none"
+        }),
+        onClick: _cache[0] || (_cache[0] = withModifiers(() => {
+        }, ["stop"]))
+      }, [
+        createVNode(_sfc_main$1, {
+          "row-key": "id",
+          headless: "",
+          virtual: "",
+          "no-data-full": "",
+          theme: theme.value,
+          "row-active": false,
+          "row-height": 20,
+          bordered: false,
+          columns: columns.value,
+          "data-source": options.value,
+          onRowClick: handleRowClick
+        }, null, 8, ["theme", "columns", "data-source"]),
+        createElementVNode("footer", null, [
+          createElementVNode("button", { onClick: handleClear }, "↺"),
+          createElementVNode("button", { onClick: confirm }, "✓")
+        ])
+      ], 6);
+    };
+  }
+});
+export {
+  _sfc_main as default
+};

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

@@ -242,6 +242,13 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
      * @see {@link initVirtualScrollY}
      */
     initVirtualScrollY: (height?: number) => void;
+    /**
+     * 清空 mergeCells 结果缓存并强制重算合并结果
+     *
+     * en: Clear mergeCells result cache and force recomputation
+     * @see {@link clearMergeCellsCache}
+     */
+    clearMergeCellsCache: () => void;
     /**
      * 选中一行
      *
@@ -757,13 +764,13 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
     maxWidth: string;
     sortConfig: SortConfig<any>;
     colKey: UniqKeyProp;
-    rowHeight: number;
     headless: boolean;
     autoRowHeight: boolean | AutoRowHeightConfig<any>;
     stripe: boolean;
     optimizeVue2Scroll: boolean;
     rowKey: UniqKeyProp;
     headerRowHeight: number | string;
+    rowHeight: number;
     scrollbar: boolean | ScrollbarOptions;
     fixedMode: boolean;
     theme: "light" | "dark";
@@ -814,7 +821,7 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
     }): any;
     expand?(_: {
         row: any;
-        col: StkTableColumn<any> | undefined;
+        col: any;
     }): any;
     empty?(_: {}): any;
     customBottom?(_: {}): any;

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

@@ -0,0 +1,26 @@
+import { MergeCellsParam } from './types';
+
+/** mergeCells 计算结果 */
+export type MergeCellsResult = {
+    colspan: number;
+    rowspan: number;
+};
+/**
+ * mergeCells 结果缓存工厂。
+ *
+ * - 缓存键为「绝对行索引 + 叶子列索引」，所有 mergeCells 调用处
+ *   （hiddenCellMap 构建、virtual-x 可视列范围修正、视口上方占位计算、单元格渲染）共享，
+ *   同一单元格只调用一次用户回调；
+ * - 缓存可跨虚拟滚动帧复用（键为绝对索引，不随窗口滑动变化），
+ *   稳态滚动时仅新进入窗口的行会触发回调，只需在数据/列真正变化时 clear；
+ * - 条目额外保存行引用并在命中时校验同一性：即使数据被重排/替换（如排序后同一批行对象
+ *   顺序变化），也不会取到错行的旧结果，缓存清理时机不再影响正确性。
+ * - 注意：引用同一性校验无法感知行字段被原地修改（行引用不变）。
+ *   业务原地改行且 mergeCells 结果依赖该字段时，需调用 clear() 显式失效
+ *   （组件已暴露 clearMergeCellsCache 实例方法）。
+ */
+export declare function createMergeCellsCache(): {
+    getMergeCellsResult: (row: MergeCellsParam<any>["row"], col: MergeCellsParam<any>["col"], rowIndex: number, colIndex: number) => MergeCellsResult;
+    clear: () => void;
+};
+export type MergeCellsCache = ReturnType<typeof createMergeCellsCache>;

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

@@ -165,6 +165,12 @@ export type PrivateStkTableColumn<T extends Record<string, any>> = StkTableColum
      * @private
      */
     __VT_C_SP__?: number;
+    /**
+     * Above-viewport placeholder colspan. Marks a placeholder td for rows
+     * above the viewport that only need structural colspan, not real content.
+     * @private
+     */
+    __VT_PH__?: number;
 };
 /** private row keys */
 export type PrivateRowDT = {

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

@@ -1,4 +1,4 @@
 import { ShallowRef } from 'vue';
 import { PrivateStkTableColumn, RowKeyGen, UniqKey } from './types';
 
-export declare function useMaxRowSpan(props: any, tableHeaderLast: ShallowRef<PrivateStkTableColumn<any>[]>, rowKeyGen: RowKeyGen, dataSourceCopy: ShallowRef<any[]>): readonly [Map<UniqKey, number>, () => void];
+export declare function useMaxRowSpan(props: any, tableHeaderLast: ShallowRef<PrivateStkTableColumn<any>[]>, rowKeyGen: RowKeyGen, dataSourceCopy: ShallowRef<any[]>): readonly [Map<UniqKey, number>, () => void, () => number];

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

@@ -1,7 +1,29 @@
-import { Ref, ShallowRef } from 'vue';
-import { ColKeyGen, MergeCellsParam, PrivateStkTableColumn, RowActiveOption, RowKeyGen, UniqKey } from './types';
+import { ComputedRef, Ref, ShallowRef } from 'vue';
+import { MergeCellsCache } from './mergeCellsCache';
+import { ColKeyGen, MergeCellsParam, PrivateRowDT, PrivateStkTableColumn, RowActiveOption, RowKeyGen, UniqKey } from './types';
+import { VirtualScrollStore } from './useVirtualScroll';
 
-export declare function useMergeCells(rowActiveProp: Ref<RowActiveOption<any>>, tableHeaderLast: ShallowRef<PrivateStkTableColumn<any>[]>, rowKeyGen: RowKeyGen, colKeyGen: ColKeyGen, virtual_dataSourcePart: ShallowRef<any[]>): readonly [Ref<Record<UniqKey, Set<UniqKey>> | null, Record<UniqKey, Set<UniqKey>> | null>, (row: MergeCellsParam<any>["row"], col: MergeCellsParam<any>["col"], rowIndex: MergeCellsParam<any>["rowIndex"], colIndex: MergeCellsParam<any>["colIndex"]) => {
+/** Above-viewport cell descriptor: real column or placeholder colspan */
+type AboveViewportCell = PrivateStkTableColumn<PrivateRowDT> | {
+    __VT_PH__: number;
+};
+export declare function useMergeCells(rowActiveProp: Ref<RowActiveOption<any>>, tableHeaderLast: ShallowRef<PrivateStkTableColumn<PrivateRowDT>[]>, rowKeyGen: RowKeyGen, colKeyGen: ColKeyGen, virtual_dataSourcePart: ShallowRef<any[]>, virtualScroll: Ref<VirtualScrollStore>, 
+/** 视口行渲染使用的列列表（virtual-x 时为可视列子集，否则即 tableHeaderLast） */
+virtualX_columnPart: ComputedRef<PrivateStkTableColumn<PrivateRowDT>[]>, 
+/** 全量数据（仅用于缓存失效判定） */
+dataSourceCopy: ShallowRef<any[]>, 
+/** mergeCells 结果共享缓存（与 useVirtualScroll 共用，可跨滚动帧复用） */
+mergeCellsCache: MergeCellsCache, 
+/** 是否允许把连续空行合并为占位 tr（virtual && !autoRowHeight） */
+canMergeEmptyRows: Ref<boolean>, 
+/** 视口下方合并为占位 tr 的行数（渲染 rowspan 属性修正用） */
+belowViewportRowCount: Ref<number>): readonly [Ref<Record<UniqKey, Set<UniqKey>> | null, Record<UniqKey, Set<UniqKey>> | null>, (row: MergeCellsParam<any>["row"], col: MergeCellsParam<any>["col"], rowIndex: MergeCellsParam<any>["rowIndex"], colIndex: MergeCellsParam<any>["colIndex"]) => {
     colspan?: number;
     rowspan?: number;
-} | undefined, Ref<Set<string> & Omit<Set<string>, keyof Set<any>>, Set<string> | (Set<string> & Omit<Set<string>, keyof Set<any>>)>, (rowKey: UniqKey | undefined) => void, Ref<Set<string> & Omit<Set<string>, keyof Set<any>>, Set<string> | (Set<string> & Omit<Set<string>, keyof Set<any>>)>, (clear?: boolean, rowKey?: UniqKey) => void];
+} | undefined, Ref<Set<string> & Omit<Set<string>, keyof Set<any>>, Set<string> | (Set<string> & Omit<Set<string>, keyof Set<any>>)>, (rowKey: UniqKey | undefined) => void, Ref<Set<string> & Omit<Set<string>, keyof Set<any>>, Set<string> | (Set<string> & Omit<Set<string>, keyof Set<any>>)>, (clear?: boolean, rowKey?: UniqKey) => void, ComputedRef<Map<UniqKey, AboveViewportCell[]>>, ComputedRef<{
+    start: number;
+    count: number;
+}[]>, ComputedRef<{
+    count: number;
+}[]>];
+export {};

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

@@ -1,4 +1,5 @@
 import { Ref, ShallowRef } from 'vue';
+import { MergeCellsCache } from './mergeCellsCache';
 import { PrivateRowDT, PrivateStkTableColumn, RowKeyGen, UniqKey } from './types';
 import { ScrollbarOptions } from './useScrollbar';
 
@@ -21,6 +22,10 @@ export type VirtualScrollStore = {
     /** 总滚动高度 */
     scrollHeight: number;
     translateY: number;
+    /** 视口实际起始行索引（rowspan 修正前的原始值，用于区分 above-viewport 行） */
+    viewportStartIndex: number;
+    /** 视口实际结束行索引（rowspan 修正前的原始值，用于区分 below-viewport 行） */
+    viewportEndIndex: number;
 };
 /** 暂存横向虚拟滚动的数据 */
 export type VirtualScrollXStore = {
@@ -41,42 +46,19 @@ export type VirtualScrollXStore = {
  * virtual scroll
  * @returns
  */
-export declare function useVirtualScroll(props: any, tableContainerRef: Ref<HTMLElement | undefined>, trRef: Ref<HTMLTableRowElement[] | undefined>, dataSourceCopy: ShallowRef<PrivateRowDT[]>, tableHeaderLast: ShallowRef<PrivateStkTableColumn<PrivateRowDT>[]>, tableHeaders: ShallowRef<PrivateStkTableColumn<PrivateRowDT>[][]>, rowKeyGen: RowKeyGen, maxRowSpan: Map<UniqKey, number>, scrollbarOptions: Ref<Required<ScrollbarOptions>>, isExperimentalScrollY: Ref<boolean | undefined>): readonly [Ref<{
-    containerHeight: number;
-    pageSize: number;
-    startIndex: number;
-    endIndex: number;
-    rowHeight: number;
-    offsetTop: number;
-    scrollTop: number;
-    scrollHeight: number;
-    translateY: number;
-}, VirtualScrollStore | {
-    containerHeight: number;
-    pageSize: number;
-    startIndex: number;
-    endIndex: number;
-    rowHeight: number;
-    offsetTop: number;
-    scrollTop: number;
-    scrollHeight: number;
-    translateY: number;
-}>, Ref<{
-    containerWidth: number;
-    scrollWidth: number;
-    startIndex: number;
-    endIndex: number;
-    offsetLeft: number;
-    scrollLeft: number;
-}, VirtualScrollXStore | {
-    containerWidth: number;
-    scrollWidth: number;
-    startIndex: number;
-    endIndex: number;
-    offsetLeft: number;
-    scrollLeft: number;
-}>, import('vue').ComputedRef<any>, import('vue').ComputedRef<PrivateRowDT[]>, import('vue').ComputedRef<number>, import('vue').ComputedRef<any>, import('vue').ComputedRef<number>, import('vue').ComputedRef<number>, (height?: number) => void, (height?: number) => void, () => void, (sTop?: number) => void, (sLeft?: number) => void, (rowKey: UniqKey, height?: number | null) => void, () => void, () => void, import('vue').ComputedRef<PrivateStkTableColumn<PrivateRowDT>[][]>, import('vue').ComputedRef<number>, import('vue').ComputedRef<{
+export declare function useVirtualScroll(props: any, tableContainerRef: Ref<HTMLElement | undefined>, trRef: Ref<HTMLTableRowElement[] | undefined>, dataSourceCopy: ShallowRef<PrivateRowDT[]>, tableHeaderLast: ShallowRef<PrivateStkTableColumn<PrivateRowDT>[]>, tableHeaders: ShallowRef<PrivateStkTableColumn<PrivateRowDT>[][]>, rowKeyGen: RowKeyGen, maxRowSpan: Map<UniqKey, number>, 
+/** 全局最大 rowspan（限定跨界修正扫描范围用） */
+getMaxRowSpanValue: () => number, scrollbarOptions: Ref<Required<ScrollbarOptions>>, isExperimentalScrollY: Ref<boolean | undefined>, 
+/** mergeCells 结果共享缓存（与 useMergeCells 共用，避免重复调用用户回调） */
+mergeCellsCache: MergeCellsCache): readonly [ShallowRef<VirtualScrollStore, VirtualScrollStore>, ShallowRef<VirtualScrollXStore, VirtualScrollXStore>, import('vue').ComputedRef<any>, import('vue').ComputedRef<PrivateRowDT[]>, import('vue').ComputedRef<number>, import('vue').ComputedRef<any>, import('vue').ComputedRef<number>, import('vue').ComputedRef<number>, (height?: number) => void, (height?: number) => void, () => void, (sTop?: number) => void, (sLeft?: number) => void, (rowKey: UniqKey, height?: number | null) => void, () => void, () => void, import('vue').ComputedRef<PrivateStkTableColumn<PrivateRowDT>[][]>, import('vue').ComputedRef<number>, import('vue').ComputedRef<{
     startIndex: number;
     endIndex: number;
     offsetLeft: number;
-}>, import('vue').ComputedRef<PrivateStkTableColumn<PrivateRowDT>[]>];
+}>, import('vue').ComputedRef<PrivateStkTableColumn<PrivateRowDT>[]>, import('vue').ComputedRef<{
+    prefix: PrivateStkTableColumn<PrivateRowDT>[];
+    leftExpand: PrivateStkTableColumn<PrivateRowDT>[];
+    viewport: PrivateStkTableColumn<PrivateRowDT>[];
+    suffix: PrivateStkTableColumn<PrivateRowDT>[];
+    /** leftExpand 起始的绝对叶子列索引（mergeCells 缓存键用） */
+    leftExpandStart: number;
+} | null>];