vue2-client 1.20.19 → 1.20.21

package/src/base-client/components/common/XDescriptions/index.md

@@ -1,382 +1,382 @@
-# XDescriptionsGroup
-
-动态Descriptions分组控件，根据JSON配置动态生成Descriptions，支持多种字段函数控制显示、样式和格式化。
-
-## 何时使用
-
-当需要一个动态生成的、支持条件显示、自定义样式和数据格式化的Descriptions时
-
-## 引用方式
-
-```javascript
-import XDescriptionsGroup from '@vue2-client/base-client/components/common/XDescriptions/XDescriptionsGroup'
-
-export default {
-    components: {
-      XDescriptionsGroup
-    }
-}
-```
-
-## API
-
-| 参数              | 说明          | 类型     | 默认值  |
-|-----------------|-------------|--------|------|
-| data           | 业务数据        | Object | {}   |
-| configName     | 配置文件名      | String | ''   |
-| serviceName     | 配置所属命名空间    | String | process.env.VUE_APP_SYSTEM_NAME |
-
-## 配置格式
-
-### 配置结构
-
-```javascript
-[
-  {
-    "name": "分组名称",
-    "type": "normal",     // 分组类型：normal/array/slot（可选，默认normal）
-    "key": "dataKey",     // 数据key（数组类型时必需）
-    "fields": [
-      {
-        "key": "字段key",
-        "name": "字段显示名称",
-        "span": 2,          // 列宽（可选，默认1）
-        "showIf": "(data, field) => ...",     // 条件显示函数（可选）
-        "styleFunc": "(value, data, field) => ...", // 样式函数（可选）
-        "formatFunc": "(value, data, field) => ...", // 格式化函数（可选）
-        "requireFunc": "(data, field) => ..." // 必填标记函数（可选）
-      }
-    ]
-  }
-]
-```
-
-### 全局配置说明
-
-#### column - 列数控制
-
-- **作用**: 控制每行显示的列数
-- **类型**: `Number`
-- **默认值**: `3`
-- **示例**: `"column": 2` 表示每行显示 2 列
-
-#### getRealData - 数据处理方式
-
-- **作用**: 是否使用 `getRealKeyData` 方法处理数据
-- **类型**: `Boolean`
-- **默认值**: `false`
-- **示例**: `"getRealData": true` 启用数据处理
-
-#### tabMode - 显示模式
-
-- **作用**: 控制组件的显示模式
-- **类型**: `String`
-- **可选值**: `'left' | 'top' | 'none'`
-- **默认值**: `'left'`
-- **示例**: `"tabMode": "top"` 使用顶部横向导航
-
-### 分组类型说明
-
-#### normal - 普通分组（默认）
-
-```javascript
-[
-  {
-    "name": "基本信息",
-    "type": "normal",
-    "fields": [
-      {
-        "key": "f_name",
-        "name": "设备名称"
-      }
-    ]
-  }
-]
-```
-
-#### array - 数组分组
-
-用于处理数组类型数据，会为每个数组项生成一个子描述：
-
-```javascript
-[
-  {
-    "name": "设备列表",
-    "type": "array",
-    "key": "devices",
-    "fields": [
-      {
-        "key": "f_name",
-        "name": "设备名称"
-      },
-      {
-        "key": "f_status",
-        "name": "设备状态"
-      }
-    ]
-  }
-]
-```
-
-#### slot - 插槽分组
-
-用于将某个分组交给父组件通过**具名插槽**自定义渲染，适用于配置无法覆盖的展示或交互。
-
-**配置说明：**
-
-- **name**：分组标题（left/top 模式下作为 Tab 文案，none 模式下可选展示）
-- **type**：`"slot"`，表示该分组为插槽分组
-- **slotName**：字符串，与父组件具名插槽名一致；省略时使用 `name` 作为插槽名
-
-**数组格式配置示例：**
-
-```javascript
-[
-  {
-    "name": "自定义区块",
-    "type": "slot",
-    "slotName": "customSection"
-  }
-]
-```
-
-**对象格式配置示例：**
-
-```javascript
-{
-  "自定义区块": {
-    "type": "slot",
-    "slotName": "customSection"
-  }
-}
-```
-
-**父组件用法：**
-
-通过具名插槽传入内容，插槽名与配置中的 `slotName` 一致。组件会向插槽注入当前详情 `data`，可使用作用域插槽接收：
-
-```html
-<XDescriptionsGroup :data="detail" config-name="xxx">
-  <template #customSection="{ data }">
-    <div>自定义内容，可访问当前详情 data：{{ data }}</div>
-  </template>
-</XDescriptionsGroup>
-```
-
-若不需要使用 `data`，也可使用默认插槽写法：
-
-```html
-<XDescriptionsGroup :data="detail" config-name="xxx">
-  <template #customSection>自定义静态内容</template>
-</XDescriptionsGroup>
-```
-
-### 字段属性说明
-
-#### span - 列宽控制
-
-- **作用**: 控制字段占用的列数
-- **类型**: `Number`
-- **默认值**: `1`
-- **示例**: `"span": 2` 表示该字段占用 2 列宽度
-
-### 字段函数说明
-
-#### 1. showIf - 条件显示函数
-
-- **作用**: 控制字段是否显示
-- **参数**: `(data, field)`
-- **返回值**: `boolean`
-- **示例**: `"showIf": "(data, field) => data.amount > 1000"`
-
-#### 2. styleFunc - 样式函数
-
-- **作用**: 设置字段内容的样式
-- **参数**: `(value, data, field)`
-- **返回值**: `Object` 样式对象，如 `{color: 'red'}`
-- **示例**: `"styleFunc": "(value, data, field) => ({ color: value > 0 ? 'green' : 'red' })"`
-
-#### 3. formatFunc - 格式化函数
-
-- **作用**: 自定义字段值的显示格式
-- **参数**: `(value, data, field)`
-- **返回值**: `String` 格式化后的字符串
-- **示例**: `"formatFunc": "(value, data, field) => '￥' + value.toLocaleString()"`
-
-#### 4. requireFunc - 必填标记函数
-
-- **作用**: 在字段标题后显示红色星号
-- **参数**: `(data, field)`
-- **返回值**: `boolean`
-- **示例**: `"requireFunc": "(data, field) => data.type === 'important'"`
-
-#### 4. canEdit - 是否可进行修改
-
-- **作用**: 如果canEdit配置为true，则渲染铅笔修改图标，由外部组件实现具体编辑逻辑
-- **参数**: `(field, value, data)`
-- **示例**: `"canEdit": true`
-
-## 完整配置示例
-
-### 普通分组配置示例
-
-```javascript
-// 配置文件：deviceInfo.json
-[
-  {
-    "name": "基本信息",
-    "fields": [
-      {
-        "key": "f_name",
-        "name": "设备名称",
-        "span": 2,
-        "requireFunc": "true",
-        "canEdit": true
-      },
-      {
-        "key": "f_status",
-        "name": "状态",
-        "showIf": "(data, field) => data.f_status",
-        "styleFunc": "(value, data, field) => ({ color: value === '正常' ? 'green' : 'red' })"
-      }
-    ]
-  },
-  {
-    "name": "财务信息",
-    "fields": [
-      {
-        "key": "f_amount",
-        "name": "金额",
-        "span": 2,
-        "showIf": "(data, field) => data.f_amount > 0",
-        "styleFunc": "(value, data, field) => ({ color: value > 5000 ? 'red' : 'green', fontWeight: 'bold' })",
-        "formatFunc": "(value, data, field) => '￥' + Number(value).toLocaleString()",
-        "requireFunc": "(data, field) => data.f_amount > 1000"
-      },
-      {
-        "key": "f_phone",
-        "name": "联系电话",
-        "formatFunc": "(value, data, field) => value ? value.replace(/(\\d{3})\\d{4}(\\d{4})/, '$1****$2') : '--'"
-      }
-    ]
-  }
-]
-```
-
-### 数组分组配置示例
-
-```javascript
-// 配置文件：deviceList.json
-[
-  {
-    "name": "设备列表",
-    "type": "array",
-    "key": "devices",
-    "fields": [
-      {
-        "key": "f_name",
-        "name": "设备名称",
-        "styleFunc": "(value, data, field) => ({ fontWeight: 'bold' })"
-      },
-      {
-        "key": "f_status",
-        "name": "状态",
-        "styleFunc": "(value, data, field) => ({ color: value === '在线' ? 'green' : 'gray' })"
-      },
-      {
-        "key": "f_amount",
-        "name": "金额",
-        "formatFunc": "(value, data, field) => value ? '￥' + value : '--'"
-      }
-    ]
-  }
-]
-```
-
-## 使用示例
-
-### 基础使用
-
-```vue
-<template>
-  <x-descriptions-group
-    :data="deviceData"
-    configName="deviceInfo">
-  </x-descriptions-group>
-</template>
-
-<script>
-import XDescriptionsGroup from '@vue2-client/base-client/components/common/XDescriptions/XDescriptionsGroup'
-
-export default {
-  components: {
-    XDescriptionsGroup
-  },
-  data () {
-    return {
-      deviceData: {
-        f_name: '智能水表001',
-        f_status: '正常',
-        f_amount: 15000,
-        f_phone: '13812345678'
-      }
-    }
-  }
-}
-</script>
-```
-
-### 高级用法 - 动态配置
-
-```vue
-<template>
-  <x-descriptions-group
-    :data="formData"
-    :configName="configName"
-    serviceName="customService">
-  </x-descriptions-group>
-</template>
-
-<script>
-export default {
-  data () {
-    return {
-      configName: 'dynamicForm',
-      formData: {
-        // 根据业务需求动态构建数据
-      }
-    }
-  },
-  created() {
-    // 根据用户权限动态选择配置
-    this.configName = this.isAdmin ? 'adminForm' : 'userForm'
-  }
-}
-</script>
-```
-
-## 注意事项
-
-1. **函数格式**: 所有函数字符串必须使用箭头函数格式，如 `"(data, field) => data.amount > 1000"`
-2. **错误处理**: 函数执行错误时会输出警告日志，不会影响组件正常渲染
-3. **性能考虑**: 函数会在每次渲染时执行，避免在函数中编写耗时操作
-4. **样式应用**: styleFunc 通过内联样式应用到字段内容上，优先级低于CSS类
-5. **兼容性**: 保持向后兼容，不配置函数的字段按原样显示
-
-## 支持的显示模式
-
-组件支持三种 tab 显示模式，通过配置文件设置：
-
-- `left`: 左侧垂直导航（默认）
-- `top`: 顶部横向导航
-- `none`: 无导航，直接显示所有内容
-
-配置示例：
-
-```javascript
-{
-  "tabMode": "top",
-  "column": 2,
-  "groups": [...]
-}
-```
+# XDescriptionsGroup
+
+动态Descriptions分组控件，根据JSON配置动态生成Descriptions，支持多种字段函数控制显示、样式和格式化。
+
+## 何时使用
+
+当需要一个动态生成的、支持条件显示、自定义样式和数据格式化的Descriptions时
+
+## 引用方式
+
+```javascript
+import XDescriptionsGroup from '@vue2-client/base-client/components/common/XDescriptions/XDescriptionsGroup'
+
+export default {
+    components: {
+      XDescriptionsGroup
+    }
+}
+```
+
+## API
+
+| 参数              | 说明          | 类型     | 默认值  |
+|-----------------|-------------|--------|------|
+| data           | 业务数据        | Object | {}   |
+| configName     | 配置文件名      | String | ''   |
+| serviceName     | 配置所属命名空间    | String | process.env.VUE_APP_SYSTEM_NAME |
+
+## 配置格式
+
+### 配置结构
+
+```javascript
+[
+  {
+    "name": "分组名称",
+    "type": "normal",     // 分组类型：normal/array/slot（可选，默认normal）
+    "key": "dataKey",     // 数据key（数组类型时必需）
+    "fields": [
+      {
+        "key": "字段key",
+        "name": "字段显示名称",
+        "span": 2,          // 列宽（可选，默认1）
+        "showIf": "(data, field) => ...",     // 条件显示函数（可选）
+        "styleFunc": "(value, data, field) => ...", // 样式函数（可选）
+        "formatFunc": "(value, data, field) => ...", // 格式化函数（可选）
+        "requireFunc": "(data, field) => ..." // 必填标记函数（可选）
+      }
+    ]
+  }
+]
+```
+
+### 全局配置说明
+
+#### column - 列数控制
+
+- **作用**: 控制每行显示的列数
+- **类型**: `Number`
+- **默认值**: `3`
+- **示例**: `"column": 2` 表示每行显示 2 列
+
+#### getRealData - 数据处理方式
+
+- **作用**: 是否使用 `getRealKeyData` 方法处理数据
+- **类型**: `Boolean`
+- **默认值**: `false`
+- **示例**: `"getRealData": true` 启用数据处理
+
+#### tabMode - 显示模式
+
+- **作用**: 控制组件的显示模式
+- **类型**: `String`
+- **可选值**: `'left' | 'top' | 'none'`
+- **默认值**: `'left'`
+- **示例**: `"tabMode": "top"` 使用顶部横向导航
+
+### 分组类型说明
+
+#### normal - 普通分组（默认）
+
+```javascript
+[
+  {
+    "name": "基本信息",
+    "type": "normal",
+    "fields": [
+      {
+        "key": "f_name",
+        "name": "设备名称"
+      }
+    ]
+  }
+]
+```
+
+#### array - 数组分组
+
+用于处理数组类型数据，会为每个数组项生成一个子描述：
+
+```javascript
+[
+  {
+    "name": "设备列表",
+    "type": "array",
+    "key": "devices",
+    "fields": [
+      {
+        "key": "f_name",
+        "name": "设备名称"
+      },
+      {
+        "key": "f_status",
+        "name": "设备状态"
+      }
+    ]
+  }
+]
+```
+
+#### slot - 插槽分组
+
+用于将某个分组交给父组件通过**具名插槽**自定义渲染，适用于配置无法覆盖的展示或交互。
+
+**配置说明：**
+
+- **name**：分组标题（left/top 模式下作为 Tab 文案，none 模式下可选展示）
+- **type**：`"slot"`，表示该分组为插槽分组
+- **slotName**：字符串，与父组件具名插槽名一致；省略时使用 `name` 作为插槽名
+
+**数组格式配置示例：**
+
+```javascript
+[
+  {
+    "name": "自定义区块",
+    "type": "slot",
+    "slotName": "customSection"
+  }
+]
+```
+
+**对象格式配置示例：**
+
+```javascript
+{
+  "自定义区块": {
+    "type": "slot",
+    "slotName": "customSection"
+  }
+}
+```
+
+**父组件用法：**
+
+通过具名插槽传入内容，插槽名与配置中的 `slotName` 一致。组件会向插槽注入当前详情 `data`，可使用作用域插槽接收：
+
+```html
+<XDescriptionsGroup :data="detail" config-name="xxx">
+  <template #customSection="{ data }">
+    <div>自定义内容，可访问当前详情 data：{{ data }}</div>
+  </template>
+</XDescriptionsGroup>
+```
+
+若不需要使用 `data`，也可使用默认插槽写法：
+
+```html
+<XDescriptionsGroup :data="detail" config-name="xxx">
+  <template #customSection>自定义静态内容</template>
+</XDescriptionsGroup>
+```
+
+### 字段属性说明
+
+#### span - 列宽控制
+
+- **作用**: 控制字段占用的列数
+- **类型**: `Number`
+- **默认值**: `1`
+- **示例**: `"span": 2` 表示该字段占用 2 列宽度
+
+### 字段函数说明
+
+#### 1. showIf - 条件显示函数
+
+- **作用**: 控制字段是否显示
+- **参数**: `(data, field)`
+- **返回值**: `boolean`
+- **示例**: `"showIf": "(data, field) => data.amount > 1000"`
+
+#### 2. styleFunc - 样式函数
+
+- **作用**: 设置字段内容的样式
+- **参数**: `(value, data, field)`
+- **返回值**: `Object` 样式对象，如 `{color: 'red'}`
+- **示例**: `"styleFunc": "(value, data, field) => ({ color: value > 0 ? 'green' : 'red' })"`
+
+#### 3. formatFunc - 格式化函数
+
+- **作用**: 自定义字段值的显示格式
+- **参数**: `(value, data, field)`
+- **返回值**: `String` 格式化后的字符串
+- **示例**: `"formatFunc": "(value, data, field) => '￥' + value.toLocaleString()"`
+
+#### 4. requireFunc - 必填标记函数
+
+- **作用**: 在字段标题后显示红色星号
+- **参数**: `(data, field)`
+- **返回值**: `boolean`
+- **示例**: `"requireFunc": "(data, field) => data.type === 'important'"`
+
+#### 4. canEdit - 是否可进行修改
+
+- **作用**: 如果canEdit配置为true，则渲染铅笔修改图标，由外部组件实现具体编辑逻辑
+- **参数**: `(field, value, data)`
+- **示例**: `"canEdit": true`
+
+## 完整配置示例
+
+### 普通分组配置示例
+
+```javascript
+// 配置文件：deviceInfo.json
+[
+  {
+    "name": "基本信息",
+    "fields": [
+      {
+        "key": "f_name",
+        "name": "设备名称",
+        "span": 2,
+        "requireFunc": "true",
+        "canEdit": true
+      },
+      {
+        "key": "f_status",
+        "name": "状态",
+        "showIf": "(data, field) => data.f_status",
+        "styleFunc": "(value, data, field) => ({ color: value === '正常' ? 'green' : 'red' })"
+      }
+    ]
+  },
+  {
+    "name": "财务信息",
+    "fields": [
+      {
+        "key": "f_amount",
+        "name": "金额",
+        "span": 2,
+        "showIf": "(data, field) => data.f_amount > 0",
+        "styleFunc": "(value, data, field) => ({ color: value > 5000 ? 'red' : 'green', fontWeight: 'bold' })",
+        "formatFunc": "(value, data, field) => '￥' + Number(value).toLocaleString()",
+        "requireFunc": "(data, field) => data.f_amount > 1000"
+      },
+      {
+        "key": "f_phone",
+        "name": "联系电话",
+        "formatFunc": "(value, data, field) => value ? value.replace(/(\\d{3})\\d{4}(\\d{4})/, '$1****$2') : '--'"
+      }
+    ]
+  }
+]
+```
+
+### 数组分组配置示例
+
+```javascript
+// 配置文件：deviceList.json
+[
+  {
+    "name": "设备列表",
+    "type": "array",
+    "key": "devices",
+    "fields": [
+      {
+        "key": "f_name",
+        "name": "设备名称",
+        "styleFunc": "(value, data, field) => ({ fontWeight: 'bold' })"
+      },
+      {
+        "key": "f_status",
+        "name": "状态",
+        "styleFunc": "(value, data, field) => ({ color: value === '在线' ? 'green' : 'gray' })"
+      },
+      {
+        "key": "f_amount",
+        "name": "金额",
+        "formatFunc": "(value, data, field) => value ? '￥' + value : '--'"
+      }
+    ]
+  }
+]
+```
+
+## 使用示例
+
+### 基础使用
+
+```vue
+<template>
+  <x-descriptions-group
+    :data="deviceData"
+    configName="deviceInfo">
+  </x-descriptions-group>
+</template>
+
+<script>
+import XDescriptionsGroup from '@vue2-client/base-client/components/common/XDescriptions/XDescriptionsGroup'
+
+export default {
+  components: {
+    XDescriptionsGroup
+  },
+  data () {
+    return {
+      deviceData: {
+        f_name: '智能水表001',
+        f_status: '正常',
+        f_amount: 15000,
+        f_phone: '13812345678'
+      }
+    }
+  }
+}
+</script>
+```
+
+### 高级用法 - 动态配置
+
+```vue
+<template>
+  <x-descriptions-group
+    :data="formData"
+    :configName="configName"
+    serviceName="customService">
+  </x-descriptions-group>
+</template>
+
+<script>
+export default {
+  data () {
+    return {
+      configName: 'dynamicForm',
+      formData: {
+        // 根据业务需求动态构建数据
+      }
+    }
+  },
+  created() {
+    // 根据用户权限动态选择配置
+    this.configName = this.isAdmin ? 'adminForm' : 'userForm'
+  }
+}
+</script>
+```
+
+## 注意事项
+
+1. **函数格式**: 所有函数字符串必须使用箭头函数格式，如 `"(data, field) => data.amount > 1000"`
+2. **错误处理**: 函数执行错误时会输出警告日志，不会影响组件正常渲染
+3. **性能考虑**: 函数会在每次渲染时执行，避免在函数中编写耗时操作
+4. **样式应用**: styleFunc 通过内联样式应用到字段内容上，优先级低于CSS类
+5. **兼容性**: 保持向后兼容，不配置函数的字段按原样显示
+
+## 支持的显示模式
+
+组件支持三种 tab 显示模式，通过配置文件设置：
+
+- `left`: 左侧垂直导航（默认）
+- `top`: 顶部横向导航
+- `none`: 无导航，直接显示所有内容
+
+配置示例：
+
+```javascript
+{
+  "tabMode": "top",
+  "column": 2,
+  "groups": [...]
+}
+```