af-mobile-client-vue3 1.3.30 → 1.3.31

package/src/components/data/XCellList/XCellList.md

@@ -1,432 +1,432 @@
-# 移动端配置化表单/列表组件文档
-
-## 组件概述
-
-这是一个基于 Vue 3 + TypeScript + Vant 4 开发的移动端配置化查询列表组件系统,主要包含以下组件:
-
-- `XCellList`: 列表容器组件
-- `XCellListFilter`: 列表筛选组件
-- `XFormItem`: 表单项组件
-- `XForm`: 表单容器组件
-- `XFormGroup`: 表单分组组件
-
-## 功能特性
-
-### 列表功能
-
-- ✅ 下拉刷新
-- ✅ 上拉加载
-- ✅ 搜索过滤
-- ✅ 多条件筛选
-- ✅ 排序功能
-- ✅ 卡片式布局
-- ✅ 批量操作
-- ✅ 自定义操作按钮
-- ✅ **长按多选功能** ✨
-
-### 表单功能
-
-- ✅ 支持多种表单项类型
-- ✅ 表单分组
-- ✅ 表单验证
-- ✅ 动态显示隐藏
-- ✅ 表单联动
-- ✅ 数据字典
-- ✅ 自定义校验规则
-
-## 多选功能 ✨
-
-### 功能概述
-
-XCellList 组件新增了强大的长按多选功能，支持以下特性：
-
-- **长按触发**：长按卡片 500ms 进入多选模式
-- **精确选择**：点击标题切换选中状态，点击卡片其他区域不触发选择
-- **视觉反馈**：选中项目有高亮边框和背景色变化
-- **操作面板**：底部 ActionSheet 显示自定义操作按钮
-- **智能提示**：启用多选功能时显示操作提示
-- **按钮禁用**：多选模式下自动禁用其他操作按钮
-
-### 使用方法
-
-#### 基础多选
-
-```vue
-<script setup lang="ts">
-const multiSelectActions = ref([
-  { name: '批量操作', key: 'batchOperation', color: '#000000', icon: 'records-o' }
-])
-
-function handleMultiSelectAction(action, selectedIds, selectedItems) {
-  console.log('多选操作:', action, selectedIds, selectedItems)
-  // 处理批量操作逻辑
-}
-
-function handleSelectionChange(selectedItems) {
-  console.log('选择变化:', selectedItems)
-}
-</script>
-
-<template>
-  <XCellList
-    config-name="listConfig"
-    :service-name="serviceName"
-    :enable-multi-select="true"
-    id-key="rr_id"
-    :multi-select-actions="multiSelectActions"
-    @multi-select-action="handleMultiSelectAction"
-    @selection-change="handleSelectionChange"
-  />
-</template>
-```
-
-#### 自定义多选操作
-
-```vue
-<script setup lang="ts">
-const multiSelectActions = ref([
-  { name: '标记已读', key: 'markRead', color: '#1989fa', icon: 'eye-o' },
-  { name: '移动到文件夹', key: 'moveToFolder', color: '#07c160', icon: 'folder-o' },
-  { name: '标记重要', key: 'markImportant', color: '#ff976a', icon: 'star-o' }
-])
-
-function handleMultiSelectAction(action, selectedIds, selectedItems) {
-  switch (action) {
-    case 'markRead':
-      // 标记已读逻辑
-      break
-    case 'moveToFolder':
-      // 移动到文件夹逻辑
-      break
-    case 'markImportant':
-      // 标记重要逻辑
-      break
-  }
-}
-</script>
-```
-
-### 多选功能提示
-
-当启用多选功能（`enableMultiSelect: true`）但未进入多选模式时，会在筛选条件下方显示一个提示条：
-
-- 提示内容："长按卡片可进入多选模式"
-- 样式：浅灰色背景，信息图标，友好的提示文字
-- 进入多选模式后，此提示自动消失，显示多选模式提示条
-
-### 多选模式下的按钮禁用
-
-在多选模式下，以下按钮会被自动禁用：
-
-- 新增按钮（add-action-btn）
-- 卡片内的操作按钮（action-button）
-- 卡片底部的操作按钮（action-btn）
-- 更多按钮（⋯）
-
-这样可以避免在多选过程中误触发其他操作。
-
-## 使用示例
-
-### 基础列表
-
-```vue
-<script setup lang="ts">
-const serviceName = 'userService'
-
-function handleDetail(item) {
-  // 处理详情点击
-}
-</script>
-
-<template>
-  <XCellList
-    config-name="listConfig"
-    :service-name="serviceName"
-    @to-detail="handleDetail"
-  />
-</template>
-```
-
-### 带筛选的表单
-
-```vue
-<script setup lang="ts">
-const configName = 'searchForm'
-const serviceName = 'userService'
-const formData = ref({})
-
-function handleSubmit(data) {
-  console.log('表单提交:', data)
-}
-</script>
-
-<template>
-  <XFormGroup
-    :config-name="configName"
-    :service-name="serviceName"
-    :group-form-data="formData"
-    mode="查询"
-    @submit="handleSubmit"
-  />
-</template>
-```
-
-### 表单功能(琉璃配置中的需要勾选的新增和修改)
-
-```vue
-<script setup lang="ts">
-const configName = 'searchForm'
-const serviceName = 'userService'
-
-function addOption() {
-  console.log('新增表单')
-}
-function updateRow(item) {
-  console.log('修改表单:', item)
-}
-</script>
-
-<template>
-  <XCellList
-    :config-name="configName"
-    :service-name="serviceName"
-    :custom-add="true"
-    :custom-edit="true"
-    @update="updateRow"
-    @add="addOption"
-  />
-</template>
-```
-
-## API 文档
-
-### XCellList Props
-
-| 参数                   | 说明                   | 类型        | 默认值    |
-| ---------------------- | ---------------------- | ----------- | --------- |
-| configName             | 配置名称               | string      | -         |
-| serviceName            | 服务名称               | string      | -         |
-| fixQueryForm           | 固定查询参数           | object      | null      |
-| idKey                  | 主键字段               | string      | 'o_id'    |
-| customAdd              | 是否采用自定义新增按钮 | boolean     | false     |
-| customEdit             | 是否采用自定义修改按钮 | boolean     | false     |
-| **enableMultiSelect**  | **是否启用多选功能**   | **boolean** | **false** |
-| **multiSelectActions** | **多选操作按钮配置**   | **Array**   | **[]**    |
-
-### XCellList Events
-
-| 事件名                | 说明                                           | 回调参数                                                                  |
-| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
-| toDetail              | 点击详情时触发                                 | item: 当前项数据                                                          |
-| add                   | 点击新增按钮时触发（customAdd为true才会触发）  | -                                                                         |
-| update                | 点击修改按钮时触发（customEdit为true才会触发） | item: 当前项数据                                                          |
-| **multiSelectAction** | **多选操作时触发**                             | **action: 操作key, selectedIds: 选中ID数组, selectedItems: 选中项目数组** |
-| **selectionChange**   | **选择状态变化时触发**                         | **selectedItems: 选中项目数组**                                           |
-
-### 多选操作按钮配置
-
-```typescript
-interface MultiSelectAction {
-  name: string // 按钮显示名称
-  key?: string // 操作标识（可选，默认使用name）
-  color?: string // 按钮颜色（可选，默认黑色）
-  icon?: string // 按钮图标（可选，默认records-o）
-}
-```
-
-### XFormGroup Props
-
-| 参数          | 说明     | 类型                       | 默认值 |
-| ------------- | -------- | -------------------------- | ------ |
-| configName    | 配置名称 | string                     | ''     |
-| serviceName   | 服务名称 | string                     | -      |
-| groupFormData | 表单数据 | object                     | {}     |
-| mode          | 表单模式 | '查询' \| '新增' \| '修改' | '查询' |
-
-### XFormItem Props
-
-| 参数      | 说明         | 类型         | 默认值 |
-| --------- | ------------ | ------------ | ------ |
-| attr      | 表单项配置   | FormItemAttr | -      |
-| form      | 表单数据对象 | object       | -      |
-| mode      | 表单模式     | string       | '查询' |
-| showLabel | 是否显示标签 | boolean      | true   |
-
-## 配置说明
-
-### 列表配置
-
-```typescript
-interface ListConfig {
-  // 列配置
-  columnJson: {
-    // 列类型: mobile_header_column | mobile_subtitle_column | mobile_details_column | mobile_footer_column
-    mobileColumnType: string
-    // 数据字段
-    dataIndex: string
-    // 标题
-    title: string
-    // 展示类型
-    slotType?: 'badge' | 'action'
-    // 操作按钮配置
-    actionArr?: Array<{
-      text: string
-      func: string
-    }>
-  }[]
-
-  // 按钮状态
-  buttonState: {
-    add?: boolean
-    edit?: boolean
-    delete?: boolean
-  }
-
-  // 是否显示排序
-  showSortIcon?: boolean
-
-  // 查询表单配置
-  formJson: FormItem[]
-}
-```
-
-### 表单配置
-
-```typescript
-interface FormItem {
-  // 表单项类型
-  type: 'input' | 'select' | 'date' | 'checkbox' | 'radio' | 'switch' | 'textarea' | 'uploader'
-
-  // 字段名
-  model: string
-
-  // 标签名
-  name: string
-
-  // 校验规则
-  rule?: {
-    required: string
-    type: 'string' | 'number' | 'integer' | 'float'
-  }
-
-  // 占位提示
-  placeholder?: string
-
-  // 数据源配置
-  keyName?: string
-
-  // 是否只读
-  readonly?: boolean
-
-  // 是否禁用
-  disabled?: boolean
-}
-```
-
-## 高级功能
-
-### 表单联动
-
-```typescript
-// 配置联动显示函数
-const showFormItemFunc = `function(form, attr, data, mode) {
-  return form.type === '1'
-}`
-
-// 配置值变化函数
-const dataChangeFunc = `function(form, attr, data, mode) {
-  if(form.type === '1') {
-    form.name = 'test'
-  }
-}`
-```
-
-### 自定义样式
-
-```typescript
-// 配置样式函数
-const styleFunctionForValue = `function(value) {
-  return {
-    color: value > 100 ? 'red' : 'green'
-  }
-}`
-```
-
-## 注意事项
-
-1. 配置名称必须与后端配置一致
-2. 表单验证规则需要按照规范配置
-3. 自定义函数需要使用字符串形式
-4. 数据源配置支持多种方式:
-
-- logic@: 逻辑处理
-- config@: 配置数据
-- search@: 搜索数据5.对于默认的新增和修改功能，单表已经实现（也可以自定义），多表关联及自定义sql请使用自定义按钮实现
-- 配置按钮状态（customAdd、customEdit）为 true
-- 监听 add 和 update 事件
-- 实现自定义逻辑
-
-## 最佳实践
-
-1. 合理使用表单分组
-2. 适当配置表单联动
-3. 统一管理配置文件
-4. 做好错误处理
-5. 优化列表性能
-
-## 常见问题
-
-1. Q: 如何配置自定义校验规则?
-   A: 在 rule 中配置 validator 函数
-
-2. Q: 如何实现表单联动?
-   A: 使用 showFormItemFunc 和 dataChangeFunc 配置联动逻辑
-
-3. Q: 如何自定义列表样式?
-   A: 使用 styleFunctionForValue 配置样式函数
-
-4. **Q: 多选功能如何触发？**
-   **A: 长按卡片 500ms 即可进入多选模式**
-
-5. **Q: 如何自定义多选操作按钮？**
-   **A: 通过 `multiSelectActions` 属性配置，支持自定义名称、颜色和图标**
-
-6. **Q: 多选模式下如何选择项目？**
-   **A: 点击项目标题可以切换选中状态，点击卡片其他区域不会触发选择**
-
-7. **Q: 如何获取选中的项目数据？**
-   **A: 监听 `selectionChange` 事件，或通过 `multiSelectAction` 事件获取**
-
-## 更新日志
-
-### v1.0.0
-
-- 初始版本发布
-- 支持基础列表功能
-- 支持表单配置
-
-### v1.1.0
-
-- 添加表单联动
-- 优化列表性能
-- 修复已知问题
-
-## 后续规划
-
-1. [ ] 支持更多表单类型
-2. [ ] 添加表单预览功能
-3. [ ] 优化列表性能
-4. [ ] 完善错误处理
-5. [ ] 添加单元测试
-
-## 贡献指南
-
-欢迎提交 Issue 和 PR,请遵循以下规范:
-
-1. 遵循代码规范
-2. 添加必要的测试
-3. 更新相关文档
-
-## 许可证
-
-MIT License
+# 移动端配置化表单/列表组件文档
+
+## 组件概述
+
+这是一个基于 Vue 3 + TypeScript + Vant 4 开发的移动端配置化查询列表组件系统,主要包含以下组件:
+
+- `XCellList`: 列表容器组件
+- `XCellListFilter`: 列表筛选组件
+- `XFormItem`: 表单项组件
+- `XForm`: 表单容器组件
+- `XFormGroup`: 表单分组组件
+
+## 功能特性
+
+### 列表功能
+
+- ✅ 下拉刷新
+- ✅ 上拉加载
+- ✅ 搜索过滤
+- ✅ 多条件筛选
+- ✅ 排序功能
+- ✅ 卡片式布局
+- ✅ 批量操作
+- ✅ 自定义操作按钮
+- ✅ **长按多选功能** ✨
+
+### 表单功能
+
+- ✅ 支持多种表单项类型
+- ✅ 表单分组
+- ✅ 表单验证
+- ✅ 动态显示隐藏
+- ✅ 表单联动
+- ✅ 数据字典
+- ✅ 自定义校验规则
+
+## 多选功能 ✨
+
+### 功能概述
+
+XCellList 组件新增了强大的长按多选功能，支持以下特性：
+
+- **长按触发**：长按卡片 500ms 进入多选模式
+- **精确选择**：点击标题切换选中状态，点击卡片其他区域不触发选择
+- **视觉反馈**：选中项目有高亮边框和背景色变化
+- **操作面板**：底部 ActionSheet 显示自定义操作按钮
+- **智能提示**：启用多选功能时显示操作提示
+- **按钮禁用**：多选模式下自动禁用其他操作按钮
+
+### 使用方法
+
+#### 基础多选
+
+```vue
+<script setup lang="ts">
+const multiSelectActions = ref([
+  { name: '批量操作', key: 'batchOperation', color: '#000000', icon: 'records-o' }
+])
+
+function handleMultiSelectAction(action, selectedIds, selectedItems) {
+  console.log('多选操作:', action, selectedIds, selectedItems)
+  // 处理批量操作逻辑
+}
+
+function handleSelectionChange(selectedItems) {
+  console.log('选择变化:', selectedItems)
+}
+</script>
+
+<template>
+  <XCellList
+    config-name="listConfig"
+    :service-name="serviceName"
+    :enable-multi-select="true"
+    id-key="rr_id"
+    :multi-select-actions="multiSelectActions"
+    @multi-select-action="handleMultiSelectAction"
+    @selection-change="handleSelectionChange"
+  />
+</template>
+```
+
+#### 自定义多选操作
+
+```vue
+<script setup lang="ts">
+const multiSelectActions = ref([
+  { name: '标记已读', key: 'markRead', color: '#1989fa', icon: 'eye-o' },
+  { name: '移动到文件夹', key: 'moveToFolder', color: '#07c160', icon: 'folder-o' },
+  { name: '标记重要', key: 'markImportant', color: '#ff976a', icon: 'star-o' }
+])
+
+function handleMultiSelectAction(action, selectedIds, selectedItems) {
+  switch (action) {
+    case 'markRead':
+      // 标记已读逻辑
+      break
+    case 'moveToFolder':
+      // 移动到文件夹逻辑
+      break
+    case 'markImportant':
+      // 标记重要逻辑
+      break
+  }
+}
+</script>
+```
+
+### 多选功能提示
+
+当启用多选功能（`enableMultiSelect: true`）但未进入多选模式时，会在筛选条件下方显示一个提示条：
+
+- 提示内容："长按卡片可进入多选模式"
+- 样式：浅灰色背景，信息图标，友好的提示文字
+- 进入多选模式后，此提示自动消失，显示多选模式提示条
+
+### 多选模式下的按钮禁用
+
+在多选模式下，以下按钮会被自动禁用：
+
+- 新增按钮（add-action-btn）
+- 卡片内的操作按钮（action-button）
+- 卡片底部的操作按钮（action-btn）
+- 更多按钮（⋯）
+
+这样可以避免在多选过程中误触发其他操作。
+
+## 使用示例
+
+### 基础列表
+
+```vue
+<script setup lang="ts">
+const serviceName = 'userService'
+
+function handleDetail(item) {
+  // 处理详情点击
+}
+</script>
+
+<template>
+  <XCellList
+    config-name="listConfig"
+    :service-name="serviceName"
+    @to-detail="handleDetail"
+  />
+</template>
+```
+
+### 带筛选的表单
+
+```vue
+<script setup lang="ts">
+const configName = 'searchForm'
+const serviceName = 'userService'
+const formData = ref({})
+
+function handleSubmit(data) {
+  console.log('表单提交:', data)
+}
+</script>
+
+<template>
+  <XFormGroup
+    :config-name="configName"
+    :service-name="serviceName"
+    :group-form-data="formData"
+    mode="查询"
+    @submit="handleSubmit"
+  />
+</template>
+```
+
+### 表单功能(琉璃配置中的需要勾选的新增和修改)
+
+```vue
+<script setup lang="ts">
+const configName = 'searchForm'
+const serviceName = 'userService'
+
+function addOption() {
+  console.log('新增表单')
+}
+function updateRow(item) {
+  console.log('修改表单:', item)
+}
+</script>
+
+<template>
+  <XCellList
+    :config-name="configName"
+    :service-name="serviceName"
+    :custom-add="true"
+    :custom-edit="true"
+    @update="updateRow"
+    @add="addOption"
+  />
+</template>
+```
+
+## API 文档
+
+### XCellList Props
+
+| 参数                   | 说明                   | 类型        | 默认值    |
+| ---------------------- | ---------------------- | ----------- | --------- |
+| configName             | 配置名称               | string      | -         |
+| serviceName            | 服务名称               | string      | -         |
+| fixQueryForm           | 固定查询参数           | object      | null      |
+| idKey                  | 主键字段               | string      | 'o_id'    |
+| customAdd              | 是否采用自定义新增按钮 | boolean     | false     |
+| customEdit             | 是否采用自定义修改按钮 | boolean     | false     |
+| **enableMultiSelect**  | **是否启用多选功能**   | **boolean** | **false** |
+| **multiSelectActions** | **多选操作按钮配置**   | **Array**   | **[]**    |
+
+### XCellList Events
+
+| 事件名                | 说明                                           | 回调参数                                                                  |
+| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
+| toDetail              | 点击详情时触发                                 | item: 当前项数据                                                          |
+| add                   | 点击新增按钮时触发（customAdd为true才会触发）  | -                                                                         |
+| update                | 点击修改按钮时触发（customEdit为true才会触发） | item: 当前项数据                                                          |
+| **multiSelectAction** | **多选操作时触发**                             | **action: 操作key, selectedIds: 选中ID数组, selectedItems: 选中项目数组** |
+| **selectionChange**   | **选择状态变化时触发**                         | **selectedItems: 选中项目数组**                                           |
+
+### 多选操作按钮配置
+
+```typescript
+interface MultiSelectAction {
+  name: string // 按钮显示名称
+  key?: string // 操作标识（可选，默认使用name）
+  color?: string // 按钮颜色（可选，默认黑色）
+  icon?: string // 按钮图标（可选，默认records-o）
+}
+```
+
+### XFormGroup Props
+
+| 参数          | 说明     | 类型                       | 默认值 |
+| ------------- | -------- | -------------------------- | ------ |
+| configName    | 配置名称 | string                     | ''     |
+| serviceName   | 服务名称 | string                     | -      |
+| groupFormData | 表单数据 | object                     | {}     |
+| mode          | 表单模式 | '查询' \| '新增' \| '修改' | '查询' |
+
+### XFormItem Props
+
+| 参数      | 说明         | 类型         | 默认值 |
+| --------- | ------------ | ------------ | ------ |
+| attr      | 表单项配置   | FormItemAttr | -      |
+| form      | 表单数据对象 | object       | -      |
+| mode      | 表单模式     | string       | '查询' |
+| showLabel | 是否显示标签 | boolean      | true   |
+
+## 配置说明
+
+### 列表配置
+
+```typescript
+interface ListConfig {
+  // 列配置
+  columnJson: {
+    // 列类型: mobile_header_column | mobile_subtitle_column | mobile_details_column | mobile_footer_column
+    mobileColumnType: string
+    // 数据字段
+    dataIndex: string
+    // 标题
+    title: string
+    // 展示类型
+    slotType?: 'badge' | 'action'
+    // 操作按钮配置
+    actionArr?: Array<{
+      text: string
+      func: string
+    }>
+  }[]
+
+  // 按钮状态
+  buttonState: {
+    add?: boolean
+    edit?: boolean
+    delete?: boolean
+  }
+
+  // 是否显示排序
+  showSortIcon?: boolean
+
+  // 查询表单配置
+  formJson: FormItem[]
+}
+```
+
+### 表单配置
+
+```typescript
+interface FormItem {
+  // 表单项类型
+  type: 'input' | 'select' | 'date' | 'checkbox' | 'radio' | 'switch' | 'textarea' | 'uploader'
+
+  // 字段名
+  model: string
+
+  // 标签名
+  name: string
+
+  // 校验规则
+  rule?: {
+    required: string
+    type: 'string' | 'number' | 'integer' | 'float'
+  }
+
+  // 占位提示
+  placeholder?: string
+
+  // 数据源配置
+  keyName?: string
+
+  // 是否只读
+  readonly?: boolean
+
+  // 是否禁用
+  disabled?: boolean
+}
+```
+
+## 高级功能
+
+### 表单联动
+
+```typescript
+// 配置联动显示函数
+const showFormItemFunc = `function(form, attr, data, mode) {
+  return form.type === '1'
+}`
+
+// 配置值变化函数
+const dataChangeFunc = `function(form, attr, data, mode) {
+  if(form.type === '1') {
+    form.name = 'test'
+  }
+}`
+```
+
+### 自定义样式
+
+```typescript
+// 配置样式函数
+const styleFunctionForValue = `function(value) {
+  return {
+    color: value > 100 ? 'red' : 'green'
+  }
+}`
+```
+
+## 注意事项
+
+1. 配置名称必须与后端配置一致
+2. 表单验证规则需要按照规范配置
+3. 自定义函数需要使用字符串形式
+4. 数据源配置支持多种方式:
+
+- logic@: 逻辑处理
+- config@: 配置数据
+- search@: 搜索数据5.对于默认的新增和修改功能，单表已经实现（也可以自定义），多表关联及自定义sql请使用自定义按钮实现
+- 配置按钮状态（customAdd、customEdit）为 true
+- 监听 add 和 update 事件
+- 实现自定义逻辑
+
+## 最佳实践
+
+1. 合理使用表单分组
+2. 适当配置表单联动
+3. 统一管理配置文件
+4. 做好错误处理
+5. 优化列表性能
+
+## 常见问题
+
+1. Q: 如何配置自定义校验规则?
+   A: 在 rule 中配置 validator 函数
+
+2. Q: 如何实现表单联动?
+   A: 使用 showFormItemFunc 和 dataChangeFunc 配置联动逻辑
+
+3. Q: 如何自定义列表样式?
+   A: 使用 styleFunctionForValue 配置样式函数
+
+4. **Q: 多选功能如何触发？**
+   **A: 长按卡片 500ms 即可进入多选模式**
+
+5. **Q: 如何自定义多选操作按钮？**
+   **A: 通过 `multiSelectActions` 属性配置，支持自定义名称、颜色和图标**
+
+6. **Q: 多选模式下如何选择项目？**
+   **A: 点击项目标题可以切换选中状态，点击卡片其他区域不会触发选择**
+
+7. **Q: 如何获取选中的项目数据？**
+   **A: 监听 `selectionChange` 事件，或通过 `multiSelectAction` 事件获取**
+
+## 更新日志
+
+### v1.0.0
+
+- 初始版本发布
+- 支持基础列表功能
+- 支持表单配置
+
+### v1.1.0
+
+- 添加表单联动
+- 优化列表性能
+- 修复已知问题
+
+## 后续规划
+
+1. [ ] 支持更多表单类型
+2. [ ] 添加表单预览功能
+3. [ ] 优化列表性能
+4. [ ] 完善错误处理
+5. [ ] 添加单元测试
+
+## 贡献指南
+
+欢迎提交 Issue 和 PR,请遵循以下规范:
+
+1. 遵循代码规范
+2. 添加必要的测试
+3. 更新相关文档
+
+## 许可证
+
+MIT License