纷享销客开发者手册

简体中文

English

表单字段传值说明

约 954 字大约 3 分钟

2026-07-13

本文整理对象表单字段在插件、接口或脚本中设置值时的推荐传值格式。

通用规则

  • 空值统一传 null。
  • 数字、金额、百分数建议传字符串形式的数字，避免带格式化符号。
  • 日期、日期时间、时间字段传毫秒时间戳字符串。
  • 查找关联字段除字段本身值外，还需要同步传 字段名__r，否则页面可能无法显示名称。
  • 文件类字段传数组，数组元素为文件对象。

文本类

字段类型示例值说明
单行文本"test"普通字符串
多行文本"这是多行文本"如需换行显示，使用 \n 分隔
手机"15810172396"手机号字符串
邮箱"fxi@fxiaoke.com"邮箱字符串
网址"https://www.fxiaoke.com"也可传 "www.fxiaoke.com"
长文本"这是长文本"如需换行显示，使用 \n 分隔
富文本"<p style='font-size:18px'><span style='color:red'>测试富文本数据</span></p>"HTML 字符串

多行文本或长文本换行示例：

"1.采购流程\n2.线上汇报\n3.采购流程"

协同富文本示例：

{
  "text": "测试富文本数据",
  "__xt": {
    "__json": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "attrs": {
            "textAlign": "left"
          },
          "content": [
            {
              "type": "text",
              "marks": [
                {
                  "type": "bold"
                },
                {
                  "type": "textStyle",
                  "attrs": {
                    "color": "rgb(51, 51, 51)",
                    "fontSize": false
                  }
                }
              ],
              "text": "测试富文本数据"
            }
          ]
        }
      ]
    },
    "__summeryNodeCount": 1,
    "version": 2
  }
}

数字类

字段类型正确示例错误示例说明
数字"1000.00"-传数字字符串
金额"1000.00""1,000.00"、"$1000.00"不要传千分位或币种符号
百分数"90""90%""90" 表示 90%

日期类

字段类型正确示例错误示例说明
日期"1729244925956""2024/10/18"传对应年月日的毫秒数
日期时间"1729244997591""2024/10/18 17:50"传对应年月日时分的毫秒数
时间"1729244997591""17:50"传对应年月日时分的毫秒数

选项类

字段类型示例值说明
单选"options1"传选项值
多选["options1", "options2", "options3"]传选项值数组
布尔值truetrue 表示是，默认选中否传 false

文件类

图片、签名、附件、大附件均传文件对象数组。

图片或签名示例：

[
  {
    ext: "jpg",
    filename: "图片测试.jpg",
    path: "N_1243.jpg",
    size: 433390
  }
]

附件或大附件示例：

[
  {
    create_time: 1729246925703,
    ext: "jpg",
    filename: "图片测试.jpg",
    path: "N_1243.jpg",
    size: 433390
  }
]

数据类

查找关联

查找关联单选字段传目标数据 ID，同时需要传显示名称字段。

以 account_id 为例：

{
  account_id: "xxxxxx",
  account_id__r: "显示名称"
}

如果不传 account_id__r，页面可能无法显示名称。

查找关联多选

查找关联多选字段传 ID 数组，同时需要传 字段名__r 的显示对象数组。

以 contact_ids 为例：

{
  contact_ids: ["xxxxxx1", "xxxxxx2"],
  contact_ids__r: [
    {
      _id: "xxxxxx1",
      name: "显示名称1"
    },
    {
      _id: "xxxxxx2",
      name: "显示名称2"
    }
  ]
}

人员部门类

字段类型示例值说明
人员["1000"]1000 为人员 ID
人员多选["1000", "1001"]传人员 ID 数组
外部人员["1000000000000001"]传外部人员 ID 数组
部门["1005"]传部门 ID 数组
部门多选["1005", "1006"]传部门 ID 数组
外部部门["30000000000001"]传外部部门 ID 数组

地图类

字段类型示例值说明
定位"114.086027#%$23.017722#%$广东省东莞市文明路与友谊路交叉口西南20米表单印刷贴纸标签彩页吊牌电脑纸说明书广告"经度、纬度、详细地址使用 #%$ 拼接
国家"248"对应国家编码
省"321"对应省编码
市"456"对应市编码
区"1000"对应区编码

常见错误

场景错误写法推荐写法
金额带格式"1,000.00"、"$1000.00""1000.00"
百分数字段带百分号"90%""90"
日期传格式化字符串"2024/10/18""1729244925956"
日期时间传格式化字符串"2024/10/18 17:50""1729244997591"
时间只传时分"17:50""1729244997591"
查找关联只传 ID{ account_id: "xxxxxx" }{ account_id: "xxxxxx", account_id__r: "显示名称" }