@yidun/antd-super-table 0.0.1 → 0.0.3

package/README.md

@@ -9,6 +9,9 @@ Antd Super Table 是一个基于 Ant Design Vue 的高级表格组件，提供
 - 🎯 场景管理功能
 - ⚡️ 高性能渲染
 - 🛠 可定制的表格配置
+- 🔄 表格拖拽排序
+- 📱 响应式设计
+- 🎨 主题定制
 
 ## 安装
 
@@ -20,40 +23,68 @@ npm install @yidun/antd-super-table
 
 ```vue
 <template>
-  <SuperTable
-    :form-items="formItems"
-    :columns="columns"
-    :request="onRequest"
-  />
+  <SuperTable :form-items="formItems" :columns="columns" :request="onRequest" scene-type="user-list" />
 </template>
 
 <script setup lang="ts">
-import SuperTable from 'antd-super-table'
-import type { SuperTableFormItem, SuperTableColumn } from 'antd-super-table'
+import SuperTable from '@yidun/antd-super-table'
+import type { SuperTableFormItem, SuperTableColumn } from '@yidun/antd-super-table'
 
 // 定义查询条件
 const formItems: SuperTableFormItem[] = [
   {
     type: 'input',
-    key: 'name',
+    name: 'name',
     label: '姓名',
+    fixed: true,
+  },
+  {
+    type: 'select',
+    name: 'status',
+    label: '状态',
+    props: {
+      options: [
+        { label: '启用', value: 1 },
+        { label: '禁用', value: 0 },
+      ],
+    },
   },
 ]
 
 // 定义表格列
 const columns: SuperTableColumn[] = [
   {
-    type: 'text',
     key: 'name',
     title: '姓名',
+    content: 'name',
+    width: 150,
+  },
+  {
+    key: 'status',
+    title: '状态',
+    type: 'tag',
+    content: record => ({
+      label: record.status === 1 ? '启用' : '禁用',
+      color: record.status === 1 ? 'green' : 'red',
+    }),
+  },
+  {
+    key: 'actions',
+    title: '操作',
+    type: 'button',
+    fixed: 'right',
+    content: () => [
+      { label: '编辑', onClick: () => console.log('编辑') },
+      { label: '删除', onClick: () => console.log('删除') },
+    ],
   },
 ]
 
 // 定义请求函数
-const onRequest = async (params: Record<string, any>) => {
-  const res = await api.getList(params)
+const onRequest = async (options: { params: Record<string, any>; pageSize: number; pageNum: number }) => {
+  const res = await api.getList(options.params, options.pageNum, options.pageSize)
   return {
-    list: res.data,
+    data: res.data,
     total: res.total,
   }
 }
@@ -64,13 +95,26 @@ const onRequest = async (params: Record<string, any>) => {
 
 默认启用场景，场景相关的配置存储在localStorage中
 
-| 属性名           | 类型    | 默认值  | 说明                                |
-| ---------------- | ------- | ------- | ----------------------------------- |
-| sceneType        | string  | ''      | 场景对应的标识                      |
-| enableScene      | boolean | `true`  | 是否启用场景管理                    |
-| sceneStorageType | string  | `local` | 场景存储位置，可选 `local` 或 `api` |
-| sceneRequestUrl  | string  | `''`    | 场景存储的api地址                   |
-| defaultScene     | array   |         | 默认场景配置                        |
+| 属性名           | 类型         | 默认值      | 说明                                |
+| ---------------- | ------------ | ----------- | ----------------------------------- |
+| sceneType        | string       | ''          | 场景对应的标识                      |
+| enableScene      | boolean      | `true`      | 是否启用场景管理                    |
+| sceneStorageType | string       | `local`     | 场景存储位置，可选 `local` 或 `api` |
+| sceneRequestUrls | object       | 内置API地址 | 场景存储的API地址配置               |
+| defaultScene     | object/array |             | 默认场景配置                        |
+| maxSceneCount    | number       | `100`       | 最大场景数量                        |
+
+### 场景存储配置
+
+```typescript
+// 场景API地址配置
+const sceneRequestUrls = {
+  query: 'https://api.example.com/scene/query',
+  create: 'https://api.example.com/scene/create',
+  update: 'https://api.example.com/scene/update',
+  delete: 'https://api.example.com/scene/delete',
+}
+```
 
 ## 查询条件配置
 
@@ -85,7 +129,25 @@ const onRequest = async (params: Record<string, any>) => {
 - 日期范围选择器 (rangePicker)
 - 级联选择 (cascader)
 - 树形选择 (treeSelect)
-- 自定义组件 (custom)
+- 自定义组件 (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    | 是否显示标签                        |
 
 ### 完整示例
 
@@ -221,6 +283,46 @@ export const createFormItems = () => {
       modelPropName: 'checked', // 默认通过v-model:value绑定数据，可通过modelPropName自定义修改，最终效果为v-model:[modelPropName]
       showLabel: false, // 是否显示label，默认为true
     },
+    {
+      key: 'cascader',
+      type: 'cascader',
+      label: '级联选择',
+      name: 'cascader',
+      props: {
+        options: [
+          {
+            value: 'zhejiang',
+            label: 'Zhejiang',
+            children: [
+              {
+                value: 'hangzhou',
+                label: 'Hangzhou',
+              },
+            ],
+          },
+        ],
+      },
+    },
+    {
+      key: 'treeSelect',
+      type: 'treeSelect',
+      label: '树形选择',
+      name: 'treeSelect',
+      props: {
+        treeData: [
+          {
+            title: 'Node1',
+            value: '0-0',
+            children: [
+              {
+                title: 'Child Node1',
+                value: '0-0-0',
+              },
+            ],
+          },
+        ],
+      },
+    },
   ]
 }
 ```
@@ -239,6 +341,24 @@ export const createFormItems = () => {
 
 内置解析类型，均支持在一个单元格内展示多个节点，超出最大个数后会展示更多按钮，点击更多按钮可展开查看所有数据，所以可以扩展出文本列表、图片列表、按钮列表、标签列表等展示形式
 
+### 表格列属性
+
+| 属性名       | 类型                    | 默认值 | 说明                                |
+| ------------ | ----------------------- | ------ | ----------------------------------- |
+| 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
@@ -249,9 +369,7 @@ import { Input } from 'ant-design-vue'
  * @param { object } options 一些提供给表格内置组件使用的扩展
  *
  * */
-export const createTableColumns = (options: {
-  onDelete: (record: Record<string, any>) => void
-}) => {
+export const createTableColumns = (options: { onDelete: (record: Record<string, any>) => void }) => {
   return [
     {
       key: 'text',
@@ -385,63 +503,178 @@ export const createTableColumns = (options: {
 }
 ```
 
-###
+## 高级功能
+
+### 表格拖拽排序
+
+```vue
+<template>
+  <SuperTable
+    :form-items="formItems"
+    :columns="columns"
+    :request="onRequest"
+    :sortable="true"
+    @row-sort-end="onRowSortEnd"
+  />
+</template>
+
+<script setup>
+const onRowSortEnd = newData => {
+  console.log('排序后的数据:', newData)
+  // 处理排序后的数据
+}
+</script>
+```
+
+### 表格配置
+
+```vue
+<template>
+  <SuperTable :form-items="formItems" :columns="columns" :request="onRequest" :enable-table-config="true" />
+</template>
+```
+
+### 自定义查询参数
+
+```vue
+<template>
+  <SuperTable
+    :form-items="formItems"
+    :columns="columns"
+    :request="onRequest"
+    :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      | 数据请求函数 | `(params: Record<string, any>) => Promise<{ list: any[], total: number }>` | -                          |
-| sceneType    | 场景类型     | `string`                                                                   | -                          |
-| loading      | 加载状态     | `boolean`                                                                  | `false`                    |
-| pagination   | 分页配置     | `boolean                                                                   | TablePaginationConfig`     |
-| rowKey       | 行数据的 key | `string                                                                    | ((record: any) => string)` |
-| rowSelection | 行选择配置   | `TableRowSelection`                                                        | -                          |
+| 参数              | 说明             | 类型                                         | 默认值           |
+| ----------------- | ---------------- | -------------------------------------------- | ---------------- |
+| formItems         | 查询条件配置     | `SuperTableFormItem[]`                       | `[]`             |
+| columns           | 表格列配置       | `SuperTableColumn[]`                         | `[]`             |
+| request           | 数据请求函数     | `PropTableRequestFunction`                   | -                |
+| sceneType         | 场景类型         | `string`                                     | `''`             |
+| enableScene       | 是否启用场景管理 | `boolean`                                    | `true`           |
+| sceneStorageType  | 场景存储位置     | `'local' \| 'api'`                           | `'local'`        |
+| sceneRequestUrls  | 场景API地址配置  | `object`                                     | 内置地址         |
+| defaultScene      | 默认场景配置     | `DefaultSceneConfig \| DefaultSceneConfig[]` | -                |
+| 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`          |
+| enableTableConfig | 开启表格设置     | `boolean`                                    | `true`           |
 
 ### Events
 
-| 事件名           | 说明           | 回调参数                                                   |
-| ---------------- | -------------- | ---------------------------------------------------------- |
-| search           | 搜索事件       | `(params: Record<string, any>) => void`                    |
-| reset            | 重置事件       | `() => void`                                               |
-| change           | 表格变化事件   | `(pagination, filters, sorter) => void`                    |
-| selection-change | 选择项变化事件 | `(selectedRowKeys: string[], selectedRows: 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
 
-| 方法名         | 说明         | 参数                            |
-| -------------- | ------------ | ------------------------------- |
-| reload         | 重新加载数据 | `(resetPage?: boolean) => void` |
-| reset          | 重置查询条件 | `() => void`                    |
-| clearSelection | 清空选择项   | `() => 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`                                              |
 
-## Interface
+## TypeScript 类型定义
 
-### 表格列类型
+### 基础类型
 
 ```typescript
 /** 表格列对应的type类型 */
-export type SuperTableColumnType =
-  | 'text'
-  | 'link'
-  | 'button'
-  | 'tag'
-  | 'image'
+export type SuperTableColumnType = 'text' | 'link' | 'button' | 'tag' | 'image' | 'component' | 'sort'
+
+/** 查询表单项对应的type类型 */
+export type SuperTableFormItemType =
+  | 'input'
+  | 'inputGroup'
+  | 'inputNumber'
+  | 'inputNumberRange'
+  | 'select'
+  | 'treeSelect'
+  | 'cascader'
+  | 'datePicker'
+  | 'rangePicker'
   | 'component'
-  | 'sort'
 
+/** 表格单条数据 */
+export type TableDataItem = Record<string, any>
+
+/** 表格列吸附方式 */
+export type TableColumnFixedType = 'left' | 'right'
+
+/** 排序方式 */
+export type SortOrders = 'ascending' | 'descending' | null
+```
+
+### 表格列配置
+
+```typescript
 /** 表格列配置 */
 export interface SuperTableColumn {
   /** 列对应key */
   key: string
 
-  /** 展示类型 text: 文本 button: 按钮 link: 链接 tag: 标签 component：自定义组件 */
+  /** 展示类型 */
   type?: SuperTableColumnType | ((row: TableDataItem, index: number) => SuperTableColumnType)
 
   /** 标题 */
@@ -473,25 +706,17 @@ export interface SuperTableColumn {
 
   /** 宽度 */
   width?: number
+
+  /** 固定列位置 */
+  fixed?: TableColumnFixedType
+
+  [key: string]: any
 }
 ```
 
-### 查询条件类型
+### 查询条件配置
 
 ```typescript
-/** 查询表单项对应的type类型 */
-export type SuperTableFormItemType =
-  | 'input'
-  | 'inputGroup'
-  | 'inputNumber'
-  | 'inputNumberRange'
-  | 'select'
-  | 'treeSelect'
-  | 'cascader'
-  | 'datePicker'
-  | 'rangePicker'
-  | 'component'
-
 /** 查询条件配置 */
 export interface SuperTableFormItem {
   /** 查询详类型 */
@@ -537,6 +762,21 @@ export interface SuperTableFormItem {
    * 1. 高级搜索弹窗打开时会默认选中对应的搜索项
    * 2. 没有配置默认场景时，会根据选中的项目生成一个默认场景 */
   selected?: boolean
+
+  // 以下为内置属性，不允许修改
+  /** 默认值 */
+  _defaultValue?: any
+
+  /** 排序 */
+  _order?: number
+
+  /** 是否选中 */
+  _selected?: boolean
+
+  /** 在选中场景中的排序 */
+  _orderInScene?: number
+
+  [key: string]: any
 }
 ```
 
@@ -595,11 +835,69 @@ export interface DefaultSceneConfig {
     value: any
   }[]
 }
+
+/** 场景状态 */
+export interface SuperTableSceneState {
+  /** 查询场景列表 */
+  list: SuperTableQueryScene[]
+
+  /** 是否正在加载场景 */
+  loading: boolean
+
+  /** 是否正在保存场景 */
+  submiting: boolean
+
+  /** 是否已经加载过场景 */
+  loaded: boolean
+}
+```
+
+### 数据请求类型
+
+```typescript
+/** 数据请求方法 */
+export type PropTableRequestFunction = (options: {
+  /** 查询参数 */
+  params: Record<string, any>
+
+  /** 分页大小 */
+  pageSize?: number
+
+  /** 当前页码 */
+  pageNum?: number
+
+  [key: string]: any
+}) => Promise<{ total: number; data: Record<string, any>[] }>
+
+/** 表格属性扩展 */
+export interface AntdTableProps extends TableProps {
+  pagination: PaginationProps
+  columns: SuperTableColumn[]
+  dataSource: Record<string, any>[]
+}
 ```
 
 ## 注意事项
 
-1. 组件依赖于 Ant Design Vue，请确保项目中已安装相关依赖
-2. TypeScript 项目需要在 `tsconfig.json` 中配置类型声明文件路径
-3. 自定义组件需要通过 `component` 属性传入，并确保组件已全局注册或局部引入
-4. 场景管理功能需要配置 `sceneType` 属性，并实现相关的存储接口
+1. **依赖要求**：组件依赖于 Ant Design Vue，请确保项目中已安装相关依赖
+2. **TypeScript 支持**：TypeScript 项目需要在 `tsconfig.json` 中配置类型声明文件路径
+3. **自定义组件**：自定义组件需要通过 `component` 属性传入，并确保组件已全局注册或局部引入
+4. **场景管理**：场景管理功能需要配置 `sceneType` 属性，并实现相关的存储接口
+5. **性能优化**：组件内置了防抖、虚拟滚动等性能优化，大数据量场景下表现良好
+6. **响应式设计**：组件支持响应式布局，可根据屏幕尺寸自动调整
+7. **主题定制**：支持通过 CSS 变量或 Ant Design 主题系统进行样式定制
+
+## 更新日志
+
+### v0.0.2
+
+- ✨ 新增表格拖拽排序功能
+- ✨ 新增表格配置功能
+- ✨ 新增自定义查询参数支持
+- ✨ 新增多种插槽支持
+- ✨ 新增级联选择和树形选择组件
+- 🐛 修复场景管理相关问题
+- 🐛 修复表格列配置缓存问题
+- 💄 优化UI样式和交互体验
+- 📚 完善TypeScript类型定义
+- 📚 更新文档和示例代码