TDuck 表单开放平台 V2 题型与配置模型手册

本手册详细列出 OpenAPI V2 极简模式下所支持的题型定义规范、选项模型、在线考试评分配置、表单全局设置 7 大模块、主题美化及显隐跳题逻辑规则。

一、题型定义与填报数据规范

每个题目在定义时均支持指定全局唯一的 id（自定义题目 ID，如 q_name、q_age）。在后续通过 /open/v2/form/data/* 录入和读取数据时，data 对象的 Key 即为此 id。

1.1 基础输入类

1. 单行文本 (`INPUT`)

定义参数：

{
  "id": "q_name",
  "type": "INPUT",
  "label": "真实姓名",
  "required": true,
  "placeholder": "请输入您的姓名"
}

数据填报格式：String，如 "张三"

2. 多行文本 (`TEXTAREA`)

定义参数：

{
  "id": "q_remark",
  "type": "TEXTAREA",
  "label": "个人简介/备注",
  "required": false,
  "placeholder": "请输入详细描述"
}

数据填报格式：String，如 "五年云原生研发经验..."

3. 数字输入 (`NUMBER`)

定义参数：

{
  "id": "q_age",
  "type": "NUMBER",
  "label": "年龄",
  "required": true
}

数据填报格式：Number，如 28

1.2 选择与选项类

1. 单选题 (`RADIO`)

定义参数（支持直接传字符串数组或带标签/值的对象数组）：

{
  "id": "q_gender",
  "type": "RADIO",
  "label": "性别",
  "required": true,
  "options": ["男", "女"]
}

数据填报格式：String，如 "男"

2. 多选题 (`CHECKBOX`)

定义参数：

{
  "id": "q_skills",
  "type": "CHECKBOX",
  "label": "掌握技能",
  "required": true,
  "options": [
    {"label": "Java", "value": "Java"},
    {"label": "Go", "value": "Go"},
    {"label": "Python", "value": "Python"}
  ]
}

数据填报格式：Array<String>，如 ["Java", "Python"]

3. 下拉单选 (`SELECT`) 与下拉多选 (`MULTIPLE_SELECT`)

定义参数：

{
  "id": "q_city",
  "type": "SELECT",
  "label": "所在城市",
  "options": ["北京", "上海", "广州", "深圳", "杭州"]
}

数据填报格式：
- SELECT：String，如 "北京"
- MULTIPLE_SELECT：Array<String>，如 ["北京", "上海"]

1.3 日期与高级输入类

1. 日期时间 (`DATE`)

定义参数：

{
  "id": "q_birthday",
  "type": "DATE",
  "label": "出生日期",
  "required": true
}

数据填报格式：String，如 "1995-08-18" 或 "2026-08-20 14:00:00"

2. 评分组件 (`RATE`)

定义参数：

{
  "id": "q_score",
  "type": "RATE",
  "label": "服务满意度打分",
  "defaultValue": 5
}

数据填报格式：Number，如 5

3. 滑块组件 (`SLIDER`)

定义参数：

{
  "id": "q_percent",
  "type": "SLIDER",
  "label": "项目完成进度",
  "defaultValue": 60
}

数据填报格式：Number，如 80

4. 省市区级联 (`PROVINCE_CITY`)

定义参数：

{
  "id": "q_region",
  "type": "PROVINCE_CITY",
  "label": "户籍省市区"
}

数据填报格式：String，格式为 "省/市/区"，如 "广东省/深圳市/南山区"

5. 地理位置地图选点 (`INPUT_MAP`)

定义参数：

{
  "id": "q_location",
  "type": "INPUT_MAP",
  "label": "签到打卡地址"
}

数据填报格式：String，如 "北京市海淀区中关村南大街1号"

6. 手写签名 (`SIGN_PAD`)

定义参数：

{
  "id": "q_sign",
  "type": "SIGN_PAD",
  "label": "本人手写承诺签名",
  "required": true
}

数据填报格式：String（图片签名公网 URL 或 Base64 图片）

1.4 上传与多媒体类

1. 图片上传 (`IMAGE_UPLOAD`)

定义参数：

{
  "id": "q_avatar",
  "type": "IMAGE_UPLOAD",
  "label": "个人参会照片",
  "required": true
}

数据填报格式：String（图片公网 URL），如 "https://example.com/avatar.png"

2. 通用附件上传 (`UPLOAD`)

定义参数：

{
  "id": "q_resume",
  "type": "UPLOAD",
  "label": "附加材料 / 简历",
  "required": false
}

数据填报格式：String（附件文件公网 URL），如 "https://example.com/resume.pdf"

1.5 装饰与排版类

此类题目无需录入填报数据，仅作为前端表单界面的版面组织与说明。

1. 描述文本 (`DESC_TEXT`)

定义参数：

{
  "id": "desc_header",
  "type": "DESC_TEXT",
  "label": "请在 30 分钟内认真填写以下问卷，谢谢合作。"
}

2. 分割线 (`DIVIDER`)

定义参数：

{
  "id": "div_part2",
  "type": "DIVIDER",
  "label": "第二部分：业务调研"
}

二、在线考试与测评模型 (Exam)

当创建 type = "EXAM" 的考试表单时，可以在各选择题（RADIO、CHECKBOX）中附加 exam 属性以启用自动阅卷与评分功能。

2.1 题目考试属性说明

字段名	类型	说明
`score`	Double / BigDecimal	题目分值（如 `10.0`）
`answer`	String / Array<String>	标准正确答案。单选题为字符串（如 `"A"`），多选题为数组（如 `["A", "B", "D"]`）
`answerAnalysis`	String	试题解析说明
`scoringType`	Integer	计分规则：`1` 全部答对才得分（默认）；`2` 漏选按比例得分；`3` 答对任一即得分
`showAnswer`	Boolean	交卷后是否向考生展示标准答案与解析

2.2 单选/多选题考试定义示例

{
  "name": "Java 后端工程师专业测评",
  "type": "EXAM",
  "items": [
    {
      "id": "exam_q1",
      "type": "RADIO",
      "label": "Java 中所有类的根父类是？",
      "required": true,
      "options": [
        {"label": "Object", "value": "A"},
        {"label": "Class", "value": "B"},
        {"label": "String", "value": "C"},
        {"label": "Thread", "value": "D"}
      ],
      "exam": {
        "score": 10.0,
        "answer": "A",
        "answerAnalysis": "java.lang.Object 是 Java 类继承体系的最顶层公共父类。",
        "showAnswer": true
      }
    },
    {
      "id": "exam_q2",
      "type": "CHECKBOX",
      "label": "以下属于基本数据类型的有？",
      "required": true,
      "options": ["int", "boolean", "String", "double", "Integer"],
      "exam": {
        "score": 20.0,
        "scoringType": 1,
        "answer": ["int", "boolean", "double"],
        "answerAnalysis": "String 与 Integer 为引用对象类型，其余三项为 Java 原生基本数据类型。",
        "showAnswer": true
      }
    }
  ]
}

三、表单全局设置模型 (Setting)

表单设置对象通过 setting 字段传递，全面覆盖表单访问控制、频次限制、答题体验、结果通知与防作弊策略。

3.1 填写权限模块 (Write Permission)

字段名	类型	说明
`mustLogin`	Boolean	是否必须登录后才允许填写
`anonymousWrite`	Boolean	是否匿名填写（不记录提交人信息）
`enableWhiteList`	Boolean	是否启用白名单限制
`whiteListType`	Integer	白名单类型：`1` 邮箱，`2` 手机号，`3` 自定义文本
`whiteListTips`	String	非白名单人员访问提示文案
`whiteListUseCount`	Integer	白名单每人允许使用的提交次数
`onlyWxWrite`	Boolean	仅允许在微信内置浏览器中打开填写
`recordWxUser`	Boolean	是否静默/授权获取并记录微信用户信息（OpenId、昵称、头像）

3.2 提交限制模块 (Submit Limit)

字段名	类型	说明
`ipWriteCountLimitStatus`	Boolean	是否开启 IP 提交频次限制
`ipWriteCountLimit`	Integer	限制提交次数
`ipWriteCountLimitDateType`	Integer	限制周期类型：`1` 总共, `2` 每天, `3` 每周, `4` 每月
`accountWriteCountLimitStatus`	Boolean	是否开启账号答题次数限制
`accountWriteCountLimit`	Integer	限制账号提交次数
`deviceWriteCountLimitStatus`	Boolean	是否开启每台设备提交次数限制
`totalWriteCountLimitStatus`	Boolean	是否开启表单总回收份数上限控制
`totalWriteCountLimit`	Integer	总回收份数上限值（达到后自动停止收集）
`writeInterviewTimeStatus`	Boolean	是否开启可访问起止日期时间限制
`writeInterviewDateTimeRange`	Array<String>	开放填报起止时间范围（如 `["2026-08-01 00:00:00", "2026-08-31 23:59:59"]`）
`passwordWriteStatus`	Boolean	是否开启访问密码保护
`writePassword`	String	填报访问密码（最大 50 字符）

3.3 填写体验模块 (Write Experience)

字段名	类型	说明
`enableProgress`	Boolean	是否在顶部展示答题进度条
`showProgressDetail`	Boolean	是否显示详细进度百分比
`saveSubmitStatus`	Boolean	再次打开时是否自动回显上次已提交的数据
`saveNotSubmitStatus`	Boolean	答题过程中是否自动在本地暂存未提交的草稿
`aiFillStatus`	Boolean	是否开启 AI 智能快捷填报辅助
`onePageOneQuestion`	Object	一页一题模式配置（`enable`: 是否开启, `autoScroll`: 自动翻页等）

3.4 提交后行为模块 (Submit Behavior)

字段名	类型	说明
`submitShowType`	Integer	提交后展示形式：`1` 系统默认完成页, `2` 自定义富文本 HTML
`submitShowCustomPageContent`	String	自定义提示页面 HTML 富文本内容
`submitJump`	Boolean	提交后是否自动跳转外部链接
`submitJumpUrl`	String	跳转目标 URL 网址
`showSubmitContentBtn`	Boolean	提交成功后是否允许填报人查看自己填写的明细
`updateSubmitContentBtn`	Boolean	提交后是否允许填报人二次修改已填内容
`enableAgainWrite`	Boolean	提交完成页是否展示“再填一份”按钮
`downloadTemplateAfterSubmit`	Boolean	提交后是否提供凭证/准考证打印与下载功能
`printTemplateKey`	String	绑定的凭证打印模板 Key

3.5 社交分享模块 (Share Setting)

字段名	类型	说明
`shareWxTitle`	Boolean	是否启用自定义微信分享卡片标题
`shareWxTitleContent`	String	自定义分享卡片主标题
`shareWxDesc`	Boolean	是否启用自定义微信分享卡片描述
`shareWxDescContent`	String	自定义分享卡片副标题/描述
`shareWxImg`	Boolean	是否启用自定义分享卡片缩略图
`shareWxImgUrl`	String	缩略图图片公网 URL

3.6 数据通知模块 (Notification Setting)

字段名	类型	说明
`emailNotify`	Boolean	是否开启新提交邮件提醒
`newWriteNotifyEmail`	String	接收通知的电子邮箱地址
`wxNotify`	Boolean	是否开启微信公众号新数据模板消息通知

3.7 考试与防作弊模块 (Exam & Anti-Cheat)

配置于 setting.examSettings 子对象中：

字段名	类型	说明
`showScoreText`	Boolean	交卷后立即显示考试总分与评语
`showAnswerRightWrong`	Boolean	是否在交卷后标注每道题的对错状态
`enableViewAnswer`	Boolean	是否允许考生查看标准答案与解析
`showRank`	Boolean	是否展示排行榜
`enableExamTime`	Boolean	是否限制整场考试的开考与截止时间
`startTime` / `endTime`	String	考试开放的起止具体时间（`yyyy-MM-dd HH:mm:ss`）
`enablePassScore`	Boolean	是否设置及格分数线
`passScore`	BigDecimal	及格分数标准（如 `60.0`）
`enableCertificate`	Boolean	及格后是否自动颁发电子合格证书
`certificateId`	Long	电子证书模板 ID
`practiceMode`	Boolean	练习模式（做完一题即显示对错和解析）
`randomQuestionOrder`	Boolean	题目顺序随机打乱（千人千卷）
`enableMonitor`	Boolean	开启在线监考模式
`enableSwitchCount`	Boolean	是否开启切屏限制
`maxSwitchCount`	Integer	最大允许离开页面/切屏次数（超额自动强制交卷）
`disableCopyQuestion`	Boolean	是否禁止在页面上复制题目文本
`enableMaxTime`	Boolean	是否开启答题倒计时限制
`maxTime`	Integer	考试倒计时限时（单位：分钟，如 `60`）

四、主题美化配置模型 (Theme)

表单主题对象通过 theme 字段传递：

字段名	类型	说明	示例
`themeColor`	String	表单主色调（按钮、选中框等高亮色）	`"#1890ff"`
`backgroundColor`	String	页面整体背景颜色	`"#f0f2f5"`
`backgroundImg`	String	页面背景平铺大图 URL	`"https://oss.example.com/bg.jpg"`
`headImgUrl`	String	表单顶部海报横幅图片 URL	`"https://oss.example.com/banner.png"`
`logoImgUrl`	String	品牌 Logo 图片 URL	`"https://oss.example.com/logo.png"`
`logoPosition`	String	Logo 显示对齐位置：`"left"`, `"center"`, `"right"`	`"left"`
`submitBtnText`	String	底部提交按钮文案	`"确认提交"`
`showFormTitle`	Boolean	是否显示表单主标题	`true`
`showFormNumber`	Boolean	是否在题目左侧显示题号序号	`true`
`watermark`	Boolean	是否开启防泄密水印	`true`
`watermarkText`	String	水印自定义文案	`"仅限内部使用"`
`watermarkUserName`	Boolean	是否将填报人真实姓名/账号作为背景水印	`true`
`enableCover`	Boolean	是否启用引导封面页	`true`
`coverTitle`	String	封面页大标题	`"2026 技术大会欢迎您"`
`coverBtnText`	String	封面页进入答题按钮文案	`"开始填报"`

五、显隐与跳题逻辑规则模型 (Logic)

逻辑规则通过 logic.rules 列表配置，支持配置多题联动、条件判断以及满足条件时的动作（显示/隐藏题目、跳题结束等）。

5.1 规则对象结构

conditionList：触发条件集合（支持多个条件与/或判断）
triggerList：满足条件后执行的动作列表

5.2 条件对象属性 (`conditionList`)

字段名	类型	说明	示例
`formItemId`	String	判定题目的自定义 ID	`"q_gender"`
`operator`	String	比较运算符：`eq` (等于), `ne` (不等于), `gt` (大于), `ge` (大于等于), `lt` (小于), `le` (小于等于), `contain` (包含), `not_contain` (不包含)	`"eq"`
`value`	Object	触发的目标比对值	`"女"`

5.3 动作对象属性 (`triggerList`)

字段名	类型	说明	示例
`formItemId`	String	受影响的题目自定义 ID	`"q_pregnancy"`
`action`	String	动作类型：`show` (显示), `hide` (隐藏), `jump` (跳转至指定题目), `finish` (提前结束并提交)	`"show"`

5.4 逻辑规则示例

场景：当用户性别 q_gender 选择 "女" 时，自动显示 "q_pregnancy"（是否已婚育）题目；否则保持隐藏。

{
  "logic": {
    "rules": [
      {
        "conditionList": [
          {
            "formItemId": "q_gender",
            "operator": "eq",
            "value": "女"
          }
        ],
        "triggerList": [
          {
            "formItemId": "q_pregnancy",
            "action": "show"
          }
        ]
      }
    ]
  }
}

官方文档·

约 25 分钟阅读 (9797 字)

最后更新于 2026-08-20 15:31:41

这篇文章对您有帮助吗？

您的反馈将帮助我们不断改进平台技术文档质量

接入说明

TDuck MCP Server 与 OAuth 2.0 接入指南

TDuck 表单开放平台 V2 题型与配置模型手册

TDuck 表单开放平台 V2 题型与配置模型手册

目录

一、 题型定义与填报数据规范

1.1 基础输入类

1. 单行文本 (INPUT)

2. 多行文本 (TEXTAREA)

3. 数字输入 (NUMBER)

1.2 选择与选项类

1. 单选题 (RADIO)

2. 多选题 (CHECKBOX)

3. 下拉单选 (SELECT) 与 下拉多选 (MULTIPLE_SELECT)

1.3 日期与高级输入类

1. 日期时间 (DATE)

2. 评分组件 (RATE)

3. 滑块组件 (SLIDER)

4. 省市区级联 (PROVINCE_CITY)

5. 地理位置地图选点 (INPUT_MAP)

6. 手写签名 (SIGN_PAD)

1.4 上传与多媒体类

1. 图片上传 (IMAGE_UPLOAD)

2. 通用附件上传 (UPLOAD)

1.5 装饰与排版类

1. 描述文本 (DESC_TEXT)

2. 分割线 (DIVIDER)

二、 在线考试与测评模型 (Exam)

2.1 题目考试属性说明

2.2 单选/多选题考试定义示例

三、 表单全局设置模型 (Setting)

3.1 填写权限模块 (Write Permission)

3.2 提交限制模块 (Submit Limit)

3.3 填写体验模块 (Write Experience)

3.4 提交后行为模块 (Submit Behavior)

3.5 社交分享模块 (Share Setting)

3.6 数据通知模块 (Notification Setting)

3.7 考试与防作弊模块 (Exam & Anti-Cheat)

四、 主题美化配置模型 (Theme)

五、 显隐与跳题逻辑规则模型 (Logic)

5.1 规则对象结构

5.2 条件对象属性 (conditionList)

5.3 动作对象属性 (triggerList)

5.4 逻辑规则示例

一、题型定义与填报数据规范

1. 单行文本 (`INPUT`)

2. 多行文本 (`TEXTAREA`)

3. 数字输入 (`NUMBER`)

1. 单选题 (`RADIO`)

2. 多选题 (`CHECKBOX`)

3. 下拉单选 (`SELECT`) 与下拉多选 (`MULTIPLE_SELECT`)

1. 日期时间 (`DATE`)

2. 评分组件 (`RATE`)

3. 滑块组件 (`SLIDER`)

4. 省市区级联 (`PROVINCE_CITY`)

5. 地理位置地图选点 (`INPUT_MAP`)

6. 手写签名 (`SIGN_PAD`)

1. 图片上传 (`IMAGE_UPLOAD`)

2. 通用附件上传 (`UPLOAD`)

1. 描述文本 (`DESC_TEXT`)

2. 分割线 (`DIVIDER`)

二、在线考试与测评模型 (Exam)

三、表单全局设置模型 (Setting)

四、主题美化配置模型 (Theme)

五、显隐与跳题逻辑规则模型 (Logic)

5.2 条件对象属性 (`conditionList`)

5.3 动作对象属性 (`triggerList`)