stk-table-vue 0.3.4 → 0.3.6

package/README.md

@@ -549,16 +549,19 @@ export type SortConfig<T extends Record<string, any>> = {
 ### 鼠标悬浮表头时，不展示title
 * 将 `StkTableColumn` 中的 `title` 字段置为 "" 空字符串。这样th中就没有title了。
 * 使用 `StkTableColumn` 中的 `customHeaderCell` 属性中，自定义表头渲染。
-### 性能
-#### highlight
-* 在虚拟滚动下高亮强制使用 `css @keyframes` 实现动画。`setHighlightDimRow`/`setHighlightCellRow` 最后一个参数传入 `{method: 'css'}` 即可。（滚动后动画会中断） 
-* 指定 `{method:'animation'}` 在虚拟滚动下使用animation api实现动画。好处是动画流畅，且滚动后动画不中断。坏处是不支持帧率配置。
+
+## Performance optimization
+### highlight
 * 配置 `props.highlightConfig.fps` 指定高亮帧率。降低帧率有利于性能。
-#### relative fixed
+### relative fixed
 * 配置 `props.cellFixedMode` 为 `relative` 时，将使用相对定位实现固定列与固定表头，相较于`sticky`的实现，渲染合成层更少。
 * 问题：若开启了纵向虚拟滚动，不开启横向虚拟滚动，且不设置某些列宽时。如果纵向滚动导致某些列宽变化，则会导致右侧固定列计算错误。
-#### tr 分层
-* 通过css选择器将 stk-table tbody tr 配置 `transform:translateZ(0)` 对每行 tr 进行分层。在 `customCell` 较多且复杂时，尝试开启此功能可能对性能有帮助。
+### tr 分层
+* 通过css选择器将 stk-table tbody tr 配置 `transform:translateZ(0)` 对每行 tr 进行分层。对性能有帮助。
+  - 提升合成层可能导致黑底红字字体颜色发生变化。
+  - 以下情况尝试开启此功能。
+    - 在 `customCell` 较多且复杂时。
+    - 大量 highlight 动画时。
 
 ## Other
 * `$*$` 兼容注释

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

@@ -1,4 +1,4 @@
-import { HighlightConfig, Order, SeqConfig, SortConfig, SortOption, SortState, StkTableColumn, UniqKey, UniqKeyProp } from './types/index';
+import { HighlightConfig, Order, SeqConfig, SortConfig, SortOption, SortState, StkTableColumn, UniqKeyProp } from './types/index';
 /** Generic stands for DataType */
 type DT = any;
 /**
@@ -191,7 +191,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
         duration?: number | undefined;
     }) => void;
     /** 设置高亮渐暗行 */
-    setHighlightDimRow: (rowKeyValues: UniqKey[], option?: {
+    setHighlightDimRow: (rowKeyValues: import("./types/index").UniqKey[], option?: {
         method?: "animation" | "css" | "js" | undefined;
         useCss?: boolean | undefined;
         className?: string | undefined;

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

@@ -8,7 +8,10 @@ type Sorter<T> = boolean | ((data: T[], option: {
 export type CustomCellFunc<T extends Record<string, any>> = (props: {
     row: T;
     col: StkTableColumn<T>;
+    /** row[col.dataIndex] 的值 */
     cellValue: any;
+    rowIndex: number;
+    colIndex: number;
 }) => VNode;
 export type CustomHeaderCellFunc<T extends Record<string, any>> = (props: {
     col: StkTableColumn<T>;

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

@@ -12,7 +12,5 @@ type Params<DT extends Record<string, any>> = {
 export declare function useColResize<DT extends Record<string, any>>({ tableContainerRef, tableHeaderLast, colResizeIndicatorRef, props, emits, colKeyGen, }: Params<DT>): {
     isColResizing: Ref<boolean>;
     onThResizeMouseDown: (e: MouseEvent, col: StkTableColumn<DT>, isPrev?: boolean) => void;
-    onThResizeMouseMove: (e: MouseEvent) => void;
-    onThResizeMouseUp: (e: MouseEvent) => void;
 };
 export {};

package/lib/src/StkTable/{utils.d.ts → utils/index.d.ts}

@@ -1,4 +1,4 @@
-import { Order, SortConfig, SortOption, SortState, StkTableColumn } from './types';
+import { Order, SortConfig, SortOption, SortState, StkTableColumn } from '../types';
 /**
  * 对有序数组插入新数据
  * @param sortState

package/lib/src/StkTable/utils/useTriggerRef.d.ts

@@ -0,0 +1,15 @@
+import { Ref } from 'vue';
+type UseTriggerRef<T> = {
+    getRef: () => Ref<T>;
+    getValue: () => T;
+    setValue: (v: T) => void;
+    triggerRef: () => void;
+};
+/**
+ * 创建一个可触发更新的引用对象。
+ * @template T 引用对象的类型。
+ * @param initialValue 初始值。
+ * @returns 包含获取引用、获取值、设置值和触发更新的函数的对象。
+ */
+export declare function useTriggerRef<T>(initialValue: T): UseTriggerRef<T>;
+export {};

package/lib/stk-table-vue.js

@@ -260,10 +260,11 @@ function useColResize({
     const { clientX } = e;
     const { scrollLeft, scrollTop } = tableContainerRef.value;
     const { left } = tableContainerRef.value.getBoundingClientRect();
-    let colIndex = tableHeaderLast.value.findIndex((it) => colKeyGen.value(it) === colKeyGen.value(col));
+    const tableHeaderLastValue = tableHeaderLast.value;
+    let colIndex = tableHeaderLastValue.findIndex((it) => colKeyGen.value(it) === colKeyGen.value(col));
     if (isPrev) {
       colIndex -= 1;
-      col = tableHeaderLast.value[colIndex];
+      col = tableHeaderLastValue[colIndex];
     }
     const offsetTableX = clientX - left + scrollLeft;
     isColResizing.value = true;
@@ -337,9 +338,7 @@ function useColResize({
   }
   return {
     isColResizing,
-    onThResizeMouseDown,
-    onThResizeMouseMove,
-    onThResizeMouseUp
+    onThResizeMouseDown
   };
 }
 function useFixedCol({ props, colKeyGen, tableHeaders, tableHeaderLast, tableContainerRef }) {
@@ -350,10 +349,11 @@ function useFixedCol({ props, colKeyGen, tableHeaders, tableHeaderLast, tableCon
   const fixedShadowCols = shallowRef([]);
   const fixedColClassMap = computed(() => {
     const colMap = /* @__PURE__ */ new Map();
+    const fixedShadowColsValue = fixedShadowCols.value;
     tableHeaders.value.forEach((cols) => {
       cols.forEach((col) => {
         const { showR, showL } = fixedShadow.value;
-        const showShadow = props.fixedColShadow && col.fixed && (showL && col.fixed === "left" || showR && col.fixed === "right") && fixedShadowCols.value.includes(col);
+        const showShadow = props.fixedColShadow && col.fixed && (showL && col.fixed === "left" || showR && col.fixed === "right") && fixedShadowColsValue.includes(col);
         const classObj = {
           "fixed-cell": col.fixed,
           ["fixed-cell--" + col.fixed]: col.fixed,
@@ -367,10 +367,11 @@ function useFixedCol({ props, colKeyGen, tableHeaders, tableHeaderLast, tableCon
   function dealFixedColShadow() {
     if (!props.fixedColShadow)
       return;
-    fixedShadowCols.value = [];
+    const fixedShadowColsTemp = [];
     let lastLeftCol = null;
-    for (let i = tableHeaderLast.value.length - 1; i >= 0; i--) {
-      const col = tableHeaderLast.value[i];
+    const tableHeaderLastValue = tableHeaderLast.value;
+    for (let i = tableHeaderLastValue.length - 1; i >= 0; i--) {
+      const col = tableHeaderLastValue[i];
       if (col.fixed === "left") {
         lastLeftCol = col;
         break;
@@ -379,16 +380,17 @@ function useFixedCol({ props, colKeyGen, tableHeaders, tableHeaderLast, tableCon
     let node = { __PARENT__: lastLeftCol };
     while (node = node.__PARENT__) {
       if (node.fixed) {
-        fixedShadowCols.value.push(node);
+        fixedShadowColsTemp.push(node);
       }
     }
-    const lastRightCol = tableHeaderLast.value.find((it) => it.fixed === "right");
+    const lastRightCol = tableHeaderLastValue.find((it) => it.fixed === "right");
     node = { __PARENT__: lastRightCol };
     while (node = node.__PARENT__) {
       if (node.fixed) {
-        fixedShadowCols.value.push(node);
+        fixedShadowColsTemp.push(node);
       }
     }
+    fixedShadowCols.value = fixedShadowColsTemp;
   }
   function updateFixedShadow() {
     if (!props.fixedColShadow)
@@ -877,31 +879,33 @@ function useVirtualScroll({
     return props.virtualX && tableHeaderLast.value.reduce((sum, col) => sum += getCalculatedColWidth(col), 0) > virtualScrollX.value.containerWidth + 100;
   });
   const virtualX_columnPart = computed(() => {
+    const tableHeaderLastValue = tableHeaderLast.value;
     if (virtualX_on.value) {
       const leftCols = [];
       const rightCols = [];
       const { startIndex, endIndex } = virtualScrollX.value;
       for (let i = 0; i < startIndex; i++) {
-        const col = tableHeaderLast.value[i];
-        if (col.fixed === "left")
+        const col = tableHeaderLastValue[i];
+        if ((col == null ? void 0 : col.fixed) === "left")
           leftCols.push(col);
       }
-      for (let i = endIndex; i < tableHeaderLast.value.length; i++) {
-        const col = tableHeaderLast.value[i];
-        if (col.fixed === "right")
+      for (let i = endIndex; i < tableHeaderLastValue.length; i++) {
+        const col = tableHeaderLastValue[i];
+        if ((col == null ? void 0 : col.fixed) === "right")
           rightCols.push(col);
       }
-      const mainColumns = tableHeaderLast.value.slice(startIndex, endIndex);
+      const mainColumns = tableHeaderLastValue.slice(startIndex, endIndex);
       return leftCols.concat(mainColumns).concat(rightCols);
     }
-    return tableHeaderLast.value;
+    return tableHeaderLastValue;
   });
   const virtualX_offsetRight = computed(() => {
     if (!virtualX_on.value)
       return 0;
     let width = 0;
-    for (let i = virtualScrollX.value.endIndex; i < tableHeaderLast.value.length; i++) {
-      const col = tableHeaderLast.value[i];
+    const tableHeaderLastValue = tableHeaderLast.value;
+    for (let i = virtualScrollX.value.endIndex; i < tableHeaderLastValue.length; i++) {
+      const col = tableHeaderLastValue[i];
       if (col.fixed !== "right") {
         width += getCalculatedColWidth(col);
       }
@@ -909,11 +913,15 @@ function useVirtualScroll({
     return width;
   });
   function initVirtualScrollY(height) {
+    if (height !== void 0 && typeof height !== "number") {
+      console.warn("initVirtualScrollY: height must be a number");
+      height = 0;
+    }
     if (!virtual_on.value)
       return;
     const { offsetHeight, scrollTop } = tableContainerRef.value || {};
     const { rowHeight } = virtualScroll.value;
-    const containerHeight = height ?? (offsetHeight || DEFAULT_TABLE_HEIGHT);
+    const containerHeight = height || offsetHeight || DEFAULT_TABLE_HEIGHT;
     const { headless, headerRowHeight } = props;
     let pageSize = Math.ceil(containerHeight / rowHeight);
     if (!headless) {
@@ -973,10 +981,10 @@ function useVirtualScroll({
   }
   let vue2ScrollXTimeout = null;
   function updateVirtualScrollX(sLeft = 0) {
-    var _a;
     if (!props.virtualX)
       return;
-    const headerLength = (_a = tableHeaderLast.value) == null ? void 0 : _a.length;
+    const tableHeaderLastValue = tableHeaderLast.value;
+    const headerLength = tableHeaderLastValue == null ? void 0 : tableHeaderLastValue.length;
     if (!headerLength)
       return;
     const { scrollLeft } = virtualScrollX.value;
@@ -986,7 +994,7 @@ function useVirtualScroll({
     let leftColWidthSum = 0;
     let leftFirstColRestWidth = 0;
     for (let colIndex = 0; colIndex < headerLength; colIndex++) {
-      const col = tableHeaderLast.value[colIndex];
+      const col = tableHeaderLastValue[colIndex];
       const colWidth = getCalculatedColWidth(col);
       startIndex++;
       if (col.fixed === "left") {
@@ -1005,7 +1013,7 @@ function useVirtualScroll({
     const containerWidth = virtualScrollX.value.containerWidth - leftColWidthSum;
     let endIndex = headerLength;
     for (let colIndex = startIndex + 1; colIndex < headerLength; colIndex++) {
-      const col = tableHeaderLast.value[colIndex];
+      const col = tableHeaderLastValue[colIndex];
       colWidthSum += getCalculatedColWidth(col);
       if (colWidthSum >= containerWidth) {
         endIndex = colIndex + 1;
@@ -1216,14 +1224,20 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       () => props.columns,
       () => {
         dealColumns();
-        nextTick(initVirtualScrollX);
+        nextTick(() => {
+          initVirtualScrollX();
+          dealFixedColShadow();
+        });
       }
     );
     watch(
       () => props.virtualX,
       () => {
         dealColumns();
-        nextTick(initVirtualScrollX);
+        nextTick(() => {
+          initVirtualScrollX();
+          dealFixedColShadow();
+        });
       }
     );
     watch(
@@ -1252,6 +1266,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     );
     watch(() => props.fixedColShadow, dealFixedColShadow);
     dealColumns();
+    dealFixedColShadow();
     onMounted(() => {
       initVirtualScroll();
       updateFixedShadow();
@@ -1264,7 +1279,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       setSorter(dataIndex, order, { force: false, silent });
     }
     function dealColumns() {
-      tableHeaders.value = [];
+      let tableHeadersTemp = [];
       const copyColumn = props.columns;
       const deep = howDeepTheHeader(copyColumn);
       const tempHeaderLast = [];
@@ -1272,8 +1287,8 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
         console.error("多级表头不支持横向虚拟滚动");
       }
       function flat(arr, parent, depth = 0) {
-        if (!tableHeaders.value[depth]) {
-          tableHeaders.value[depth] = [];
+        if (!tableHeadersTemp[depth]) {
+          tableHeadersTemp[depth] = [];
         }
         let allChildrenLen = 0;
         let allChildrenWidthSum = 0;
@@ -1294,7 +1309,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
             colWidth = getColWidth(col);
             tempHeaderLast.push(col);
           }
-          tableHeaders.value[depth].push(col);
+          tableHeadersTemp[depth].push(col);
           const rowSpan = col.children ? 1 : deep - depth;
           const colSpan = colChildrenLen;
           if (rowSpan !== 1) {
@@ -1310,8 +1325,8 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
         return [allChildrenLen, allChildrenWidthSum];
       }
       flat(copyColumn, null);
+      tableHeaders.value = tableHeadersTemp;
       tableHeaderLast.value = tempHeaderLast;
-      dealFixedColShadow();
     }
     function rowKeyGen(row) {
       if (!row)
@@ -1706,10 +1721,10 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
                       key: 0,
                       col,
                       row,
-                      "row-index": rowIndex,
-                      "col-index": colIndex,
-                      "cell-value": row[col.dataIndex]
-                    }, null, 8, ["col", "row", "row-index", "col-index", "cell-value"])) : (openBlock(), createElementBlock("div", {
+                      rowIndex,
+                      colIndex,
+                      cellValue: row[col.dataIndex]
+                    }, null, 8, ["col", "row", "rowIndex", "colIndex", "cellValue"])) : (openBlock(), createElementBlock("div", {
                       key: 1,
                       class: "table-cell-wrapper",
                       title: !col.type ? row[col.dataIndex] : ""

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "stk-table-vue",
-    "version": "0.3.4",
+    "version": "0.3.6",
     "description": "Simple realtime virtual table for vue3 and vue2.7",
     "main": "./lib/stk-table-vue.js",
     "types": "./lib/src/StkTable/index.d.ts",
@@ -32,7 +32,7 @@
     "author": "japlus",
     "repository": {
         "type": "git",
-        "url": "https://gitee.com/japlus/stk-table-vue"
+        "url": "https://github.com/ja-plus/stk-table-vue"
     },
     "license": "MIT",
     "devDependencies": {

package/src/StkTable/StkTable.vue

@@ -176,9 +176,9 @@
                             v-if="col.customCell"
                             :col="col"
                             :row="row"
-                            :row-index="rowIndex"
-                            :col-index="colIndex"
-                            :cell-value="row[col.dataIndex]"
+                            :rowIndex="rowIndex"
+                            :colIndex="colIndex"
+                            :cellValue="row[col.dataIndex]"
                         />
                         <div v-else class="table-cell-wrapper" :title="!col.type ? row[col.dataIndex] : ''">
                             <template v-if="col.type === 'seq'">
@@ -210,7 +210,7 @@
  */
 import { CSSProperties, computed, nextTick, onMounted, ref, shallowRef, toRaw, watch } from 'vue';
 import { DEFAULT_ROW_HEIGHT } from './const';
-import { HighlightConfig, Order, SeqConfig, SortConfig, SortOption, SortState, StkTableColumn, TagType, UniqKey, UniqKeyProp } from './types/index';
+import { HighlightConfig, Order, SeqConfig, SortConfig, SortOption, SortState, StkTableColumn, TagType, UniqKeyProp } from './types/index';
 import { useAutoResize } from './useAutoResize';
 import { useColResize } from './useColResize';
 import { useFixedCol } from './useFixedCol';
@@ -219,7 +219,7 @@ import { useHighlight } from './useHighlight';
 import { useKeyboardArrowScroll } from './useKeyboardArrowScroll';
 import { useThDrag } from './useThDrag';
 import { useVirtualScroll } from './useVirtualScroll';
-import { createStkTableId, getCalculatedColWidth, getColWidth, howDeepTheHeader, tableSort, transformWidthToStr } from './utils';
+import { createStkTableId, getCalculatedColWidth, getColWidth, howDeepTheHeader, tableSort, transformWidthToStr } from './utils/index';
 
 /** Generic stands for DataType */
 type DT = any;
@@ -596,14 +596,22 @@ watch(
     () => props.columns,
     () => {
         dealColumns();
-        nextTick(initVirtualScrollX);
+        // initVirtualScrollX 需要获取容器滚动宽度等。必须等渲染完成后再调用。因此使用nextTick。
+        nextTick(() => {
+            initVirtualScrollX();
+            dealFixedColShadow();
+        });
     },
 );
 watch(
     () => props.virtualX,
     () => {
         dealColumns();
-        nextTick(initVirtualScrollX);
+        // initVirtualScrollX 需要获取容器滚动宽度等。必须等渲染完成后再调用。因此使用nextTick。
+        nextTick(() => {
+            initVirtualScrollX();
+            dealFixedColShadow();
+        });
     },
 );
 
@@ -637,6 +645,7 @@ watch(
 watch(() => props.fixedColShadow, dealFixedColShadow);
 
 dealColumns();
+dealFixedColShadow();
 
 onMounted(() => {
     initVirtualScroll();
@@ -656,7 +665,7 @@ function dealDefaultSorter() {
  */
 function dealColumns() {
     // reset
-    tableHeaders.value = [];
+    let tableHeadersTemp: StkTableColumn<DT>[][] = [];
     const copyColumn = props.columns; // do not deep clone
     const deep = howDeepTheHeader(copyColumn);
     const tempHeaderLast: StkTableColumn<DT>[] = [];
@@ -673,8 +682,8 @@ function dealColumns() {
      * @param parentFixed 父节点固定列继承。
      */
     function flat(arr: StkTableColumn<DT>[], parent: StkTableColumn<DT> | null, depth = 0 /* , parentFixed: 'left' | 'right' | null = null */) {
-        if (!tableHeaders.value[depth]) {
-            tableHeaders.value[depth] = [];
+        if (!tableHeadersTemp[depth]) {
+            tableHeadersTemp[depth] = [];
         }
         /** 所有子节点数量 */
         let allChildrenLen = 0;
@@ -700,7 +709,7 @@ function dealColumns() {
                 tempHeaderLast.push(col); // 没有children的列作为colgroup
             }
             // 回溯
-            tableHeaders.value[depth].push(col);
+            tableHeadersTemp[depth].push(col);
             const rowSpan = col.children ? 1 : deep - depth;
             const colSpan = colChildrenLen;
             if (rowSpan !== 1) {
@@ -718,10 +727,8 @@ function dealColumns() {
 
     flat(copyColumn, null);
 
-    // tableHeaders.value = [...tableHeaders.value];
-
+    tableHeaders.value = tableHeadersTemp;
     tableHeaderLast.value = tempHeaderLast;
-    dealFixedColShadow();
 }
 
 /**

package/src/StkTable/types/index.ts

@@ -5,7 +5,15 @@ export type Order = null | 'asc' | 'desc';
 
 type Sorter<T> = boolean | ((data: T[], option: { order: Order; column: any }) => T[]);
 
-export type CustomCellFunc<T extends Record<string, any>> = (props: { row: T; col: StkTableColumn<T>; cellValue: any }) => VNode;
+export type CustomCellFunc<T extends Record<string, any>> = (props: {
+    row: T;
+    col: StkTableColumn<T>;
+    /** row[col.dataIndex] 的值 */
+    cellValue: any;
+    rowIndex: number;
+    colIndex: number;
+}) => VNode;
+
 export type CustomHeaderCellFunc<T extends Record<string, any>> = (props: { col: StkTableColumn<T> }) => VNode;
 
 /** 表格列配置 */

package/src/StkTable/useColResize.ts

@@ -77,12 +77,13 @@ export function useColResize<DT extends Record<string, any>>({
         const { clientX } = e;
         const { scrollLeft, scrollTop } = tableContainerRef.value;
         const { left } = tableContainerRef.value.getBoundingClientRect();
+        const tableHeaderLastValue = tableHeaderLast.value;
         /** 列下标 */
-        let colIndex = tableHeaderLast.value.findIndex(it => colKeyGen.value(it) === colKeyGen.value(col));
+        let colIndex = tableHeaderLastValue.findIndex(it => colKeyGen.value(it) === colKeyGen.value(col));
         if (isPrev) {
             // 上一列
             colIndex -= 1;
-            col = tableHeaderLast.value[colIndex];
+            col = tableHeaderLastValue[colIndex];
         }
         const offsetTableX = clientX - left + scrollLeft;
 
@@ -175,7 +176,5 @@ export function useColResize<DT extends Record<string, any>>({
     return {
         isColResizing,
         onThResizeMouseDown,
-        onThResizeMouseMove,
-        onThResizeMouseUp,
     };
 }

package/src/StkTable/useFixedCol.ts

@@ -29,6 +29,7 @@ export function useFixedCol<DT extends Record<string, any>>({ props, colKeyGen,
 
     const fixedColClassMap = computed(() => {
         const colMap = new Map();
+        const fixedShadowColsValue = fixedShadowCols.value;
         tableHeaders.value.forEach(cols => {
             cols.forEach(col => {
                 const { showR, showL } = fixedShadow.value;
@@ -36,7 +37,7 @@ export function useFixedCol<DT extends Record<string, any>>({ props, colKeyGen,
                     props.fixedColShadow &&
                     col.fixed &&
                     ((showL && col.fixed === 'left') || (showR && col.fixed === 'right')) &&
-                    fixedShadowCols.value.includes(col);
+                    fixedShadowColsValue.includes(col);
                 const classObj = {
                     'fixed-cell': col.fixed,
                     ['fixed-cell--' + col.fixed]: col.fixed,
@@ -51,11 +52,13 @@ export function useFixedCol<DT extends Record<string, any>>({ props, colKeyGen,
     /** 处理固定列阴影 */
     function dealFixedColShadow() {
         if (!props.fixedColShadow) return;
-        fixedShadowCols.value = [];
+        const fixedShadowColsTemp = [];
+
         // 找到最右边的固定列 findLast
         let lastLeftCol = null;
-        for (let i = tableHeaderLast.value.length - 1; i >= 0; i--) {
-            const col = tableHeaderLast.value[i];
+        const tableHeaderLastValue = tableHeaderLast.value;
+        for (let i = tableHeaderLastValue.length - 1; i >= 0; i--) {
+            const col = tableHeaderLastValue[i];
             if (col.fixed === 'left') {
                 lastLeftCol = col;
                 break;
@@ -65,18 +68,20 @@ export function useFixedCol<DT extends Record<string, any>>({ props, colKeyGen,
         let node: any = { __PARENT__: lastLeftCol };
         while ((node = node.__PARENT__)) {
             if (node.fixed) {
-                fixedShadowCols.value.push(node);
+                fixedShadowColsTemp.push(node);
             }
         }
 
         // 找到最左边的固定列
-        const lastRightCol = tableHeaderLast.value.find(it => it.fixed === 'right');
+        const lastRightCol = tableHeaderLastValue.find(it => it.fixed === 'right');
         node = { __PARENT__: lastRightCol };
         while ((node = node.__PARENT__)) {
             if (node.fixed) {
-                fixedShadowCols.value.push(node);
+                fixedShadowColsTemp.push(node);
             }
         }
+        // trigger
+        fixedShadowCols.value = fixedShadowColsTemp;
     }
 
     /** 滚动条变化时，更新需要展示阴影的列 */

package/src/StkTable/useVirtualScroll.ts

@@ -103,34 +103,42 @@ export function useVirtualScroll<DT extends Record<string, any>>({
     });
 
     const virtualX_columnPart = computed(() => {
+        const tableHeaderLastValue = tableHeaderLast.value;
         if (virtualX_on.value) {
             // 虚拟横向滚动，固定列要一直保持存在
             const leftCols = [];
             const rightCols = [];
+            /**
+             * 存在问题：
+             * table columns 从多到少时。比方原来的start=5,end=10，现在start=4,end=8。这时候endIndex就超出数组范围了。
+             * FIXME: 如果新列数 < endIndex，此时需要重新计算列startIndex和endIndex。
+             */
             const { startIndex, endIndex } = virtualScrollX.value;
+
             // 左侧固定列，如果在左边不可见区。则需要拿出来放在前面
             for (let i = 0; i < startIndex; i++) {
-                const col = tableHeaderLast.value[i];
-                if (col.fixed === 'left') leftCols.push(col);
+                const col = tableHeaderLastValue[i];
+                if (col?.fixed === 'left') leftCols.push(col);
             }
             // 右侧固定列，如果在右边不可见区。则需要拿出来放在后面
-            for (let i = endIndex; i < tableHeaderLast.value.length; i++) {
-                const col = tableHeaderLast.value[i];
-                if (col.fixed === 'right') rightCols.push(col);
+            for (let i = endIndex; i < tableHeaderLastValue.length; i++) {
+                const col = tableHeaderLastValue[i];
+                if (col?.fixed === 'right') rightCols.push(col);
             }
 
-            const mainColumns = tableHeaderLast.value.slice(startIndex, endIndex);
+            const mainColumns = tableHeaderLastValue.slice(startIndex, endIndex);
 
             return leftCols.concat(mainColumns).concat(rightCols);
         }
-        return tableHeaderLast.value;
+        return tableHeaderLastValue;
     });
 
     const virtualX_offsetRight = computed(() => {
         if (!virtualX_on.value) return 0;
         let width = 0;
-        for (let i = virtualScrollX.value.endIndex; i < tableHeaderLast.value.length; i++) {
-            const col = tableHeaderLast.value[i];
+        const tableHeaderLastValue = tableHeaderLast.value;
+        for (let i = virtualScrollX.value.endIndex; i < tableHeaderLastValue.length; i++) {
+            const col = tableHeaderLastValue[i];
             if (col.fixed !== 'right') {
                 width += getCalculatedColWidth(col);
             }
@@ -143,10 +151,14 @@ export function useVirtualScroll<DT extends Record<string, any>>({
      * @param {number} [height] 虚拟滚动的高度
      */
     function initVirtualScrollY(height?: number) {
+        if (height !== void 0 && typeof height !== 'number') {
+            console.warn('initVirtualScrollY: height must be a number');
+            height = 0;
+        }
         if (!virtual_on.value) return;
         const { offsetHeight, scrollTop } = tableContainerRef.value || {};
         const { rowHeight } = virtualScroll.value;
-        const containerHeight = height ?? (offsetHeight || DEFAULT_TABLE_HEIGHT);
+        const containerHeight = height || offsetHeight || DEFAULT_TABLE_HEIGHT;
         const { headless, headerRowHeight } = props;
         let pageSize = Math.ceil(containerHeight / rowHeight);
         if (!headless) {
@@ -228,7 +240,8 @@ export function useVirtualScroll<DT extends Record<string, any>>({
     /** 通过横向滚动条位置，计算横向虚拟滚动的参数 */
     function updateVirtualScrollX(sLeft = 0) {
         if (!props.virtualX) return;
-        const headerLength = tableHeaderLast.value?.length;
+        const tableHeaderLastValue = tableHeaderLast.value;
+        const headerLength = tableHeaderLastValue?.length;
         if (!headerLength) return;
 
         const { scrollLeft } = virtualScrollX.value;
@@ -242,7 +255,7 @@ export function useVirtualScroll<DT extends Record<string, any>>({
         let leftFirstColRestWidth = 0;
 
         for (let colIndex = 0; colIndex < headerLength; colIndex++) {
-            const col = tableHeaderLast.value[colIndex];
+            const col = tableHeaderLastValue[colIndex];
             const colWidth = getCalculatedColWidth(col);
             startIndex++;
             // fixed left 不进入计算列宽
@@ -264,7 +277,7 @@ export function useVirtualScroll<DT extends Record<string, any>>({
         const containerWidth = virtualScrollX.value.containerWidth - leftColWidthSum;
         let endIndex = headerLength;
         for (let colIndex = startIndex + 1; colIndex < headerLength; colIndex++) {
-            const col = tableHeaderLast.value[colIndex];
+            const col = tableHeaderLastValue[colIndex];
             colWidthSum += getCalculatedColWidth(col);
             // 列宽大于容器宽度则停止
             if (colWidthSum >= containerWidth) {

package/src/StkTable/{utils.ts → utils/index.ts}

@@ -1,5 +1,5 @@
-import { DEFAULT_COL_WIDTH, STK_ID_PREFIX } from './const';
-import { Order, SortConfig, SortOption, SortState, StkTableColumn } from './types';
+import { DEFAULT_COL_WIDTH, STK_ID_PREFIX } from '../const';
+import { Order, SortConfig, SortOption, SortState, StkTableColumn } from '../types';
 
 /** 是否空值 */
 function isEmptyValue(val: any, isNumber?: boolean) {

package/src/StkTable/utils/useTriggerRef.ts

@@ -0,0 +1,33 @@
+import { Ref, shallowRef } from 'vue';
+
+type UseTriggerRef<T> = {
+    getRef: () => Ref<T>;
+    getValue: () => T;
+    setValue: (v: T) => void;
+    triggerRef: () => void;
+};
+/**
+ * 创建一个可触发更新的引用对象。
+ * @template T 引用对象的类型。
+ * @param initialValue 初始值。
+ * @returns 包含获取引用、获取值、设置值和触发更新的函数的对象。
+ */
+export function useTriggerRef<T>(initialValue: T): UseTriggerRef<T> {
+    let value = initialValue;
+    const ref = shallowRef(value);
+
+    function getValue() {
+        return value;
+    }
+    function setValue(v: T) {
+        value = v;
+    }
+    function getRef() {
+        return ref;
+    }
+    function triggerRef() {
+        ref.value = value;
+    }
+
+    return { getRef, getValue, setValue, triggerRef };
+}