stk-table-vue 0.2.2 → 0.2.3

package/README.md

@@ -5,7 +5,8 @@ Vue3 简易虚拟滚动表格。用于实时数据展示，新数据行高亮渐
 Vue2.7支持引入源码(**ts**)使用。
 
 ## Bug TODO:
-* [] props.dataSource 为 shallowRef 时，高亮行不生效。(2024.02.21)
+* [x] props.dataSource 为 shallowRef 时，高亮行不生效。(bug:2024.02.21)(resolved:0.2.3)
+
 ## Feature TODO:
 * [x] 高亮行，单元格。
 * [x] 虚拟滚动。
@@ -22,7 +23,7 @@ Vue2.7支持引入源码(**ts**)使用。
 * [x] 表头拖动调整列宽。
 * [x] 排序
   - [x] 基本表头点击排序。
-  - [] 支持配置 `null` | `undefined` 永远排最后。
+  - [x] 支持配置 `null` | `undefined` 永远排最后。
   - [] 支持配置 string 使用 `String.prototype.localCompare` 排序。
 * 多级表头。
   - [x] 支持最多`2级`表头。
@@ -126,9 +127,9 @@ export type StkProps = {
   /** 表格数据源 */
   dataSource?: any[];
   /** 行唯一键 */
-  rowKey?: UniqKey;
+  rowKey?: UniqKeyProp;
   /** 列唯一键 */
-  colKey?: UniqKey;
+  colKey?: UniqKeyProp;
   /** 空值展示文字 */
   emptyCellText?: string;
   /** 暂无数据兜底高度是否撑满 */
@@ -181,7 +182,12 @@ export type StkProps = {
   /** 排序配置 */
   sortConfig?: {
     /** 空值是否排最下面 */
-    emptyToBottom: false,
+    emptyToBottom: boolean,
+    /** 默认排序（1.初始化时触发 2.排序方向为null时触发) */
+    defaultSort?: {
+        dataIndex: keyof T;
+        order: Order;
+    };
   },
 };
 ```
@@ -192,7 +198,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)```

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 指定排序参数
+ * @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,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 优化vue2 滚动 */
     optimizeVue2Scroll?: boolean | undefined;
     /** 排序配置 */
-    sortConfig?: SortConfig | undefined;
+    sortConfig?: SortConfig<any> | undefined;
 }>, {
     width: string;
     fixedMode: boolean;
@@ -159,7 +159,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 +173,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 +217,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 +268,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     /** 优化vue2 滚动 */
     optimizeVue2Scroll?: boolean | undefined;
     /** 排序配置 */
-    sortConfig?: SortConfig | undefined;
+    sortConfig?: SortConfig<any> | undefined;
 }>, {
     width: string;
     fixedMode: boolean;
@@ -312,7 +312,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 +335,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 +352,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__
     autoResize: boolean | (() => void);
     fixedColShadow: boolean;
     optimizeVue2Scroll: boolean;
-    sortConfig: SortConfig;
+    sortConfig: SortConfig<any>;
 }, {}>, {
     tableHeader?(_: {
         col: StkTableColumn<any>;

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

@@ -63,16 +63,25 @@ 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;
+    };
 };
 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/utils.d.ts

@@ -14,11 +14,13 @@ export declare function insertToOrderedArray<T extends object>(sortState: SortSt
  * 可以在组件外部自己实现表格排序，组件配置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;
 /** 获取列宽 */

package/lib/stk-table-vue.js

@@ -138,14 +138,18 @@ function separatedData(sortOption, targetDataSource, isNumber) {
 function tableSort(sortOption, order, dataSource, sortConfig = {}) {
   if (!(dataSource == null ? void 0 : dataSource.length))
     return dataSource || [];
-  sortConfig = Object.assign({ emptyToBottom: false }, sortConfig);
+  sortConfig = { emptyToBottom: false, ...sortConfig };
   let targetDataSource = [...dataSource];
+  let sortField = sortOption.sortField || sortOption.dataIndex;
+  if (!order && sortConfig.defaultSort) {
+    order = sortConfig.defaultSort.order;
+    sortField = sortConfig.defaultSort.dataIndex;
+  }
   if (typeof sortOption.sorter === "function") {
     const customSorterData = sortOption.sorter(targetDataSource, { order, column: sortOption });
     if (customSorterData)
       targetDataSource = customSorterData;
   } else if (order) {
-    const sortField = sortOption.sortField || sortOption.dataIndex;
     let { sortType } = sortOption;
     if (!sortType)
       sortType = typeof dataSource[0][sortField];
@@ -436,11 +440,14 @@ function useFixedStyle({ props, tableHeaderLast, virtualScroll, virtualScrollX,
     getFixedStyle
   };
 }
-function useHighlight({ props, tableContainer, rowKeyGen }) {
-  const highlightInter = computed(() => {
-    return interpolateRgb(Highlight_Color[props.theme].from, Highlight_Color[props.theme].to);
-  });
-  const highlightDimRows = /* @__PURE__ */ new Set();
+const HIGHLIGHT_ROW_CLASS = "highlight-row";
+const HIGHLIGHT_CELL_CLASS = "highlight-cell";
+function useHighlight({ props, tableContainer }) {
+  const highlightRowStore = ref({});
+  const highlightFrom = Highlight_Color[props.theme].from;
+  const highlightTo = Highlight_Color[props.theme].to;
+  const highlightInter = computed(() => interpolateRgb(highlightFrom, highlightTo));
+  const highlightDimRowKeys = /* @__PURE__ */ new Set();
   const highlightDimRowsTimeout = /* @__PURE__ */ new Map();
   const highlightDimCellsTimeout = /* @__PURE__ */ new Map();
   let calcHighlightDimLoop = false;
@@ -451,18 +458,17 @@ function useHighlight({ props, tableContainer, rowKeyGen }) {
     const recursion = () => {
       window.setTimeout(() => {
         const nowTs = Date.now();
-        const needDeleteRows = [];
-        highlightDimRows.forEach((row) => {
-          const progress = (nowTs - row._bgc_progress_ms) / Highlight_Duration;
+        highlightDimRowKeys.forEach((rowKeyValue) => {
+          const highlightItem = highlightRowStore.value[rowKeyValue];
+          const progress = (nowTs - highlightItem.bgc_progress_ms) / Highlight_Duration;
           if (0 < progress && progress < 1) {
-            row._bgc = highlightInter.value(progress);
+            highlightItem.bgc = highlightInter.value(progress);
           } else {
-            row._bgc = "";
-            needDeleteRows.push(row);
+            highlightItem.bgc = "";
+            highlightDimRowKeys.delete(rowKeyValue);
           }
         });
-        needDeleteRows.forEach((row) => highlightDimRows.delete(row));
-        if (highlightDimRows.size > 0) {
+        if (highlightDimRowKeys.size > 0) {
           recursion();
         } else {
           calcHighlightDimLoop = false;
@@ -476,16 +482,16 @@ function useHighlight({ props, tableContainer, rowKeyGen }) {
     const cellEl = (_a = tableContainer.value) == null ? void 0 : _a.querySelector(`[data-row-key="${rowKeyValue}"]>[data-index="${dataIndex}"]`);
     if (!cellEl)
       return;
-    if (cellEl.classList.contains("highlight-cell")) {
-      cellEl.classList.remove("highlight-cell");
+    if (cellEl.classList.contains(HIGHLIGHT_CELL_CLASS)) {
+      cellEl.classList.remove(HIGHLIGHT_CELL_CLASS);
       void cellEl.offsetHeight;
     }
-    cellEl.classList.add("highlight-cell");
+    cellEl.classList.add(HIGHLIGHT_CELL_CLASS);
     window.clearTimeout(highlightDimCellsTimeout.get(rowKeyValue));
     highlightDimCellsTimeout.set(
       rowKeyValue,
       window.setTimeout(() => {
-        cellEl.classList.remove("highlight-cell");
+        cellEl.classList.remove(HIGHLIGHT_CELL_CLASS);
         highlightDimCellsTimeout.delete(rowKeyValue);
       }, Highlight_Duration)
     );
@@ -498,11 +504,12 @@ function useHighlight({ props, tableContainer, rowKeyGen }) {
       const nowTs = Date.now();
       for (let i = 0; i < rowKeyValues.length; i++) {
         const rowKeyValue = rowKeyValues[i];
-        const row = props.dataSource.find((it) => rowKeyGen(it) === rowKeyValue);
-        if (!row)
-          continue;
-        row._bgc_progress_ms = nowTs;
-        highlightDimRows.add(row);
+        highlightRowStore.value[rowKeyValue] = {
+          bgc: "",
+          bgc_progress: 0,
+          bgc_progress_ms: nowTs
+        };
+        highlightDimRowKeys.add(rowKeyValue);
       }
       calcHighlightLoop();
     } else {
@@ -513,8 +520,8 @@ function useHighlight({ props, tableContainer, rowKeyGen }) {
         const rowEl = (_a = tableContainer.value) == null ? void 0 : _a.querySelector(`[data-row-key="${rowKeyValue}"]`);
         if (!rowEl)
           continue;
-        if (rowEl.classList.contains("highlight-row")) {
-          rowEl.classList.remove("highlight-row");
+        if (rowEl.classList.contains(HIGHLIGHT_ROW_CLASS)) {
+          rowEl.classList.remove(HIGHLIGHT_ROW_CLASS);
           needRepaint = true;
         }
         rowElTemp.push(rowEl);
@@ -522,7 +529,7 @@ function useHighlight({ props, tableContainer, rowKeyGen }) {
         highlightDimRowsTimeout.set(
           rowKeyValue,
           window.setTimeout(() => {
-            rowEl.classList.remove("highlight-row");
+            rowEl.classList.remove(HIGHLIGHT_ROW_CLASS);
             highlightDimRowsTimeout.delete(rowKeyValue);
           }, Highlight_Duration)
         );
@@ -530,10 +537,11 @@ function useHighlight({ props, tableContainer, rowKeyGen }) {
       if (needRepaint) {
         void ((_b = tableContainer.value) == null ? void 0 : _b.offsetWidth);
       }
-      rowElTemp.forEach((el) => el.classList.add("highlight-row"));
+      rowElTemp.forEach((el) => el.classList.add(HIGHLIGHT_ROW_CLASS));
     }
   }
   return {
+    highlightRowStore,
     setHighlightDimRow,
     setHighlightDimCell
   };
@@ -887,8 +895,8 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     virtualX: { type: Boolean, default: false },
     columns: { default: () => [] },
     dataSource: { default: () => [] },
-    rowKey: { type: [String, Function], default: "" },
-    colKey: { type: [String, Function], default: "dataIndex" },
+    rowKey: { type: [String, Number, Function], default: "" },
+    colKey: { type: [String, Number, Function], default: "dataIndex" },
     emptyCellText: { default: "--" },
     noDataFull: { type: Boolean, default: false },
     showNoData: { type: Boolean, default: true },
@@ -956,7 +964,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       virtualX_on,
       virtualX_offsetRight
     });
-    const { setHighlightDimCell, setHighlightDimRow } = useHighlight({ props, tableContainer, rowKeyGen });
+    const { highlightRowStore, setHighlightDimCell, setHighlightDimRow } = useHighlight({ props, tableContainer });
     if (props.autoResize) {
       useAutoResize({ tableContainer, initVirtualScroll, props, debounceMs: 200 });
     }
@@ -1008,7 +1016,14 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     onMounted(() => {
       initVirtualScroll();
       updateFixedShadow();
+      dealDefaultSorter();
     });
+    function dealDefaultSorter() {
+      if (!props.sortConfig.defaultSort)
+        return;
+      const { dataIndex, order } = props.sortConfig.defaultSort;
+      setSorter(dataIndex, order);
+    }
     function dealColumns() {
       tableHeaders.value = [];
       tableHeaderLast.value = [];
@@ -1104,8 +1119,14 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       if (click)
         sortOrderIndex.value++;
       sortOrderIndex.value = sortOrderIndex.value % 3;
-      const order = sortSwitchOrder[sortOrderIndex.value];
+      let order = sortSwitchOrder[sortOrderIndex.value];
       const sortConfig = props.sortConfig;
+      const defaultSort = sortConfig.defaultSort;
+      if (!order && defaultSort) {
+        order = defaultSort.order;
+        sortOrderIndex.value = sortSwitchOrder.indexOf(order);
+        sortCol.value = defaultSort.dataIndex;
+      }
       if (!props.sortRemote || options.force) {
         dataSourceCopy.value = tableSort(col, order, props.dataSource, sortConfig);
       }
@@ -1189,7 +1210,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       var _a;
       const newOption = { silent: true, sortOption: null, sort: true, ...option };
       sortCol.value = dataIndex;
-      sortOrderIndex.value = sortSwitchOrder.findIndex((it) => it === order);
+      sortOrderIndex.value = sortSwitchOrder.indexOf(order);
       if (newOption.sort && ((_a = dataSourceCopy.value) == null ? void 0 : _a.length)) {
         const column = newOption.sortOption || tableHeaderLast.value.find((it) => it.dataIndex === sortCol.value);
         if (column)
@@ -1377,6 +1398,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
               }), 128)) : createCommentVNode("", true)
             ], 4)) : createCommentVNode("", true),
             (openBlock(true), createElementBlock(Fragment, null, renderList(unref(virtual_dataSourcePart), (row, i) => {
+              var _a;
               return openBlock(), createElementBlock("tr", {
                 key: _ctx.rowKey ? rowKeyGen(row) : i,
                 "data-row-key": _ctx.rowKey ? rowKeyGen(row) : i,
@@ -1386,7 +1408,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
                   [_ctx.rowClassName(row, i)]: true
                 }),
                 style: normalizeStyle({
-                  backgroundColor: row._bgc
+                  backgroundColor: (_a = unref(highlightRowStore)[rowKeyGen(row)]) == null ? void 0 : _a.bgc
                 }),
                 onClick: (e) => onRowClick(e, row),
                 onDblclick: (e) => onRowDblclick(e, row),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "stk-table-vue",
-    "version": "0.2.2",
+    "version": "0.2.3",
     "description": "Simple realtime virtual table for vue3&vue2.7",
     "main": "./lib/stk-table-vue.js",
     "types": "./lib/StkTable/index.d.ts",

package/src/StkTable/StkTable.vue

@@ -148,7 +148,7 @@
                         [rowClassName(row, i)]: true,
                     }"
                     :style="{
-                        backgroundColor: row._bgc,
+                        backgroundColor: highlightRowStore[rowKeyGen(row)]?.bgc,
                     }"
                     @click="e => onRowClick(e, row)"
                     @dblclick="e => onRowDblclick(e, row)"
@@ -191,7 +191,7 @@
  */
 import { CSSProperties, onMounted, ref, shallowRef, toRaw, watch } from 'vue';
 import { Default_Row_Height } from './const';
-import { Order, SortConfig, SortOption, SortState, StkTableColumn, UniqKey } from './types/index';
+import { Order, SortConfig, SortOption, SortState, StkTableColumn, UniqKeyProp } from './types/index';
 import { useAutoResize } from './useAutoResize';
 import { useColResize } from './useColResize';
 import { useFixedCol } from './useFixedCol';
@@ -235,9 +235,9 @@ const props = withDefaults(
         /** 表格数据源 */
         dataSource?: DT[];
         /** 行唯一键 */
-        rowKey?: UniqKey;
+        rowKey?: UniqKeyProp;
         /** 列唯一键 */
-        colKey?: UniqKey;
+        colKey?: UniqKeyProp;
         /** 空值展示文字 */
         emptyCellText?: string;
         /** 暂无数据兜底高度是否撑满 */
@@ -286,7 +286,7 @@ const props = withDefaults(
         /** 优化vue2 滚动 */
         optimizeVue2Scroll?: boolean;
         /** 排序配置 */
-        sortConfig?: SortConfig;
+        sortConfig?: SortConfig<DT>;
     }>(),
     {
         width: '',
@@ -330,7 +330,7 @@ const emits = defineEmits<{
      * 排序变更触发
      * ```(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<DT>): void;
     /**
      * 一行点击事件
      * ```(ev: MouseEvent, row: DT)```
@@ -484,7 +484,7 @@ const { getFixedStyle } = useFixedStyle({
 /**
  * 高亮行，高亮单元格
  */
-const { setHighlightDimCell, setHighlightDimRow } = useHighlight({ props, tableContainer, rowKeyGen });
+const { highlightRowStore, setHighlightDimCell, setHighlightDimRow } = useHighlight({ props, tableContainer });
 
 if (props.autoResize) {
     useAutoResize({ tableContainer, initVirtualScroll, props, debounceMs: 200 });
@@ -548,8 +548,16 @@ watch(() => props.fixedColShadow, dealFixedColShadow);
 onMounted(() => {
     initVirtualScroll();
     updateFixedShadow();
+    dealDefaultSorter();
 });
 
+/** 处理默认排序 */
+function dealDefaultSorter() {
+    if (!props.sortConfig.defaultSort) return;
+    const { dataIndex, order } = props.sortConfig.defaultSort;
+    setSorter(dataIndex as string, order);
+}
+
 /**
  * 处理多级表头
  */
@@ -559,7 +567,7 @@ function dealColumns() {
     tableHeaderLast.value = [];
     const copyColumn = props.columns; // do not deep clone
     const deep = howDeepTheHeader(copyColumn);
-    const tempHeaderLast: StkTableColumn<any>[] = [];
+    const tempHeaderLast: StkTableColumn<DT>[] = [];
 
     if (deep > 1 && props.virtualX) {
         console.error('多级表头不支持横向虚拟滚动');
@@ -637,7 +645,7 @@ function colKeyGen(col: StkTableColumn<DT>) {
 }
 
 /** 获取列宽度样式 */
-function getColWidthStyle(col: StkTableColumn<any>) {
+function getColWidthStyle(col: StkTableColumn<DT>) {
     const style: CSSProperties = {
         width: col.width,
         minWidth: col.minWidth,
@@ -662,7 +670,7 @@ function getColWidthStyle(col: StkTableColumn<any>) {
  * @param col
  * @param depth 表头层级
  */
-function getCellStyle(tagType: 1 | 2, col: StkTableColumn<any>, depth?: number): CSSProperties {
+function getCellStyle(tagType: 1 | 2, col: StkTableColumn<DT>, depth?: number): CSSProperties {
     const style: CSSProperties = {
         ...getColWidthStyle(col),
         ...getFixedStyle(tagType, col, depth),
@@ -680,10 +688,11 @@ function getCellStyle(tagType: 1 | 2, col: StkTableColumn<any>, depth?: number):
 
 /**
  * 表头点击排序
- * @param {boolean} options.force sort-remote 开启后是否强制排序
- * @param {boolean} options.emit 是否触发回调
+ * @param click 是否为点击表头触发
+ * @param options.force sort-remote 开启后是否强制排序
+ * @param options.emit 是否触发回调
  */
-function onColumnSort(col?: StkTableColumn<any>, click = true, options: { force?: boolean; emit?: boolean } = {}) {
+function onColumnSort(col?: StkTableColumn<DT>, click = true, options: { force?: boolean; emit?: boolean } = {}) {
     if (!col?.sorter) return;
     options = { force: false, emit: false, ...options };
     if (sortCol.value !== col.dataIndex) {
@@ -694,8 +703,16 @@ function onColumnSort(col?: StkTableColumn<any>, click = true, options: { force?
     if (click) sortOrderIndex.value++;
     sortOrderIndex.value = sortOrderIndex.value % 3;
 
-    const order = sortSwitchOrder[sortOrderIndex.value];
+    let order = sortSwitchOrder[sortOrderIndex.value];
     const sortConfig = props.sortConfig;
+    const defaultSort = sortConfig.defaultSort;
+
+    if (!order && defaultSort) {
+        // 没有排序时变成默认排序
+        order = defaultSort.order;
+        sortOrderIndex.value = sortSwitchOrder.indexOf(order);
+        sortCol.value = defaultSort.dataIndex as string;
+    }
     if (!props.sortRemote || options.force) {
         dataSourceCopy.value = tableSort(col, order, props.dataSource, sortConfig);
     }
@@ -813,16 +830,16 @@ function setCurrentRow(rowKey: string, option = { silent: false }) {
 
 /**
  * 设置表头排序状态
- * @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 指定排序参数
+ * @param option.sort 是否触发排序-默认true
+ * @param option.silent 是否禁止触发回调-默认true
  */
-function setSorter(dataIndex: string, order: null | 'asc' | 'desc', option: { sortOption?: SortOption; silent?: boolean; sort?: boolean } = {}) {
+function setSorter(dataIndex: string, order: Order, option: { sortOption?: SortOption<DT>; silent?: boolean; sort?: boolean } = {}) {
     const newOption = { silent: true, sortOption: null, sort: true, ...option };
     sortCol.value = dataIndex;
-    sortOrderIndex.value = sortSwitchOrder.findIndex(it => it === order);
+    sortOrderIndex.value = sortSwitchOrder.indexOf(order);
 
     if (newOption.sort && dataSourceCopy.value?.length) {
         // 如果表格有数据，则进行排序

package/src/StkTable/types/index.ts

@@ -59,18 +59,27 @@ 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;
+    };
 };

package/src/StkTable/useHighlight.ts

@@ -1,22 +1,41 @@
 import { interpolateRgb } from 'd3-interpolate';
-import { Ref, computed } from 'vue';
+import { Ref, computed, ref } from 'vue';
 import { Highlight_Color, Highlight_Color_Change_Freq, Highlight_Duration } from './const';
+import { UniqKey } from './types';
 
 type Params = {
     props: { theme: 'light' | 'dark'; virtual: boolean; dataSource: any[] };
     tableContainer: Ref<HTMLElement | undefined>;
-    rowKeyGen: (p: any) => string;
 };
+
+/** 高亮行保存的东西 */
+type HighlightRowStore = {
+    bgc: string;
+    bgc_progress_ms: number;
+    bgc_progress: number;
+};
+
+/** 高亮行class */
+const HIGHLIGHT_ROW_CLASS = 'highlight-row';
+/** 高连单元格class */
+const HIGHLIGHT_CELL_CLASS = 'highlight-cell';
+
 /**
  * 高亮单元格，行
  * row中新增_bgc_progress_ms 属性控制高亮状态,_bgc控制颜色
  */
-export function useHighlight({ props, tableContainer, rowKeyGen }: Params) {
-    const highlightInter = computed(() => {
-        return interpolateRgb(Highlight_Color[props.theme].from, Highlight_Color[props.theme].to);
-    });
-    /** 存放高亮行的对象*/
-    const highlightDimRows = new Set<any>();
+export function useHighlight({ props, tableContainer }: Params) {
+    /**
+     * 高亮行记录 key-rowKey, value-obj
+     */
+    const highlightRowStore = ref<Record<UniqKey, HighlightRowStore>>({});
+
+    const highlightFrom = Highlight_Color[props.theme].from;
+    const highlightTo = Highlight_Color[props.theme].to;
+    const highlightInter = computed(() => interpolateRgb(highlightFrom, highlightTo));
+
+    /** 存放高亮行的key*/
+    const highlightDimRowKeys = new Set<UniqKey>();
     /** 高亮后渐暗的行定时器 */
     const highlightDimRowsTimeout = new Map();
     /** 高亮后渐暗的单元格定时器 */
@@ -36,9 +55,8 @@ export function useHighlight({ props, tableContainer, rowKeyGen }: Params) {
         const recursion = () => {
             window.setTimeout(() => {
                 const nowTs = Date.now();
-                const needDeleteRows: any = [];
 
-                highlightDimRows.forEach(row => {
+                highlightDimRowKeys.forEach(rowKeyValue => {
                     //   const rowKeyValue = rowKeyGen(row);
                     //   const rowEl = tableContainer.value?.querySelector<HTMLElement>(`[data-row-key="${rowKeyValue}"]`);
                     //   if (rowEl && row._bgc_progress === 0) {
@@ -47,21 +65,18 @@ export function useHighlight({ props, tableContainer, rowKeyGen }: Params) {
                     //     void rowEl.offsetHeight; // reflow
                     //     rowEl.classList.add('highlight-row-transition');
                     //   }
-
+                    const highlightItem = highlightRowStore.value[rowKeyValue];
                     /** 经过的时间 ÷ 高亮持续时间 计算出 颜色过渡进度 (0-1) */
-                    const progress = (nowTs - row._bgc_progress_ms) / Highlight_Duration;
-                    //   row._bgc_progress = progress;
+                    const progress = (nowTs - highlightItem.bgc_progress_ms) / Highlight_Duration;
                     if (0 < progress && progress < 1) {
-                        row._bgc = highlightInter.value(progress);
+                        highlightItem.bgc = highlightInter.value(progress);
                     } else {
-                        row._bgc = ''; // 清空颜色
-                        needDeleteRows.push(row);
+                        highlightItem.bgc = ''; // 清空颜色
+                        highlightDimRowKeys.delete(rowKeyValue);
                     }
                 });
-                needDeleteRows.forEach((row: any) => highlightDimRows.delete(row));
-                // TODO: shallowRef 时，需要手动更新
 
-                if (highlightDimRows.size > 0) {
+                if (highlightDimRowKeys.size > 0) {
                     // 还有高亮的行,则下一次循环
                     recursion();
                 } else {
@@ -78,16 +93,16 @@ export function useHighlight({ props, tableContainer, rowKeyGen }: Params) {
         // TODO: 支持动态计算高亮颜色。不易实现。需记录每一个单元格的颜色情况。
         const cellEl = tableContainer.value?.querySelector<HTMLElement>(`[data-row-key="${rowKeyValue}"]>[data-index="${dataIndex}"]`);
         if (!cellEl) return;
-        if (cellEl.classList.contains('highlight-cell')) {
-            cellEl.classList.remove('highlight-cell');
+        if (cellEl.classList.contains(HIGHLIGHT_CELL_CLASS)) {
+            cellEl.classList.remove(HIGHLIGHT_CELL_CLASS);
             void cellEl.offsetHeight; // 通知浏览器重绘
         }
-        cellEl.classList.add('highlight-cell');
+        cellEl.classList.add(HIGHLIGHT_CELL_CLASS);
         window.clearTimeout(highlightDimCellsTimeout.get(rowKeyValue));
         highlightDimCellsTimeout.set(
             rowKeyValue,
             window.setTimeout(() => {
-                cellEl.classList.remove('highlight-cell');
+                cellEl.classList.remove(HIGHLIGHT_CELL_CLASS);
                 highlightDimCellsTimeout.delete(rowKeyValue);
             }, Highlight_Duration),
         );
@@ -97,18 +112,19 @@ export function useHighlight({ props, tableContainer, rowKeyGen }: Params) {
      * 高亮一行
      * @param rowKeyValues
      */
-    function setHighlightDimRow(rowKeyValues: Array<string | number>) {
+    function setHighlightDimRow(rowKeyValues: UniqKey[]) {
         if (!Array.isArray(rowKeyValues)) rowKeyValues = [rowKeyValues];
         if (props.virtual) {
             // --------虚拟滚动用js计算颜色渐变的高亮方案
             const nowTs = Date.now(); // 重置渐变进度
             for (let i = 0; i < rowKeyValues.length; i++) {
                 const rowKeyValue = rowKeyValues[i];
-                const row = props.dataSource.find((it: any) => rowKeyGen(it) === rowKeyValue);
-                if (!row) continue;
-                row._bgc_progress_ms = nowTs;
-                // row._bgc_progress = 0;
-                highlightDimRows.add(row);
+                highlightRowStore.value[rowKeyValue] = {
+                    bgc: '',
+                    bgc_progress: 0,
+                    bgc_progress_ms: nowTs,
+                };
+                highlightDimRowKeys.add(rowKeyValue);
             }
             calcHighlightLoop();
         } else {
@@ -121,8 +137,8 @@ export function useHighlight({ props, tableContainer, rowKeyGen }: Params) {
                 const rowKeyValue = rowKeyValues[i];
                 const rowEl = tableContainer.value?.querySelector<HTMLTableRowElement>(`[data-row-key="${rowKeyValue}"]`);
                 if (!rowEl) continue;
-                if (rowEl.classList.contains('highlight-row')) {
-                    rowEl.classList.remove('highlight-row');
+                if (rowEl.classList.contains(HIGHLIGHT_ROW_CLASS)) {
+                    rowEl.classList.remove(HIGHLIGHT_ROW_CLASS);
                     needRepaint = true;
                 }
                 rowElTemp.push(rowEl);
@@ -131,7 +147,7 @@ export function useHighlight({ props, tableContainer, rowKeyGen }: Params) {
                 highlightDimRowsTimeout.set(
                     rowKeyValue,
                     window.setTimeout(() => {
-                        rowEl.classList.remove('highlight-row');
+                        rowEl.classList.remove(HIGHLIGHT_ROW_CLASS);
                         highlightDimRowsTimeout.delete(rowKeyValue); // 回收内存
                     }, Highlight_Duration),
                 );
@@ -139,11 +155,12 @@ export function useHighlight({ props, tableContainer, rowKeyGen }: Params) {
             if (needRepaint) {
                 void tableContainer.value?.offsetWidth; //强制浏览器重绘
             }
-            rowElTemp.forEach(el => el.classList.add('highlight-row')); // 统一添加动画
+            rowElTemp.forEach(el => el.classList.add(HIGHLIGHT_ROW_CLASS)); // 统一添加动画
         }
     }
 
     return {
+        highlightRowStore,
         setHighlightDimRow,
         setHighlightDimCell,
     };

package/src/StkTable/utils.ts

@@ -67,12 +67,12 @@ function strCompare(a: string, b: string, type: 'number' | 'string'): number {
  * 分离出空数据和非空数据成两个数组
  * @param sortOption
  * @param targetDataSource
- * @param isNumber 1 数组
+ * @param isNumber 1 数字
  * @return [值数组,空数组]
  */
-function separatedData(sortOption: SortOption, targetDataSource: any[], isNumber?: boolean) {
-    const emptyArr: any[] = [];
-    const valueArr: any[] = [];
+function separatedData<T extends Record<string, any>>(sortOption: SortOption<T>, targetDataSource: T[], isNumber?: boolean) {
+    const emptyArr: T[] = [];
+    const valueArr: T[] = [];
 
     for (let i = 0; i < targetDataSource.length; i++) {
         const row = targetDataSource[i];
@@ -96,20 +96,33 @@ function separatedData(sortOption: SortOption, targetDataSource: any[], isNumber
  * 可以在组件外部自己实现表格排序，组件配置remote，使表格不排序。
  * 使用者在@sort-change事件中自行更改table props 'dataSource'完成排序。
  * TODO: key 唯一值，排序字段相同时，根据唯一值排序。
+ *
+ * sortConfig.defaultSort 会在order为null时生效
  * @param sortOption 列配置
  * @param order 排序方式
  * @param dataSource 排序的数组
  */
-export function tableSort(sortOption: SortOption, order: Order, dataSource: any[], sortConfig: SortConfig = {}): any[] {
+export function tableSort<T extends Record<string, any>>(
+    sortOption: SortOption<T>,
+    order: Order,
+    dataSource: T[],
+    sortConfig: SortConfig<T> = {},
+): T[] {
     if (!dataSource?.length) return dataSource || [];
-    sortConfig = Object.assign({ emptyToBottom: false } as SortConfig, sortConfig);
+    sortConfig = { emptyToBottom: false, ...sortConfig };
     let targetDataSource = [...dataSource];
+    let sortField = sortOption.sortField || sortOption.dataIndex;
+
+    if (!order && sortConfig.defaultSort) {
+        // 默认排序
+        order = sortConfig.defaultSort.order;
+        sortField = sortConfig.defaultSort.dataIndex;
+    }
 
     if (typeof sortOption.sorter === 'function') {
         const customSorterData = sortOption.sorter(targetDataSource, { order, column: sortOption });
         if (customSorterData) targetDataSource = customSorterData;
     } else if (order) {
-        const sortField = sortOption.sortField || sortOption.dataIndex;
         let { sortType } = sortOption;
         if (!sortType) sortType = typeof dataSource[0][sortField] as 'number' | 'string';