@a2simcode/ui 0.0.154 → 0.0.155

package/docs/components/table-panel.md

@@ -1,236 +1,236 @@
-# TablePanel 表格面板
-
-基于 Table 组件封装的高级表格面板，集成搜索、筛选、排序、分页等常用功能。
-
-## 基础用法
-
-通过 `columns` 配置列，`loadData` 加载数据，`buttons` 配置工具栏按钮，`actions` 配置行内操作按钮。需设置 `row-key` 指定行数据的唯一标识字段。
-
-<Demo :source-code="tablePanelBasicCode">
-  <template #source>
-    <table-panel-basic />
-  </template>
-  <template #description>
-    配置 `columns` 中的 `config.filter.isSearchKeyword` 开启关键字搜索支持。注意：必须配置 `row-key` 属性指定数据唯一标识（如 id），否则无法正常使用多选功能。**重要提示：** 关键字搜索功能需要后端支持，`loadData` 方法会接收包含 `keyword` 参数的对象，需要将关键字传递给后端接口进行数据过滤。
-  </template>
-</Demo>
-
-## 树形数据
-
-当 `isTree` 为 `true` 时，可配合 `parentKey` 将扁平数据自动转换为树形结构展示。
-
-<Demo :source-code="tablePanelTreeParentKeyCode">
-  <template #source>
-    <table-panel-tree-parent-key />
-  </template>
-  <template #description>
-    设置 `is-tree` 和 `parent-key`，在 `loadData` 返回的扁平数据中通过 `parent-key` 指定的字段建立父子关系。
-  </template>
-</Demo>
-
-## 筛选功能
-
-支持多条件筛选，可以针对不同字段类型选择不同的筛选方式。
-
-**重要提示：** 查询过滤功能（包括关键字搜索和筛选条件）需要后端支持。`loadData` 方法会接收包含 `keyword`（关键字搜索）和 `filter`（筛选条件）的参数，需要将这些参数传递给后端接口进行数据过滤。示例中的前端过滤仅用于演示，实际使用时请确保后端接口支持相应的查询参数。
-
-<Demo :source-code="tablePanelFilterCode">
-  <template #source>
-    <table-panel-filter />
-  </template>
-  <template #description>
-    通过 `config.dataType` 配置字段类型，筛选面板会自动根据类型提供合适的筛选方式。支持的类型：`options`（选项）、`dateTime`（日期时间）等。筛选面板可以点击固定按钮固定在右侧显示。**注意：** 此示例中的查询过滤功能需要后端支持，实际使用时请确保后端接口能够处理 `loadData` 传入的 `keyword` 和 `filter` 参数。
-  </template>
-</Demo>
-
-## 分页
-
-通过 `isPage` 开启分页，`loadData` 返回 `{ rows, records }` 格式数据。
-
-<Demo :source-code="tablePanelPaginationCode">
-  <template #source>
-    <table-panel-pagination />
-  </template>
-  <template #description>
-    设置 `isPage` 为 `true` 开启分页，`loadData` 方法会接收包含 `pagination` 信息的参数对象，返回数据需要包含 `rows`（当前页数据）和 `records`（总条数）。
-  </template>
-</Demo>
-
-## 懒加载子表数据
-
-当子表数据量较大时，可以将主表记录的 `children` 设置为 `true` 作为“需要懒加载”的标识；在用户展开该行时，组件会调用 `loadChildren(record)` 异步获取子表数据，并自动写入并展开。
-
-- 触发条件：展开行且 `originData.children === true`
-- 成功后：会把返回的数组设置为该行的子数据（下次再展开不会重复请求）
-
-<Demo :source-code="tablePanelSubTableLazyCode">
-  <template #source>
-    <table-panel-sub-table-lazy />
-  </template>
-  <template #description>
-    将主表行的 <code>children</code> 设置为 <code>true</code> 作为懒加载标识；展开该行时会调用 <code>loadChildren(record)</code> 获取子表数据并写入。
-  </template>
-</Demo>
-
-## 多选功能
-
-通过 `is-multiple` 属性开启多选功能。多选功能支持两种使用场景：
-
-### 1. 无批处理按钮的多选
-
-当只需要多选功能，但不需要批处理按钮时，设置 `is-multiple` 为 `true` 即可。此时：
-
-- 表格会显示复选框列，支持单选和全选
-- 选中状态会跨页保持（需要配置 `row-key`）
-- 选中记录后，工具栏会显示选中记录数、"仅选中"/"全部"切换按钮、清空选中按钮
-- 支持"仅显示选中"模式，可以只查看已选中的记录
-- 工具栏按钮（如新增、导出等）始终显示
-- 查询设置按钮（搜索、筛选、排序等）在选中记录后仍显示，但进入"仅显示选中"模式后会隐藏
-- 可以通过组件实例的 `getSelection()` 方法获取当前选中的记录
-- 可以通过 `@select` 事件监听选中状态变化
-
-<Demo :source-code="tablePanelMultipleSelectionCode">
-  <template #source>
-    <table-panel-multiple-selection />
-  </template>
-  <template #description>
-    设置 `is-multiple` 为 `true` 开启多选功能。必须配置 `row-key` 属性指定数据唯一标识，否则无法跨页保持选中状态。选中记录后，会显示选中记录数、"仅选中"/"全部"切换按钮、清空选中按钮，支持仅显示选中项的功能。可以通过组件实例的 `getSelection()` 方法获取选中的记录，或通过 `@select` 事件监听选中状态变化。
-  </template>
-</Demo>
-
-### 2. 带批处理按钮的多选
-
-当需要批量操作功能时，除了设置 `is-multiple` 为 `true`，还需要配置 `batchButtons` 属性。此时：
-
-- 表格会显示复选框列，支持单选和全选
-- 选中记录后，工具栏会显示选中记录数、切换显示模式、清空选中等控制按钮
-- 配置的批量操作按钮会在选中记录后显示
-- 选中记录后，会隐藏原先的工具栏按钮和查询设置按钮（搜索、筛选、排序、列管理、刷新）
-- 批量操作按钮的 `click` 函数会接收当前选中的记录数组作为参数
-- 支持"仅显示选中"模式，可以只查看已选中的记录
-
-<Demo :source-code="tablePanelBatchOperationsCode">
-  <template #source>
-    <table-panel-batch-operations />
-  </template>
-  <template #description>
-    通过 `batchButtons` 配置批量操作按钮，`click` 函数会接收当前选中的记录数组作为参数。选中记录后，会显示选中记录数、切换显示/仅显示选中、清空选中等控制按钮，以及配置的批量操作按钮。同时会隐藏原先的按钮和查询设置按钮（搜索、筛选、排序、列管理、刷新）。
-  </template>
-</Demo>
-
-### 多选功能说明
-
-**重要提示：**
-
-1. **必须配置 `row-key`**：开启多选功能时，必须配置 `row-key` 属性指定数据唯一标识字段（如 `id`、`orderId` 等），否则无法正常使用多选功能，也无法跨页保持选中状态。
-
-2. **跨页保持选中**：
-   - 当配置了 `row-key` 时，选中状态会跨页保持
-   - 切换页面时，之前选中的记录仍然保持选中状态
-   - 如果数据被刷新或重新加载，有批处理按钮时会清空选中状态，无批处理按钮时会尝试保留仍然存在的记录
-
-3. **获取选中数据**：
-   <Demo :source-code="tablePanelGetSelectionCode">
-   <template #source>
-   <table-panel-get-selection />
-   </template>
-   <template #description>
-   通过 `@select` 监听选中变化；通过组件实例方法 `getSelection()` 获取选中数据，`clearSelection()` 清空选中。
-   </template>
-   </Demo>
-
-4. **两种模式的区别**：
-
-| 特性           | 无批处理按钮                             | 有批处理按钮             |
-| -------------- | ---------------------------------------- | ------------------------ |
-| 工具栏按钮     | 始终显示                                 | 选中后切换为选中控制按钮 |
-| 查询设置按钮   | 选中后仍显示，进入"仅显示选中"模式后隐藏 | 选中后立即隐藏           |
-| 选中状态保持   | 跨页保持，刷新后尝试保留                 | 跨页保持，刷新后清空     |
-| 仅显示选中模式 | 支持                                     | 支持                     |
-| 适用场景       | 需要获取选中数据，但操作在外部处理       | 需要批量操作功能         |
-
-## 批量操作
-
-批量操作是多选功能的一种扩展使用方式，详见上面的"多选功能"章节中的"带批处理按钮的多选"部分。
-
-## 按钮显示控制
-
-可以通过属性控制右上角功能按钮是否显示。
-
-<Demo :source-code="tablePanelButtonVisibilityCode">
-  <template #source>
-    <table-panel-button-visibility />
-  </template>
-  <template #description>
-    通过 `showFilterButton / showOrderButton / showColumnButton / showRefreshButton / showFullscreenButton` 控制按钮显示。
-  </template>
-</Demo>
-
-## API
-
-<ApiTable :data="tablePanelApi" componentName="table-panel" />
-
-### ButtonItem 类型
-
-| 属性名 | 说明         | 类型                                                                  | 默认值 |
-| ------ | ------------ | --------------------------------------------------------------------- | ------ |
-| label  | 按钮显示文本 | `string`                                                              | -      |
-| icon   | 按钮图标     | `string`                                                              | -      |
-| type   | 按钮类型     | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'text'` | -      |
-| click  | 按钮点击回调 | `() => void`                                                          | -      |
-
-### loadData 参数
-
-调用 `loadData` 时会传入以下参数：
-
-```ts
-interface LoadDataParams {
-  // 关键字搜索
-  keyword?: {
-    value: string // 搜索关键字
-    fields: string[] // 搜索字段
-  }
-  // 筛选条件
-  filter?: {
-    rel: 'and' | 'or' // 条件关系
-    cond: {
-      // 条件列表
-      field: string // 字段名
-      method: string // 筛选方式: eq, ne, like, unlike, in, nin, gte, lte, range, empty, not_empty
-      value: any // 筛选值
-      type: string // 值类型
-    }[]
-  }
-  // 分页信息（isPage=true 时）
-  pagination?: {
-    rows: number // 每页条数
-    page: number // 当前页码
-    sort: string // 排序字段
-  }
-  // 排序（isPage=false 时）
-  sort?: string
-}
-```
-
-<script setup>
-import TablePanelBasic from '../examples/table-panel/basic.vue'
-import TablePanelTreeParentKey from '../examples/table-panel/tree-parent-key.vue'
-import TablePanelFilter from '../examples/table-panel/filter.vue'
-import TablePanelPagination from '../examples/table-panel/pagination.vue'
-import TablePanelMultipleSelection from '../examples/table-panel/multiple-selection.vue'
-import TablePanelBatchOperations from '../examples/table-panel/batch-operations.vue'
-import TablePanelSubTableLazy from '../examples/table-panel/sub-table-lazy.vue'
-import TablePanelGetSelection from '../examples/table-panel/get-selection.vue'
-import TablePanelButtonVisibility from '../examples/table-panel/button-visibility.vue'
-import tablePanelApi from './meta/table-panel'
-
-import tablePanelBasicCode from '../examples/table-panel/basic.vue?raw'
-import tablePanelTreeParentKeyCode from '../examples/table-panel/tree-parent-key.vue?raw'
-import tablePanelFilterCode from '../examples/table-panel/filter.vue?raw'
-import tablePanelPaginationCode from '../examples/table-panel/pagination.vue?raw'
-import tablePanelMultipleSelectionCode from '../examples/table-panel/multiple-selection.vue?raw'
-import tablePanelBatchOperationsCode from '../examples/table-panel/batch-operations.vue?raw'
-import tablePanelSubTableLazyCode from '../examples/table-panel/sub-table-lazy.vue?raw'
-import tablePanelGetSelectionCode from '../examples/table-panel/get-selection.vue?raw'
-import tablePanelButtonVisibilityCode from '../examples/table-panel/button-visibility.vue?raw'
-</script>
+# TablePanel 表格面板
+
+基于 Table 组件封装的高级表格面板，集成搜索、筛选、排序、分页等常用功能。
+
+## 基础用法
+
+通过 `columns` 配置列，`loadData` 加载数据，`buttons` 配置工具栏按钮，`actions` 配置行内操作按钮。需设置 `row-key` 指定行数据的唯一标识字段。
+
+<Demo :source-code="tablePanelBasicCode">
+  <template #source>
+    <table-panel-basic />
+  </template>
+  <template #description>
+    配置 `columns` 中的 `config.filter.isSearchKeyword` 开启关键字搜索支持。注意：必须配置 `row-key` 属性指定数据唯一标识（如 id），否则无法正常使用多选功能。**重要提示：** 关键字搜索功能需要后端支持，`loadData` 方法会接收包含 `keyword` 参数的对象，需要将关键字传递给后端接口进行数据过滤。
+  </template>
+</Demo>
+
+## 树形数据
+
+当 `isTree` 为 `true` 时，可配合 `parentKey` 将扁平数据自动转换为树形结构展示。
+
+<Demo :source-code="tablePanelTreeParentKeyCode">
+  <template #source>
+    <table-panel-tree-parent-key />
+  </template>
+  <template #description>
+    设置 `is-tree` 和 `parent-key`，在 `loadData` 返回的扁平数据中通过 `parent-key` 指定的字段建立父子关系。
+  </template>
+</Demo>
+
+## 筛选功能
+
+支持多条件筛选，可以针对不同字段类型选择不同的筛选方式。
+
+**重要提示：** 查询过滤功能（包括关键字搜索和筛选条件）需要后端支持。`loadData` 方法会接收包含 `keyword`（关键字搜索）和 `filter`（筛选条件）的参数，需要将这些参数传递给后端接口进行数据过滤。示例中的前端过滤仅用于演示，实际使用时请确保后端接口支持相应的查询参数。
+
+<Demo :source-code="tablePanelFilterCode">
+  <template #source>
+    <table-panel-filter />
+  </template>
+  <template #description>
+    通过 `config.dataType` 配置字段类型，筛选面板会自动根据类型提供合适的筛选方式。支持的类型：`options`（选项）、`dateTime`（日期时间）等。筛选面板可以点击固定按钮固定在右侧显示。**注意：** 此示例中的查询过滤功能需要后端支持，实际使用时请确保后端接口能够处理 `loadData` 传入的 `keyword` 和 `filter` 参数。
+  </template>
+</Demo>
+
+## 分页
+
+通过 `isPage` 开启分页，`loadData` 返回 `{ rows, records }` 格式数据。
+
+<Demo :source-code="tablePanelPaginationCode">
+  <template #source>
+    <table-panel-pagination />
+  </template>
+  <template #description>
+    设置 `isPage` 为 `true` 开启分页，`loadData` 方法会接收包含 `pagination` 信息的参数对象，返回数据需要包含 `rows`（当前页数据）和 `records`（总条数）。
+  </template>
+</Demo>
+
+## 懒加载子表数据
+
+当子表数据量较大时，可以将主表记录的 `children` 设置为 `true` 作为“需要懒加载”的标识；在用户展开该行时，组件会调用 `loadChildren(record)` 异步获取子表数据，并自动写入并展开。
+
+- 触发条件：展开行且 `originData.children === true`
+- 成功后：会把返回的数组设置为该行的子数据（下次再展开不会重复请求）
+
+<Demo :source-code="tablePanelSubTableLazyCode">
+  <template #source>
+    <table-panel-sub-table-lazy />
+  </template>
+  <template #description>
+    将主表行的 <code>children</code> 设置为 <code>true</code> 作为懒加载标识；展开该行时会调用 <code>loadChildren(record)</code> 获取子表数据并写入。
+  </template>
+</Demo>
+
+## 多选功能
+
+通过 `is-multiple` 属性开启多选功能。多选功能支持两种使用场景：
+
+### 1. 无批处理按钮的多选
+
+当只需要多选功能，但不需要批处理按钮时，设置 `is-multiple` 为 `true` 即可。此时：
+
+- 表格会显示复选框列，支持单选和全选
+- 选中状态会跨页保持（需要配置 `row-key`）
+- 选中记录后，工具栏会显示选中记录数、"仅选中"/"全部"切换按钮、清空选中按钮
+- 支持"仅显示选中"模式，可以只查看已选中的记录
+- 工具栏按钮（如新增、导出等）始终显示
+- 查询设置按钮（搜索、筛选、排序等）在选中记录后仍显示，但进入"仅显示选中"模式后会隐藏
+- 可以通过组件实例的 `getSelection()` 方法获取当前选中的记录
+- 可以通过 `@select` 事件监听选中状态变化
+
+<Demo :source-code="tablePanelMultipleSelectionCode">
+  <template #source>
+    <table-panel-multiple-selection />
+  </template>
+  <template #description>
+    设置 `is-multiple` 为 `true` 开启多选功能。必须配置 `row-key` 属性指定数据唯一标识，否则无法跨页保持选中状态。选中记录后，会显示选中记录数、"仅选中"/"全部"切换按钮、清空选中按钮，支持仅显示选中项的功能。可以通过组件实例的 `getSelection()` 方法获取选中的记录，或通过 `@select` 事件监听选中状态变化。
+  </template>
+</Demo>
+
+### 2. 带批处理按钮的多选
+
+当需要批量操作功能时，除了设置 `is-multiple` 为 `true`，还需要配置 `batchButtons` 属性。此时：
+
+- 表格会显示复选框列，支持单选和全选
+- 选中记录后，工具栏会显示选中记录数、切换显示模式、清空选中等控制按钮
+- 配置的批量操作按钮会在选中记录后显示
+- 选中记录后，会隐藏原先的工具栏按钮和查询设置按钮（搜索、筛选、排序、列管理、刷新）
+- 批量操作按钮的 `click` 函数会接收当前选中的记录数组作为参数
+- 支持"仅显示选中"模式，可以只查看已选中的记录
+
+<Demo :source-code="tablePanelBatchOperationsCode">
+  <template #source>
+    <table-panel-batch-operations />
+  </template>
+  <template #description>
+    通过 `batchButtons` 配置批量操作按钮，`click` 函数会接收当前选中的记录数组作为参数。选中记录后，会显示选中记录数、切换显示/仅显示选中、清空选中等控制按钮，以及配置的批量操作按钮。同时会隐藏原先的按钮和查询设置按钮（搜索、筛选、排序、列管理、刷新）。
+  </template>
+</Demo>
+
+### 多选功能说明
+
+**重要提示：**
+
+1. **必须配置 `row-key`**：开启多选功能时，必须配置 `row-key` 属性指定数据唯一标识字段（如 `id`、`orderId` 等），否则无法正常使用多选功能，也无法跨页保持选中状态。
+
+2. **跨页保持选中**：
+   - 当配置了 `row-key` 时，选中状态会跨页保持
+   - 切换页面时，之前选中的记录仍然保持选中状态
+   - 如果数据被刷新或重新加载，有批处理按钮时会清空选中状态，无批处理按钮时会尝试保留仍然存在的记录
+
+3. **获取选中数据**：
+   <Demo :source-code="tablePanelGetSelectionCode">
+   <template #source>
+   <table-panel-get-selection />
+   </template>
+   <template #description>
+   通过 `@select` 监听选中变化；通过组件实例方法 `getSelection()` 获取选中数据，`clearSelection()` 清空选中。
+   </template>
+   </Demo>
+
+4. **两种模式的区别**：
+
+| 特性           | 无批处理按钮                             | 有批处理按钮             |
+| -------------- | ---------------------------------------- | ------------------------ |
+| 工具栏按钮     | 始终显示                                 | 选中后切换为选中控制按钮 |
+| 查询设置按钮   | 选中后仍显示，进入"仅显示选中"模式后隐藏 | 选中后立即隐藏           |
+| 选中状态保持   | 跨页保持，刷新后尝试保留                 | 跨页保持，刷新后清空     |
+| 仅显示选中模式 | 支持                                     | 支持                     |
+| 适用场景       | 需要获取选中数据，但操作在外部处理       | 需要批量操作功能         |
+
+## 批量操作
+
+批量操作是多选功能的一种扩展使用方式，详见上面的"多选功能"章节中的"带批处理按钮的多选"部分。
+
+## 按钮显示控制
+
+可以通过属性控制右上角功能按钮是否显示。
+
+<Demo :source-code="tablePanelButtonVisibilityCode">
+  <template #source>
+    <table-panel-button-visibility />
+  </template>
+  <template #description>
+    通过 `showFilterButton / showOrderButton / showColumnButton / showRefreshButton / showFullscreenButton` 控制按钮显示。
+  </template>
+</Demo>
+
+## API
+
+<ApiTable :data="tablePanelApi" componentName="table-panel" />
+
+### ButtonItem 类型
+
+| 属性名 | 说明         | 类型                                                                  | 默认值 |
+| ------ | ------------ | --------------------------------------------------------------------- | ------ |
+| label  | 按钮显示文本 | `string`                                                              | -      |
+| icon   | 按钮图标     | `string`                                                              | -      |
+| type   | 按钮类型     | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'text'` | -      |
+| click  | 按钮点击回调 | `() => void`                                                          | -      |
+
+### loadData 参数
+
+调用 `loadData` 时会传入以下参数：
+
+```ts
+interface LoadDataParams {
+  // 关键字搜索
+  keyword?: {
+    value: string // 搜索关键字
+    fields: string[] // 搜索字段
+  }
+  // 筛选条件
+  filter?: {
+    rel: 'and' | 'or' // 条件关系
+    cond: {
+      // 条件列表
+      field: string // 字段名
+      method: string // 筛选方式: eq, ne, like, unlike, in, nin, gte, lte, range, empty, not_empty
+      value: any // 筛选值
+      type: string // 值类型
+    }[]
+  }
+  // 分页信息（isPage=true 时）
+  pagination?: {
+    rows: number // 每页条数
+    page: number // 当前页码
+    sort: string // 排序字段
+  }
+  // 排序（isPage=false 时）
+  sort?: string
+}
+```
+
+<script setup>
+import TablePanelBasic from '../examples/table-panel/basic.vue'
+import TablePanelTreeParentKey from '../examples/table-panel/tree-parent-key.vue'
+import TablePanelFilter from '../examples/table-panel/filter.vue'
+import TablePanelPagination from '../examples/table-panel/pagination.vue'
+import TablePanelMultipleSelection from '../examples/table-panel/multiple-selection.vue'
+import TablePanelBatchOperations from '../examples/table-panel/batch-operations.vue'
+import TablePanelSubTableLazy from '../examples/table-panel/sub-table-lazy.vue'
+import TablePanelGetSelection from '../examples/table-panel/get-selection.vue'
+import TablePanelButtonVisibility from '../examples/table-panel/button-visibility.vue'
+import tablePanelApi from './meta/table-panel'
+
+import tablePanelBasicCode from '../examples/table-panel/basic.vue?raw'
+import tablePanelTreeParentKeyCode from '../examples/table-panel/tree-parent-key.vue?raw'
+import tablePanelFilterCode from '../examples/table-panel/filter.vue?raw'
+import tablePanelPaginationCode from '../examples/table-panel/pagination.vue?raw'
+import tablePanelMultipleSelectionCode from '../examples/table-panel/multiple-selection.vue?raw'
+import tablePanelBatchOperationsCode from '../examples/table-panel/batch-operations.vue?raw'
+import tablePanelSubTableLazyCode from '../examples/table-panel/sub-table-lazy.vue?raw'
+import tablePanelGetSelectionCode from '../examples/table-panel/get-selection.vue?raw'
+import tablePanelButtonVisibilityCode from '../examples/table-panel/button-visibility.vue?raw'
+</script>