跳到主要内容

API V1 字段结构 Schema

通过 API 获取表单结构时，会返回如下类似结果：

{
    "name": "产品需求调研表",
    "description": "感谢您能抽出几分钟时间填写以下内容，现在我们马上开始吧！",
    "fields": [
        {
            "field_1": {
                "label": "姓名",
                "type": "single_line_text",
                "notes": "",
                "private": false,
                "validation": {}
            },
            "field_2": {
                "label": "手机",
                "type": "mobile",
                "notes": "",
                "private": false,
                "validation": {}
            }
        }
    ]
}

其中，fields 包含了该表单的所有字段。每个字段的 Key （例如 field_1, field_2）是该字段的唯一标识符，用于在获取数据或者新增数据时指定字段。

下面对每个字段的 Schema 做详细解释。

通用属性​

以下列表为字段通用属性，即，每个自动都会包含如下属性：

参数名称是否必须类型说明
label是String字段标题
type是String字段类型
notes是String字段提示（可能是 HTML 格式富文本）
private是Bool是否隐藏
validation是Hash字段校验规则

字段 type 对应表​

type字段
single_line_text单行文字，姓名
paragraph_text多行文字
single_choice单项选择，图片单选
multiple_choice多项选择，图片多选
drop_down下拉框
cascade_drop_down多级下拉框
number数字
attachment上传文件
time时间
date_time日期
link网址
geo_location地理信息
goods配图商品，无图商品
mobile手机
email邮箱
phone电话
address地址
matrix矩阵填空
likert矩阵单选
table表格字段
matrix_scale矩阵量表
multiple_blanks横向填空
form_association表单关联
rating评分字段
npsNPS字段
sort排序字段
e_signature电子签名
formula计算字段

通用校验（validation）属性​

{
  "validation": {
    "required": true,
    "unique": true,
    "access_control_list_limit": true,
    "access_control_type": "white"
  }
}
参数名称是否必须类型说明
required否Bool是否必填
unique否Bool是否不能与已有数据重复
access_control_list_limit否Bool是否开启「白名单」「黑名单」限制
access_control_type否String「白名单」「黑名单」限制类型。可选值：white, black

字段特定属性​

无特殊属性的字段​

包括：

  • 姓名
  • 手机
  • 电话
  • 邮箱
  • 电子签名
  • 地址
  • 网址
  • 地理信息

这些字段无特殊属性，只包含上述的通用属性和通用校验类型

文本类字段（单行文字、多行文字）​

{
    "label": "多行文字",
    "type": "paragraph_text",
    "notes": "",
    "private": false,
    "validation": {
        "minimum_length": 100,
        "maximum_length": 10000
    }
}
参数名称是否必须类型说明
validation.minimum_length否Number最少多少字
validation.maximum_length否Number最多多少字

附件/文件上传​

{
    "field_10": {
        "label": "上传文件",
        "type": "attachment",
        "notes": "",
        "private": false,
        "validation": {},
        "max_file_quantity": 3,
        "media_type": {
            "type": "unlimited",
            "value": []
        }
    }
}
参数名称是否必须类型说明
max_file_quantity是Number最大文件数量
media_type是Hash文件上传类型
media_type.type否String文件上传类型（unlimited 或制定类型）
media_type.value否Array允许上传的文件扩展名

数字字段​

{
    "label": "数字",
    "type": "number",
    "notes": "",
    "private": false,
    "validation": {
        "min": 10000.0,
        "max": 20000.0
    },
    "precision": 2,
    "thousands_separator": true
}
参数名称是否必须类型说明
validation.min否Number最小值
validation.max否Number最大值
precision否Number精度（不超过几位小数）
thousands_separator否Bool显示千分分隔符
display_as_percentage否Bool显示百分比

选项类字段​

包括

  • 单项选择
  • 多项选择
  • 下拉框
  • 图片单选
  • 图片多选
  • 多级下拉框
  • 排序字段
{
    "label": "单项选择",
    "type": "single_choice",
    "notes": "",
    "private": false,
    "validation": {},
    "choices": [
        {
            "name": "选项 A",
            "value": "nSBX",
            "hidden": false,
            "quota": 10,
            "operand_value": 1.0
        },
        {
            "name": "选项 B",
            "value": "Ei3b",
            "hidden": true,
            "quota": 11,
            "operand_value": 2.0
        },
        {
            "name": "选项 C",
            "value": "jGwK",
            "hidden": false,
            "quota": 10,
            "operand_value": 3.0
        }
    ],
    "allow_other": false
}
参数名称是否必须类型说明
choices是Array选项
choices.name是String选项名称
choices.value是String选项 API Code
choices.hidden是Bool隐藏选项
choices.quota是Number选项名额
choices.operand_value是Number选项赋值
choices.sub_choices否Hash下级下拉框（仅对多级下拉框有效）
allow_other是Bool是否包含其他选项
min_selected否Number最少选几项（多项选择，图片多选，排序字段）
max_selected否Number最多选几项（多项选择，图片多选，排序字段）

日期字段​

{
    "label": "日期",
    "type": "date_time",
    "notes": "",
    "private": false,
    "validation": {
        "start": "2021-01-01",
        "end": "2021-12-15"
    },
    "precision": "day"
}
参数名称是否必须类型说明
validation.start否Date起始日期
validation.end否Date结束日期
precision是String精度（格式）：second minute hour day month year

时间​

{
    "label": "时间",
    "type": "time",
    "notes": "",
    "private": false,
    "include_second": true,
    "validation": {}
}
参数名称是否必须类型说明
include_second否Bool精确到秒

配图商品、无图商品​

{
    "label": "配图商品",
    "type": "goods",
    "notes": "",
    "private": false,
    "validation": {},
    "goods_items": [
        {
            "name": "商品 A",
            "value": "2dZT",
            "description": null,
            "inventory": 100,
            "hidden": false,
            "price": 20.0,
            "original_price": 25.0,
            "skus": []
        },
        {
            "name": "商品 B",
            "value": "RPCC",
            "description": null,
            "inventory": 300,
            "hidden": false,
            "price": null,
            "original_price": null,
            "skus": [
                {
                    "spec": {
                        "规格1": "A1",
                        "规格2": "B1"
                    },
                    "price": 15.0,
                    "original_price": 20.0,
                    "inventory": 100
                },
                {
                    "spec": {
                        "规格1": "A2",
                        "规格2": "B1"
                    },
                    "price": 25.0,
                    "original_price": 30.0,
                    "inventory": 200
                },
            ]
        }
    ]
}
参数名称是否必须类型说明
goods_items是Array商品项目
goods_items.name是String商品名
goods_items.value是String商品对应的 API Code
goods_items.description是String商品说明
goods_items.inventory是Number库存
goods_items.hidden是Bool隐藏选项
goods_items.price是Number商品价格
goods_items.original_price是Number商品划线价
goods_items.skus是Array商品规格
goods_items.skus.price是Number商品规格价格
goods_items.skus.original_price是Number商品规格划线价
goods_items.skus.inventory是Number商品规格库存
goods_items.skus.spec是Hash商品规格描述

表单关联​

{
    "label": "表单关联",
    "type": "form_association",
    "notes": "",
    "private": false,
    "validation": {},
    "associated_form_token": "ABC123",
    "associated_field_api_codes": [
        "field_1"
    ],
    "display_field_settings": [
        {
            "api_code": "field_2",
            "privacy_safe": true,
            "public_display": false
        }
    ]
}
参数名称是否必须类型说明
associated_form_token是String关联表单的 Token
associated_field_api_codes是String关联表单的字段 API Code（支持多个）
display_field_settings是Array展示字段列表
display_field_settings.api_code是String展示字段 API Code
display_field_settings.privacy_safe是Bool展示字段是否开启隐私保护
display_field_settings.public_display是Bool展示字段是否在公开表单展示

计算字段​

{
    "label": "计算字段",
    "type": "formula",
    "notes": "",
    "private": false,
    "validation": {},
    "formula": "field_1 + field_2",
    "formula_display": "$(语文成绩) + $(数学成绩)"
}
参数名称是否必须类型说明
formula_display是String公式（用于表单管理员阅读）
formula是String公式（用于服务器后台计算）

矩阵单选​

{
    "label": "矩阵单选",
    "type": "likert",
    "notes": "",
    "private": false,
    "validation": {},
    "choices": [
        {
            "name": "选项 A",
            "value": "2Y09",
            "hidden": false
        },
        {
            "name": "选项 B",
            "value": "v944",
            "hidden": false
        }
    ],
    "statements": [
        {
            "name": "题目 1",
            "value": "g4fI"
        },
        {
            "name": "题目 2",
            "value": "U5sl"
        }
    ]
}
参数名称是否必须类型说明
choices是Array选项
choices.name是String选项名称
choices.value是String选项 API Code
choices.hidden是Bool隐藏选项
statements是Array题目
statements.name是String题目名称
statements.value是String题目 API Code

矩阵填空，矩阵量表​

{
    "label": "矩阵填空",
    "type": "matrix",
    "notes": "",
    "private": false,
    "validation": {},
    "statements": [
        {
            "name": "题目 1",
            "value": "4lwY"
        },
        {
            "name": "题目 2",
            "value": "GhAK"
        }
    ],
    "dimensions": [
        {
            "field_1": {
                "label": "项目 A",
                "type": "single_line_text",
                "notes": null,
                "private": false,
                "validation": {}
            }
        },
        {
            "field_2": {
                "label": "项目 B",
                "type": "single_line_text",
                "notes": null,
                "private": false,
                "validation": {}
            }
        }
    ]
}
参数名称是否必须类型说明
statements是Array题目
statements.name是String题目名称
statements.value是String题目 API Code
dimensions是Array项目

每一个项目都是一个嵌入的 field，可以根据 field type 参考具体 field 的结构

横向填空​

 {
    "label": "横向填空",
    "type": "multiple_blanks",
    "notes": "",
    "private": false,
    "validation": {},
    "placeholder": "太阳${field_1}$ 升,${field_2}$ 落",
    "dimensions": [
        {
            "field_1": {
                "label": "",
                "type": "single_line_text",
                "notes": null,
                "private": false,
                "validation": {}
            }
        },
        {
            "field_2": {
                "label": "",
                "type": "single_line_text",
                "notes": null,
                "private": false,
                "validation": {}
            }
        }
    ]
}
参数名称是否必须类型说明
placeholder是Array填空编辑内容（下划线使用 ${field_x} 替换）
dimensions是Array项目

每一个项目都是一个嵌入的 field，默认固定位单行文字，可以参考单行文字的结构说明

表格​

{
    "label": "表格",
    "type": "table",
    "notes": "",
    "private": false,
    "validation": {},
    "dimensions": [
        {
            "field_1": {
                "label": "项目 A",
                "type": "single_line_text",
                "notes": null,
                "private": false,
                "validation": {}
            }
        },
        {
            "field_2": {
                "label": "项目 B",
                "type": "single_line_text",
                "notes": null,
                "private": false,
                "validation": {}
            }
        }
    ]
}

NPS 字段​

{
    "label": "你有多大可能把我们推荐给朋友或同事？请从0分到10分打分。",
    "type": "nps",
    "notes": "",
    "private": false,
    "validation": {},
    "minimum_ratings_display_text": "不可能",
    "maximum_ratings_display_text": "极有可能",
    "highlight_color": "rgb(40,117,232)"
}
参数名称是否必须类型说明
minimum_ratings_display_text是String最低分文案
maximum_ratings_display_text是String最高分文案
highlight_color是String颜色（不可编辑）

评分字段​

{
    "label": "评分",
    "type": "rating",
    "notes": "",
    "private": false,
    "validation": {},
    "rating_type": "star",
    "rating_max": 10
}
参数名称是否必须类型说明
rating_type是String外观
rating_max是Number量级
参数名称是否必须类型说明
dimensions是Array项目

每一个项目都是一个嵌入的 field，可以根据 field type 参考具体 field 的结构

预约字段​

{
    "field_1": {
        "private": false,
        "reservation_items": [
            {
                "hidden": false,
                "name": "预约项目1",
                "value": "9iVb"
            },
            {
                "hidden": false,
                "name": "预约项目2",
                "value": "lU4f"
            }
        ],
        "label": "选择预约项目",
        "type": "reservation",
        "validation": {
            "required": true
        }
    }
}
参数名称是否必须类型说明
reservation_items是Array预约项目
reservation_items.hidden是Bool隐藏选项
reservation_items.name是String项目名称
reservation_items.value是String项目API Code