stk-table-vue 0.2.9 → 0.3.0

package/README.md

@@ -12,10 +12,11 @@ repo:
 * [x] props.dataSource 为 shallowRef 时，高亮行不生效。(bug:2024.02.21)(resolved:0.2.3)
 
 ## Feature TODO:
-* [x] 高亮行，单元格。使用css keyframe实现。
-  - [x] 虚拟滚动默认通过js计算行高亮背景色，可通过 `useCss` 设置为css keyframe实现 。
+* [x] 高亮行，单元格。使用css @keyframes实现。
+  - [x] 虚拟滚动默认通过js计算行高亮背景色，可通过 `useCss` 设置为css @keyframe实现 。
   - [x] 支持配置高亮参数（持续时间，颜色，频率（虚拟滚动））。(`v0.2.9`)
   - [x] `setHighlightDimRow`/`setHighlightCellRow`支持自定义高亮css类名。(`v0.2.9`)
+  - [x] 使用 `Web Animations API` 实现高亮。
 * [x] 虚拟滚动。
   - [x] 纵向。
   - [x] 横向（必须设置列宽）。
@@ -43,7 +44,8 @@ repo:
 * [] 非虚拟滚动时，大数据分批加载。
 * [x] vue2.7支持（引入源码使用）。
   - [x] `props.optimizeVue2Scroll` 优化vue2虚拟滚动流畅度。(`v0.2.0`)
-* [x] `props.emptyCellText` 支持传入函数。(`v0.2.6`)
+* [x] 支持配置序号列。`StkTableColumn['type']`。(`v0.3.0`)
+
 
 
 
@@ -55,9 +57,21 @@ repo:
 import { StkTable } from 'stk-table-vue'
 import { ref } from 'vue'
 const stkTable = ref<InstanceType<typeof StkTable>>();
-// highlight
-stkTable.value.setHighlightDimRow([rowId]，{useCss:false,className:'custom-class-name'});// highlight row
-stkTable.value.setHighlightDimCell(rowId, colId,{className:'custom-class-name'}) // highlight cell
+
+// highlight row
+stkTable.value.setHighlightDimRow([rowKey]，{
+  method: 'css'|'js'|'animation',// 是否使用css @keyframe实现。虚拟滚动下默认false。
+  className: 'custom-class-name',// useCss 为true时生效。
+  keyframe: [{backgroundColor:'#aaa'},{backgroundColor: '#222'}],//same as https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Animations_API/Keyframe_Formats
+  duration: 2000,// 动画时长。
+});
+ // highlight cell
+stkTable.value.setHighlightDimCell(rowKey, colDataIndex, {
+  method: 'css'|'animation',
+  className:'custom-class-name',// method css 时生效。
+  keyframe: [{backgroundColor:'#aaa'},{backgroundColor: '#222'}], // method animation 时生效。
+  duration: 2000,// 动画时长。
+})
 </script>
 
 <template>
@@ -128,7 +142,7 @@ export type StkProps = {
   headerRowHeight?: number | null;
   /** 虚拟滚动 */
   virtual?: boolean;
-  /** x轴虚拟滚动 */
+  /** x轴虚拟滚动(必须设置列宽)*/
   virtualX?: boolean;
   /** 表格列配置 */
   columns?: StkTableColumn<any>[];
@@ -214,6 +228,11 @@ export type StkProps = {
     /** 高亮帧率(虚拟滚动生效) */
     fps?: number;
   };
+  /** 序号列配置 */
+  seqConfig?: {
+    /** 序号列起始下标 用于适配分页 */
+    startIndex?: number;
+  };
 };
 ```
 #### Emits
@@ -324,6 +343,11 @@ defineExpose({
 type Sorter<T> = boolean | ((data: T[], option: { order: Order; column: any }) => T[]);
 /** 表格列配置 */
 export type StkTableColumn<T extends Record<string, any>> = {
+    /**
+     * 列类型
+     * - seq 序号列
+     */
+    type?: 'seq';
     /** 取值id */
     dataIndex: keyof T & string;
     /** 表头文字 */
@@ -386,6 +410,51 @@ export type SortConfig<T extends Record<string, any>> = {
 };
 ```
 
+### setHighlightDimCell & setHighlightDimRow
+#### setHighlightDimCell
+```ts
+  setHighlightDimCell(
+    rowKeyValues: UniqKey[],
+      option: {
+        method?: 'css' | 'animation' | 'js';
+        /** @deprecated 请使用method */
+        useCss?: boolean;
+        className?: string;
+        keyframe?: Parameters<Animatable['animate']>['0'];
+        duration?: number;
+    } = {},
+    )
+```
+#### setHighlightDimRow
+```ts
+  setHighlightDimRow(
+    rowKeyValues: UniqKey[],
+      option: {
+        method?: 'css' | 'animation' | 'js';  
+        /** @deprecated 请使用method */
+        useCss?: boolean;
+        className?: string;
+        keyframe?: Parameters<Animatable['animate']>['0'];
+        duration?: number;
+    }
+  )
+```
+#### option
+| key |value| desc |
+| ---- | ---- | ---- |
+| method | `css` `animation` `js` | 设置高亮方式。虚拟滚动默认js。否则css |
+| ~~useCss~~  `deprecated` | `boolean`| ~~是否使用css~~ |
+| className | `string` | 设置高亮样式。method == 'css' 生效 |
+| keyframe | `Parameters<Animatable['animate']>['0']` | 设置高亮动画。method == 'animation' 生效。 |
+| duration | `number` | 设置高亮动画持续时间。 method='css'状态下，用于移除class，如果传入了className则需要与自定义的动画时间一致。|
+
+##### option.method
+| `option.method`| desc |
+| ---- | ---- |
+| css | 使用css class 实现高亮。 |
+| animation | 使用 animation api 实现高亮。 |
+| js | 使用 js 循环计算颜色实现高亮。虚拟滚动默认使用js。 |
+
 ### Example
 ```vue
 <template>
@@ -458,6 +527,9 @@ export type SortConfig<T extends Record<string, any>> = {
 ### 鼠标悬浮表头时，不展示title
 * 将 `StkTableColumn` 中的 `title` 字段置为 "" 空字符串。这样th中就没有title了。
 * 使用 `StkTableColumn` 中的 `customHeaderCell` 属性中，自定义表头渲染。
+### 虚拟滚动高亮性能
+* 虚拟滚动下，高亮默认由js计算背景实现。好处是滚动不影响高亮状态。
+* 在虚拟滚动下，高亮强制使用css @keyframes 实现动画。`setHighlightDimRow`/`setHighlightCellRow` 最后一个参数传入 `{useCss: true}` 即可。
 
 
 ## Other

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

@@ -1,4 +1,4 @@
-import { HighlightConfig, Order, SortConfig, SortOption, SortState, StkTableColumn, UniqKeyProp } from './types/index';
+import { HighlightConfig, Order, SeqConfig, SortConfig, SortOption, SortState, StkTableColumn, UniqKeyProp } from './types/index';
 /** Generic stands for DataType */
 type DT = any;
 /**
@@ -56,7 +56,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     headerRowHeight?: number | null | undefined;
     /** 虚拟滚动 */
     virtual?: boolean | undefined;
-    /** x轴虚拟滚动 */
+    /** x轴虚拟滚动(必须设置列宽)*/
     virtualX?: boolean | undefined;
     /** 表格列配置 */
     columns?: StkTableColumn<any>[] | undefined;
@@ -122,6 +122,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     hideHeaderTitle?: boolean | string[] | undefined;
     /** 高亮配置 */
     highlightConfig?: HighlightConfig | undefined;
+    /** 序号列配置 */
+    seqConfig?: SeqConfig | undefined;
 }>, {
     width: string;
     fixedMode: boolean;
@@ -159,6 +161,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     };
     hideHeaderTitle: boolean;
     highlightConfig: () => {};
+    seqConfig: () => {};
 }>, {
     /** 初始化横向纵向虚拟滚动 */
     initVirtualScroll: (height?: number | undefined) => void;
@@ -171,11 +174,17 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 设置高亮渐暗单元格 */
     setHighlightDimCell: (rowKeyValue: string, dataIndex: string, option?: {
         className?: string | undefined;
+        method?: "css" | "animation" | undefined;
+        keyframe?: Keyframe[] | PropertyIndexedKeyframes | null | undefined;
+        duration?: number | undefined;
     }) => void;
     /** 设置高亮渐暗行 */
     setHighlightDimRow: (rowKeyValues: import("./types/index").UniqKey[], option?: {
+        method?: "css" | "animation" | "js" | undefined;
         useCss?: boolean | undefined;
         className?: string | undefined;
+        keyframe?: Keyframe[] | PropertyIndexedKeyframes | null | undefined; /** v-model:columns col resize 时更新宽度*/
+        duration?: number | undefined;
     }) => void;
     /** 表格排序列dataIndex */
     sortCol: import("vue").Ref<string | null | undefined>;
@@ -227,7 +236,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     headerRowHeight?: number | null | undefined;
     /** 虚拟滚动 */
     virtual?: boolean | undefined;
-    /** x轴虚拟滚动 */
+    /** x轴虚拟滚动(必须设置列宽)*/
     virtualX?: boolean | undefined;
     /** 表格列配置 */
     columns?: StkTableColumn<any>[] | undefined;
@@ -293,6 +302,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     hideHeaderTitle?: boolean | string[] | undefined;
     /** 高亮配置 */
     highlightConfig?: HighlightConfig | undefined;
+    /** 序号列配置 */
+    seqConfig?: SeqConfig | undefined;
 }>, {
     width: string;
     fixedMode: boolean;
@@ -330,6 +341,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     };
     hideHeaderTitle: boolean;
     highlightConfig: () => {};
+    seqConfig: () => {};
 }>>> & {
     onScroll?: ((ev: Event, data: {
         startIndex: number;
@@ -385,6 +397,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     sortConfig: SortConfig<any>;
     hideHeaderTitle: boolean | string[];
     highlightConfig: HighlightConfig;
+    seqConfig: SeqConfig;
 }, {}>, {
     tableHeader?(_: {
         col: StkTableColumn<any>;

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

@@ -16,10 +16,11 @@ export declare const HIGHLIGHT_COLOR: {
 /** 高亮持续时间 */
 export declare const HIGHLIGHT_DURATION = 2000;
 /** 高亮变更频率 */
-export declare const HIGHLIGHT_FREQ = 100;
+export declare const HIGHLIGHT_FREQ: number;
 /** 高亮行class */
 export declare const HIGHLIGHT_ROW_CLASS = "highlight-row";
 /** 高连单元格class */
 export declare const HIGHLIGHT_CELL_CLASS = "highlight-cell";
 /** 是否兼容低版本模式 */
 export declare const IS_LEGACY_MODE: boolean;
+export declare const STK_ID_PREFIX = "stk";

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

@@ -15,6 +15,11 @@ export type CustomHeaderCellFunc<T extends Record<string, any>> = (props: {
 }) => VNode;
 /** 表格列配置 */
 export type StkTableColumn<T extends Record<string, any>> = {
+    /**
+     * 列类型
+     * - seq 序号列
+     */
+    type?: 'seq';
     /** 取值id */
     dataIndex: keyof T & string;
     /** 表头文字 */
@@ -62,6 +67,8 @@ export type StkTableColumn<T extends Record<string, any>> = {
     children?: StkTableColumn<T>[];
     /** 父节点引用 */
     __PARENT__?: StkTableColumn<T> | null;
+    /** 保存计算的宽度。横向虚拟滚动用。 */
+    __WIDTH__?: number;
 };
 export type SortOption<T extends Record<string, any>> = Pick<StkTableColumn<T>, 'sorter' | 'dataIndex' | 'sortField' | 'sortType'>;
 /** 排序状态 */
@@ -103,18 +110,12 @@ export declare const enum TagType {
 export type HighlightConfig = {
     /** 高亮持续时间(s) */
     duration?: number;
-    /** 高亮背景色 */
-    color?: {
-        light?: {
-            from: string;
-            to: string;
-        };
-        dark?: {
-            from: string;
-            to: string;
-        };
-    };
-    /** 高亮帧率(虚拟滚动生效) */
+    /** 高亮帧率 */
     fps?: number;
 };
+/** 序号列配置 */
+export type SeqConfig = {
+    /** 序号列起始下标 用于适配分页 */
+    startIndex?: number;
+};
 export {};

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

@@ -1,7 +1,7 @@
 import { Ref } from 'vue';
 type Options = {
     props: any;
-    tableContainer: Ref<HTMLElement | undefined>;
+    tableContainerRef: Ref<HTMLElement | undefined>;
     initVirtualScroll: () => void;
     /** 防抖延时 */
     debounceMs: number;
@@ -10,5 +10,5 @@ type Options = {
  * 窗口变化自动重置虚拟滚动
  * @param param0
  */
-export declare function useAutoResize({ tableContainer, initVirtualScroll, props, debounceMs }: Options): void;
+export declare function useAutoResize({ tableContainerRef, initVirtualScroll, props, debounceMs }: Options): void;
 export {};

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

@@ -1,15 +1,15 @@
-import { Ref } from 'vue';
+import { Ref, ShallowRef } from 'vue';
 import { StkTableColumn } from './types';
 type Params<DT extends Record<string, any>> = {
     props: any;
     emits: any;
-    tableContainer: Ref<HTMLElement | undefined>;
-    tableHeaderLast: Ref<StkTableColumn<DT>[]>;
-    colResizeIndicator: Ref<HTMLElement | undefined>;
+    tableContainerRef: Ref<HTMLElement | undefined>;
+    tableHeaderLast: ShallowRef<StkTableColumn<DT>[]>;
+    colResizeIndicatorRef: Ref<HTMLElement | undefined>;
     colKeyGen: (p: any) => string;
 };
 /** 列宽拖动 */
-export declare function useColResize<DT extends Record<string, any>>({ tableContainer, tableHeaderLast, colResizeIndicator, props, emits, colKeyGen, }: Params<DT>): {
+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;

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

@@ -1,17 +1,17 @@
-import { Ref } from 'vue';
+import { Ref, ShallowRef } from 'vue';
 import { StkTableColumn } from './types';
 type Params<T extends Record<string, any>> = {
     props: any;
     colKeyGen: (col: StkTableColumn<T>) => string;
-    tableHeaders: Ref<StkTableColumn<T>[][]>;
-    tableHeaderLast: Ref<StkTableColumn<T>[]>;
-    tableContainer: Ref<HTMLDivElement | undefined>;
+    tableHeaders: ShallowRef<StkTableColumn<T>[][]>;
+    tableHeaderLast: ShallowRef<StkTableColumn<T>[]>;
+    tableContainerRef: Ref<HTMLDivElement | undefined>;
 };
 /**
  * 固定列处理
  * @returns
  */
-export declare function useFixedCol<DT extends Record<string, any>>({ props, colKeyGen, tableHeaders, tableHeaderLast, tableContainer }: Params<DT>): {
+export declare function useFixedCol<DT extends Record<string, any>>({ props, colKeyGen, tableHeaders, tableHeaderLast, tableContainerRef }: Params<DT>): {
     /** 固定列class */
     fixedColClassMap: import("vue").ComputedRef<Map<any, any>>;
     /** 处理固定列阴影 */

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

@@ -1,9 +1,9 @@
-import { CSSProperties, Ref } from 'vue';
+import { CSSProperties, Ref, ShallowRef } from 'vue';
 import { StkTableColumn, TagType } from './types';
 import { VirtualScrollStore, VirtualScrollXStore } from './useVirtualScroll';
 type Options<T extends Record<string, any>> = {
     props: any;
-    tableHeaders: Ref<StkTableColumn<T>[][]>;
+    tableHeaders: ShallowRef<StkTableColumn<T>[][]>;
     virtualScroll: Ref<VirtualScrollStore>;
     virtualScrollX: Ref<VirtualScrollXStore>;
     virtualX_on: Ref<boolean>;
@@ -15,6 +15,6 @@ type Options<T extends Record<string, any>> = {
  * @returns
  */
 export declare function useFixedStyle<DT extends Record<string, any>>({ props, tableHeaders, virtualScroll, virtualScrollX, virtualX_on, virtualX_offsetRight, }: Options<DT>): {
-    getFixedStyle: (tagType: TagType, col: StkTableColumn<DT>, depth?: number) => CSSProperties;
+    getFixedStyle: (tagType: TagType, col: StkTableColumn<DT>, depth?: number) => CSSProperties | null;
 };
 export {};

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

@@ -2,27 +2,27 @@ import { Ref } from 'vue';
 import { UniqKey } from './types';
 type Params = {
     props: any;
-    tableContainer: Ref<HTMLElement | undefined>;
-};
-/** 高亮行保存的东西 */
-type HighlightRowStore = {
-    bgc: string;
-    bgc_progress_ms: number;
-    bgc_progress: number;
+    stkTableId: string;
+    tableContainerRef: Ref<HTMLDivElement | undefined>;
 };
 /**
  * 高亮单元格，行
- * row中新增_bgc_progress_ms 属性控制高亮状态,_bgc控制颜色
  */
-export declare function useHighlight({ props, tableContainer }: Params): {
-    highlightRowStore: Ref<Record<UniqKey, HighlightRowStore>>;
-    highlightFrom: import("vue").ComputedRef<string>;
+export declare function useHighlight({ props, stkTableId, tableContainerRef }: Params): {
+    highlightSteps: number;
     setHighlightDimRow: (rowKeyValues: UniqKey[], option?: {
+        method?: 'css' | 'animation' | 'js';
+        /** @deprecated 请使用method */
         useCss?: boolean;
         className?: string;
+        keyframe?: Parameters<Animatable['animate']>['0'];
+        duration?: number;
     }) => void;
     setHighlightDimCell: (rowKeyValue: string, dataIndex: string, option?: {
         className?: string;
+        method?: 'css' | 'animation';
+        keyframe?: Parameters<Animatable['animate']>['0'];
+        duration?: number;
     }) => void;
 };
 export {};

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

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

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

@@ -2,10 +2,10 @@ import { Ref, ShallowRef } from 'vue';
 import { StkTableColumn } from './types';
 type Option<DT extends Record<string, any>> = {
     props: any;
-    tableContainer: Ref<HTMLElement | undefined>;
+    tableContainerRef: Ref<HTMLElement | undefined>;
     dataSourceCopy: ShallowRef<DT[]>;
-    tableHeaderLast: Ref<StkTableColumn<DT>[]>;
-    tableHeaders: Ref<StkTableColumn<DT>[][]>;
+    tableHeaderLast: ShallowRef<StkTableColumn<DT>[]>;
+    tableHeaders: ShallowRef<StkTableColumn<DT>[][]>;
 };
 /** 暂存纵向虚拟滚动的数据 */
 export type VirtualScrollStore = {
@@ -42,7 +42,7 @@ export type VirtualScrollXStore = {
  * @param param0
  * @returns
  */
-export declare function useVirtualScroll<DT extends Record<string, any>>({ props, tableContainer, dataSourceCopy, tableHeaderLast, tableHeaders, }: Option<DT>): {
+export declare function useVirtualScroll<DT extends Record<string, any>>({ props, tableContainerRef, dataSourceCopy, tableHeaderLast, tableHeaders, }: Option<DT>): {
     virtualScroll: Ref<{
         containerHeight: number;
         pageSize: number;

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

@@ -23,7 +23,15 @@ export declare function insertToOrderedArray<T extends object>(sortState: SortSt
 export declare function tableSort<T extends Record<string, any>>(sortOption: SortOption<T>, order: Order, dataSource: T[], sortConfig?: SortConfig<T>): T[];
 /** 表头column配置的层级 */
 export declare function howDeepTheHeader(arr: StkTableColumn<any>[], level?: number): number;
-/** 获取列宽 */
+/**
+ * 获取列宽
+ *
+ * 关于列宽的操作往往在横向滚动中使用。既然已经有横向滚动了，则列宽会被压缩至minWidth，所以优先取minWidth
+ */
 export declare function getColWidth(col: StkTableColumn<any> | null): number;
-/** 获取列宽配置。用于支持列宽配置数字 */
-export declare function getColWidthStr(col: StkTableColumn<any> | null | undefined, key?: 'width' | 'minWidth' | 'maxWidth'): string | undefined;
+/** 获取计算后的宽度 */
+export declare function getCalculatedColWidth(col: StkTableColumn<any> | null): number;
+/** number列宽+px */
+export declare function transformWidthToStr(width?: string | number): string | undefined;
+/** 创建组件唯一标识 */
+export declare function createStkTableId(): string;