---
title: "4.2.4.1、表单数据：FormDataAPIService"
docId: "954968132767711233"
source: "https://weapp.eteams.cn/build/techdoc/wdoc/index.html#/public/repository/9c2e5f92-03b4-4207-9b22-a0c1dd79ac56/doc/954968132767711233"
---
> 所属包：weaver-common-form-extend
> 
> 所属类：com.weaver.common.form.formapi.FormAPIService

### 1 表单数据(FormData)相关接口

#### 1.1 保存/修改表单数据(包括表单数据详情-保存全部字段数据)

**方法名：**

```java
/**
 * @Description: 保存/修改表单数据(包括表单数据详情-保存全部字段数据)
 * @param formData 表单数据
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return FormData 表单数据
 * @throws
 */
FormData saveFormData(FormData formData, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formData | 是 | FormData | com.weaver.common.form.data.FormData | 表单数据Bean |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| FormData | com.weaver.common.form.data.FormData | 表单数据Bean |
| **示例：** |  |  |

```java
@GetMapping("/buildFormData")
public void buildFormData(){
    // 临时人员（正式使用这里需要替换成真正人员）
    SimpleEmployee employee = new SimpleEmployee();
    employee.setId(idGenerator.generate());     // 人员id
    employee.setTenantKey("t7akvdnf84");        // 租户key
    // 表单id
    Long formId = 123122132l;
    // 获取表单布局详情
    FormLayout formLayout = formLayoutService.getByFormId(formId);
    // 根据表单布局对象构建表单数据默认值（控件默认值）
    // isSave:是否保存数据到数据库，true:保存到数据库 formdata里面可以取到id  false:不保存到数据库
    FormData formData = formDataService.createFormData(formLayout,employee,false);
    List<FormDataDetail> dataDetails = formData.getDataDetails();
    // isDel 0 未删除  1已删除  null 查询全部字段
    List<FormField> formFields = formFieldService.getFieldByStatus(formId,0,employee);
    for(FormField field : formFields){
        FormDataDetail dataDetail = new FormDataDetail();
        dataDetail.setFormField(field);
        // 选项类型控件
        if(ComponentConfig.isOptionComponent(field.getComponentKey())){
            List<FormDataOption>  dataOptions = new ArrayList<>();
            // 根据选项名称生成选项
            List<FieldOption> fieldOptions = fieldOptionService.getByFieldIdAndFormId(formId,field.getId(),employee);
            List<Option> options = new ArrayList<>();
            for(FieldOption fieldOption : fieldOptions){
                Option opt = new Option();
                opt.setName(fieldOption.getName());
                opt.setSelectionId(fieldOption.getId()+"");
                opt.setScore(fieldOption.getScore()+"");
                options.add(opt);
            }
            FormDataOption dataOption = formDataOptionService.bulidFormDataOption(options,"选项1",null);
            dataOptions.add(dataOption);
            dataDetail.setDataOptions(dataOptions);
        // 多行文本控件
        }else if(ComponentType.TextArea.toString().equals(field.getComponentKey())){
            dataDetail.setFormField(field);
            FormDataText text = new FormDataText();
            text.setContent("文本框值");                 // 纯文本
            text.setRichContent("<span>文本框值</span>");// 富文本
            dataDetail.setDataText(text);
        // 文本类型控件
        }else{
            dataDetail.setContent("文本框值");
        }
        dataDetails.add(dataDetail);
    }
    formAPIService.saveFormData(formData,employee);
    logger.info(JSONObject.toJSONString(formData));
}
```

#### 1.2 保存/修改表单数据并校验必填(包括表单数据详情-保存全部字段数据)

**方法名：**

```java
/**
 * @Description: 保存/修改表单数据并校验必填(包括表单数据详情-保存全部字段数据)
 * @param formData 表单数据
 * @param fieldIds 需要校验必填的字段ID集合
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return FormData 表单数据
 * @throws
 */
FormData saveFormDataAndCheckRequired(FormData formData, List<Long> fieldIds, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formData | 是 | FormData | com.weaver.common.form.data.FormData | 表单数据Bean |
| fieldIds | 是 | SimpleEmployee | java.lang.Long | 需要校验必填的字段ID集合 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| FormData | com.weaver.common.form.data.FormData | 表单数据Bean |

#### 1.3 保存表单字段数据（自动保存-保存部分字段数据）

**方法名：**

```java
/**
 * @Description: 保存表单字段数据（自动保存-保存部分字段数据）
 * @param formData 表单数据
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return FormData 表单数据
 * @throws
 */
FormData saveFieldData(FormData formData, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formData | 是 | FormData | com.weaver.common.form.data.FormData | 表单数据Bean |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| FormData | com.weaver.common.form.data.FormData | 表单数据Bean |

#### 1.4 根据表单布局创建表单数据（包含默认值）

**方法名：**

```java
/**
 * @Description: 根据表单布局创建表单数据（包含默认值）
 * @param layout 表单布局
 * @param isSave 创建的数据是否直接插入到数据库中
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return FormData 表单数据
 * @throws
 */
FormData createFormDataDefaultValueByFormLayout(FormLayout layout, boolean isSave, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| layout | 是 | FormLayout | com.weaver.common.form.layout.FormLayout | 表单布局Bean |
| isSave | 是 | boolean | - | 创建的数据是否直接插入到数据库中 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| FormData | com.weaver.common.form.data.FormData | 表单数据Bean |

#### 1.5 根据ID获取表单数据（包含字段数据详情FormDataDetail）

**方法名：**

```java
/**
 * @Description: 根据ID获取表单数据（包含字段数据详情FormDataDetail）
 * @param dataId 表单数据ID
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return FormData 表单数据
 * @throws
 */
FormData getFormDataContainsDataDetailsById(Long dataId, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataId | 是 | Long | java.lang.Long | 表单数据ID |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| FormData | com.weaver.common.form.data.FormData | 表单数据Bean |
| **示例：** |  |  |

```java
FormData formdata = formAPIService.getFormDataContainsDataDetailsById(dataId, employee);
```

#### 1.6 根据表单数据ID集合查询表单数据集合（包含字段数据详情FormDataDetail）

**方法名：**

```java
/**
 * @Description: 根据表单数据ID集合查询表单数据集合（包含字段数据详情FormDataDetail）
 * @param dataIds 表单数据ID集合
 * @param formId 表单ID
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return List<FormData> 表单数据集合
 * @throws
 */
List<FormData> listFormDataContainsDataDetailsByIds(List<Long> dataIds, Long formId, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataIds | 是 | `List<Long>` | java.lang.Long | 表单数据ID集合 |
| formId | 是 | Long | java.lang.Long | 表单ID |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| `List<FormData>` | com.weaver.common.form.data.FormData | 表单数据Bean集合 |
| **示例：** |  |  |

```java
List<FormData> formDatas = formAPIService.listFormDataContainsDataDetailsByIds(dataIds, formId, employee);
```

#### 1.7 高级搜索：根据表单数据搜索实体类，查询表单数据集合

**方法名：**

```java
/**
 * @Description: 高级搜索：根据表单数据搜索实体类，查询表单数据集合
 * @param entity 表单数据搜索实体类
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return List<FormData> 表单数据集合 
 * @throws
 */
List<FormData> listFormDataBySearchEntity(FormDataSearchEntity entity, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| entity | 是 | FormDataSearchEntity | com.weaver.common.form.searchentity.FormDataSearchEntity | 表单数据高级搜索实体类 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |

**FormDataSearchEntity：**

> 描述：表单数据高级搜索实体类（支持扩展条件）
> 
> 所属包：weaver-common-form-extend
> 
> 所属类：com.weaver.common.form.searchentity.FormDataSearchEntity

| 属性名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataId | 否 | Long | java.lang.Long | 表单数据Id |
| dataIds | 否 | `List<Long>` | java.lang.Long | 表单数据Id集合（与dataId不可同时传入） |
| formId | 是 | Long | java.lang.Long | 表单Id |
| containsDataDetails | 否 | boolean | - | 是否查询表单数据详情 |
| fieldIsDelete | 是 | Integer | java.lang.Integer | 是否删除 0 :未删除;1:已删除; null:全部（默认为 0） |
| formTableIdList | 否 | List<Long> | java.lang.Long | 物理表Id集合，如果传递了只会查询当前物理表下的字段数据 |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| `List<FormData>` | com.weaver.common.form.data.FormData | 表单数据Bean集合 |
| **示例：** |  |  |

```java
List<FormData> formDatas = formAPIService.listFormDataBySearchEntity(entity, employee);
```

#### 1.8 根据表单Id创建表单数据

**方法名：**

```java
/**
 * @Description: 根据表单Id创建表单数据
 * @param formId 表单Id
 * @param formData 表单数据（有值时，直接保存；传入null时，根据formId生成表单默认值）
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return FormData 表单数据
 * @throws
 */
FormData createFormDataByFormId(Long formId, FormData formData, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formId | 是 | Long | java.lang.Long | 表单Id |
| formData | 是 | FormData | com.weaver.common.form.data.FormData | 表单数据Bean 有值时：直接保存  传入null时：根据formId生成表单默认值 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| FormData | com.weaver.common.form.data.FormData | 表单数据Bean |

#### 1.9 批量保存/修改表单数据(包括表单数据详情-保存全部字段数据)

**方法名：**

```java
/**
 * @Description: 批量保存/修改表单数据(包括表单数据详情-保存全部字段数据)
 * @param formDataList 表单数据集合
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return FormData 表单数据
 * @throws
 */
List<FormData> batchSaveFormData(List<FormData> formDataList, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formDataList | 是 | `List<FormData>` | com.weaver.common.form.data.FormData | 表单数据Bean集合 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| `List<FormData>` | com.weaver.common.form.data.FormData | 表单数据Bean集合 |

#### 1.10 表单数据必填校验

**方法名：**

```java
/**
 * @Description: 表单数据必填校验
 * @param entity 表单数据校验实体类
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return WeaResult 校验信息
 * @throws
 */
WeaResult checkRequiredByCheckEntity(FormDataCheckEntity entity, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| entity | 是 | FormDataCheckEntity | com.weaver.common.form.searchentity.FormDataCheckEntity | 表单数据校验实体类 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |

**FormDataCheckEntity：**

> 描述：表单数据校验实体类（支持扩展条件）
> 
> 所属包：weaver-common-form-extend
> 
> 所属类：com.weaver.common.form.searchentity.FormDataCheckEntity

**FormDataCheckEntity属性优先级说明：**

> 必填校验两个关键参数：formData、fieldIdList
> 
> formData来源优先级：formData > formDataList > formDataId > formDataIds
> 
> 传入formDataIds时，必须传入formId
> 
> fieldIdList来源优先级：fieldIdList > permissionIds
> 
> permissionIds传入多个权限Id时，写权限合并（必填校验只校验有【写权限】的字段）
> 
> 无法获取formData或fieldIdList时，不做校验（WeaResult返回【status: true】）

| 属性名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formId | 否 | Long | java.lang.Long | 表单Id |
| formDataId | 否 | Long | java.lang.Long | 表单数据Id |
| formData | 否 | FormData | com.weaver.common.form.data.FormData | 表单数据Bean |
| formDataIds | 否 | `List<Long>` | java.lang.Long | 表单数据Id |
| formDataList | 否 | `List<FormData>` | com.weaver.common.form.data.FormData | 表单数据Bean集合 |
| fieldIdList | 否 | `List<Long>` | java.lang.Long | 需要校验必填的表单字段Id集合 |
| permissionIds | 否 | `List<Long>` | java.lang.Long | 字段权限Id集合 |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| WeaResult | com.weaver.common.base.entity.result.WeaResult | 接口统一返回类 |
| **示例：** |  |  |

```java
WeaResult result = formAPIService.checkRequiredByCheckEntity(entity, employee);
```

#### 1.11 批量更新表单数据状态

**方法名：**

```java
 /**
     * @Description: 批量更新表单数据删除状态
     * @param dataIds 表单数据Id集合
     * @param isDelete 删除状态（0-未删除；1-回收站；2-彻底删除 3-定时物理删除）
     * @param employee 用户信息（必须包含id和tenantKey）
     */
void batchUpdateFormDataIsDelete(Set<Long> dataIds, int isDelete, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataIds | 是 | `List<Long>` | java.lang.Long | 表单数据Id集合 |
| isDelete | 是 | int |  | 表单数据状态（0,1,2,3） |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |
|  |  |  |  | 无 |

**示例：**

```java
formAPIService.batchUpdateStatusByDataIds(ids, dataStatus, employee);
```

#### 1.12 根据表单数据Id、字段权限Id，获取指定的formData数据

**方法名：**

```java
/**
 * @Description: 根据表单数据Id、字段权限Id，获取指定的formData数据
 * @param dataId 表单数据Id
 * @param permissionId 字段权限Id：传入空时，复制所有数据
 * @param type 字段权限过滤类型：0-有查看、编辑权限的数据、1-有查看权限的数据
 * @return FormData 表单数据
 * @throws
 */
FormData copyFormDataByIdAndPermissionId(Long dataId, Long permissionId, Integer type, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataId | 是 | Long | java.lang.Long | 表单数据ID |
| permissionId | 是 | Long | java.lang.Long | 字段权限Id：传入空时，复制所有数据 |
| type | 是 | Long | java.lang.Integer | 字段权限过滤类型：0-有查看、编辑权限的数据、1-有查看权限的数据 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| FormData | com.weaver.common.form.data.FormData | 表单数据Bean |
| **示例：** |  |  |

```java
FormData formDatas = formAPIService.copyFormDataByIdAndPermissionId(dataId, permissionId, 0, employee)
```

 

### 2 表单数据详情(FormDataDetail)相关接口

#### 2.1 根据表单数据ID、表单字段ID集合，获取指定表单数据中，指定表单字段的数据详情集合

**方法名：**

```java
/**
 * @Description: 根据表单数据ID、表单字段ID集合，获取指定表单数据中，指定表单字段的数据详情集合
 * @param dataId 表单数据ID
 * @param fieldIds 表单字段ID集合
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return List<FormDataDetail> 表单数据详情集合
 * @throws
 */
List<FormDataDetail> listFormDataDetailByFormDataIdAndFieldIds(Long dataId, List<Long> fieldIds, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataId | 是 | Long | java.lang.Long | 表单数据ID |
| fieldIds | 是 | `List<Long>` | java.lang.Long | 表单字段ID集合 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| `List<FormDataDetail>` | com.weaver.common.form.data.detail.FormDataDetail | 表单数据详情Bean集合 |
| **示例：** |  |  |

```java
List<FormDataDetail> dataDetails = formAPIService.listFormDataDetailByFormDataIdAndFieldIds(dataId, fieldIds, employee);
```

#### 2.2 高级搜索：根据表单数据详情搜索实体类，查询表单数据详情集合

**方法名：**

```java
/**
 * @Description: 高级搜索：根据表单数据详情搜索实体类，查询表单数据详情集合
 * @param entity 表单数据详情搜索实体类
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return List<FormDataDetail> 表单数据详情集合 
 * @throws
 */
List<FormDataDetail> listFormDataDetailBySearchEntity(FormDataDeatilSearchEntity entity, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| entity | 是 | FormDataDeatilSearchEntity | com.weaver.common.form.searchentity.FormDataDeatilSearchEntity | 表单数据详情高级搜索实体类 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |

**FormDataDeatilSearchEntity：**

> 描述：表单数据详情高级搜索实体类（支持扩展条件）
> 
> 所属包：weaver-common-form-extend
> 
> 所属类：com.weaver.common.form.searchentity.FormDataDeatilSearchEntity

| 属性名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataId | 是 | Long | java.lang.Long | 表单数据Id |
| fieldIds | 否 | `List<Long>` | java.lang.Long | 表单字段Id集合 |
| subFormIds | 否 | `List<Long>` | java.lang.Long | 明细表Id集合 |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| `List<FormDataDetail>` | com.weaver.common.form.data.detail.FormDataDetail | 表单数据详情Bean集合 |
| **示例：** |  |  |

```java
List<FormDataDetail> formDataDetails = formAPIService.listFormDataDetailBySearchEntity(entity, employee);
```

#### 2.3 获取字段详情内容

**方法名：**

```java
/**
 * @Description: 获取字段详情内容
 * @param dataDetail 表单数据详情
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return String 详情内容（富文本-取纯文本内容；选项型-选项名称逗号拼接字符串）
 * @throws
 */
String getFormDataDetailContent(FormDataDetail dataDetail, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataDetail | 是 | FormDataDetail | com.weaver.common.form.data.detail.FormDataDetail | 表单数据详情Bean |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| String | java.lang.Long | 详情内容（富文本-取纯文本内容；选项型-选项名称逗号拼接字符串） |
| **示例：** |  |  |

```java
String content = formAPIService.getFormDataDetailContent(dataDetail, employee);
```

**方法名：**

```java
/**
 * @Description: 根据formDataId、fieldIdList获取指定字段数据
 * @param formDataId 表单数据ID
 * @param fieldIdList 表单字段ID集合
 * @param employee  用户信息（必须包含id和tenantKey）
 * @return 对应字段填写数据详情
 */
Map <Long, List<FormDataDetail>> getFormDataDetailByFormDataIdAndFieldIds(Long formDataId, List<Long> fieldIdList, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| dataId | 是 | Long | java.lang.Long | 表单数据ID |
| fieldIds | 是 | `List<Long>` | java.lang.Long | 表单字段ID集合 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| `Map<String, Object>` | `java.util.Map<K, V>` | 字段权限数据回显Map |
| **返回值Map说明：** |  |  |

| Key | 描述 |
| --- | --- |
| fieldList | 表单字段 |

|  | value | 描述 |
| --- | --- | --- |
| List | com.weaver.common.form.data.detail.FormDataDetail | 表单数据详情Bean集合 |

**示例：**

```java
Map <Long, List<FormDataDetail>> formDataDetailMap = formAPIService.getFormDataDetailByFormDataIdAndFieldIds(dataId, fieldIds, employee);
```

### 3 表单数据选项(FormDataOption)相关接口

#### 3.1 高级搜索：根据表单数据选项搜索实体类，查询表单数据选项分页数据

**方法名：**

```java
/**
 * @Description: 高级搜索：根据表单数据选项搜索实体类，查询表单数据选项分页数据
 * @param entity 表单数据选项搜索实体类
 * @param page 分页信息
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return List<FormDataOption> 表单数据选项集合
 * @throws
 */
List<FormDataOption> pageFormDataOptionBySearchEntity(FormDataOptionSearchEntity entity, Page<FormDataOption> page, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| entity | 是 | FormDataOptionSearchEntity | com.weaver.common.form.searchentity.FormDataOptionSearchEntity | 表单数据选项高级搜索实体类 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **FormDataOptionSearchEntity：** |  |  |  |  |

> 描述：表单数据选项高级搜索实体类（支持扩展条件）
> 
> 所属包：weaver-common-form-extend
> 
> 所属类：com.weaver.common.form.searchentity.FormDataOptionSearchEntity

| 属性名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| fieldId | 是 | Long | java.lang.Long | 表单字段Id |
| keywords | 否 | String | java.lang.String | 选项名称关键字 |
| optionIds | 否 | `List<Long>` | java.lang.Long | 选项Id集合 |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| `List<FormDataOption>` | com.weaver.common.form.data.option.FormDataOption | 表单数据选项Bean集合 |
| **示例：** |  |  |

```java
FormDataOptionSearchEntity entity = new FormDataOptionSearchEntity();
entity.setFieldId(fieldId);
entity.setKeywords(keywords);
entity.setOptionIds(optionIds);
Page<FormDataOption> page = new Page<FormDataOption>(pageNo, pageSize);

List<FormDataOption> optionList = formAPIService.pageFormDataOptionBySearchEntity(entity, page, employee);
```

### 4 API列表

#### 4.1 创建表单数据接口

```java
/**
 * 创建表单数据
 * @param formDataDto 数据详情
 * @param employee 操作人
 * @return FormDataDto
 */
FormDataDto createFormData(FormDataDto formDataDto, SimpleEmployee employee);
```

#### 4.2 更新表单数据

```
/**
 * 更新数据 
 * 
 * @param formDataDto 数据详情
 * @param employee 操作人
 * @return FormDataDto
 */
FormDataDto saveFormData(FormDataDto formDataDto, SimpleEmployee employee);
```

#### 4.3 更新字段数据

```
/**
 * 更新字段数据
 * @param formDataDto 数据详情
 * @param employee 操作人
 * @return FormDataDto
 */
FormDataDto saveFieldData(FormDataDto formDataDto, SimpleEmployee employee);
```

#### 4.4 批量更新字段数据接口

```
    /**
     * 批量局部修改接口
     * 注：
     * 1、不支持多布局数据保存
     * 2、数据必须是同表数据
     * 3、数据id不能为空，此接口只支持修改不支持新增
     * @param param 参数详情
     * @param employee  用户信息
     * @return  数据详情
     */
    List<FormDataDto> saveFieldDatas(FormDataDtoParam param,SimpleEmployee employee);
```

#### 4.5 根据条件进行修改、新增字段数据接口

```

  /**
     * 根据条件进行修改、新增
     * 支持根据条件批量修改、局部修改、批量新增
     * 注：
     * 1、不支持多布局数据保存
     * 2、数据必须是同表数据
     * @param  param    参数详情
     * @param employee  用户信息
     * @return 数据详情
     */
    List<FormDataDto> saveFormDatasByCondition(FormDataDtoParam param,SimpleEmployee employee);

```

**[com.weaver.common.form.dto.data](http://com.weaver.common.form.dto.data)****.FormDataDtoParam**

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| formDataDtos | List | 数据集合 |
| fieldIds | List | 过滤条件 字段id; 根据id 去匹配 formDataDetails 里面的数据; 根据数据去匹配对应的dataId |
| fixFieldIds | List | 固定字段id集合 ;根据id 去匹配 formDataDetails 里面的数据; 根据数据去匹配对应的dataId；匹配方法需要模块复写 |
| matchMore | DataUpdatePolicy | 匹配到多行的时候 更新策略 ；ZERO；FIRST；LAST；EXCEPTION；ALL； 默认zero |
| noMatch | DataUpdatePolicy | 没匹配到的时候 更新策略 ZERO； EXCEPTION；ADD； 默认zero |
| subFormMatchFields | Map<Long, SubFormMatchDto> | 所有明细表 的更新策略集合 key =subFormId |
| execMonitor | boolean | 是否执行运算，默认false，依赖布局ID:未传递，按内置规则查找布局 |
| execRelate | boolean | 是否执行钻取，默认false，依赖布局ID:未传递，按内置规则查找布局 |
| formId | Long | 表单id |
| module | String | 所属模块 |
| execIgnoreParam | boolean | 是否忽略运算入参（配置了运算函数）默认false |
| newLayout | boolean | 是否使用最新布局，默认true |
| optionNoFindIgnore | boolean | 浏览按钮选项未找到时是否忽略,默认true |
| layoutMultiId | Long | 布局id，默认使用表单默认布局 |

**[com.weaver.common.form.dto.data](http://com.weaver.common.form.dto.data)****.SubFormMatchDto**

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| subFieldIds | List | 明细表 匹配字段id ;根据数据去匹配对应的rowId; |
| cover | Boolean | 是否覆盖;true 覆盖;false 累加; null 不做处理 |
| subFormMatchMore | DataUpdatePolicy | 明细表策略 匹配到多行的时候 更新策略 默认zero |
| subFormNoMatch | DataUpdatePolicy | 明细表策略 没匹配到的时候 更新策略 默认zero |

**com.weaver.common.form.dto.enums.DataUpdatePolicy**

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| FIRST | Long | 只更新第1行 |
| ZERO | Long | 不更新 |
| ADD | Long | 新增 |
| LAST | Long | 只更新最后1行 |
| EXCEPTION | Long | 抛出异常 |
| ALL | Long | 全部更新 |

**[com.weaver.common.form.dto.data](http://com.weaver.common.form.dto.data)****.FormDataDto**

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| dataId | Long | 表单数据id |
| objectId | Long | 事项id，比如审批ID，数据上班ID |
| formId | Long | 表单id |
| layoutMultiId | Long | 布局id，默认使用表单默认布局 |
| module | String | 所属模块 |
| dataDetails | List | 数据详情 |
| customParams | Map<String, Object> | 业务模块自定义参数 |
| newLayout | boolean | 是否使用最新布局，默认true |
| optionNoFindIgnore | boolean | 浏览按钮选项未找到时是否忽略,默认true ｜ |
| execMonitor | boolean | 是否执行运算，默认false，依赖布局ID:未传递，按内置规则查找布局｜ |
| execRelate | boolean | 是否执行钻取，默认false，依赖布局ID:未传递，按内置规则查找布局｜ |
| coverMap | Map<Long, Boolean> | 标记明细表是否覆盖还是新增 key=明细表id；value=(true:覆盖；false：新增) |

**[com.weaver.common.form.dto.data](http://com.weaver.common.form.dto.data)****.FormDataDetailDto**

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| fieldId | Long | 字段id |
| content | String | 字段值 |
| operate | String | 数字类型控件支持=+、=-，其他控件无效。eg:FormDataDetailDto.OPERATE_PLUS |
| needCopy | boolean | 默认false，为true的时候，formDataDto的objectId一定要有值 |
| matchByName | boolean | 选项控件根据名称匹配，目前只支持以下字段（非数据源模版的时候）Select，CheckBox，RadioBox，ImageCheckBox，ImageRadioBox，ComboSelect,MatrixComponent |
| dataOptions | List | 默认null，有值的时候，以这个值为准，忽略content的内容 |
| dataIndex | Long | 明细行号 |
| extendParams | Map<String,String> | 字段值扩展参数  <br>moneyType: 金额类型属性名 |

**[com.weaver.common.form.dto.data](http://com.weaver.common.form.dto.data)****.FormDataOptionDto**

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| optionId | String | 选项ID |
| targetId | Long | 图片单选多选的选项的图片id |
| content | String | 选项名称 |
| type | ModuleSource | 选项类型(用于存储附件控件的附件类型:imageFile(图片控件),image(附件控件)，file(附件控件)...) |
| score | string | 选项分数 |
| optionObj | Object | 选项的其他附属属性（人力资源条件等需要） |

**[com.weaver.common.form.dto.data](http://com.weaver.common.form.dto.data)****.FormDataDetailDto.extendParams**

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| moneyType | String | 金额类型属性名,金额控件开启填写时选择货币时使用 |
| optionOther | String | 选项型控件选择其他填写内容 |
| latitude | String | 地理位置控件： 纬度 |
| longitude | String | 地理位置控件： 经度 |

#### 4.6 根据id获取数据（批量接口，支持返回浏览按钮名称、币种、千分符、百分比、金额大写等）

```

/**
     * 根据参数批量获取dataId数据
     *
     * @param param 参数配置
     * @param employee 租户信息
     * @return java.util.List<com.weaver.common.form.data.detail.FormDataDetail>
     * @author mcl
     * @date 2024/7/17 17:45
     */
List<FormDataDetail> getByFormDataIdsAndField(FormDataShowContentParam param, SimpleEmployee employee);
```

入参：

| 属性名 | 必传 | 类型 | 描述 |
| --- | --- | --- | --- |
| param.formId | 是 | Long | 表单字段Id |
| param.dataIds | 是 | `List<Long>` | 数据id集合 |
| param.fieldIds | 否 | `List<Long>` | 字段Id集合 |
| param.needShowContent | 否 | Boolean | 是否展示拼接内容（币种、千分符、百分比和数值合并一起返回） |
| param.needEncrypt | 否 | Boolean | 是否对敏感加密信息进行换*处理； |
| param.needDesensitization | 否 | Boolean | 是否对数据进行脱敏处理 |
| param.containsOptionContent | 否 | Boolean | 是否需要返回最新的选项名称 |
|  |  |  |  |

#### 4.7 根据表单ID和数据ID列表获取最大行数及总行数

```
 /**
     * 根据表单ID和数据ID列表获取最大行数及总行数
     * @param formId 表单ID
     * @param dataIds 需要查询的数据ID列表
     * @param employee 执行查询的操作员工
     * @return 包含最大行号和总行数的FormDataRowNumberDto对象，若参数无效或无数据则返回null
     */
    FormDataRowNumberDto getMaxRowNumberByDataIds(Long formId, List<Long> dataIds, SimpleEmployee employee);

```

入参：

| 属性名 | 必传 | 类型 | 描述 |
| --- | --- | --- | --- |
| formId | 是 | Long | 表单Id |
| dataIds | 是 | List<Long> | 数据Id集合 |
| employee | 是 | SimpleEmployee | 人员ID和租户key |
|  |  |  |  |

出参：

|  |
| --- |

```json
{
			"maxRowNumber": "4", // 单条dataId最大行数
			"sumRowNumber": "8" // 传入的dataId汇总后的总行数
}
```

#### 4.8 物理表数据转换为表单数据对象的方法

```
/**
 * 将物理表数据转换为表单数据对象。
 *
 * @param formId          表单ID
 * @param dataId      表单数据ID
 * @param physicalTableDataMap 物理表数据映射，键为表名，值为该表的数据列表 List里面的Map key 是列名称，value 是对应的值
 * @param employee        当前操作员信息
 * @return 转换后的FormData对象，若参数无效则返回null
 */
FormData changePhysicalTableDataToFormData(Long formId,Long dataId,Map<String,List<Map<String,Object>>> physicalTableDataMap, SimpleEmployee employee);
```

入参：

| 属性名 | 必传 | 类型 | 描述 |
| --- | --- | --- | --- |
| formId | 是 | Long | 表单Id |
| dataId | 是 | Long | 数据Id |
| employee | 是 | SimpleEmployee | 人员ID和租户key |
| physicalTableDataMap | 是 | Map | 物理表数据映射，键为表名，值为该表的数据列表 List里面的Map key 是列名称，value 是对应的值 |
