af-mobile-client-vue3 1.3.15 → 1.3.17

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

@@ -1,313 +1,313 @@
-# 移动端配置化表单/列表组件文档
-
-## 组件概述
-
-这是一个基于 Vue 3 + TypeScript + Vant 4 开发的移动端配置化查询列表组件系统,主要包含以下组件:
-
-- `XCellList`: 列表容器组件
-- `XCellListFilter`: 列表筛选组件
-- `XFormItem`: 表单项组件
-- `XForm`: 表单容器组件
-- `XFormGroup`: 表单分组组件
-
-## 功能特性
-
-### 列表功能
-
-- ✅ 下拉刷新
-- ✅ 上拉加载
-- ✅ 搜索过滤
-- ✅ 多条件筛选
-- ✅ 排序功能
-- ✅ 卡片式布局
-- ✅ 批量操作
-- ✅ 自定义操作按钮
-
-### 表单功能
-
-- ✅ 支持多种表单项类型
-- ✅ 表单分组
-- ✅ 表单验证
-- ✅ 动态显示隐藏
-- ✅ 表单联动
-- ✅ 数据字典
-- ✅ 自定义校验规则
-
-## 使用示例
-
-### 基础列表
-
-```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  |
-
-### XCellList Events
-
-| 事件名   | 说明                                           | 回调参数         |
-| -------- | ---------------------------------------------- | ---------------- |
-| toDetail | 点击详情时触发                                 | item: 当前项数据 |
-| add      | 点击新增按钮时触发（customAdd为true才会触发）  | -                |
-| update   | 点击修改按钮时触发（customEdit为true才会触发） | item: 当前项数据 |
-
-### 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 配置样式函数
-
-## 更新日志
-
-### 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`: 表单分组组件
+
+## 功能特性
+
+### 列表功能
+
+- ✅ 下拉刷新
+- ✅ 上拉加载
+- ✅ 搜索过滤
+- ✅ 多条件筛选
+- ✅ 排序功能
+- ✅ 卡片式布局
+- ✅ 批量操作
+- ✅ 自定义操作按钮
+
+### 表单功能
+
+- ✅ 支持多种表单项类型
+- ✅ 表单分组
+- ✅ 表单验证
+- ✅ 动态显示隐藏
+- ✅ 表单联动
+- ✅ 数据字典
+- ✅ 自定义校验规则
+
+## 使用示例
+
+### 基础列表
+
+```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  |
+
+### XCellList Events
+
+| 事件名   | 说明                                           | 回调参数         |
+| -------- | ---------------------------------------------- | ---------------- |
+| toDetail | 点击详情时触发                                 | item: 当前项数据 |
+| add      | 点击新增按钮时触发（customAdd为true才会触发）  | -                |
+| update   | 点击修改按钮时触发（customEdit为true才会触发） | item: 当前项数据 |
+
+### 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 配置样式函数
+
+## 更新日志
+
+### v1.0.0
+
+- 初始版本发布
+- 支持基础列表功能
+- 支持表单配置
+
+### v1.1.0
+
+- 添加表单联动
+- 优化列表性能
+- 修复已知问题
+
+## 后续规划
+
+1. [ ] 支持更多表单类型
+2. [ ] 添加表单预览功能
+3. [ ] 优化列表性能
+4. [ ] 完善错误处理
+5. [ ] 添加单元测试
+
+## 贡献指南
+
+欢迎提交 Issue 和 PR,请遵循以下规范:
+
+1. 遵循代码规范
+2. 添加必要的测试
+3. 更新相关文档
+
+## 许可证
+
+MIT License