af-mobile-client-vue3 1.2.39 → 1.2.40

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "af-mobile-client-vue3",
   "type": "module",
-  "version": "1.2.39",
+  "version": "1.2.40",
   "packageManager": "pnpm@10.12.3",
   "description": "Vue + Vite component lib",
   "engines": {

package/src/components/data/XCellList/index.vue

@@ -141,6 +141,9 @@ const title = ref('')
 // 按钮权限
 const buttonPermissions = ref([])
 
+// 默认参数
+const defaultParams = {}
+
 const slots = useSlots()
 
 // 当前组件实例（不推荐使用，可能会在后续的版本更迭中调整，暂时用来绑定函数的上下文）
@@ -235,7 +238,6 @@ function initComponent() {
 
 // 初始化条件参数
 function initConditionParams(formItems, isQuery) {
-  const defaultParams = {}
   let hasDefaults: boolean
 
   // 从表单配置中获取所有默认值
@@ -287,7 +289,7 @@ function onRefresh() {
     finishedText.value = '加载完成'
     finished.value = false
     loading.value = true
-    onLoad()
+    onLoad(defaultParams)
   }, 100)
 }
 

package/src/components/data/XFormGroup/README.md

@@ -0,0 +1,677 @@
+# XFormGroup 表单组组件
+
+## 组件概述
+
+XFormGroup 是一个基于 Vue 3 + TypeScript + Vant 4 开发的表单组组件，支持多标签页表单展示，可以通过配置实现复杂的表单组合。组件支持两种模式：普通表单模式和插槽（slot）模式。
+
+## 功能特性
+
+- 🏷️ **多标签页支持**：使用 Vant Tabs 组件实现标签页切换
+- 🔧 **插槽模式**：支持通过 slot 自定义表单内容
+- 📝 **表单验证**：支持表单数据验证和提交
+- 🎯 **动态配置**：通过配置文件动态生成表单结构
+- 🔄 **数据绑定**：支持表单数据的双向绑定
+- 📱 **移动端优化**：基于 Vant 4 组件库，专为移动端设计
+
+## 基础用法
+
+```vue
+<template>
+  <XFormGroup
+    :config-name="configName"
+    :service-name="serviceName"
+    :group-form-data="formData"
+    mode="新增"
+    @submit="handleSubmit"
+  />
+</template>
+
+<script setup lang="ts">
+import XFormGroup from '@af-mobile-client-vue3/components/data/XFormGroup/index.vue'
+import { ref } from 'vue'
+
+const configName = ref('appapplyuserinfoFormGroup')
+const serviceName = ref('af-apply')
+const formData = ref({})
+
+function handleSubmit(result: any) {
+  console.log('表单提交数据:', result)
+}
+</script>
+```
+
+## Props 参数详解
+
+### configName
+- **类型**: `string`
+- **默认值**: `''`
+- **说明**: 表单配置名称，用于从后端获取表单配置信息
+- **示例**: `'appapplyuserinfoFormGroup'`
+
+### serviceName
+- **类型**: `string | undefined`
+- **默认值**: `undefined`
+- **说明**: 服务名称，用于指定后端服务
+- **示例**: `'af-apply'`
+
+### groupFormData
+- **类型**: `object`
+- **默认值**: `() => ({})`
+- **说明**: 表单组数据，用于初始化表单数据
+- **示例**: 
+```javascript
+{
+  userInfo: { name: '张三', age: 25 },
+  deviceInfo: { deviceId: '001', status: 'active' }
+}
+```
+
+### mode
+- **类型**: `string`
+- **默认值**: `'查询'`
+- **说明**: 表单模式，控制表单的显示和操作模式
+- **可选值**: `'查询'` | `'新增'` | `'编辑'` | `'查看'`
+
+## 插槽（Slot）使用详解
+
+### 插槽模式配置
+
+当配置中的 `formGroupType` 为 `'slot'` 时，组件会渲染插槽内容而不是默认的 XForm 组件。
+
+#### 插槽参数
+
+插槽会接收以下参数：
+
+- **item**: 当前标签页的配置项
+- **formData**: 当前标签页对应的表单数据
+- **setRef**: 注册表单实例的函数
+- **removeRef**: 注销表单实例的函数
+
+### 完整使用示例
+
+下面是一个完整的使用示例，展示了如何使用 XFormGroup 组件和插槽功能：
+
+#### 1. 主页面组件
+
+```vue
+<!-- FormGroupDemo.vue -->
+<template>
+  <NormalDataLayout title="表单组示例">
+    <template #layout_content>
+      <XFormGroup
+        ref="formGroup"
+        :config-name="configName"
+        :service-name="serviceName"
+        :group-form-data="formData"
+        mode="新增"
+        @submit="handleSubmit"
+      >
+        <!-- 用户信息插槽 -->
+        <template #user="{ setRef, removeRef, item, formData }">
+          <UserForm 
+            :set-ref="setRef"
+            :remove-ref="removeRef"
+            :form-group-name="'userInfo'"
+            :form-data="formData"
+          />
+        </template>
+        
+        <!-- 设备信息插槽 -->
+        <template #device="{ setRef, removeRef, item, formData }">
+          <DeviceForm
+            :set-ref="setRef"
+            :remove-ref="removeRef"
+            :form-group-name="'deviceInfo'"
+            :form-data="formData"
+          />
+        </template>
+      </XFormGroup>
+    </template>
+  </NormalDataLayout>
+</template>
+
+<script setup lang="ts">
+import XFormGroup from '@af-mobile-client-vue3/components/data/XFormGroup/index.vue'
+import NormalDataLayout from '@af-mobile-client-vue3/components/layout/NormalDataLayout/index.vue'
+import UserForm from './components/UserForm.vue'
+import DeviceForm from './components/DeviceForm.vue'
+import { showToast } from 'vant'
+import { ref } from 'vue'
+
+const configName = ref('complexFormGroup')
+const serviceName = ref('af-apply')
+const formData = ref({
+  userInfo: {},
+  deviceInfo: {}
+})
+
+const formGroup = ref()
+
+function handleSubmit(result: any) {
+  console.log('提交数据:', result)
+  // result 结构：
+  // {
+  //   userInfo: { name: '张三', phone: '13800138000', email: 'zhangsan@example.com' },
+  //   deviceInfo: { deviceId: '001', deviceName: '测试设备', deviceType: '传感器', status: 'active' }
+  // }
+  showToast('提交成功')
+}
+</script>
+```
+
+#### 2. 用户信息表单组件
+
+```vue
+<!-- components/UserForm.vue -->
+<script setup lang="ts">
+import { defineExpose, defineProps, onMounted, onUnmounted, ref } from 'vue'
+import { Field as VanField, CellGroup as VanCellGroup } from 'vant'
+
+interface UserFormProps {
+  setRef?: (refValue: any) => void
+  removeRef?: (refValue: any) => void
+  formGroupName?: string
+  formData?: any
+}
+
+const props = withDefaults(defineProps<UserFormProps>(), {
+  setRef: () => {},
+  removeRef: () => {},
+  formGroupName: 'userInfo',
+  formData: () => ({})
+})
+
+const formData = ref({
+  name: '',
+  phone: '',
+  email: '',
+  ...props.formData
+})
+
+// 表单验证方法
+async function validate() {
+  if (!formData.value.name) {
+    throw new Error('姓名不能为空')
+  }
+  if (!formData.value.phone) {
+    throw new Error('手机号不能为空')
+  }
+  // 手机号格式验证
+  const phoneRegex = /^1[3-9]\d{9}$/
+  if (!phoneRegex.test(formData.value.phone)) {
+    throw new Error('手机号格式不正确')
+  }
+  return Promise.resolve()
+}
+
+// 获取表单数据方法
+function getFormData() {
+  return {
+    name: formData.value.name,
+    phone: formData.value.phone,
+    email: formData.value.email
+  }
+}
+
+// 重置表单方法
+function resetForm() {
+  formData.value = {
+    name: '',
+    phone: '',
+    email: ''
+  }
+}
+
+// 暴露给父组件的方法和属性
+const exposeObj = {
+  validate,
+  getFormData,
+  resetForm,
+  formGroupName: props.formGroupName
+}
+
+// 暴露给父组件
+defineExpose(exposeObj)
+
+// 组件挂载时注册到父组件
+onMounted(() => {
+  console.log('UserForm 组件挂载，注册到父组件')
+  props.setRef(exposeObj)
+})
+
+// 组件卸载时从父组件注销
+onUnmounted(() => {
+  console.log('UserForm 组件卸载，从父组件注销')
+  props.removeRef(exposeObj)
+})
+</script>
+
+<template>
+  <div class="user-form">
+    <van-cell-group inset>
+      <van-field
+        v-model="formData.name"
+        label="姓名"
+        placeholder="请输入姓名"
+        :rules="[{ required: true, message: '请输入姓名' }]"
+      />
+      <van-field
+        v-model="formData.phone"
+        label="手机号"
+        placeholder="请输入手机号"
+        :rules="[{ required: true, message: '请输入手机号' }]"
+      />
+      <van-field
+        v-model="formData.email"
+        label="邮箱"
+        placeholder="请输入邮箱"
+      />
+    </van-cell-group>
+  </div>
+</template>
+
+<style scoped lang="less">
+.user-form {
+  padding: 16px;
+}
+</style>
+```
+
+#### 3. 设备信息表单组件
+
+```vue
+<!-- components/DeviceForm.vue -->
+<script setup lang="ts">
+import { defineExpose, defineProps, onMounted, onUnmounted, ref } from 'vue'
+import { Field as VanField, Cell as VanCell, CellGroup as VanCellGroup, Switch as VanSwitch } from 'vant'
+
+interface DeviceFormProps {
+  setRef?: (refValue: any) => void
+  removeRef?: (refValue: any) => void
+  formGroupName?: string
+  formData?: any
+}
+
+const props = withDefaults(defineProps<DeviceFormProps>(), {
+  setRef: () => {},
+  removeRef: () => {},
+  formGroupName: 'deviceInfo',
+  formData: () => ({})
+})
+
+const formData = ref({
+  deviceId: '',
+  deviceName: '',
+  deviceType: '',
+  status: 'active',
+  isOnline: false,
+  ...props.formData
+})
+
+// 表单验证
+async function validate() {
+  if (!formData.value.deviceId) {
+    throw new Error('设备ID不能为空')
+  }
+  if (!formData.value.deviceName) {
+    throw new Error('设备名称不能为空')
+  }
+  return Promise.resolve()
+}
+
+// 获取表单数据
+function getFormData() {
+  return {
+    deviceId: formData.value.deviceId,
+    deviceName: formData.value.deviceName,
+    deviceType: formData.value.deviceType,
+    status: formData.value.status,
+    isOnline: formData.value.isOnline
+  }
+}
+
+// 重置表单
+function resetForm() {
+  formData.value = {
+    deviceId: '',
+    deviceName: '',
+    deviceType: '',
+    status: 'active',
+    isOnline: false
+  }
+}
+
+// 暴露给父组件
+const exposeObj = {
+  validate,
+  getFormData,
+  resetForm,
+  formGroupName: props.formGroupName
+}
+
+defineExpose(exposeObj)
+
+// 生命周期管理
+onMounted(() => {
+  console.log('DeviceForm 挂载，注册到父组件')
+  props.setRef(exposeObj)
+})
+
+onUnmounted(() => {
+  console.log('DeviceForm 卸载，从父组件注销')
+  props.removeRef(exposeObj)
+})
+</script>
+
+<template>
+  <div class="device-form">
+    <van-cell-group inset>
+      <van-field
+        v-model="formData.deviceId"
+        label="设备ID"
+        placeholder="请输入设备ID"
+        :rules="[{ required: true, message: '请输入设备ID' }]"
+      />
+      <van-field
+        v-model="formData.deviceName"
+        label="设备名称"
+        placeholder="请输入设备名称"
+        :rules="[{ required: true, message: '请输入设备名称' }]"
+      />
+      <van-field
+        v-model="formData.deviceType"
+        label="设备类型"
+        placeholder="请输入设备类型"
+      />
+      <van-cell title="设备状态">
+        <template #value>
+          <span :class="formData.status === 'active' ? 'text-success' : 'text-warning'">
+            {{ formData.status === 'active' ? '正常' : '异常' }}
+          </span>
+        </template>
+      </van-cell>
+      <van-cell title="在线状态">
+        <template #value>
+          <van-switch v-model="formData.isOnline" />
+        </template>
+      </van-cell>
+    </van-cell-group>
+  </div>
+</template>
+
+<style scoped lang="less">
+.device-form {
+  padding: 16px;
+  
+  .text-success {
+    color: #07c160;
+  }
+  .text-warning {
+    color: #ff976a;
+  }
+}
+</style>
+```
+
+#### 4. 配置结构示例
+
+```javascript
+// 后端配置结构示例
+{
+  "groups": [
+    {
+      "groupName": "userInfo",
+      "describe": "用户信息",
+      "tableName": "用户信息表",
+      "formGroupType": "slot",
+      "slotName": "user",
+      "showSubmitBtn": false
+    },
+    {
+      "groupName": "deviceInfo", 
+      "describe": "设备信息",
+      "tableName": "设备信息表",
+      "formGroupType": "slot",
+      "slotName": "device",
+      "showSubmitBtn": true
+    }
+  ],
+  "showSubmitBtn": true
+}
+```
+
+#### 5. setRef 和 removeRef 工作原理
+
+```javascript
+// XFormGroup 组件内部的实现逻辑
+const xFormListRef = ref<XFormLike[]>([])
+
+// 注册表单实例，避免重复
+function setRef(refValue: XFormLike) {
+  if (refValue && !xFormListRef.value.includes(refValue)) {
+    xFormListRef.value.push(refValue)
+    console.log('注册表单实例:', refValue.formGroupName)
+  }
+}
+
+// 注销表单实例
+function removeRef(refValue: XFormLike) {
+  const idx = xFormListRef.value.indexOf(refValue)
+  if (idx !== -1) {
+    xFormListRef.value.splice(idx, 1)
+    console.log('注销表单实例:', refValue.formGroupName)
+  }
+}
+
+// 提交时收集所有表单数据
+async function submit() {
+  const allFormData = {}
+  
+  for (const formInstance of xFormListRef.value) {
+    try {
+      // 验证表单
+      await formInstance.validate()
+      
+      // 获取表单数据
+      if (formInstance.formGroupName && typeof formInstance.getFormData === 'function') {
+        allFormData[formInstance.formGroupName] = formInstance.getFormData()
+      }
+    } catch (error) {
+      console.error('表单验证失败:', error)
+      return
+    }
+  }
+  
+  emit('submit', allFormData)
+}
+```
+
+### 关键要点
+
+1. **必须实现的方法**：
+   - `validate()`: 表单验证方法
+   - `getFormData()`: 获取表单数据方法
+   - `formGroupName`: 表单组名称
+
+2. **生命周期管理**：
+   - 在 `onMounted` 时调用 `setRef` 注册
+   - 在 `onUnmounted` 时调用 `removeRef` 注销
+
+3. **数据传递**：
+   - 通过 `defineExpose` 暴露方法给父组件
+   - 通过 `props` 接收父组件传递的参数
+
+4. **插槽使用**：
+   - 插槽名称必须与配置中的 `slotName` 一致
+   - 必须传递 `setRef` 和 `removeRef` 给子组件
+
+## 事件
+
+### submit
+- **参数**: `formData: object`
+- **说明**: 表单提交事件，当用户点击提交按钮时触发
+- **示例**:
+```javascript
+function handleSubmit(formData) {
+  console.log('表单数据:', formData)
+  // 处理表单提交逻辑
+}
+```
+
+## 方法
+
+### init(params: Form)
+- **参数**: `params` - 初始化参数对象
+- **说明**: 手动初始化组件，可以动态改变配置
+- **示例**:
+```javascript
+formGroup.value.init({
+  configName: 'newConfig',
+  serviceName: 'newService',
+  groupFormData: { ... },
+  mode: '新增'
+})
+```
+
+### setRef(refValue: XFormLike)
+- **参数**: `refValue` - 表单实例
+- **说明**: 注册表单实例到组件中，用于统一管理和提交
+
+### removeRef(refValue: XFormLike)
+- **参数**: `refValue` - 表单实例
+- **说明**: 从组件中注销表单实例
+
+## 配置结构说明
+
+### 基础配置结构
+```javascript
+{
+  "groups": [
+    {
+      "groupName": "userInfo",
+      "describe": "用户信息",
+      "tableName": "用户信息表",
+      "formGroupType": "form", // 或 "slot"
+      "slotName": "user", // 当 formGroupType 为 "slot" 时使用
+      "showSubmitBtn": false
+    },
+    {
+      "groupName": "deviceInfo", 
+      "describe": "设备信息",
+      "tableName": "设备信息表",
+      "formGroupType": "slot",
+      "slotName": "device",
+      "showSubmitBtn": true
+    }
+  ],
+  "showSubmitBtn": true
+}
+```
+
+### 配置项说明
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| groupName | string | 分组名称，用于数据分组 |
+| describe | string | 标签页显示标题 |
+| tableName | string | 表名，当 describe 为空时作为标题 |
+| formGroupType | string | 表单类型，'form' 为普通表单，'slot' 为插槽 |
+| slotName | string | 插槽名称，当 formGroupType 为 'slot' 时使用 |
+| showSubmitBtn | boolean | 是否显示提交按钮 |
+
+## 样式定制
+
+组件使用 Less 预处理器，可以通过以下方式定制样式：
+
+```less
+#x-form-group {
+  background-color: #f7f8fa;
+  padding-bottom: 10px;
+  
+  .x-form-group-item {
+    margin: 20px 0;
+  }
+  
+  // 自定义标签页样式
+  :deep(.van-tabs__nav) {
+    background-color: #fff;
+  }
+  
+  // 自定义按钮样式
+  :deep(.van-button--primary) {
+    background-color: #1989fa;
+  }
+}
+```
+
+## 注意事项
+
+1. **插槽注册**: 使用插槽模式时，子组件必须通过 `setRef` 和 `removeRef` 注册到父组件
+2. **数据同步**: 插槽组件需要实现 `getFormData` 方法返回表单数据
+3. **表单验证**: 插槽组件可以实现 `validate` 方法进行表单验证
+4. **生命周期**: 插槽组件需要在 `onMounted` 时注册，`onUnmounted` 时注销
+5. **配置加载**: 组件会在 `onBeforeMount` 时自动加载配置，也可以通过 `init` 方法手动初始化
+
+## 完整示例
+
+```vue
+<template>
+  <NormalDataLayout title="表单组示例">
+    <template #layout_content>
+      <XFormGroup
+        ref="formGroup"
+        :config-name="configName"
+        :service-name="serviceName"
+        :group-form-data="formData"
+        mode="新增"
+        @submit="handleSubmit"
+      >
+        <!-- 用户信息插槽 -->
+        <template #user="{ setRef, removeRef, item, formData }">
+          <UserForm 
+            :set-ref="setRef"
+            :remove-ref="removeRef"
+            :form-group-name="'userInfo'"
+            :form-data="formData"
+          />
+        </template>
+        
+        <!-- 设备信息插槽 -->
+        <template #device="{ setRef, removeRef, item, formData }">
+          <DeviceForm
+            :set-ref="setRef"
+            :remove-ref="removeRef"
+            :form-group-name="'deviceInfo'"
+            :form-data="formData"
+          />
+        </template>
+      </XFormGroup>
+    </template>
+  </NormalDataLayout>
+</template>
+
+<script setup lang="ts">
+import XFormGroup from '@af-mobile-client-vue3/components/data/XFormGroup/index.vue'
+import NormalDataLayout from '@af-mobile-client-vue3/components/layout/NormalDataLayout/index.vue'
+import UserForm from './components/UserForm.vue'
+import DeviceForm from './components/DeviceForm.vue'
+import { showToast } from 'vant'
+import { ref } from 'vue'
+
+const configName = ref('complexFormGroup')
+const serviceName = ref('af-apply')
+const formData = ref({
+  userInfo: {},
+  deviceInfo: {}
+})
+
+const formGroup = ref()
+
+function handleSubmit(result: any) {
+  console.log('提交数据:', result)
+  showToast('提交成功')
+}
+</script>
+```
+
+这个文档详细介绍了 XFormGroup 组件的使用方法，特别是插槽的使用方式和各个参数的详细说明。开发者可以根据这个文档快速上手使用该组件。