stk-table-vue 0.0.2 → 0.1.0

package/README.md

@@ -1,7 +1,7 @@
 # StkTable (Sticky Table)
 
 Vue3 简易虚拟滚动表格。用于实时数据展示，新数据行高亮渐暗动效。
-js体积(未压缩41kb)
+js体积(未压缩44kb)
 
 ## Feature TODO:
 * [x] 高亮行，单元格。
@@ -17,9 +17,11 @@ js体积(未压缩41kb)
 * [x] 支持table-layout: fixed 配置。
 * 鼠标悬浮在表格上，键盘滚动虚拟表格。
   - [x] 键盘 `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight` 按键支持。
-  - [] 键盘 `PageUp`/ `PageDown` 按键支持。
+  - [x] 键盘 `PageUp`/ `PageDown` 按键支持。
 * [x] 斑马纹。
-* [] 列固定阴影。
+* [x] 列固定阴影。
+  - [] 多级表头固定列阴影。
+  - [] sticky column 动态计算阴影位置。
 * [] 不传row-key 时，自动按序号生成id。
 * [] 列筛选。
 * [] 非虚拟滚动时，大数据分批加载。
@@ -42,8 +44,13 @@ stkTable.value.setHighlightDimCell(rowId, colId) // highlight cell
 </template>
 
 ```
+
+## Notice
+注意，组件会改动 `props.columns` 中的对象。如果多个组件 `columns` 数组元素存在引用同一个 `StkTableColumn` 对象。则考虑赋值 `columns` 前进行深拷贝。
+
 ## API
-### StkTable Component Props
+### StkTable Component 
+#### Props
 ```ts
 export type StkProps = {
   width?: string;
@@ -61,6 +68,8 @@ export type StkProps = {
   theme?: 'light' | 'dark';
   /** 行高 */
   rowHeight?: number;
+  /** 表头行高。default = rowHeight */
+  headerRowHeight?: number | null;
   /** 虚拟滚动 */
   virtual?: boolean;
   /** x轴虚拟滚动 */
@@ -116,10 +125,112 @@ export type StkProps = {
    * 传入方法表示resize后的回调
    */
   autoResize?: boolean | (() => void);
+  /** 是否展示固定列阴影。默认不展示。 */
+  fixedColShadow?: boolean;
 };
 ```
+#### Emits
+```js
+  {
+    /**
+     * 排序变更触发
+     * ```(col: StkTableColumn<DT>, order: Order, data: DT[])```
+     */
+    (e: 'sort-change', col: StkTableColumn<DT>, order: Order, data: DT[]): void;
+    /**
+     * 一行点击事件
+     * ```(ev: MouseEvent, row: DT)```
+     */
+    (e: 'row-click', ev: MouseEvent, row: DT): void;
+    /**
+     * 选中一行触发。ev返回null表示不是点击事件触发的
+     * ```(ev: MouseEvent | null, row: DT)```
+     */
+    (e: 'current-change', ev: MouseEvent | null, row: DT): void;
+    /**
+     * 行双击事件
+     * ```(ev: MouseEvent, row: DT)```
+     */
+    (e: 'row-dblclick', ev: MouseEvent, row: DT): void;
+    /**
+     * 表头右键事件
+     * ```(ev: MouseEvent)```
+     */
+    (e: 'header-row-menu', ev: MouseEvent): void;
+    /**
+     * 表体行右键点击事件
+     * ```(ev: MouseEvent, row: DT)```
+     */
+    (e: 'row-menu', ev: MouseEvent, row: DT): void;
+    /**
+     * 单元格点击事件
+     * ```(ev: MouseEvent, row: DT, col: StkTableColumn<DT>)```
+     */
+    (e: 'cell-click', ev: MouseEvent, row: DT, col: StkTableColumn<DT>): void;
+    /**
+     * 表头单元格点击事件
+     * ```(ev: MouseEvent, col: StkTableColumn<DT>)```
+     */
+    (e: 'header-cell-click', ev: MouseEvent, col: StkTableColumn<DT>): void;
+    /**
+     * 表格滚动事件
+     * ```(ev: Event, data: { startIndex: number; endIndex: number })```
+     */
+    (e: 'scroll', ev: Event, data: { startIndex: number; endIndex: number }): void;
+    /**
+     * 表格横向滚动事件
+     * ```(ev: Event)```
+     */
+    (e: 'scroll-x', ev: Event): void;
+    /**
+     * 表头列拖动事件
+     * ```(dragStartKey: string, targetColKey: string)```
+     */
+    (e: 'col-order-change', dragStartKey: string, targetColKey: string): void;
+    /**
+     * 表头列拖动开始
+     * ```(dragStartKey: string)```
+     */
+    (e: 'th-drag-start', dragStartKey: string): void;
+    /**
+     * 表头列拖动drop
+     * ```(targetColKey: string)```
+     */
+    (e: 'th-drop', targetColKey: string): void;
+    /** v-model:columns col resize 时更新宽度*/
+    (e: 'update:columns', cols: StkTableColumn<DT>[]): void;
+}
+```
+
+#### Expose
+```js
+defineExpose({
+  /** 初始化横向纵向虚拟滚动 */
+  initVirtualScroll,
+  /** 初始化横向虚拟滚动 */
+  initVirtualScrollX,
+  /** 初始化纵向虚拟滚动 */
+  initVirtualScrollY,
+  /** 设置当前选中行 */
+  setCurrentRow,
+  /** 设置高亮渐暗单元格 */
+  setHighlightDimCell,
+  /** 设置高亮渐暗行 */
+  setHighlightDimRow,
+  /** 表格排序列dataIndex */
+  sortCol,
+  /** 设置排序 */
+  setSorter,
+  /** 重置排序 */
+  resetSorter,
+  /** 滚动至 */
+  scrollTo,
+  /** 获取表格数据 */
+  getTableData,
+});
+```
 
-### StkTableColumn
+### StkTableColumn 列配置
 ``` ts
 type Sorter<T> = boolean | ((data: T[], option: { order: Order; column: any }) => T[]);
 /** 表格列配置 */
@@ -184,6 +295,7 @@ export type StkTableColumn<T extends Record<string, any>> = {
     no-data-full
     col-resizable
     auto-resize
+    fixed-col-shadow
     :col-min-width="10"
     :headless="false"
     :data-source="dataSource"
@@ -196,6 +308,7 @@ export type StkTableColumn<T extends Record<string, any>> = {
     @cell-click="onCellClick"
     @header-cell-click="onHeaderCellClick"
     @scroll="onTableScroll"
+    @scroll-x="onTableScrollX"
     @col-order-change="onColOrderChange"
   />
 </template>

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

@@ -46,6 +46,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     theme?: "light" | "dark" | undefined;
     /** 行高 */
     rowHeight?: number | undefined;
+    /** 表头行高。default = rowHeight */
+    headerRowHeight?: number | null | undefined;
     /** 虚拟滚动 */
     virtual?: boolean | undefined;
     /** x轴虚拟滚动 */
@@ -101,6 +103,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
      * 传入方法表示resize后的回调
      */
     autoResize?: boolean | (() => void) | undefined;
+    /** 是否展示固定列阴影。默认不展示。 */
+    fixedColShadow?: boolean | undefined;
 }>, {
     width: string;
     fixedMode: boolean;
@@ -110,6 +114,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     headless: boolean;
     theme: string;
     rowHeight: number;
+    headerRowHeight: null;
     virtual: boolean;
     virtualX: boolean;
     columns: () => never[];
@@ -129,17 +134,29 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     colMinWidth: number;
     bordered: boolean;
     autoResize: boolean;
+    fixedColShadow: boolean;
 }>, {
+    /** 初始化横向纵向虚拟滚动 */
     initVirtualScroll: (height?: number | undefined) => void;
+    /** 初始化横向虚拟滚动 */
     initVirtualScrollX: () => void;
+    /** 初始化纵向虚拟滚动 */
     initVirtualScrollY: (height?: number | undefined) => void;
+    /** 设置当前选中行 */
     setCurrentRow: typeof setCurrentRow;
+    /** 设置高亮渐暗单元格 */
     setHighlightDimCell: (rowKeyValue: string, dataIndex: string) => void;
+    /** 设置高亮渐暗行 */
     setHighlightDimRow: (rowKeyValues: (string | number)[]) => void;
+    /** 表格排序列dataIndex */
     sortCol: import("vue").Ref<string | null | undefined>;
+    /** 设置排序 */
     setSorter: typeof setSorter;
+    /** 重置排序 */
     resetSorter: typeof resetSorter;
+    /** 滚动至 */
     scrollTo: typeof scrollTo;
+    /** 获取表格数据 */
     getTableData: typeof getTableData;
 }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "sort-change": (col: StkTableColumn<any>, order: Order, data: any[]) => void;
@@ -175,6 +192,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     theme?: "light" | "dark" | undefined;
     /** 行高 */
     rowHeight?: number | undefined;
+    /** 表头行高。default = rowHeight */
+    headerRowHeight?: number | null | undefined;
     /** 虚拟滚动 */
     virtual?: boolean | undefined;
     /** x轴虚拟滚动 */
@@ -230,6 +249,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
      * 传入方法表示resize后的回调
      */
     autoResize?: boolean | (() => void) | undefined;
+    /** 是否展示固定列阴影。默认不展示。 */
+    fixedColShadow?: boolean | undefined;
 }>, {
     width: string;
     fixedMode: boolean;
@@ -239,6 +260,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     headless: boolean;
     theme: string;
     rowHeight: number;
+    headerRowHeight: null;
     virtual: boolean;
     virtualX: boolean;
     columns: () => never[];
@@ -258,6 +280,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     colMinWidth: number;
     bordered: boolean;
     autoResize: boolean;
+    fixedColShadow: boolean;
 }>>> & {
     onScroll?: ((ev: Event, data: {
         startIndex: number;
@@ -281,10 +304,11 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     minWidth: string;
     maxWidth: string;
     rowHeight: number;
+    headless: boolean;
+    headerRowHeight: number | null;
     colKey: UniqKey;
     stripe: boolean;
     fixedMode: boolean;
-    headless: boolean;
     theme: "light" | "dark";
     virtual: boolean;
     virtualX: boolean;
@@ -304,9 +328,10 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     colMinWidth: number;
     bordered: boolean | "h" | "v" | "body-v";
     autoResize: boolean | (() => void);
+    fixedColShadow: boolean;
 }, {}>, {
     tableHeader?(_: {
-        column: StkTableColumn<any>;
+        col: StkTableColumn<any>;
     }): any;
     empty?(_: {}): any;
 }>;

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

@@ -1,20 +1,21 @@
-export declare const Default_Col_Width = "100";
-export declare const Default_Table_Height = 100;
-export declare const Default_Table_Width = 200;
-/** 高亮背景色 */
-export declare const Highlight_Color: {
-    light: {
-        from: string;
-        to: string;
-    };
-    dark: {
-        from: string;
-        to: string;
-    };
-};
-/** 高亮持续时间 */
-export declare const Highlight_Duration = 2000;
-/** 高亮变更频率 */
-export declare const Highlight_Color_Change_Freq = 100;
-/** 是否兼容低版本模式 */
-export declare const Is_Legacy_Mode: boolean;
+export declare const Default_Col_Width = "100";
+export declare const Default_Table_Height = 100;
+export declare const Default_Table_Width = 200;
+export declare const Default_Row_Height = 28;
+/** 高亮背景色 */
+export declare const Highlight_Color: {
+    light: {
+        from: string;
+        to: string;
+    };
+    dark: {
+        from: string;
+        to: string;
+    };
+};
+/** 高亮持续时间 */
+export declare const Highlight_Duration = 2000;
+/** 高亮变更频率 */
+export declare const Highlight_Color_Change_Freq = 100;
+/** 是否兼容低版本模式 */
+export declare const Is_Legacy_Mode: boolean;

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

@@ -43,12 +43,25 @@ export type StkTableColumn<T extends Record<string, any>> = {
     fixed?: 'left' | 'right' | null;
     /** private */ rowSpan?: number;
     /** private */ colSpan?: number;
-    /**自定义 td 渲染内容 */
+    /**
+     * 自定义 td 渲染内容。
+     *
+     * 组件prop入参:
+     * - props.row 一行的记录。
+     * - props.col 列配置
+     */
     customCell?: Component | VNode | CustomCellFunc<T>;
-    /** 自定义 th 渲染内容 */
+    /**
+     * 自定义 th 渲染内容
+     *
+     * 组件prop入参:
+     * - props.col 列配置
+     */
     customHeaderCell?: Component | VNode | CustomHeaderCellFunc<T>;
     /** 二级表头 */
     children?: StkTableColumn<T>[];
+    /** 父节点引用 */
+    __PARENT__?: StkTableColumn<T> | null;
 };
 export type SortOption = Pick<StkTableColumn<any>, 'sorter' | 'dataIndex' | 'sortField' | 'sortType'>;
 export type SortState<T> = {

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

@@ -1,14 +1,17 @@
 import { Ref } from 'vue';
+import { StkTableColumn } from './types';
 import { VirtualScrollStore, VirtualScrollXStore } from './useVirtualScroll';
-type Options = {
-    scrollTo: (x: number | null, y: number | null) => void;
+type Options<DT extends Record<string, any>> = {
+    props: any;
+    scrollTo: (y: number | null, x: number | null) => void;
     virtualScroll: Ref<VirtualScrollStore>;
     virtualScrollX: Ref<VirtualScrollXStore>;
+    tableHeaders: Ref<StkTableColumn<DT>[][]>;
 };
 /**
  * 按下键盘箭头滚动。只有悬浮在表体上才能生效键盘。
  *
  * 在低版本浏览器中，虚拟滚动时，使用键盘滚动，等选中的行消失在视口外时，滚动会失效。
  */
-export declare function useKeyboardArrowScroll(targetElement: Ref<HTMLElement | undefined>, { scrollTo, virtualScroll, virtualScrollX }: Options): void;
+export declare function useKeyboardArrowScroll<DT extends Record<string, any>>(targetElement: Ref<HTMLElement | undefined>, { props, scrollTo, virtualScroll, virtualScrollX, tableHeaders }: Options<DT>): void;
 export {};