stk-table-vue 0.0.1 → 0.1.0

package/README.md

@@ -1,7 +1,7 @@
 # StkTable (Sticky Table)
 
 Vue3 简易虚拟滚动表格。用于实时数据展示，新数据行高亮渐暗动效。
-js体积(未压缩41kb)
+js体积(未压缩44kb)
 
 ## Feature TODO:
 * [x] 高亮行，单元格。
@@ -9,13 +9,21 @@ js体积(未压缩41kb)
 * [x] 列固定。
 * [x] 表头拖动更改顺序。
 * [x] 表头列宽拖动调整宽度。
-* [x] 多级表头。（不支持横向虚拟滚动）
+* 多级表头。
+  - [x] 支持最多`2级`表头。
+  - [x] 支持更多级表头
+  - [] 多级表头固定列横向滚动
+  - [] 横向虚拟滚动。
 * [x] 支持table-layout: fixed 配置。
-* [x] 鼠标悬浮在表格上，键盘上下左右滚动虚拟表格
-* [x] 斑马纹
-* [] 列固定阴影
-* [] 不传row-key 时，自动按序号生成id
-* [] 列筛选
+* 鼠标悬浮在表格上，键盘滚动虚拟表格。
+  - [x] 键盘 `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight` 按键支持。
+  - [x] 键盘 `PageUp`/ `PageDown` 按键支持。
+* [x] 斑马纹。
+* [x] 列固定阴影。
+  - [] 多级表头固定列阴影。
+  - [] sticky column 动态计算阴影位置。
+* [] 不传row-key 时，自动按序号生成id。
+* [] 列筛选。
 * [] 非虚拟滚动时，大数据分批加载。
 
 ## Usage
@@ -36,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;
@@ -55,6 +68,8 @@ export type StkProps = {
   theme?: 'light' | 'dark';
   /** 行高 */
   rowHeight?: number;
+  /** 表头行高。default = rowHeight */
+  headerRowHeight?: number | null;
   /** 虚拟滚动 */
   virtual?: boolean;
   /** x轴虚拟滚动 */
@@ -110,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[]);
 /** 表格列配置 */
@@ -178,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"
@@ -190,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>