# 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": [...]
}
```
