stk-table-vue 0.2.2 → 0.2.5

package/README.md

@@ -4,8 +4,13 @@ Vue3 简易虚拟滚动表格。用于实时数据展示，新数据行高亮渐
 
 Vue2.7支持引入源码(**ts**)使用。
 
+repo: 
+- [Github](https://github.com/ja-plus/stk-table-vue)
+- [Gitee](https://gitee.com/japlus/stk-table-vue) 🇨🇳
+
 ## Bug TODO:
-* [] props.dataSource 为 shallowRef 时，高亮行不生效。(2024.02.21)
+* [x] props.dataSource 为 shallowRef 时，高亮行不生效。(bug:2024.02.21)(resolved:0.2.3)
+
 ## Feature TODO:
 * [x] 高亮行，单元格。
 * [x] 虚拟滚动。
@@ -17,12 +22,12 @@ Vue2.7支持引入源码(**ts**)使用。
     - [] sticky column 动态计算阴影位置。
 * [] 列筛选。
 * [x] 斑马纹。
-  - [] 虚拟滚动斑马纹。
+  - [x] 虚拟滚动斑马纹。
 * [x] 表头拖动更改顺序。
 * [x] 表头拖动调整列宽。
 * [x] 排序
   - [x] 基本表头点击排序。
-  - [] 支持配置 `null` | `undefined` 永远排最后。
+  - [x] 支持配置 `null` | `undefined` 永远排最后。
   - [] 支持配置 string 使用 `String.prototype.localCompare` 排序。
 * 多级表头。
   - [x] 支持最多`2级`表头。
@@ -32,10 +37,10 @@ Vue2.7支持引入源码(**ts**)使用。
 * 鼠标悬浮在表格上，键盘滚动虚拟表格。
   - [x] 键盘 `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight` 按键支持。
   - [x] 键盘 `PageUp`/ `PageDown` 按键支持。
-* [] 不传row-key 时，自动按序号生成id。
 * [] 非虚拟滚动时，大数据分批加载。
 * [x] vue2.7支持（引入源码使用）。
   - [x] `props.optimizeVue2Scroll` 优化vue2虚拟滚动流畅度。
+* [] `props.emptyCellText` 支持传入函数。
 
 
 ## Usage
@@ -126,9 +131,9 @@ export type StkProps = {
   /** 表格数据源 */
   dataSource?: any[];
   /** 行唯一键 */
-  rowKey?: UniqKey;
+  rowKey?: UniqKeyProp;
   /** 列唯一键 */
-  colKey?: UniqKey;
+  colKey?: UniqKeyProp;
   /** 空值展示文字 */
   emptyCellText?: string;
   /** 暂无数据兜底高度是否撑满 */
@@ -181,8 +186,20 @@ export type StkProps = {
   /** 排序配置 */
   sortConfig?: {
     /** 空值是否排最下面 */
-    emptyToBottom: false,
+    emptyToBottom: boolean,
+    /** 默认排序（1.初始化时触发 2.排序方向为null时触发) */
+    defaultSort?: {
+        dataIndex: keyof T;
+        order: Order;
+    };
+    /**
+     * string排序是否使用 String.prototype.localCompare
+     * 默认true (历史设计问题，为了兼容，默认true)
+     */
+    stringLocaleCompare?: boolean;
   },
+  /** 隐藏头部title。可传入dataIndex数组 */
+  hideHeaderTitle?: boolean | string[];
 };
 ```
 #### Emits
@@ -192,7 +209,7 @@ export type StkProps = {
      * 排序变更触发
      * ```(col: StkTableColumn<DT>, order: Order, data: DT[])```
      */
-    (e: 'sort-change', col: StkTableColumn<DT>, order: Order, data: DT[], sortConfig:SortConfig): void;
+    (e: 'sort-change', col: StkTableColumn<DT>, order: Order, data: DT[], sortConfig: SortConfig): void;
     /**
      * 一行点击事件
      * ```(ev: MouseEvent, row: DT)```
@@ -398,3 +415,8 @@ export type StkTableColumn<T extends Record<string, any>> = {
   ]
 </script>
 ```
+
+## Special Example
+### 鼠标悬浮表头时，不展示title
+* 将 `StkTableColumn` 中的 `title` 字段置为 "" 空字符串。这样th中就没有title了。
+* 使用 `StkTableColumn` 中的 `customHeaderCell` 属性中，自定义表头渲染。

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

@@ -1,4 +1,4 @@
-import { Order, SortConfig, SortOption, SortState, StkTableColumn, UniqKey } from './types/index';
+import { Order, SortConfig, SortOption, SortState, StkTableColumn, UniqKeyProp } from './types/index';
 /** Generic stands for DataType */
 type DT = any;
 /**
@@ -11,14 +11,14 @@ declare function setCurrentRow(rowKey: string, option?: {
 }): void;
 /**
  * 设置表头排序状态
- * @param {string} dataIndex 列字段
- * @param {'asc'|'desc'|null} order
- * @param {object} option.sortOption 指定排序参数
- * @param {boolean} option.sort 是否触发排序
- * @param {boolean} option.silent 是否触发回调
+ * @param dataIndex 列字段
+ * @param order 正序倒序
+ * @param option.sortOption 指定排序参数。同 StkTableColumn 中排序相关字段。建议从columns中find得到。
+ * @param option.sort 是否触发排序-默认true
+ * @param option.silent 是否禁止触发回调-默认true
  */
-declare function setSorter(dataIndex: string, order: null | 'asc' | 'desc', option?: {
-    sortOption?: SortOption;
+declare function setSorter(dataIndex: string, order: Order, option?: {
+    sortOption?: SortOption<DT>;
     silent?: boolean;
     sort?: boolean;
 }): any[];
@@ -61,9 +61,9 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 表格数据源 */
     dataSource?: any[] | undefined;
     /** 行唯一键 */
-    rowKey?: UniqKey | undefined;
+    rowKey?: UniqKeyProp | undefined;
     /** 列唯一键 */
-    colKey?: UniqKey | undefined;
+    colKey?: UniqKeyProp | undefined;
     /** 空值展示文字 */
     emptyCellText?: string | undefined;
     /** 暂无数据兜底高度是否撑满 */
@@ -112,7 +112,9 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 优化vue2 滚动 */
     optimizeVue2Scroll?: boolean | undefined;
     /** 排序配置 */
-    sortConfig?: SortConfig | undefined;
+    sortConfig?: SortConfig<any> | undefined;
+    /** 隐藏头部title。可传入dataIndex数组 */
+    hideHeaderTitle?: boolean | string[] | undefined;
 }>, {
     width: string;
     fixedMode: boolean;
@@ -146,7 +148,9 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     optimizeVue2Scroll: boolean;
     sortConfig: () => {
         emptyToBottom: boolean;
+        stringLocaleCompare: boolean;
     };
+    hideHeaderTitle: boolean;
 }>, {
     /** 初始化横向纵向虚拟滚动 */
     initVirtualScroll: (height?: number | undefined) => void;
@@ -159,7 +163,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 设置高亮渐暗单元格 */
     setHighlightDimCell: (rowKeyValue: string, dataIndex: string) => void;
     /** 设置高亮渐暗行 */
-    setHighlightDimRow: (rowKeyValues: (string | number)[]) => void;
+    setHighlightDimRow: (rowKeyValues: import("./types/index").UniqKey[]) => void;
     /** 表格排序列dataIndex */
     sortCol: import("vue").Ref<string | null | undefined>;
     /** 获取当前排序状态 */
@@ -173,7 +177,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 获取表格数据 */
     getTableData: typeof getTableData;
 }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    "sort-change": (col: StkTableColumn<any>, order: Order, data: any[], sortConfig: SortConfig) => void;
+    "sort-change": (col: StkTableColumn<any>, order: Order, data: any[], sortConfig: SortConfig<any>) => void;
     "row-click": (ev: MouseEvent, row: any) => void;
     "current-change": (ev: MouseEvent | null, row: any) => void;
     "row-dblclick": (ev: MouseEvent, row: any) => void;
@@ -217,9 +221,9 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 表格数据源 */
     dataSource?: any[] | undefined;
     /** 行唯一键 */
-    rowKey?: UniqKey | undefined;
+    rowKey?: UniqKeyProp | undefined;
     /** 列唯一键 */
-    colKey?: UniqKey | undefined;
+    colKey?: UniqKeyProp | undefined;
     /** 空值展示文字 */
     emptyCellText?: string | undefined;
     /** 暂无数据兜底高度是否撑满 */
@@ -268,7 +272,9 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 优化vue2 滚动 */
     optimizeVue2Scroll?: boolean | undefined;
     /** 排序配置 */
-    sortConfig?: SortConfig | undefined;
+    sortConfig?: SortConfig<any> | undefined;
+    /** 隐藏头部title。可传入dataIndex数组 */
+    hideHeaderTitle?: boolean | string[] | undefined;
 }>, {
     width: string;
     fixedMode: boolean;
@@ -302,7 +308,9 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     optimizeVue2Scroll: boolean;
     sortConfig: () => {
         emptyToBottom: boolean;
+        stringLocaleCompare: boolean;
     };
+    hideHeaderTitle: boolean;
 }>>> & {
     onScroll?: ((ev: Event, data: {
         startIndex: number;
@@ -312,7 +320,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     "onTh-drag-start"?: ((dragStartKey: string) => any) | undefined;
     "onCol-order-change"?: ((dragStartKey: string, targetColKey: string) => any) | undefined;
     "onTh-drop"?: ((targetColKey: string) => any) | undefined;
-    "onSort-change"?: ((col: StkTableColumn<any>, order: Order, data: any[], sortConfig: SortConfig) => any) | undefined;
+    "onSort-change"?: ((col: StkTableColumn<any>, order: Order, data: any[], sortConfig: SortConfig<any>) => any) | undefined;
     "onRow-click"?: ((ev: MouseEvent, row: any) => any) | undefined;
     "onCurrent-change"?: ((ev: MouseEvent | null, row: any) => any) | undefined;
     "onRow-dblclick"?: ((ev: MouseEvent, row: any) => any) | undefined;
@@ -335,8 +343,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     virtualX: boolean;
     columns: StkTableColumn<any>[];
     dataSource: any[];
-    rowKey: UniqKey;
-    colKey: UniqKey;
+    rowKey: UniqKeyProp;
+    colKey: UniqKeyProp;
     emptyCellText: string;
     noDataFull: boolean;
     showNoData: boolean;
@@ -352,7 +360,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     autoResize: boolean | (() => void);
     fixedColShadow: boolean;
     optimizeVue2Scroll: boolean;
-    sortConfig: SortConfig;
+    sortConfig: SortConfig<any>;
+    hideHeaderTitle: boolean | string[];
 }, {}>, {
     tableHeader?(_: {
         col: StkTableColumn<any>;

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

@@ -1,3 +1,4 @@
 export { default as StkTable } from './StkTable.vue';
 export { tableSort, insertToOrderedArray } from './utils';
 export type { StkTableColumn } from './types/index';
+import './style.less';

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

@@ -63,16 +63,30 @@ export type StkTableColumn<T extends Record<string, any>> = {
     /** 父节点引用 */
     __PARENT__?: StkTableColumn<T> | null;
 };
-export type SortOption = Pick<StkTableColumn<any>, 'sorter' | 'dataIndex' | 'sortField' | 'sortType'>;
+export type SortOption<T extends Record<string, any>> = Pick<StkTableColumn<T>, 'sorter' | 'dataIndex' | 'sortField' | 'sortType'>;
+/** 排序状态 */
 export type SortState<T> = {
     dataIndex: T;
     order: null | 'asc' | 'desc';
     sortType?: 'number' | 'string';
 };
-export type UniqKey = string | ((param: any) => string);
+/** 唯一键 */
+export type UniqKey = string | number;
+export type UniqKeyFun = (param: any) => UniqKey;
+export type UniqKeyProp = UniqKey | UniqKeyFun;
 /** 排序配置 */
-export type SortConfig = {
+export type SortConfig<T extends Record<string, any>> = {
     /** 空值始终排在列表末尾 */
     emptyToBottom?: boolean;
+    /** 默认排序（1.初始化时触发 2.排序方向为null时触发) */
+    defaultSort?: {
+        dataIndex: keyof T;
+        order: Order;
+    };
+    /**
+     * string排序是否使用 String.prototype.localCompare
+     * 默认true (&$&应该false)
+     */
+    stringLocaleCompare?: boolean;
 };
 export {};

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

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

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

@@ -1,4 +1,5 @@
 import { Ref } from 'vue';
+import { UniqKey } from './types';
 type Params = {
     props: {
         theme: 'light' | 'dark';
@@ -6,14 +7,20 @@ type Params = {
         dataSource: any[];
     };
     tableContainer: Ref<HTMLElement | undefined>;
-    rowKeyGen: (p: any) => string;
+};
+/** 高亮行保存的东西 */
+type HighlightRowStore = {
+    bgc: string;
+    bgc_progress_ms: number;
+    bgc_progress: number;
 };
 /**
  * 高亮单元格，行
  * row中新增_bgc_progress_ms 属性控制高亮状态,_bgc控制颜色
  */
-export declare function useHighlight({ props, tableContainer, rowKeyGen }: Params): {
-    setHighlightDimRow: (rowKeyValues: Array<string | number>) => void;
+export declare function useHighlight({ props, tableContainer }: Params): {
+    highlightRowStore: Ref<Record<UniqKey, HighlightRowStore>>;
+    setHighlightDimRow: (rowKeyValues: UniqKey[]) => void;
     setHighlightDimCell: (rowKeyValue: string, dataIndex: string) => void;
 };
 export {};

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

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

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

@@ -8,18 +8,22 @@ import { Order, SortConfig, SortOption, SortState, StkTableColumn } from './type
  * @param newItem 要插入的数据
  * @param targetArray 表格数据
  */
-export declare function insertToOrderedArray<T extends object>(sortState: SortState<keyof T>, newItem: any, targetArray: T[]): T[];
+export declare function insertToOrderedArray<T extends object>(sortState: SortState<keyof T>, newItem: any, targetArray: T[], sortConfig?: SortConfig<T>): T[];
 /**
  * 表格排序抽离
  * 可以在组件外部自己实现表格排序，组件配置remote，使表格不排序。
  * 使用者在@sort-change事件中自行更改table props 'dataSource'完成排序。
  * TODO: key 唯一值，排序字段相同时，根据唯一值排序。
+ *
+ * sortConfig.defaultSort 会在order为null时生效
  * @param sortOption 列配置
  * @param order 排序方式
  * @param dataSource 排序的数组
  */
-export declare function tableSort(sortOption: SortOption, order: Order, dataSource: any[], sortConfig?: SortConfig): any[];
+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;
 /** 获取列宽 */
 export declare function getColWidth(col: StkTableColumn<any> | null): number;
+/** 获取列宽配置。用于支持列宽配置数字 */
+export declare function getColWidthStr(col: StkTableColumn<any> | null | undefined, key?: 'width' | 'minWidth' | 'maxWidth'): string | undefined;