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

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

@@ -1,5 +1,5 @@
 import { FilterStatus } from './custom-cells/FilterCell/types';
-import { AreaSelectionConfig, AreaSelectionRange, AutoRowHeightConfig, ColResizableConfig, DragRowConfig, ExpandConfig, ExperimentalConfig, FooterConfig, HeaderDragConfig, HighlightConfig, Order, PrivateRowDT, PrivateStkTableColumn, RowActiveOption, SeqConfig, SortConfig, StkTableColumn, TreeConfig, UniqKey, UniqKeyProp } from './types/index';
+import { AreaSelectionConfig, AreaSelectionRange, AutoRowHeightConfig, ColResizableConfig, DragRowConfig, ExpandConfig, ExperimentalConfig, FooterConfig, HeaderDragConfig, HighlightConfig, Order, PrivateRowDT, PrivateStkTableColumn, RowActiveOption, ScrollToOptions, SeqConfig, SortConfig, StkTableColumn, TreeConfig, UniqKey, UniqKeyProp } from './types/index';
 import { ScrollbarOptions } from './useScrollbar';
 
 declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<import('vue').ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
@@ -338,11 +338,16 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
     resetSorter: () => void;
     /**
      * 滚动至
+     * - 数字参数：scrollTo(top, left)，null 表示不改变该轴
+     * - 对象参数：scrollTo({ top, left, behavior })，top/left 可传像素数字或 { index, key, px } 目标
      *
-     * en: Scroll to
+     * en: Scroll to position or target row/column
      * @see {@link scrollTo}
      */
-    scrollTo: (top?: number | null, left?: number | null) => void;
+    scrollTo: {
+        (top?: number | null, left?: number | null): void;
+        (options: ScrollToOptions): void;
+    };
     /**
      * 获取表格数据
      *
@@ -765,12 +770,12 @@ declare const _default: __VLS_WithTemplateSlots<import('vue').DefineComponent<im
     sortConfig: SortConfig<any>;
     colKey: UniqKeyProp;
     headless: boolean;
+    rowHeight: number;
     autoRowHeight: boolean | AutoRowHeightConfig<any>;
     stripe: boolean;
     optimizeVue2Scroll: boolean;
     rowKey: UniqKeyProp;
     headerRowHeight: number | string;
-    rowHeight: number;
     scrollbar: boolean | ScrollbarOptions;
     fixedMode: boolean;
     theme: "light" | "dark";

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

@@ -7,7 +7,7 @@ import { VirtualScrollStore, VirtualScrollXStore } from '../useVirtualScroll';
  * 支持鼠标拖拽选择、键盘导航、复制粘贴等功能
  * en: Cell area selection feature with mouse drag, keyboard navigation, copy-paste, etc.
  */
-export declare function useAreaSelection<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): {
+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>;
     isSelecting: Ref<boolean, boolean>;
     get: () => {
@@ -21,3 +21,5 @@ export declare function useAreaSelection<DT extends Record<string, any>>(props:
     onMD: (e: MouseEvent) => void;
 };
 export declare const useAreaSelectionName = "useAreaSelection";
+export declare const useAreaSelection: typeof useAreaSelectionImpl;
+export {};

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

@@ -1,7 +1,7 @@
 export { useAreaSelection } from './features/index';
 export { registerFeature } from './registerFeature';
 export { default as StkTable } from './StkTable.vue';
-export type { AreaSelectionRange, Order, SortConfig, SortOption, SortState, StkTableColumn } from './types/index';
+export type { AreaSelectionRange, Order, ScrollAxisTarget, ScrollToFn, ScrollToOptions, SortConfig, SortOption, SortState, StkTableColumn } from './types/index';
 export { binarySearch, insertToOrderedArray, strCompare, tableSort } from './utils';
 export { createFilterCell } from './custom-cells/FilterCell/index';
 export type { CreateFilterCellOption, FilterStatus } from './custom-cells/FilterCell/index';

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

@@ -434,4 +434,43 @@ export type FooterConfig = {
      */
     position?: 'bottom' | 'top';
 };
+/**
+ * scrollTo options 重载中单个滚动轴的定位目标。
+ * 最终坐标 = `index` 或 `key` 解析出的基准偏移 + `px` 附加偏移。
+ */
+export interface ScrollAxisTarget {
+    /**
+     * 目标索引（0 起始）
+     * - `top` 轴：当前展示顺序（排序/筛选/树展开后）的行索引
+     * - `left` 轴：叶子列（最深层表头列）索引
+     * 与 `key` 同时给出时 `index` 优先
+     */
+    index?: number;
+    /**
+     * 目标键值
+     * - `top` 轴：`props.rowKey` 对应的行键值
+     * - `left` 轴：列的 `dataIndex`
+     */
+    key?: string | number;
+    /** 在基准偏移之上叠加的像素偏移，可为负值。仅传 `px` 时基准为 0 */
+    px?: number;
+}
+/** scrollTo 实例方法 options 重载的参数 */
+export interface ScrollToOptions {
+    /** 纵向目标：像素坐标或行定位目标。省略表示不改变纵向位置 */
+    top?: number | ScrollAxisTarget;
+    /** 横向目标：像素坐标或列定位目标。省略表示不改变横向位置 */
+    left?: number | ScrollAxisTarget;
+    /** 滚动行为，同原生 ScrollToOptions.behavior，默认 'auto'（立即跳转） */
+    behavior?: ScrollBehavior;
+}
+/**
+ * scrollTo 实例方法的函数签名（数字重载 + options 重载）。
+ * - 数字重载中 `null` 表示不改变对应轴，省略默认 0
+ * - options 重载中省略的轴表示不改变位置
+ */
+export interface ScrollToFn {
+    (top?: number | null, left?: number | null): void;
+    (options: ScrollToOptions): void;
+}
 export {};

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

@@ -50,7 +50,7 @@ export declare function useVirtualScroll(props: any, tableContainerRef: Ref<HTML
 /** 全局最大 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<{
+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, (count: number) => number, () => void, import('vue').ComputedRef<PrivateStkTableColumn<PrivateRowDT>[][]>, import('vue').ComputedRef<number>, import('vue').ComputedRef<{
     startIndex: number;
     endIndex: number;
     offsetLeft: number;
@@ -61,4 +61,9 @@ mergeCellsCache: MergeCellsCache): readonly [ShallowRef<VirtualScrollStore, Virt
     suffix: PrivateStkTableColumn<PrivateRowDT>[];
     /** leftExpand 起始的绝对叶子列索引（mergeCells 缓存键用） */
     leftExpandStart: number;
-} | null>];
+} | null>, () => {
+    mapSize: number;
+    mapKeys: string[];
+    cacheSize: number;
+    total: number;
+}];

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

@@ -0,0 +1,26 @@
+/**
+ * 行高 Fenwick 树（树状数组）：Float64Array 存储，维护各行高度的累计和。
+ * 用于变高（autoRowHeight / 展开列）模式下以 O(log n) 定位视口行范围与推导总高度，
+ * 替代原先每滚动帧 O(n) 的逐行累加。
+ * 支持：O(n) 建树、O(log n) 单点增量更新、O(log n) 前缀和查询、O(log n) 累计和下界查找（树上二分）。
+ */
+export declare class RowHeightFenwickTree {
+    /** 内部 1-based 索引，bit[0] 不使用 */
+    private bit;
+    readonly size: number;
+    /** 全部行高之和，更新时增量维护 */
+    total: number;
+    constructor(size: number);
+    /** O(n) 顺序建树：heights[i] 为第 i 行（0-based）高度 */
+    build(heights: ArrayLike<number>): void;
+    /** 单点增量更新：第 index 行（0-based）高度变化 delta，O(log n) */
+    add(index: number, delta: number): void;
+    /** 前 count 行的累计高度（前缀和），O(log n)；count 越界时钳制到 [0, size] */
+    query(count: number): number;
+    /**
+     * 累计和下界查找（树上二分，O(log n)）：
+     * 返回首个「累计高度（含本行）≥ target」的行索引（0-based）；
+     * 总高不足 target 时返回 size（不存在满足条件的行）。
+     */
+    findFirstPrefixGE(target: number): number;
+}