新增表单数据接口

接口

HttpPost：api/FrontEnd/AddData

根据表单编码新增一条主表数据，可同时新增普通子表数据。接口使用当前登录用户作为数据创建人，并执行平台原有表单保存、必填校验、字段校验、业务规则及工作流初始化逻辑。

请求参数

参数名	参数位置	类型	是否必填	说明
`Authorization`	Header	string	是	调用者身份凭据，传入已获取的 token。
`TnCode`	Header	string	是	租户编码。
`objectId`	Body	UUID	否	主表数据 ID。不传时由服务端生成；传入时必须是尚未存在的数据 ID。
`formCode`	Body	string	是	主表功能菜单编码或表单编码。仅支持列表、工作流列表、树列表和文件列表。
`data`	Body	object	否	主表字段数据。键为表单字段编码，所有值均为 string。
`subData`	Body	array	否	普通子表数据集合；数据源子表不支持通过本接口新增。

`data` 字段对象

data 的键必须使用表单字段编码，不使用控件标题或数据库显示名称。其 Java 类型为 HashMap<String, String>，因此数字、日期、人员、附件、图片、选择项等值最终都必须传为字符串。

字段类型	`data` 中的值格式	示例
单行文本、文本域、电话、邮箱	普通字符串	`"采购一批办公用品"`
数字、金额	数值字符串	`"1250.50"`
日期	日期字符串，格式以字段配置为准	`"2026-08-16"`
日期时间	日期时间字符串，格式以字段配置为准	`"2026-08-16 14:30:00"`
下拉框、单选框	选项保存值字符串	`"Urgent"`
多选框、级联选择、JSON 控件	JSON 序列化后的字符串	`"[\"A\",\"B\"]"`
人员选择	主字段存名称，`字段编码_Id` 存用户 ID	`"Applicant": "张三", "Applicant_Id": "..."`
组织选择	主字段存名称，`字段编码_Id` 存组织 ID	`"Department": "研发部", "Department_Id": "..."`
附件控件	文件描述数组序列化后的字符串	`"[{\"fileId\":\"...\",\"fileName\":\"报价单.pdf\",\"md5\":\"...\",\"size\":1024}]"`
图片控件	图片文件描述数组序列化后的字符串	`"[{\"fileId\":\"...\",\"fileName\":\"现场照片.jpg\",\"md5\":\"...\",\"size\":204800}]"`

`subData` 子表对象

参数名	类型	是否必填	说明
`subCode`	string	是	子表表单编码。
`datas`	array	是	子表行数据集合；每一项为字段编码到字符串值的对象，复杂控件字段规则与主表 `data` 一致。
`datas[].objectId`	string	否	子表行 ID。不传时由服务端生成；传入时必须是未存在的 ID。该字段不会写入普通业务字段。

请求示例

新增普通表单数据

{
  "formCode": "46b97a76f61338bd",
  "data": {
    "Title": "采购办公用品",
    "Amount": "1250.50",
    "PurchaseDate": "2026-08-16",
    "Urgency": "Urgent",
    "Remark": "请在本周完成采购"
  }
}

新增含人员、附件、图片和子表的数据

以下示例中 Applicant 为人员选择控件，ContractFiles 为附件控件，SiteImages 为图片控件，DetailTable 为普通子表。附件和图片须先上传，取得文件信息后再调用新增接口。

{
  "objectId": "8dc8f015-4eb0-4edf-a5e2-6f30c0e4e08f",
  "formCode": "46b97a76f61338bd",
  "data": {
    "Title": "研发设备采购申请",
    "ApplyDate": "2026-08-16 14:30:00",
    "Applicant": "张三",
    "Applicant_Id": "18f923a7-5a5e-426d-94ae-a55ad1a4b239",
    "ContractFiles": "[{\"fileId\":\"file-3d731bf0\",\"fileName\":\"采购报价单.pdf\",\"md5\":\"d41d8cd98f00b204e9800998ecf8427e\",\"size\":184320}]",
    "SiteImages": "[{\"fileId\":\"file-50f7aa19\",\"fileName\":\"设备现场.jpg\",\"md5\":\"2f4a8a4f6f6f6d6c6b6a696867666564\",\"size\":204800}]",
    "Tags": "[\"设备\",\"采购\"]"
  },
  "subData": [
    {
      "subCode": "DetailTable",
      "datas": [
        {
          "ItemName": "开发工作站",
          "Quantity": "2",
          "UnitPrice": "625.25",
          "LineImages": "[{\"fileId\":\"file-50f7aa19\",\"fileName\":\"设备现场.jpg\",\"md5\":\"2f4a8a4f6f6f6d6c6b6a696867666564\",\"size\":204800}]"
        },
        {
          "ItemName": "显示器",
          "Quantity": "4",
          "UnitPrice": "249.75"
        }
      ]
    }
  ]
}

复杂控件调用说明

附件和图片控件

附件和图片的二进制内容不能直接放入 AddData 请求。应先调用文件上传接口，例如：

HttpPost：api/FrontEnd/UploadFile

上传请求使用 multipart/form-data，文件字段名为 file。上传成功后会返回 FileInfo，其中包含 FileId、FileName、Md5、Length 等信息。

写入 data 时，附件或图片字段的值必须是一个 JSON 字符串，字符串内容为文件描述数组。当前表单附件处理逻辑读取以下小写字段：

文件描述字段	类型	是否必填	说明
`fileId`	string	是	上传接口返回的 `FileId`。
`fileName`	string	是	上传接口返回的 `FileName`。
`md5`	string	否	上传接口返回的 `Md5`；无值时可传空字符串。
`size`	long	是	文件字节数，对应上传结果的 `Length`。
`url`	string	否	文件访问地址；保存附件不依赖该字段。
`type`	int	否	文件类型标识；保存附件不依赖该字段。

正确写法是将数组再次 JSON 序列化：

{
  "ContractFiles": "[{\"fileId\":\"file-3d731bf0\",\"fileName\":\"采购报价单.pdf\",\"md5\":\"d41d8cd98f00b204e9800998ecf8427e\",\"size\":184320}]"
}

不要直接传数组，否则因 data 的字段值类型为 string 而无法反序列化：

{
  "ContractFiles": [
    {
      "fileId": "file-3d731bf0"
    }
  ]
}

人员选择控件

人员控件保存为一对字段，不接收人员对象或人员 JSON 数组：

字段	值	说明
`字段编码`	人员名称	用于页面显示，例如 `Applicant` 为 `张三`。
`字段编码_Id`	用户 ID	用于平台识别人员，例如 `Applicant_Id`。

单选人员示例：

{
  "Applicant": "张三",
  "Applicant_Id": "18f923a7-5a5e-426d-94ae-a55ad1a4b239"
}

多选人员时，名称和 ID 以英文逗号按相同顺序拼接：

{
  "Reviewers": "张三,李四",
  "Reviewers_Id": "user-id-1,user-id-2"
}

推荐先调用人员选择接口获取可选人员：api/FrontEnd/person-selector/users。将接口返回的 name 写入人员主字段，将 objectId 写入同名的 _Id 扩展字段。objectId 是用户的 ObjectID，不是登录账号 code，也不是 JSON 数组中的 ObjectID 属性。

图片控件

图片控件与附件控件的保存结构相同，区别在于上传文件应为图片格式，字段编码应使用图片控件的字段编码。支持多图时同一个数组放入多份文件描述；单图控件也建议使用只含一个元素的数组，以保持平台保存格式一致。

{
  "SiteImages": "[{\"fileId\":\"file-image-1\",\"fileName\":\"现场1.jpg\",\"md5\":\"abc\",\"size\":204800},{\"fileId\":\"file-image-2\",\"fileName\":\"现场2.png\",\"md5\":\"def\",\"size\":102400}]"
}

子表

subData 会在主表保存前逐行保存。子表每一行同样是 Map<String, String>，因此人员、附件、图片、多选等复杂控件值同样必须传 JSON 字符串。子表数据源类型不支持通过本接口新增。

返回结果

接口成功时返回 HTTP 200 和统一结果对象：

{
  "Code": 200,
  "Message": "",
  "ExceptionSeqNo": null,
  "Result": true,
  "Status": 1,
  "MessageShowType": null
}

接口保存失败时，Message 返回异常内容，Result 为 null：

{
  "Code": 500,
  "Message": "主表[46b97a76f61338bd]数据操作失败，错误原因：字段[Amount]不能为空",
  "ExceptionSeqNo": null,
  "Result": null,
  "Status": 3,
  "MessageShowType": null
}

常见错误包括：

场景	服务端提示
未登录	`用户id为空` 或认证拦截器返回 `401 Unauthorized`。
表单类型不支持	`不支持的主表表单类型`。
指定 `objectId` 已存在	`objectId[xxx]该数据已存在`。
子表为数据源类型	`不支持的子表表单类型`。
表单字段或控件值不符合配置	返回主表或子表数据操作失败，并携带平台字段校验原因。

调用说明

formCode、主表字段编码和子表字段编码均应以表单设计器发布后的配置为准，可通过 api/FrontEnd/GetTableStructure/{menuCode} 查询字段结构。
未传 objectId 时主表 ID 由服务端生成；该接口返回值不包含生成后的 ID。如调用方需要预先知道 ID，应自行生成合法 UUID 后传入 objectId。
对工作流列表调用 AddData 仅保存并初始化数据；需要发起流程时应使用 api/FrontEnd/SubmitData。
文件先上传、后引用。AddData 不会接收文件二进制，也不会替调用方创建文件。
data 和 subData.datas 的字段值不能传 JSON 对象或数组本身，必须传其 JSON 字符串形式；在 JSON 请求中应正确转义内部双引号。

接口​

请求参数​

data 字段对象​

subData 子表对象​

请求示例​

新增普通表单数据​

新增含人员、附件、图片和子表的数据​

复杂控件调用说明​

附件和图片控件​

人员选择控件​

图片控件​

子表​

返回结果​

调用说明​

接口