1. 首页
  2. 番茄课堂
  3. 获取表单结构接口

获取表单结构接口

2020年02月20日 14:36　阅读量：14262　编辑：秋叶

你可以通过该API获取所需表单的结构定义，然后在自己的平台上重现渲染该表单。通过“提交数据API”，可以脱离番茄表单的网页来提交数据。

获取表单结构

请求方式：GET

请求地址：

参数说明：

参数 类型 必须 说明
access_token String 是 access_token获取
:formid String 是 表单唯一识别码——id，_id的获取

返回结果:

参数 类型 说明
data Object
└_id String 该 id 属于表单 id,唯一识别码 用于获取表单结 构和表单数据
└status Number 表单状态 0 为草稿——新建后编辑中，尚未发布。 1 为修改中——已发布的表单再次进行编辑，尚 未重新发布。 9 为发布后的状态
└name String 表单名称
└replies Number 收集量
└created Date 创建时间
└lastUpdated Date 最后修改时间
└items Array 表单包含的组件集合，具体各组件的格式查看下面说明
status Object
└ code Number 业务状态码，只有返回200才是正常调用成功
└ message String code对应的描述信息

返回数据详情及字段说明

返回值示例：

{
  "data": {
    "_id": "5a308c6745b95e3c70835934",
    "shortId": "pyrz0f",
    "status": 9,
    "name": "API测试表单",
    "description": "",
    "items": [{
      "text": "API测试表单",
      "description": "",
      "_id": "5a308c6745b95e3c70835935", // 该id与表单回复数据中values项中的definition值一致
      "titleAlign": "center",
      "type": "title"
    }, {
      "_id": "5a308c8047af3deb100001e0",
      "isHidden": false,
      "columnLayout": "vertical",
      "displayDescription": false,
      "description": "",
      "required": false,
      "label": "单选",
      "items": [{
        "_id": "5a308c8047af3deb100001e1",
        "text": "选项 1",
        "isOther": false
      }, {
        "text": "选项 2",
        "_id": "5a308c8c47af3deb100001e9",
        "isOther": false
      }, {
        "text": "其他",
        "_id": "5a30989a47af3deb10000216",
        "isOther": true
      }],
      "type": "radio"
    }, {
      "_id": "5a308cbe47af3deb1000020e",
      "isHidden": false,
      "displayDescription": false,
      "description": "",
      "required": false,
      "label": "姓名",
      "beOnly": false,
      "isRemember": false,
      "isContact": true,
      "type": "name"
    }],
    "replies": 1,
    "created": "2017-12-13T02:12:16.378Z",
    "lastUpdated": "2017-12-13T03:55:21.431Z"
  },
  "status": {
    "code": 200,
    "message": "success"
  }
}


items数组包含数据描述

表单标题 title ——

数据示例：

{
  "_id":"5a308c6745b95e3c70835935",
  "description":"",
  "text":"包含所有条目的表单",
  "titleAlign":"center",
  "type":"title"
}

字段说明：

字段名 类型 描述
_id String 表单组件唯一标示符
description String 表单组件说明
titleAlign String 标题布局，取值有：left, center, right
type String 组件类型


单选 radio ——

数据示例：

{
  "label":"这是单选组件",
  "required":false,
  "description":"",
  "displayDescription":false,
  "columnLayout":"vertical",
  "isHidden":false,
  "_id":"5a308c8047af3deb100001e0",
  "items":[
      {
          "text":"选项 1",
          "_id":"5a308c8047af3deb100001e1",
          "isOther":false
      },
      {
          "_id":"5a308c8c47af3deb100001e9",
          "text":"选项 2",
          "isOther":false
      },
      {
          "isOther": true,
          "text": "其他",
          "_id": "5a30989a47af3deb10000216"
      }
  ],
  "type":"radio"
}

字段说明：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
columnLayout String 列布局方式
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件的唯一标示符
items Array 单选组件具体的每个选项值
items.text String 单选选项的值
items._id String 单选选项的唯一表示符
items.isOther Boolean 是否为其他选项，即允许用户自己输入
type String 组件类型


多选 checkbox ——

数据示例：

{
  "label":"多选",
  "required":false,
  "description":"",
  "displayDescription":false,
  "columnLayout":"vertical",
  "countMin":null,
  "countMax":null,
  "isHidden":false,
  "_id":"5a308c8147af3deb100001e2",
  "items":[
      {
          "text":"选项 1",
          "_id":"5a308c8147af3deb100001e3",
          "isOther":false
      },
      {
          "_id":"5a308c8f47af3deb100001ea",
          "text":"选项 2",
          "isOther":false
      }
  ],
  "type":"checkbox"
}

字段说明：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
columnLayout String 列布局方式
countMin Number 最少选择项
countMax Number 最多选择项
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件的唯一标示符
items Array 多选组件具体的每个选项值
items.text String 选项的值
items._id String 选项的唯一表示符
items.isOther Boolean 是否为其他选项，即允许用户自己输入
type String 组件类型


下拉 dropdown ——

数据示例：

{
  "label":"下拉",
  "required":false,
  "description":"",
  "displayDescription":false,
  "isHidden":false,
  "_id":"5a308c8247af3deb100001e4",
  "items":[
      {
          "text":"选项 1",
          "isOther":false,
          "_id":"5a308c8247af3deb100001e5"
      },
      {
          "_id":"5a308c9247af3deb100001eb",
          "isOther":false,
          "text":"选项 2"
      }
  ],
  "type":"dropdown"
}

字段说明：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
columnLayout String 列布局方式
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件到唯一标示符
items Array 组件具体的每个选项值
items.text String 组件选项的值
items._id String 组件选项的唯一表示符
items.isOther Boolean 是否为其他选项，即允许用户自己输入
type String 组件类型


输入框 text ——

数据示例：

{
  "label":"输入框",
  "required":false,
  "description":"",
  "displayDescription":false,
  "lengthMin":null,
  "lengthMax":null,
  "isHidden":false,
  "_id":"5a308c8347af3deb100001e6",
  "beOnly":false,
  "isMultiline":false,
  "isNumber":false,
  "type":"text"
}

字段说明：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
columnLayout String 列布局方式
lengthMin Number 最小长度
lengthMax Number 最大长度
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件到唯一标示符
beOnly Boolean 是否唯一，如果为true则该表单的该组件被提交的值不能再次提交
isMultiline Boolean 是否多行输入框
isNumber Boolean 是否是数字
type String 组件类型


评分 score ——

数据示例：

{
  "label":"评分",
  "required":false,
  "description":"",
  "displayDescription":false,
  "fullScore":5,
  "iconType":1,
  "isHidden":false,
  "_id":"5a308c8447af3deb100001e7",
  "type":"score"
}

字段说明：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
fullScore Number 满分分数
iconType Number 图标类型
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件到唯一标示符
type String 组件类型


图片单选 imageradio ——

数据示例：

{
  "_id":"5a308c9947af3deb100001ec",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"图片单选",
  "items":[
      {
          "_id":"5a30a48a47af3deb10000217",
          "text":"这是图片1",
          "imageUrl":"//img.tomatoform.com/20171213115450-391346.png"
      },
      {
          "_id":"5a30a49047af3deb10000218",
          "text":"这是图片2",
          "imageUrl":"//img.tomatoform.com/20171213115456-833081.png"
      }
  ],
  "type":"imageradio"
}

字段说明：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件到唯一标示符
items Array 单选组件具体的每个选项值
items.text String 图片描述，默认为上传图片的图片名称
items._id String 选项的唯一表示符
items.imageUrl String 上传图片后的图片链接，域名均为：img.tomatoform.com
type String 组件类型


图片多选 imagecheckbox ——

数据示例：

{
  "_id":"5a308c9a47af3deb100001ed",
  "isHidden":false,
  "countMax":null,
  "countMin":null,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"图片多选",
  "items":[
      {
          "_id":"5a30a49a47af3deb10000219",
          "text":"这是图片1",
          "imageUrl":"//img.tomatoform.com/20171213115506-373705.png"
      },
      {
          "_id":"5a30a49e47af3deb1000021a",
          "text":"这是图片2",
          "imageUrl":"//img.tomatoform.com/20171213115450-391346.png"
      }
  ],
  "type":"imagecheckbox"
}

字段说明：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
columnLayout String 列布局方式
countMin Number 最少选择项
countMax Number 最多选择项
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件到唯一标示符
items Array 多选组件具体的每个选项值
items.text String 图片描述，默认为上传图片的图片名称
items._id String 选项的唯一表示符
items.imageUrl String 上传图片后的图片链接，域名均为：img.tomatoform.com
type String 组件类型


多级下拉 cascadedropdown ——

数据示例：

{
  "_id":"5a308c9c47af3deb100001ee",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "levels":2,
  "label":"多级下拉",
  "items":[
      {
          "_id":"5a308c9c47af3deb100001ef",
          "text":"一级选项 1",
          "subItems":[
              {
                  "_id":"5a308c9c47af3deb100001f0",
                  "text":"二级选项 1",
                  "subItems":[

                  ]
              }
          ]
      }
  ],
  "type":"cascadedropdown"
}

字段说明：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
levels Number 下拉级数，默认为2--二级下拉
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件到唯一标示符
items Array 多级下拉中第一级的选项
items.text String 选项的值
items._id String 选项的唯一表示符
items.subItems Array 该选项下的下一级选项
type String 组件类型


矩阵单选 radio-matrix ——

数据示例：

{
  "_id":"5a308ca047af3deb100001f1",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"矩阵单选",
  "rows":[
      {
          "_id":"5a308ca047af3deb100001f5",
          "text":"题目 1"
      },
      {
          "_id":"5a308ca047af3deb100001f6",
          "text":"题目 2"
      },
      {
          "_id":"5a308ca047af3deb100001f7",
          "text":"题目 3"
      }
  ],
  "columns":[
      {
          "_id":"5a308ca047af3deb100001f2",
          "text":"选项 1"
      },
      {
          "_id":"5a308ca047af3deb100001f3",
          "text":"选项 2"
      },
      {
          "_id":"5a308ca047af3deb100001f4",
          "text":"选项 3"
      }
  ],
  "isShowMatrixForMobile":false,
  "type":"radio-matrix"
}

字段描述：

字段名 类型 描述
label String 表单组件名称
required Boolean 该组件是否为必填项目
description String 组件描述
displayDescription Boolean 是否对填写表单的用户展示描述
isHidden Boolean 是否隐藏，隐藏后表单填写者将无法看到
_id String 组件到唯一标示符
row Array 矩阵的第一列，对应于矩阵单选的题目
row.text String 值，矩阵单选的题目
row._id String 矩阵单选的题目唯一表示符
columns Array 数组中的个元素为矩阵单选的每一个选项
columns.text String 矩阵单选的选项
columns._id String 矩阵单选选项的唯一表示符
isShowMatrixForMobile Boolean 移动端是否展示矩阵
type String 组件类型


矩阵多选 checkbox-matrix ——

数据示例：

{
  "_id":"5a308ca147af3deb100001f8",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"矩阵多选",
  "rows":[
      {
          "_id":"5a308ca147af3deb100001fc",
          "text":"题目 1"
      },
      {
          "_id":"5a308ca147af3deb100001fd",
          "text":"题目 2"
      },
      {
          "_id":"5a308ca147af3deb100001fe",
          "text":"题目 3"
      }
  ],
  "columns":[
      {
          "_id":"5a308ca147af3deb100001f9",
          "text":"选项 1"
      },
      {
          "_id":"5a308ca147af3deb100001fa",
          "text":"选项 2"
      },
      {
          "_id":"5a308ca147af3deb100001fb",
          "text":"选项 3"
      }
  ],
  "isShowMatrixForMobile": false,
  "type":"checkbox-matrix"
}

字段描述： 与上述矩阵单选完全一致


矩阵填空 text-matrix ——

数据示例：

{
  "_id":"5a308ca247af3deb100001ff",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"矩阵填空",
  "rows":[
      {
          "_id":"5a308ca247af3deb10000203",
          "text":"题目 1"
      },
      {
          "_id":"5a308ca247af3deb10000204",
          "text":"题目 2"
      },
      {
          "_id":"5a308ca247af3deb10000205",
          "text":"题目 3"
      }
  ],
  "columns":[
      {
          "_id":"5a308ca247af3deb10000200",
          "text":"填项 1"
      },
      {
          "_id":"5a308ca247af3deb10000201",
          "text":"填项 2"
      },
      {
          "_id":"5a308ca247af3deb10000202",
          "text":"填项 3"
      }
  ],
  "isShowMatrixForMobile":false,
  "isMultiline":false,
  "isNumber":false,
  "type":"text-matrix"
}

字段描述：

字段名 类型 描述
isMultiline Boolean 是否多行输入框
isNumber Boolean 是否仅允许填数字

其余内容与矩阵单选一致


表格 table ——

数据示例：

{
  "_id":"5a308ca347af3deb10000206",
  "isHidden":false,
  "isMultiline":false,
  "isNumber":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"表格",
  "columns":[
      {
          "_id":"5a308ca347af3deb10000207",
          "text":"项目 1"
      },
      {
          "_id":"5a308ca347af3deb10000208",
          "text":"项目 2"
      },
      {
          "_id":"5a308ca347af3deb10000209",
          "text":"项目 3"
      }
  ],
  "type":"table"
}

字段描述：

字段名 类型 描述
isMultiline Boolean 是否多行输入框
isNumber Boolean 是否仅允许填数字


公式运算 calculate ——

数据示例：

{
  "_id":"5a308cad47af3deb1000020a",
  "isHidden":false,
  "isPercentage":false,
  "decimalDigits":null,
  "displayDescription":false,
  "description":"",
  "label":"公式运算",
  "widgetIds":[
      "5a308e2c47af3deb10000214",
      "5a308e3047af3deb10000215"
  ],
  "formulaArray":[
      {
          "value":"输入框1(做为公式运算的输入)",
          "fieldId":"5a308e2c47af3deb10000214",
          "type":"field"
      },
      {
          "value":"+",
          "icon":"add",
          "type":"operator"
      },
      {
          "value":"输入框2(做为公式运算的输入)",
          "fieldId":"5a308e3047af3deb10000215",
          "type":"field"
      }
  ],
  "type":"calculate"
}

字段说明：

字段名 类型 描述
isPercentage Boolean 是否展示百分比
decimalDigits Number 限制的小数位数，如果为空，则不限制
widgetIds Array 所有参与计算的组件的id，值为isNumber为true的输入框的唯一标识符
formulaArray Array 计算表达式
formulaArray.value String 类型，如果值为"operator"则为计算符号，如果值"field"则为组件
formulaArray.type String 计算表达式的值，为符合或者组件名称


日期 date ——

数据示例：

{
  "_id":"5a308cb847af3deb1000020b",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"日期",
  "type":"date"
}

字段描述： 均为通用字段，与前述一致


时间 time ——

数据示例：

{
  "_id":"5a308cba47af3deb1000020c",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"时间",
  "type":"time"
}

字段描述： 均为通用字段，与前述一致


附件 ——

数据示例：

{
  "_id":"5a308cbb47af3deb1000020d",
  "isHidden":false,
  "limitedFileTypeItems":"",
  "limitedFileType":0,
  "fileCount":1,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"附件",
  "type":"files"
}

字段描述：

字段名 类型 描述
limitedFileType Number 限制文件类型名称，0:不限制;1:文档;2:图片;3:视频;4:音频;5:压缩包;6:自定义
limitedFileTypeItems String 限制文件类型，如果非自定义则为空
fileCount Number 最大文件数量


联系人组件---姓名name ——

数据示例：

{
  "_id":"5a308cbe47af3deb1000020e",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"姓名",
  "beOnly":false,
  "isRemember":false,
  "isContact":true,
  "type":"name"
}

字段说明：

字段名 类型 描述
beOnly Boolean 是否唯一输入，如果为true，该表单该组件提交过的值不能再次提交
isRemember Boolean 是否缓存在用户浏览器上，如果为true再其他表单中相同类型的组件会被自动填充
isContact Boolean 是否为联系人组件，永远为true


联系人组件---手机 mobile ——

数据示例：

{
  "_id":"5a308cbf47af3deb1000020f",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"手机",
  "beOnly":false,
  "isRemember":false,
  "isContact":true,
  "type":"mobile"
}

字段说明：与上述联系人组件---姓名 name一致


联系人组件---邮箱 email ——

数据示例：

{
  "_id":"5a308cc047af3deb10000210",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"邮箱",
  "beOnly":false,
  "isRemember":false,
  "isContact":true,
  "type":"email"
}

字段说明：与上述联系人组件---姓名 name一致


联系人组件----电话 telephone ——

数据示例：

{
  "_id":"5a308cc247af3deb10000212",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"电话",
  "beOnly":false,
  "isRemember":false,
  "isContact":true,
  "type":"telephone"
}

字段说明：与上述联系人组件---姓名 name一致


联系人组件---地址 address ——

数据示例：

{
  "_id":"5a308cc147af3deb10000211",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"地址",
  "isRemember":false,
  "isContact":true,
  "type":"address"
}

字段说明：与上述联系人组件---姓名 name一致


联系人组件---地理位置 geo ——

数据示例：

{
  "_id":"5a308cc347af3deb10000213",
  "isHidden":false,
  "displayDescription":false,
  "description":"",
  "required":false,
  "label":"地理位置",
  "isRemember":false,
  "isContact":true,
  "type":"geo"
}

字段说明：与上述联系人组件---姓名 name一致