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

### 1 表单(Form)相关接口

#### 1.1 新增/修改表单

**方法名：**

```java
/**
 * @Description: 新增/修改表单
 * @param form 表单
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return Form 表单
 * @throws
 */
Form saveForm(Form form, SimpleEmployee employee);
```

**参数：**

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

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| Form | com.weaver.common.form.metadata.Form | 表单Bean |

#### 1.2 初始化表单及布局

**方法名：**

```java
/**
 * @Description: 初始化表单及布局
 * @param components 控件对象集合
 * @param formName 表单名称
 * @param module 所属模块module
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return Form 表单
 * @throws
 */
Form buildForm(List<Component> components, String formName, ModuleSource module, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| components | 是 | `List<Component>` | com.weaver.common.form.component.base.Component | 控件对象集合 |
| formName | 是 | String | java.lang.String | 表单名称 |
| module | 是 | ModuleSource | com.weaver.common.form.metadata.ModuleSource | 所属模块module（枚举类型） |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| Form | com.weaver.common.form.metadata.Form | 表单Bean |
| **示例：** |  |  |

```java
@GetMapping("/buildForm")
public void buildForm(){
    // 临时人员（正式使用这里需要替换成真正人员）
    SimpleEmployee employee = new SimpleEmployee();
    employee.setId(idGenerator.generate()); // 人员id
    employee.setTenantKey("t7akvdnf84");    // 租户key
    // 构建表单以及布局详情
    List<Component> components= new ArrayList<>();
    // 文本框
    Text text = new Text();
    text.setTitle("文本控件示列");  // 控件名称
    text.setRequired(true);         // 必填
    text.setContent("默认值");      // 默认值
    components.add(text);
    // 选项控件
    CheckBox checkBox = new CheckBox();
    checkBox.setTitle("复选框");    // 名称
    List<Option> opts = new ArrayList<>();  // 选项
    Option opt1 = new Option();
    opt1.setName("选项1");
    Option opt2 = new Option();
    opts.add(opt1);
    opt2.setName("其他");
    opt2.setOther(true);
    opts.add(opt2);
    checkBox.setOptions(opts);
    components.add(checkBox);
    // 其他控件.......详细查看package com.weaver.common.form.component 里面的java bean对象
    Form form = formAPIService.buildForm(components, "示列表单", ModuleSource.workflow, employee);
    logger.info(JSONObject.toJSONString(form));
}
```

#### 1.3 根据ID获取表单

**方法名：**

```java
/**
 * @Description: 根据ID获取表单
 * @param formId 表单ID
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return Form 表单
 * @throws
 */
Form getFormById(Long formId, SimpleEmployee employee);
```

**参数：**

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

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| Form | com.weaver.common.form.metadata.Form | 表单Bean |
| **示例：** |  |  |

```java
Form form = formAPIService.getFormById(formId, employee);
```

#### 1.4 根据表单名称和租户Key，获取该租户下所有表单

**方法名：**

```java
/**
 * @Description: 根据表单名称和租户Key，获取该租户下所有表单
 * @param formName 表单名称（模糊匹配，传入null时查询所有表单）
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return List<Form> 表单集合
 * @throws
 */
List<Form> listFormByNameAndTenantKey(String formName, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formName | 否 | String | java.lang.String | 表单名称（模糊匹配，传入null时查询所有表单） |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |

**返回值：**

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

**示例：**

```java
List<Form> forms = formAPIService.listFormByNameAndTenantKey(formName, employee);
```

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

**方法名：**

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

**参数：**

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

**FormSearchEntity：**

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

| 属性名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formId | 否 | Long | java.lang.Long | 表单Id |
| formName | 否 | String | java.lang.String | 表单名称 |
| isDelete | 否 | Integer | java.lang.Integer | 删除状态 0：查询未删除；1：查询已删除；null：查询全部 |
| tenantKey | 否 | String | java.lang.String | 团队key |
| status | 否 | FormStatus | com.weaver.teams.domain.form.FormStatus | 表单状态枚举类 |
| formIdList | 否 | `List<Long>` | java.lang.Long | 表单Id集合（与formId不可同时传入） |
| **返回值：** |  |  |  |  |

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

```java
List<Form> forms = formAPIService.listFormBySearchEntity(entity, employee);
```

#### 1.6 根据表单主表、表单所有权复制(下载)表单

**方法名：**

```java
/**
 * @Description: 根据表单主表、表单所有权复制(下载)表单
 * @param formId 表单ID(被copy对象ID)
 * @param formName 表单名称(如果为null，默认为该表单名称+时间戳)
 * @param formType 表单所有权("云","公司","个人")
 * @param module 表单关联模块
 * @param formNew 表单对象(如果表单对象不为空，则copy表单布局)
 * @param employee 用户信息（必须包含id和tenantKey）
 * @param sourceModule 表单来源模块
 * @return Form 表单 
 * @throws
 */
Form copyForm(Long formId, String formName, FormType formType, ModuleSource module, Form formNew, SimpleEmployee employee, ModuleSource sourceModule);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formId | 是 | Long | java.lang.Long | 表单ID(被copy对象ID) |
| formName | 是 | String | java.lang.String | 表单名称(如果为null，默认为该表单名称+时间戳) |
| formType | 是 | FormType | com.weaver.common.form.metadata.FormType | 表单所有权("云","公司","个人") |
| module | 是 | ModuleSource | com.weaver.common.form.metadata.ModuleSource | 表单关联模块 |
| formNew | 是 | Form | com.weaver.common.form.metadata.Form | 表单对象(如果表单对象不为空，则copy表单布局) |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| sourceModule | 是 | ModuleSource | com.weaver.common.form.metadata.ModuleSource | 表单来源模块 |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| Form | com.weaver.common.form.metadata.Form | 表单Bean |
| **示例：** |  |  |

```java
Form form = formAPIService.copyForm(formId, formName, formType, module, formNew, employee, sourceModule);
```

#### 1.7 创建表单并初始化表单布局

**方法名：**

```java
/**
 * @Description: 创建表单并初始化表单布局
 * @param form 表单
 * @param employee 用户信息（必须包含id和tenantKey）
 * @return Form 表单
 * @throws
 */
Form createFormAndInitFormLayout(Form form, SimpleEmployee employee);
```

**参数：**

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

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| Form | com.weaver.common.form.metadata.Form | 表单Bean |
| **示例：** |  |  |

```java
Form form = new Form();
form.setName(name);						// 表单名称
form.setModule(module);					// 模块标识符
form.setOperator(employee);				// 表单创建人（系统当前登录人）
form.setCreateTime(new Date()); 		// 创建时间
form.setUpdateTime(new Date());			// 更新时间
form.setStatus(FormStatus.enable);		// 启动状态（启用/停用）
form.setOwnership(FormType.company);	// 表单所有权（团队/个人/云）

formAPIService.createFormAndInitFormLayout(form, employee);
```

#### 1.8 表单重名校验

**方法名：**

```java
/**
 * @Description: 表单重名校验
 * @param form 表单
 * @return int 表单数量
 * @throws
 */
int countByForm(Form form);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| form | 是 | Form | com.weaver.common.form.metadata.Form | 表单Bean |
| **入参【Form】支持的条件：** |  |  |  |  |

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| name | 否 | String | java.lang.String | 表单名称 |
| tenantKey | 否 | String | java.lang.String | 租户Key |
| ownership | 否 | FormType | com.weaver.common.form.metadata.FormType | 表单类型（个人、团队、云） |
| operator | 否 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id） |
| id | 否 | Long | java.lang.Long | 表单ID |
| module | 否 | ModuleSource | com.weaver.common.form.metadata.ModuleSource | 模块标识 |
| report | 否 | Form | com.weaver.common.form.metadata.Form | 报告表单Bean |
| **返回值：** |  |  |  |  |

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| int | - | 重名表单数量 |

#### 1.9 更新表单（传入哪些属性更新哪些）

**方法名：**

```java
/**
 * @Description: 更新表单（传入哪些属性更新哪些）
 * @param form 表单Bean
 * @param employee 用户信息（必须包含id和tenantKey）
 * @throws
 */
void updateForm(Form form, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| form | 是 | Form | com.weaver.common.form.metadata.Form | 表单Bean |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| **入参【Form】支持的条件：** |  |  |  |  |

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| id | 是 | Long | java.lang.Long | 表单ID |
| name | 否 | String | java.lang.String | 表单名称 |
| describe | 否 | String | java.lang.String | 表单描述 |
| status | 否 | FormStatus | com.weaver.teams.domain.form.FormStatus | 表单状态 |
| ownership | 否 | FormType | com.weaver.common.form.metadata.FormType | 表单类型（个人、团队、云） |
| isAdvance | 否 | boolean | java.lang.boolean | 是否为高级表单 |
| operator | 否 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id） |
| collectStatus | 否 | FormStatus | com.weaver.teams.domain.form.FormStatus | 表单外部收集状态 |
| formCategory | 否 | FormCategory | com.weaver.common.form.metadata.catagory.FormCategory | 表单分类 |
| sort | 否 | int | java.lang.int | 表单排序 |
| isDelete | 否 | boolean | java.lang.boolean | 是否删除（true-已删除; false-未删除）彻底删除参考1.10使用 |
| tenantKey | 否 | String | java.lang.String | 租户Key |

**返回值：**

> 无

```java
formAPIService.updateForm(form, employee);
```

#### 1.10 彻底删除表单（IS_DELETE置为2）

**方法名：**

```java
/**
 * @Description: 彻底删除表单（IS_DELETE置为2）
 * @param formId 表单Id
 * @param employee 用户信息（必须包含id和tenantKey）
 * @throws
 */
void completelyDeleteForm(Long formId, SimpleEmployee employee);
```

**参数：**

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

**返回值：**

> 无

**示例：**

```java
formAPIService.completelyDeleteForm(formId, employee);
```

#### 1.11 同步表单分权数据

**方法名：**

```java
/**
* 同步表单分权数据
* @param orgId
* @param employee 操作人
*/
void syncFormOrgId(Long orgId,SimpleEmployee employee); 
```

**参数：**

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

**接口所属包路径**

```
com.weaver.common.form.formapi.impl.FormAPIServiceImpl
```

**返回值：****

无

**示例：**

```java
formService.updateOrgValid(tenantKey,invalidIds,orgId);
```

#  2. 物理表(FormTable)相关接口

#### 2.1 根据表单ID查询物理表集合

**方法名：**

```java
    /**
     * 根据查询参数获取物理表信息
     * @param param 查询参数
     * @param employee 当前操作人
     * @return java.util.List<com.weaver.common.form.physical.entity.FormTable>
     */
    List<FormTableDto> listFormTable(FormTableParam param, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formId | 是 | Long | java.lang.Long | 表单ID |
| formTableId | 否 | Long | java.lang.Long | 物理表ID |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |
| 入参【param】支持参数 |  |  |  |  |

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| formId | 是 | Long | java.lang.Long | 表单ID |

**接口所属包路径**

```java
com.weaver.common.form.formapi.impl.FormAPIServiceImpl
```

**返回值：**

| 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- |
| `List<`FormTableDto`>` | com.weaver.common.form.dto.form.FormTableDto | 物理表信息集合，具体属性说明参考： 3.1.1 |

**示例：**

```java
FormTableParam param = new FormTableParam();
param.setFormId(1L);//表单id
List<FormTableDto> list = formApiService.listFormTable(param,employee);
```

#### 2.2 创建多物理表附属表(单接口)

**方法名：**

```java
/**
 * 新建物理表
 *
 * @param param      新建物理表param
 * @param employee 当前用户
 * @return 保存的表单表信息
 * @author hxd
 */
 FormTableSaveResult saveFormTable(FormTableSaveParam param, SimpleEmployee employee);
```

**参数：**

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| param | 是 | FormTableSaveParam | com.weaver.common.form.param.table.FormTableSaveparam | 物理表信息 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |

| DTO 参数名 | 二级参数 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- | --- |
| formTable |  | 是 | FormTable | com.weaver.common.form.physical.entity.FormTable | 物理表信息 |
|  | id | 否 | Long | java.lang.Long | 附属表Id |
|  | form.id | 是 | Long | java.lang.Long | 表单Id |
|  | tableName | 是 | String | java.long.String | 物理表名称（数据库） |
|  | name | 否 | String | java.long.String | 物理表名称，不传递默认取主表名称 |
|  | tableType | 是 | FormTableType | com.weaver.common.form.physical.enums.FormTableType | 附属表类型：<br>MAIN:主表 ,<br>SUBSIDIARY：附属表 |
| customParam |  | 否 | map | java.util.map | 自定义参数 |
| module |  | 是 | String | java.lang.String | 模块标识 |
| createFormLayout |  | 否 | Boolean |  | 是否新建布局 |
| layoutMultileDto |  | 否 |  |  | 新建布局的信息 |
|  |  |  |  |  |  |

**示例：**

```java
@Resource
private FormAPIService formAPIService;

public void saveFormTable(SimpleEmployee employee) {
    FormTableSaveParam dto = FormTableSaveParam.Builder.builder().formTable(
            FormTable.Builder.builder().form(new Form(1L)).name("测试表单").tableName("ft_aaaaa").tableType(FormTableType.SUBSIDIARY).build()
    ).build();

    FormTableSaveResult result = formAPIService.saveFormTable(dto, employee);
}
```

## 2.3 删除附属表

方法名：

```java
/**
 * 删除附属表
 * @param param 删除参数
 * @param employee 当前操作人
 * @return  FormTableDeleteResult
 */
FormTableDeleteResult deleteFormTable(FormTableDeleteParam param, SimpleEmployee employee);
```

参数：

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| param | 是 | FormTableDeleteParam | com.weaver.common.form.param.table.FormTableDeleteParam | 参数信息 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |

示例：

```java
@Resource
private FormAPIService formAPIService;

public void deleteFormTable(SimpleEmployee employee) {

    FormTableDeleteParam param = new FormTableDeleteParam();
    param.setFormTableIds(xxxx);

    FormTableDeleteResult result = formAPIService.deleteFormTable(param, employee);
}
```

## 2.4 批量修改附属表名称

方法名

```java
/**
 * 修改附属表名称
 * @param param 修改参数
 * @param employee 当前操作人
 * @return FormTableUpdateResult
 */
FormTableUpdateResult batchUpdateFormTable(FormTableUpdateParam param, SimpleEmployee employee);
```

参数：

| 参数名 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- |
| param | 是 | FormTableUpdateParam | com.weaver.common.form.param.table.FormTableUpdateParam | 参数信息 |
| employee | 是 | SimpleEmployee | com.weaver.teams.domain.user.SimpleEmployee | 用户信息（必须包含id和tenantKey） |

FormTableUpdateParam结构：

| DTO 参数名 | 二级参数 | 必传 | 类型 | 类型所属包路径 | 描述 |
| --- | --- | --- | --- | --- | --- |
| formtableList |  | 是 | FormTableDto | com.weaver.common.form.dto.form.FormTableDto | 物理表信息 |
|  | id | 是 | Long | java.lang.Long | 附属表Id |
|  | form.id | 是 | Long | java.lang.Long | 表单Id |
|  | formName | 是 | String | java.long.String | 物理表名称 |

示例：

```java
@Resource
private FormAPIService formAPIService;

public static void main(String[] args) {
    Form form = new Form();
    form.setId(xxx);
    FormTableDto dto = new FormTableDto();
    dto.setId(xxx);
    dto.setFormName(xxx);
    
    List<FormTableDto> list = new ArrayList<>();
    list.add(dto);

    FormTableUpdateParam param = new FormTableUpdateParam();
    param.setFormTableList(list);
    
    FormTableUpdateResult result = formApiservice.batchUpdateFormTable(param, employee);
}

```

## 2.5 获取物理表下所有的主子表名称

```
/**
 *  获取物理表下所有的主子表名称
 * @param formId 主表ID
 * @param deleteType 删除状态（0：查询未删除；1：查询已删除；null：查询全部）
 * @param employee 租户信息
 * @return java.util.List<com.weaver.common.form.physical.entity.FormTable>
 * @author mcl
 * @date 2025/4/09 16:23
 */
List<SimpleFormTable> findAllFormTableName(Long formId, Integer deleteType, SimpleEmployee employee);
```

返参：

```json
{
"id":"1111",   // formTableId
"tableName":"asda_1", // 物理表名称
"formId":"12312313", // 关联表单ID 可能是明细表ID；当formId相同tableName不同时，是多物理表的情况
"deleteType":"0"// 物理表删除状态标识
}
```
