@yidun/antd-super-table 0.1.1 → 0.1.3

package/README.md

@@ -1,25 +1,30 @@
 # Antd Super Table 组件
+
 ## 介绍
+
 Antd Super Table 是一个基于 Ant Design Vue 的高级表格组件，提供了丰富的功能特性：
 
-+ 🔍 灵活的查询条件配置
-+ 📊 强大的表格列配置
-+ 🎯 场景管理功能
-+ ⚡️ 高性能渲染
-+ 🛠 可定制的表格配置
-+ 🔄 表格拖拽排序
-+ 📱 响应式设计
-+ 🎨 主题定制
+- 🔍 灵活的查询条件配置
+- 📊 强大的表格列配置
+- 🎯 场景管理功能
+- ⚡️ 高性能渲染
+- 🛠 可定制的表格配置
+- 🔄 表格拖拽排序
+- 📱 响应式设计
+- 🎨 主题定制
 
 ## 示例
+
 ![](https://cdn.jsdelivr.net/npm/@yidun/antd-super-table@latest/example.png)
 
 ## 安装
+
 ```bash
 npm install @yidun/antd-super-table
 ```
 
 ## 基础用法
+
 ```vue
 <template>
   <SuperTable :form-items="formItems" :columns="columns" :request="onRequest" scene-type="user-list" />
@@ -91,39 +96,40 @@ const onRequest = async (options: { params: Record<string, any>; pageSize: numbe
       pageSize: options.pageSize,
     }),
   }).then(res => res.json())
-  
+
   return {
     data: res.data,
     total: res.total,
   }
 }
 </script>
-
 ```
 
 ## 查询场景配置
-默认启用场景，场景相关的配置存储在localStorage中
 
-| 属性名 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| sceneType | string | '' | 场景对应的标识 |
-| enableScene | boolean | `true` | 是否启用场景管理 |
-| sceneStorageType | string | `local` | 场景存储位置，可选 `local` 或 `api` |
-| sceneRequest | object | - | 场景请求函数配置（API模式时必填） |
-| defaultScene | object/array |  | 默认场景配置 |
-| maxSceneCount | number | `100` | 最大场景数量 |
+默认启用场景，场景相关的配置存储在localStorage中
 
+| 属性名           | 类型         | 默认值  | 说明                                |
+| ---------------- | ------------ | ------- | ----------------------------------- |
+| sceneType        | string       | ''      | 场景对应的标识                      |
+| enableScene      | boolean      | `true`  | 是否启用场景管理                    |
+| sceneStorageType | string       | `local` | 场景存储位置，可选 `local` 或 `api` |
+| sceneRequest     | object       | -       | 场景请求函数配置（API模式时必填）   |
+| defaultScene     | object/array |         | 默认场景配置                        |
+| maxSceneCount    | number       | `100`   | 最大场景数量                        |
 
 ### 场景存储配置
+
 #### 本地存储模式（默认）
+
 ```vue
 <template>
   <SuperTable :form-items="formItems" :columns="columns" :request="onRequest" scene-storage-type="local" enable-scene />
 </template>
-
 ```
 
 #### API存储模式
+
 ```vue
 <template>
   <SuperTable
@@ -180,10 +186,10 @@ const sceneRequest = {
   }
 }
 </script>
-
 ```
 
 #### 错误处理
+
 当 `sceneStorageType` 为 `'api'` 但没有提供 `sceneRequest` 时，组件会在控制台输出错误信息并禁用场景功能：
 
 ```javascript
@@ -192,37 +198,40 @@ SuperTable: sceneStorageType 为 "api" 时，必须提供 sceneRequest 配置
 ```
 
 ## 查询条件配置
+
 ### 支持的输入类型
-+ 文本输入框 (input)
-+ 组合输入框 (inputGroup)
-+ 数字输入框 (inputNumber)
-+ 数字范围输入框 (inputNumberRange)
-+ 选择器 (select)
-+ 日期选择器 (datePicker)
-+ 日期范围选择器 (rangePicker)
-+ 级联选择 (cascader)
-+ 树形选择 (treeSelect)
-+ 自定义组件 (component)
+
+- 文本输入框 (input)
+- 组合输入框 (inputGroup)
+- 数字输入框 (inputNumber)
+- 数字范围输入框 (inputNumberRange)
+- 选择器 (select)
+- 日期选择器 (datePicker)
+- 日期范围选择器 (rangePicker)
+- 级联选择 (cascader)
+- 树形选择 (treeSelect)
+- 自定义组件 (component)
 
 ### 查询条件属性
-| 属性名 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| type | string | - | 查询条件类型 |
-| name | string | - | 字段名称 |
-| label | string | - | 显示标签 |
-| value | any | - | 默认值 |
-| props | object | {} | 传递给组件的属性 |
-| component | Component | - | 自定义组件（type为component时必填） |
-| modelPropName | string | 'value' | 自定义组件的v-model属性名 |
-| span | number | 1 | 列宽系数 |
-| visible | boolean | true | 是否显示 |
-| fixed | boolean | false | 是否固定（不可删除） |
-| selected | boolean | false | 是否默认选中 |
-| quiet | boolean | false | 是否静默更新（不触发搜索） |
-| showLabel | boolean | true | 是否显示标签 |
 
+| 属性名        | 类型      | 默认值  | 说明                                |
+| ------------- | --------- | ------- | ----------------------------------- |
+| type          | string    | -       | 查询条件类型                        |
+| name          | string    | -       | 字段名称                            |
+| label         | string    | -       | 显示标签                            |
+| value         | any       | -       | 默认值                              |
+| props         | object    | {}      | 传递给组件的属性                    |
+| component     | Component | -       | 自定义组件（type为component时必填） |
+| modelPropName | string    | 'value' | 自定义组件的v-model属性名           |
+| span          | number    | 1       | 列宽系数                            |
+| visible       | boolean   | true    | 是否显示                            |
+| fixed         | boolean   | false   | 是否固定（不可删除）                |
+| selected      | boolean   | false   | 是否默认选中                        |
+| quiet         | boolean   | false   | 是否静默更新（不触发搜索）          |
+| showLabel     | boolean   | true    | 是否显示标签                        |
 
 ### 完整示例
+
 ```typescript
 import dayjs from 'dayjs'
 import { Switch } from 'ant-design-vue'
@@ -400,36 +409,39 @@ export const createFormItems = () => {
 ```
 
 ## 表格列配置
+
 ### 支持的列类型
-+ 文本 (text)
-+ 图片 (image)
-+ 标签 (tag)
-+ 按钮 (button)
-+ 链接 (link)
-+ 自定义 (component)
-+ 排序 (sort)
+
+- 文本 (text)
+- 图片 (image)
+- 标签 (tag)
+- 按钮 (button)
+- 链接 (link)
+- 自定义 (component)
+- 排序 (sort)
 
 内置解析类型，均支持在一个单元格内展示多个节点，超出最大个数后会展示更多按钮，点击更多按钮可展开查看所有数据，所以可以扩展出文本列表、图片列表、按钮列表、标签列表等展示形式
 
 ### 表格列属性
-| 属性名 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| key | string | - | 列的唯一标识 |
-| title | string | - | 列标题 |
-| type | string/function | 'text' | 列类型 |
-| content | string/function | - | 列内容 |
-| titleTooltip | string/function | - | 标题提示信息 |
-| tooltip | string/boolean/function | - | 内容提示信息 |
-| component | Component | - | 自定义组件（type为component时必填） |
-| props | object/function | {} | 传递给组件的属性 |
-| width | number | 120 | 列宽度 |
-| visible | boolean | true | 是否可见 |
-| fixed | string | - | 固定列位置，可选 'left' 或 'right' |
-| copyable | boolean | false | 是否可复制 |
-| ellipsis | boolean | true | 是否超出显示省略号 |
 
+| 属性名       | 类型                    | 默认值 | 说明                                |
+| ------------ | ----------------------- | ------ | ----------------------------------- |
+| key          | string                  | -      | 列的唯一标识                        |
+| title        | string                  | -      | 列标题                              |
+| type         | string/function         | 'text' | 列类型                              |
+| content      | string/function         | -      | 列内容                              |
+| titleTooltip | string/function         | -      | 标题提示信息                        |
+| tooltip      | string/boolean/function | -      | 内容提示信息                        |
+| component    | Component               | -      | 自定义组件（type为component时必填） |
+| props        | object/function         | {}     | 传递给组件的属性                    |
+| width        | number                  | 120    | 列宽度                              |
+| visible      | boolean                 | true   | 是否可见                            |
+| fixed        | string                  | -      | 固定列位置，可选 'left' 或 'right'  |
+| copyable     | boolean                 | false  | 是否可复制                          |
+| ellipsis     | boolean                 | true   | 是否超出显示省略号                  |
 
 ### 完整示例
+
 ```typescript
 import { Input } from 'ant-design-vue'
 
@@ -573,7 +585,9 @@ export const createTableColumns = (options: { onDelete: (record: Record<string,
 ```
 
 ## 高级功能
+
 ### 表格拖拽排序
+
 ```vue
 <template>
   <SuperTable
@@ -591,18 +605,18 @@ const onRowSortEnd = newData => {
   // 处理排序后的数据
 }
 </script>
-
 ```
 
 ### 表格配置
+
 ```vue
 <template>
   <SuperTable :form-items="formItems" :columns="columns" :request="onRequest" :enable-table-config="true" />
 </template>
-
 ```
 
 ### 自定义查询参数
+
 ```vue
 <template>
   <SuperTable
@@ -612,104 +626,101 @@ const onRowSortEnd = newData => {
     :custom-query-params="{ status: 1, type: 'active' }"
   />
 </template>
-
 ```
 
 ### 插槽使用
+
 ```vue
 <template>
   <SuperTable :form-items="formItems" :columns="columns" :request="onRequest">
     <!-- 场景选择器前的内容 -->
     <template #sceneAddonBefore>
       <a-button type="primary">自定义按钮</a-button>
-
     </template>
 
     <!-- 场景选择器后的内容 -->
     <template #sceneAddonAfter>
       <a-button>导出</a-button>
-
     </template>
 
     <!-- 表格头部 -->
     <template #tableHead>
       <h3>用户列表</h3>
-
     </template>
 
     <!-- 工具栏 -->
     <template #toolBar>
       <a-button type="primary">新增用户</a-button>
-
     </template>
 
     <!-- 表格底部 -->
     <template #tableFoot>
       <div>总计: {{ total }} 条数据</div>
-
     </template>
 
     <!-- 展开行 -->
     <template #expandedRowRender="{ record }">
       <p>详细信息: {{ record.description }}</p>
-
     </template>
-
   </SuperTable>
-
 </template>
-
 ```
 
 ## API
+
 ### Props
-| 参数              | 说明             | 类型                          | 默认值                          |  
-| ----------------- | ---------------- | ----------------------------- | ------------------------------- | --------- |  
-| formItems         | 查询条件配置     | `SuperTableFormItem[]`        | `[]`                            |  
-| columns           | 表格列配置       | `SuperTableColumn[]`          | `[]`                            |  
-| request           | 数据请求函数     | `SuperTableRequestFunction`   | -                               |  
-| sceneType         | 场景类型         | `string`                      | `''`                            |  
-| enableScene       | 是否启用场景管理 | `boolean`                     | `true`                          |  
-| sceneStorageType  | 场景存储位置     | `'local'                      | 'api'`                          | `'local'` |  
-| sceneRequest      | 场景请求函数配置 | `SceneRequestConfig`          | -                               |  
-| defaultScene      | 默认场景配置     | `SuperTableDefaultSceneConfig | SuperTableDefaultSceneConfig[]` | -         |  
-| maxSceneCount     | 最大场景数量     | `number`                      | `100`                           |  
-| formItemColSpan   | 查询条件列数     | `number`                      | `6`                             |  
-| debounceWait      | 查询防抖时间(ms) | `number`                      | `100`                           |  
-| refreshDeps       | 依赖刷新选项     | `any[]`                       | `[]`                            |  
-| tableProps        | 表格属性         | `TableProps`                  | `{}`                            |  
-| formatDataSource  | 转换表格数据     | `(data: any[]) => any[]`      | `(data) => data`                |  
-| sortable          | 是否可排序       | `boolean`                     | `false`                         |  
-| wrapperStyle      | 容器样式         | `object`                      | `{}`                            |  
-| customQueryParams | 默认查询条件     | `object`                      | `{}`                            |  
-| showRefreshButton | 展示刷新按钮     | `boolean`                     | `false`                         |  
+
+| 参数              | 说明             | 类型                          | 默认值                          |
+| ----------------- | ---------------- | ----------------------------- | ------------------------------- | --------- |
+| formItems         | 查询条件配置     | `SuperTableFormItem[]`        | `[]`                            |
+| columns           | 表格列配置       | `SuperTableColumn[]`          | `[]`                            |
+| request           | 数据请求函数     | `SuperTableRequestFunction`   | -                               |
+| sceneType         | 场景类型         | `string`                      | `''`                            |
+| enableScene       | 是否启用场景管理 | `boolean`                     | `true`                          |
+| sceneStorageType  | 场景存储位置     | `'local'                      | 'api'`                          | `'local'` |
+| sceneRequest      | 场景请求函数配置 | `SceneRequestConfig`          | -                               |
+| defaultScene      | 默认场景配置     | `SuperTableDefaultSceneConfig | SuperTableDefaultSceneConfig[]` | -         |
+| maxSceneCount     | 最大场景数量     | `number`                      | `100`                           |
+| formItemColSpan   | 查询条件列数     | `number`                      | `6`                             |
+| debounceWait      | 查询防抖时间(ms) | `number`                      | `100`                           |
+| refreshDeps       | 依赖刷新选项     | `any[]`                       | `[]`                            |
+| tableProps        | 表格属性         | `TableProps`                  | `{}`                            |
+| formatDataSource  | 转换表格数据     | `(data: any[]) => any[]`      | `(data) => data`                |
+| sortable          | 是否可排序       | `boolean`                     | `false`                         |
+| wrapperStyle      | 容器样式         | `object`                      | `{}`                            |
+| tableWrapperStyle | 表格容器样式     | `object`                      | `{}`                            |
+| customQueryParams | 默认查询条件     | `object`                      | `{}`                            |
+| showRefreshButton | 展示刷新按钮     | `boolean`                     | `false`                         |
 | enableTableConfig | 开启表格设置     | `boolean`                     | `true`                          |
 
 ### Events
-| 事件名 | 说明 | 回调参数 |
-| --- | --- | --- |
-| form-item-change | 表单项值变更 | `(name: string, value: any, formItem: SuperTableFormItem) => void` |
-| scene-change | 场景切换 | `(scene: SuperTableQueryScene) => void` |
-| sort-change | 排序变化 | `(sorter: any) => void` |
-| row-sort-end | 行排序结束 | `(newData: any[]) => void` |
 
+| 事件名           | 说明         | 回调参数                                                           |
+| ---------------- | ------------ | ------------------------------------------------------------------ |
+| form-item-change | 表单项值变更 | `(name: string, value: any, formItem: SuperTableFormItem) => void` |
+| scene-change     | 场景切换     | `(scene: SuperTableQueryScene) => void`                            |
+| sort-change      | 排序变化     | `(sorter: any) => void`                                            |
+| row-sort-end     | 行排序结束   | `(newData: any[]) => void`                                         |
 
 ### Methods
-| 方法名           | 说明             | 参数                                                      |  
-| ---------------- | ---------------- | --------------------------------------------------------- | --------------------------------- |  
-| getFormItem      | 获取表单项配置   | `(name: string) => SuperTableFormItem                     | undefined`                        |  
-| setFormItem      | 设置表单项配置   | `(name: string, keyPath: string, newConfig: any) => void` |  
-| getFormValue     | 获取表单项值     | `(name: string) => any`                                   |  
-| setFormValue     | 设置表单项值     | `(name: string, value: any) => void`                      |  
-| getFormValues    | 获取所有表单项值 | `(name?: string                                           | string[]) => Record<string, any>` |  
-| setFormValues    | 批量设置表单项值 | `(values: Record<string, any>) => void`                   |  
-| getTableData     | 获取表格数据     | `() => any[]`                                             |  
-| setTableData     | 设置表格数据     | `(data: any[]) => void`                                   |  
-| setTableDataItem | 修改单条数据     | `(index: number, data: Record<string, any>) => void`      |  
+
+| 方法名           | 说明             | 参数                                                      |
+| ---------------- | ---------------- | --------------------------------------------------------- | --------------------------------- |
+| getFormItem      | 获取表单项配置   | `(name: string) => SuperTableFormItem                     | undefined`                        |
+| setFormItem      | 设置表单项配置   | `(name: string, keyPath: string, newConfig: any) => void` |
+| getFormValue     | 获取表单项值     | `(name: string) => any`                                   |
+| setFormValue     | 设置表单项值     | `(name: string, value: any) => void`                      |
+| getFormValues    | 获取所有表单项值 | `(name?: string                                           | string[]) => Record<string, any>` |
+| setFormValues    | 批量设置表单项值 | `(values: Record<string, any>) => void`                   |
+| getTableData     | 获取表格数据     | `() => any[]`                                             |
+| setTableData     | 设置表格数据     | `(data: any[]) => void`                                   |
+| setTableDataItem | 修改单条数据     | `(index: number, data: Record<string, any>) => void`      |
 | onRefresh        | 刷新表格数据     | `() => void`                                              |
 
 ## TypeScript 类型定义
+
 ### 基础类型
+
 ```typescript
 /** 表格列对应的type类型 */
 export type SuperTableColumnType = 'text' | 'link' | 'button' | 'tag' | 'image' | 'component' | 'sort'
@@ -738,6 +749,7 @@ export type SuperTableSortOrders = 'ascend' | 'descend' | null
 ```
 
 ### 表格列配置
+
 ```typescript
 /** 表格列配置 */
 export interface SuperTableColumn {
@@ -785,6 +797,7 @@ export interface SuperTableColumn {
 ```
 
 ### 查询条件配置
+
 ```typescript
 /** 查询条件配置 */
 export interface SuperTableFormItem {
@@ -850,6 +863,7 @@ export interface SuperTableFormItem {
 ```
 
 ### 场景管理类型
+
 ```typescript
 /** 场景请求函数配置 */
 export interface SceneRequestConfig {
@@ -948,6 +962,7 @@ export interface SuperTableSceneState {
 ```
 
 ### 数据请求类型
+
 ```typescript
 /** 数据请求方法 */
 export type SuperTableRequestFunction = (options: {
@@ -972,51 +987,63 @@ export interface SuperTableAntdProps extends TableProps {
 ```
 
 ## 注意事项
+
 1. **依赖要求**：组件依赖于 Ant Design Vue，请确保项目中已安装相关依赖
 2. **TypeScript 支持**：TypeScript 项目需要在 `tsconfig.json` 中配置类型声明文件路径
 3. **自定义组件**：自定义组件需要通过 `component` 属性传入，并确保组件已全局注册或局部引入
 4. **场景管理**：
-    - 场景管理功能需要配置 `sceneType` 属性
-    - 使用 `local` 存储模式时，场景数据保存在浏览器的 localStorage 中
-    - 使用 `api` 存储模式时，必须提供 `sceneRequest` 配置，否则会禁用场景功能并在控制台输出错误信息
+   - 场景管理功能需要配置 `sceneType` 属性
+   - 使用 `local` 存储模式时，场景数据保存在浏览器的 localStorage 中
+   - 使用 `api` 存储模式时，必须提供 `sceneRequest` 配置，否则会禁用场景功能并在控制台输出错误信息
 5. **性能优化**：组件内置了防抖、虚拟滚动等性能优化，大数据量场景下表现良好
 6. **响应式设计**：组件支持响应式布局，可根据屏幕尺寸自动调整
 7. **主题定制**：支持通过 CSS 变量或 Ant Design 主题系统进行样式定制
 
 ## 更新日志
+
 ### v0.0.7
-+ 🔄 **重构场景管理API**：
-    - 将 `sceneRequestUrls` 重构为 `sceneRequest`
-    - 从传递URL字符串改为传递请求函数，提供更大的灵活性
-    - 支持自定义请求逻辑、错误处理和认证机制
-+ 🔧 **优化错误处理**：
-    - 当 `sceneStorageType` 为 `'api'` 但未提供 `sceneRequest` 时，提供清晰的错误提示
-    - 实现优雅降级，避免应用崩溃
-+ 🗑️ **移除冗余代码**：
-    - 删除 `apiSceneService` 中间层，直接使用 `sceneRequest`
-    - 简化架构，提高代码可维护性
-+ 📚 **完善文档**：
-    - 更新API文档和类型定义
-    - 添加详细的配置示例和错误处理说明
-    - 提供本地存储和API存储两种模式的完整示例
-+ 🖼️ **修复文档图片**：
-    - 修复 npm 包中示例图片无法显示的问题
-    - 使用 CDN 方式确保图片在不同平台都能正确显示
+
+- 🔄 **重构场景管理API**：
+  - 将 `sceneRequestUrls` 重构为 `sceneRequest`
+  - 从传递URL字符串改为传递请求函数，提供更大的灵活性
+  - 支持自定义请求逻辑、错误处理和认证机制
+- 🔧 **优化错误处理**：
+  - 当 `sceneStorageType` 为 `'api'` 但未提供 `sceneRequest` 时，提供清晰的错误提示
+  - 实现优雅降级，避免应用崩溃
+- 🗑️ **移除冗余代码**：
+  - 删除 `apiSceneService` 中间层，直接使用 `sceneRequest`
+  - 简化架构，提高代码可维护性
+- 📚 **完善文档**：
+  - 更新API文档和类型定义
+  - 添加详细的配置示例和错误处理说明
+  - 提供本地存储和API存储两种模式的完整示例
+- 🖼️ **修复文档图片**：
+  - 修复 npm 包中示例图片无法显示的问题
+  - 使用 CDN 方式确保图片在不同平台都能正确显示
 
 ### v0.0.6
-+ 🐛 修复场景管理相关问题
-+ 🐛 修复表格列配置缓存问题
-+ 💄 优化UI样式和交互体验
+
+- 🐛 修复场景管理相关问题
+- 🐛 修复表格列配置缓存问题
+- 💄 优化UI样式和交互体验
 
 ### v0.0.2
-+ ✨ 新增表格拖拽排序功能
-+ ✨ 新增表格配置功能
-+ ✨ 新增自定义查询参数支持
-+ ✨ 新增多种插槽支持
-+ ✨ 新增级联选择和树形选择组件
-+ 🐛 修复场景管理相关问题
-+ 🐛 修复表格列配置缓存问题
-+ 💄 优化UI样式和交互体验
-+ 📚 完善TypeScript类型定义
-+ 📚 更新文档和示例代码
 
+- ✨ 新增表格拖拽排序功能
+- ✨ 新增表格配置功能
+- ✨ 新增自定义查询参数支持
+- ✨ 新增多种插槽支持
+- ✨ 新增级联选择和树形选择组件
+- 🐛 修复场景管理相关问题
+- 🐛 修复表格列配置缓存问题
+- 💄 优化UI样式和交互体验
+- 📚 完善TypeScript类型定义
+- 📚 更新文档和示例代码
+
+## 更新记录
+
+### 0.1.2
+
+- 新增 `tableWrapperStyle` 属性，支持自定义表格容器样式。
+- 修复 `toolBarExtra` 插槽在未提供 `tableHead` 时无法展示的问题。
+- 修复 `rowKey` 为函数时构建声明文件的类型错误。