holyes-table 1.0.12 → 1.0.14

package/README.md

@@ -2,6 +2,25 @@
 
 这个基于Canvas计算行高的虚拟滚动表格组件。
 
+## 目录
+
+- [优化](#优化)
+- [注意事项](#注意事项)
+- [组件依赖](#组件依赖)
+- [基本用法](#基本用法)
+  - [安装](#安装)
+  - [简单示例](#简单示例)
+- [Props 属性](#props-属性)
+  - [列配置说明 (columns)](#列配置说明-columns)
+  - [树形结构配置 (treeConfig)](#树形结构配置-treeconfig)
+  - [展开行配置 (expandConfig)](#展开行配置-expandconfig)
+- [Emits 事件](#emits-事件)
+- [Methods 方法](#methods-方法)
+  - [方法使用示例](#方法使用示例)
+- [插槽使用](#插槽使用)
+  - [自定义插槽](#自定义插槽)
+  - [默认插槽类型](#默认插槽类型)
+
 ## 优化
 
 1. 用div+grid布局, 每一行的行高是通过Canvas计算的, 这样不会触发重排。
@@ -33,6 +52,26 @@
      - 按钮组
      - 开关
 
+## 注意事项
+
+1 **自定义插槽**
+
+- 已经默认配置了一些单元格类型 defaultType，不一定都需要自定义插槽。
+- 如果确实需要自定义插槽，必须填写插槽的高度defaultHeight，最好定死列宽度，因为整个表格的高度是根据 Canvas 计算的，能准确计算出每一行的行高。
+
+2 **性能优化**
+
+- 大数据量时建议设置 `lazyLoadSlot=true` 延迟加载自定义插槽内容
+- 避免在自定义插槽中执行复杂计算或频繁更新的操作
+- 合理使用 `cellMinHeight` 控制最小行高，避免行高计算不准确
+
+3 **样式定制**
+
+- 表格使用 CSS Grid 布局，可以通过 CSS 变量自定义样式
+- 支持斑马纹、悬停高亮、当前行高亮等样式配置
+- 表头支持固定定位，滚动时保持可见
+- 暂不支持自定义文字大小，会影响计算行高
+
 ## 组件依赖
 
 - vxe-pc-ui ^4.9.41
@@ -162,37 +201,39 @@ interface HolyesTableColumnPropsType {
   width?: number
   /** 列最小宽度 */
   minWidth?: number
-  /** 固定位置：left/right */
-  fixed?: 'left' | 'right' | ''
-  /** 是否可排序 */
+  /** 列固定位置 */
+  fixed?: "left" | "right" | ""
+  /** 列是否可排序 */
   sortable?: boolean
-  /** 列类型：seq(序号)/checkbox(多选) */
-  type?: 'seq' | 'checkbox'
+  /** 列类型 */
+  type?: "seq" | "checkbox" | "expand"
   /** 列样式 */
   style?: any
-  /** 筛选配置 */
+  /** 列是否可筛选 */
   isFilter?: {
+    /** 筛选的类型 */
     type: HolyesTableFilterType
+    /** 筛选type是listFilter时，筛选选项数组 */
     listOptions?: { label: string; value: HolyesTableFilterlistOptions }[]
   }
-  /** 是否可调整宽度 */
+  /** 列是否可调整宽度 */
   resizable?: boolean
-  /** 插槽配置 */
+  /** 列插槽 */
   slots?: {
-    /** 自定义单元格插槽 */
+    /** 列自定义插槽 */
     default?: string
-    /** 插槽高度（有插槽时必填） */
+    /** 列自定义插槽高度，有插槽的话必填，插槽单元格不自动换行 */
     defaultHeight?: number
-    /** 默认插槽类型：a(链接)/tag(标签)/icon(图标)/buttons(按钮组)/switch(开关) */
-    defaultType?: 'a' | 'tag' | 'icon' | 'buttons' | 'switch'
-    /** 插槽属性 */
+    /** 列插槽类型 */
+    defaultType?: HolyesTableSlotDefaultType
+    /** 列插槽默认属性 */
     defaultProps?: {
-      /** 标签插槽属性 */
+      /** 标签 插槽默认属性 */
       tag?: {
-        /** 标签选项数组 */
+        /** 标签匹配规则 */
         options?: {
           /** 标签状态 */
-          status?: 'primary' | 'success' | 'info' | 'warning' | 'error'
+          status?: "primary" | "success" | "info" | "warning" | "error"
           /** 标签颜色 */
           color?: any
           /** 标签显示的文本 */
@@ -201,34 +242,34 @@ interface HolyesTableColumnPropsType {
           value: any
         }[]
       }
-      /** 图标插槽属性 */
+      /** 图标 插槽默认属性 */
       icon?: {
-        /** 图标名称 */
-        name?: string
+        /** 图标名称, 参考 vxe-icon 图标名称 https://vxeui.com/#/component/icon/base */
+        name?: VxeIconPropTypes.Name
         /** 图标样式 */
         style?: any
       }
-      /** 按钮组插槽属性 */
+      /** 按钮 插槽默认属性 */
       buttons?: {
-        /** 按钮组数组，每个元素是一行 div 的按钮数组 */
+        /** 按钮组数组, 每个元素是一行div的按钮数组 */
         options?: {
-          /** 按钮内容 */
+          /** 按钮内容*/
           title?: string
           /** 按钮提示 */
           tip?: string
           /** 按钮前缀图标 */
           prefixIcon?: any
           /** 按钮大小 */
-          size?: 'medium' | 'small' | 'mini'
+          size?: "medium" | "small" | "mini"
           /** 按钮类型 */
-          type?: 'primary' | 'danger'
-          /** 按钮样式 */
-          mode?: 'text' | 'button'
-          /** 按钮是否显示，取决于 row 的哪个字段 */
+          type?: "primary" | "danger"
+          /** 按钮样式, 默认button */
+          mode?: "text" | "button"
+          /** 按钮是否显示，取决于row的哪个字段 */
           showField?: string
-          /** 按钮是否禁用，取决于 row 的哪个字段 */
+          /** 按钮是否禁用，取决于row的哪个字段 */
           disabledField?: string
-          /** 按钮是否加载中，取决于 row 的哪个字段 */
+          /** 按钮是否加载中，取决于row的哪个字段 */
           loadingField?: string
           /** 按钮点击事件 */
           onClick?: (row: any, index: number) => void
@@ -236,7 +277,7 @@ interface HolyesTableColumnPropsType {
           params?: any
         }[][]
       }
-      /** 开关插槽属性 */
+      /** 开关 插槽默认属性 */
       switch?: {
         /** 开关选中时显示的文本 */
         checkedChildren?: string
@@ -254,30 +295,62 @@ interface HolyesTableColumnPropsType {
         openValue?: any
         /** 开关未选中时的值 */
         closeValue?: any
-        /** 按钮是否显示，取决于 row 的哪个字段 */
+        /** 按钮是否显示，取决于row的哪个字段 */
         showField?: string
-        /** 按钮是否禁用，取决于 row 的哪个字段 */
+        /** 按钮是否禁用，取决于row的哪个字段 */
         disabledField?: string
-        /** 按钮是否加载中，取决于 row 的哪个字段 */
+        /** 按钮是否加载中，取决于row的哪个字段 */
         loadingField?: string
         /** 开关点击事件 */
         onChange?: (row: any, index: number) => void
       }
+      checkbox?: {
+        /** 多选框是否半选，取决于row的哪个字段 */
+        checkedIndeterminateField?: string
+        /** 多选框点击事件 */
+        onChange?: (row: any, index: number) => void
+      }
     }
-    /** 表头插槽 */
+    /** 列表头插槽 */
     header?: string
-    /** 表头插槽类型 */
-    headerType?: 'a'
+    /** 列表头插槽类型 */
+    headerType?: "a"
     /** 表尾插槽 */
     footer?: string
   }
-  /** 表尾配置 */
-  footer?: any[]
-  /** 子列（表头分组） */
+  footer?: {
+    /** 表尾行高度 */
+    height?: number
+    /** 表尾类型 */
+    type?: HolyesTableFooterType
+    dataType?: "number0" | "number1" | "number2" | "string"
+    /** 表尾文本 */
+    text?: string
+  }[]
+  /** 表头分组 */
   children?: HolyesTableColumnPropsType[]
+  /** 只对 treeConfig 配置时有效，指定为树节点 */
+  treeNode?: boolean
 }
 ```
 
+#### 筛选字段类型说明
+
+`isFilter` 属性中的类型定义：
+
+```typescript
+/** 筛选字段类型 */
+type HolyesTableFilterType = "inputFilter" | "numberFilter" | "numberFilter%" | "listFilter" | ""
+
+/** 筛选字段列表选项 */
+type HolyesTableFilterlistOptions = string | number | boolean
+```
+
+- **inputFilter**：输入筛选，模糊/精确匹配
+- **numberFilter**：数字筛选，支持 >/≥/=/</≤
+- **numberFilter%**：数字百分比筛选
+- **listFilter**：列表筛选，多选匹配
+
 #### 列配置示例
 
 ```javascript
@@ -330,7 +403,7 @@ const columns = [
 
 ```typescript
 interface HolyesTableTreeConfig {
-  /** 是否开启展开行功能 */
+  /** 是否开启树形结构功能 */
   isOpenTree: boolean
   /** 自动将列表转为树结构 */
   transform?: boolean
@@ -363,12 +436,15 @@ interface HolyesTableTreeConfig {
 
 ```javascript
 const treeConfig = {
+  isOpenTree: true,         // 开启树形结构
   transform: true,          // 自动将列表转为树结构
+  idField: 'id',             // 节点id字段, 保留展开状态时必填
   parentField: 'parentId',  // 父节点字段
   childrenField: 'children', // 子节点字段
   indent: 20,               // 缩进像素
   trigger: 'default',       // 点击按钮触发展开/收起
   showIcon: true            // 显示树形图标
+  reserve: false             // 保留展开状态
 }
 ```
 
@@ -402,6 +478,44 @@ const expandConfig = {
 }
 ```
 
+### 表尾行属性配置 (footerProps)
+
+```typescript
+/** 表尾类型 */
+type HolyesTableFooterType = "合计" | "文本"
+
+/** 表尾行数据类型 */
+type HolyesTableFooterDataType = "number0" | "number1" | "number2" | "string"
+
+/** 表尾行字段类型 */
+type HolyesTableFooterFieldTypes = {
+  /** 表尾行字段 */
+  field: string
+  /** 表尾行类型 */
+  type: HolyesTableFooterType
+  /** 表尾行文本（type为"文本"时使用） */
+  text?: string
+  /** 表尾行数据类型（type为"合计"时使用） */
+  dataType?: HolyesTableFooterDataType
+}
+
+/** 外面传入的表尾行属性 */
+type HolyesTableFooterProps = {
+  /** 表尾行高度 */
+  height?: number
+  /** 表尾行字段类型数组 */
+  fieldTypes?: HolyesTableFooterFieldTypes[]
+}
+```
+
+- **合计**：自动计算该列的合计值，需指定 `dataType`
+- **文本**：直接显示 `text` 属性的文本内容
+- **dataType 说明**：
+  - `number0`：整数
+  - `number1`：保留1位小数
+  - `number2`：保留2位小数
+  - `string`：文本
+
 ## Emits 事件
 
 | 事件名 | 参数 | 说明 |
@@ -422,7 +536,7 @@ const expandConfig = {
 | -------- | ------ | -------- | -------- |
 | reloadData | `(data: any[])` | `Promise<void>` | 重新设置表格数据 |
 | getTableData | `()` | `{ fullData, visibleData }` | 获取表格数据（包含全部数据、当前可见数据） |
-| getCheckboxRecords | `()` | `any[]` | 获取所有选中的行数据 |
+| getCheckboxRecords | `(isFull: boolean, field?: string)` | `any[]` | 获取所有选中的行数据,isFull 为false时, 只获取当前可见数据的选中行; field 为选中列字段, 默认第一个选中列字段 |
 | clearCheckboxRow | `()` | `void` | 清空多选列选中状态 |
 | updateFooter | `()` | `void` | 更新表尾行数据 |
 | updateFooterCellLabel | `(field: string, rowIndex: number, label: string)` | `void` | 更新表尾单元格文本 |
@@ -469,7 +583,7 @@ const getTableData = () => {
 
 /** 获取所有选中的行数据 */
 const getCheckboxRecords = () => {
-  const selectedRows = pretextTableRef.value?.getCheckboxRecords() || []
+  const selectedRows = pretextTableRef.value?.getCheckboxRecords(true, 'checkbox') || []
   console.log('选中的行:', selectedRows)
 }
 
@@ -568,6 +682,7 @@ const columns = [
 3. **图标类型 (icon)**: 自动渲染为图标
 4. **按钮组类型 (buttons)**: 自动渲染为按钮组
 5. **开关类型 (switch)**: 自动渲染为开关
+6. **复选框类型 (checkbox)**: 自动渲染为多选框
 
 ```javascript
 const columns = [
@@ -661,26 +776,23 @@ const columns = [
         }
       }
     }
+  },
+  
+  // 复选框类型
+  {
+    field: 'checkbox',
+    title: '多选',
+    slots: {
+      defaultType: 'checkbox',
+      defaultProps: {
+        checkbox: {
+          checkedIndeterminateField: 'halfChecked',
+          onChange: (row, index) => {
+            console.log('复选框变化', row)
+          }
+        }
+      }
+    }
   }
 ]
 ```
-
-## 注意事项
-
-1 **自定义插槽**
-
-- 已经默认配置了一些单元格类型 defaultType，不一定都需要自定义插槽。
-- 如果确实需要自定义插槽，必须填写插槽的高度defaultHeight，最好定死列宽度，因为整个表格的高度是根据 Canvas 计算的，能准确计算出每一行的行高。
-
-2 **性能优化**
-
-- 大数据量时建议设置 `lazyLoadSlot=true` 延迟加载自定义插槽内容
-- 避免在自定义插槽中执行复杂计算或频繁更新的操作
-- 合理使用 `cellMinHeight` 控制最小行高，避免行高计算不准确
-
-3 **样式定制**
-
-- 表格使用 CSS Grid 布局，可以通过 CSS 变量自定义样式
-- 支持斑马纹、悬停高亮、当前行高亮等样式配置
-- 表头支持固定定位，滚动时保持可见
-- 暂不支持自定义文字大小，会影响计算行高