字段格式

aki • 发表于：2016年08月29日 15:19:15 • 更新于：2024年05月01日 15:19:24

Index

字段的信息

使用 API 操作应用的记录时，可参考下文的字段格式来获取或设置字段的值。

可通过以下两种方法来指定字段。

  • 方法1: 指定字段名称。

    • 类别

    • 状态

    • 执行者

  • 方法2: 指定字段代码。
    除了方法1中列举的字段，其他的所有字段都用字段代码。
    “字段代码”可在“字段的设置”页面中查看。

使用添加、更新API发送JSON数据时，只需发送“value”参数。“type”无需发送。
※下文中也会提及到，个别JavaScript API在添加或更新“表格”数据时需要指定“type”。

关于记录编号和记录ID

  • 记录编号：系统自动分配给记录的、与其他记录不重复的编号。 

    • 如果没有设置应用代码，则记录编号和记录ID一样

    • 如果设置了应用代码，则记录编号是“应用代码”+”记录ID“。
      例如：应用代码为“APPCODE”的应用，其记录编号为“APPCODE-1”。

  • 记录ID：系统自动分配给记录的、与其他记录不重复的编号，必须为数值。 
    处理API时，请使用记录ID。

修饰表单的的字段

以下字段是用来修饰表单的字段。
不可对其获取/添加/更新值。

  • 标签

  • 空白栏

  • 边框

  • 组合

如果要获取或更改表单的设置信息，请使用以下API。


关联记录列表

不可获取/添加/更改关联记录列表字段的值。如要获取或更改表单的设置信息，请使用以下API。

数值字段

用 kintone JavaScript API 对数值字段设置或更改值时可使用的值如下。

  • 数値

    • 可使用的符号有“+”或“-”。

    • 可使用小数点 “.”。

    • 指可使用指数符号。指数符号中可以使用 “e” 或者 “E” 。

  • 空字符

数字或者符号仅可使用半角。

另外，使用设置记录的值 API 或者事件对象对数值字段的值进行改写时，可以使用以下值。

  • undefined null
    指定这个值时，数值字段的值为空。

  • #INVALID!
    指定这个值时，数值字段的值不可改写。

除了以上值，其他的一律认为是数值字段的不正确值。

字段格式

记录信息中的字段

字段类型typevalue的范例
※此处，【value的范例】的【字段代码】用< >括起开，实际使用时不需要。
记录编号 ※3RECORD_NUMBER

  • 获取时的应答数据

"<字段代码>": {
    "type": "RECORD_NUMBER",
    "value": "1"
}
以下为应用代码指定为【APPCODE】时的范例。
"<字段代码>": {
    "type": "RECORD_NUMBER",
    "value": "APPCODE-1"
}
记录ID ※3__ID__

  • 获取时的应答数据

"$id": {
    "type": "__ID__",
    "value": "1"
}
版本 ※3__REVISION__

  • 获取时的应答数据

"$revision": {
    "type": "__REVISION__",
    "value": "5"
}
创建人 ※4CREATOR

  • 获取时的应答数据

"<字段代码>": {
    "type": "CREATOR",
    "value": {
        "code": "zhou",
        "name": "zhou shijie"
    }
}

来宾用户的情况

"<字段代码>": {
    "type": "CREATOR",
    "value": {
        "code": "guest/zhou@cybozu.cn",
        "name": "zhou shijie"
    }
}

  • 添加时的请求数据

"<字段代码>": {
    "value": {
        "code": "zhou"
    }
}
创建时间 ※4CREATED_TIME

  • 获取时的应答数据

"<字段代码>": {
    "type": "CREATED_TIME",
    "value": "2012-01-11T11:30:00Z"
}
・【YYYY-MM-DD】和【HH:MM:SS】之间的【T】为固定值。 

・【HH:MM:SS】之后的【Z】为固定值，表示UTC。

  • 添加时的请求数据

"<字段代码>": {
    "value": "2012-01-11T11:30:00Z"
}
・【YYYY-MM-DD】和【HH:MM:SS】之间的【T】为固定值。 
・【HH:MM:SS】之后的【Z】为固定值，表示UTC。
"<字段代码>": {
    "value": "2012-01-11T11:30:00+08:00"
}

・需使用【±HH:MM】指定与UTC的时差。

・不可指定未来的时间。

更新人 ※4MODIFIER

  • 获取时的应答数据

"<字段代码>": {
    "type": "MODIFIER",
    "value": {
        "code": "zhou",
        "name": "zhou shijie"
    }
}

来宾用户的情况

"<字段代码>": {
    "type": "MODIFIER",
    "value": {
        "code": "guest/zhou@cybozu.cn",
        "name": "zhou shijie"
    }
}

  • 添加时的请求数据

"<字段代码>": {
    "value": {
        "code": "zhou"
    }
}
更新时间 ※4UPDATED_TIME

  • 获取时的应答数据

"<字段代码>": {
    "type": "UPDATED_TIME",
    "value": "2012-01-11T11:30:00Z"
}
・【YYYY-MM-DD】和【HH:MM:SS】之间的【T】为固定值。 
・【HH:MM:SS】之后的【Z】为固定值，表示UTC。

  • 添加时的请求数据

"<字段代码>": {
    "value": "2012-01-11T11:30:00Z"
}
・【YYYY-MM-DD】和【HH:MM:SS】之间的【T】为固定值。 
・【HH:MM:SS】之后的【Z】为固定值，表示UTC。
"<字段代码>": {
    "value": "2012-01-11T11:30:00+08:00"
}
・需使用【±HH:MM】指定与UTC的时差。 
・不可指定未来的时间。

自定义字段

字段类型typevalue
单行文本框SINGLE_LINE_TEXT

  • 获取时的应答数据

"<字段代码>": {
    "type": "SINGLE_LINE_TEXT",
    "value": "文本内容。"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "文本内容。"
}
多行文本框MULTI_LINE_TEXT

  • 获取时的应答数据

"<字段代码>": {
    "type": "MULTI_LINE_TEXT",
    "value": "文本\n内容。"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "文本\n内容。"
}
文本编辑框RICH_TEXT

  • 获取时的应答数据

"<字段代码>": {
    "type": "RICH_TEXT",
    "value": "<a href=\"https://www.cybozu.cn\">才望子</a>"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "<a href=\"https://www.cybozu.cn\">才望子</a>"
}
数值NUMBER

  • 获取时的应答数据

"<字段代码>": {
    "type": "NUMBER",
    "value": "123"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "123"
}
计算 ※3CALC

  • 获取时的应答数据

"<字段代码>": {
    "type": "CALC",
    "value": "123"
}
根据显示格式的设置， "value" 的值也不同。

  • 数值: "1234"

  • 数值（逗号隔开）: "1234"

  • 日期与时间: "2012-01-11T11:30:00Z"

  • 日期: "2012-01-11"

  • 时间: "11:30"

  • 时间（小时、分）: "49:30" (页面上显示"49小时30分")

  • 时间（天、小时、分）: "49:30" (页面上显示"2天1小时30分")

※以下事件时，"value"的值为空。

  • 无法使用添加/更新时的请求数据进行添加/更新。

复选框 ※1CHECK_BOX

  • 获取时的应答数据

"<字段代码>": {
     "type": "CHECK_BOX",
     "value": [
         "选项1",
         "选项2"
     ]
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": [
        "选项1",
        "选项2"
    ]
}
单选框 ※1RADIO_BUTTON

  • 获取时的应答数据

"<字段代码>": {
    "type": "RADIO_BUTTON",
    "value": "选项3"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "选项3"
}
  ・指定空字符时，将自动设置初始值。
下拉菜单 ※1DROP_DOWN

  • 获取时的应答数据

"<字段代码>": {
    "type": "DROP_DOWN",
    "value": "选项3"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "选择3"
}
多选 ※1MULTI_SELECT

  • 获取时的应答数据

"<字段代码>": {
    "type": "MULTI_SELECT",
    "value": [
        "选项1",
        "选项2"
    ]
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": [
        "选项1",
        "选项2"
    ]
}
附件FILE

  • 获取时的应答数据

"<字段代码>": {
    "type": "FILE",
    "value": [
        {
            "contentType": "text/plain",
            "fileKey":"201202061155587E339F9067544F1A92C743460E3D12B3297",
            "name": "17to20_VerupLog (1).txt",
            "size": "23175"
        },
        {
            "contentType": "text/plain",
            "fileKey": "201202061155583C763E30196F419E83E91D2E4A03746C273",
            "name": "17to20_VerupLog.txt",
            "size": "23175"
        }
    ]
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": [
        {
            "fileKey":"201202061155587E339F9067544F1A92C743460E3D12B3297",
        },
        {
            "fileKey": "201202061155583C763E30196F419E83E91D2E4A03746C273",
        }
    ]
}

  • 获取的应答数据中包含的文件密钥只能用于文件下载。

链接LINK

  • 获取时的应答数据

"<字段代码>": {
    "type": "LINK",
    "value": "https://www.cybozu.cn/"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "https://www.cybozu.cn/"
}
日期 ※2DATE

  • 获取时的应答数据

"<字段代码>": {
    "type": "DATE",
    "value": "2012-01-11"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "2012-01-11"
}
时间 ※2TIME

  • 获取时的应答数据

"<字段代码>": {
    "type": "TIME",
    "value": "11:30"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "11:30"
}
日期与时间 ※2DATETIME

  • 获取时的应答数据

"<字段代码>": {
    "type": "DATETIME",
    "value": "2012-01-11T11:30:00Z"
}
・【YYYY-MM-DD】和【HH:MM:SS】之间的【T】为固定值。 

・【HH:MM:SS】之后的【Z】为固定值，表示UTC。

・通过中国时间（CST）指定时，需按照ISO8601的格式指定如下。

  2012-01-11T11:30:00+08:00

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "2012-01-11T11:30:00Z"
}

・【YYYY-MM-DD】和【HH:MM:SS】之间的【T】为固定值。 
・【HH:MM:SS】之后的【Z】为固定值，表示UTC。

"<字段代码>": {
    "value": "2012-01-11T11:30:00+08:00"
}
・需使用【±HH:MM】指定与UTC的时差
选择用户USER_SELECT

  • 获取时的应答数据（域名的用户）

"<字段代码>": {
    "type": "USER_SELECT",
    "value": [
        {
            "code": "zhou",
            "name": "zhou shijie"
        },
        {
            "code": "chen",
            "name": "chen fei"
        }
    ]
}

来宾用户的情况

"<字段代码>": {
    "type": "USER_SELECT",
    "value": [
        {
            "code": "guest/zhou@cybozu.cn",
            "name": "zhou shijie"
        },
        {
            "code": "guest/chen@cybozu.cn",
            "name": "chen fei"
        }
    ]
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": [
        {
            "code": "zhou"
        },
        {
            "code": "chen"
        }
    ]
}
类别 ※3CATEGORY

  • 获取时的应答数据

"类别": {
    "type": "CATEGORY",
    "value": [
        "category1",
        "category2"
    ]
}

  • 无法使用添加/更新时的请求数据进行添加/更新。

状态 ※3STATUS

  • 获取时的应答数据

"状态": {
    "type": "STATUS",
    "value": "未处理"
}

  • 无法使用添加/更新时的请求数据进行添加/更新。

执行者 ※3STATUS_ASSIGNEE

  • 获取时的应答数据

"执行者": {
    "type": "STATUS_ASSIGNEE",
    "value": [
        {
            "code": "zhou",
            "name": "zhou shijie"
        }
    ]
}

  • 无法使用添加/更新时的请求数据进行添加/更新。

Lookup 
※3

SINGLE_LINE_TEXT

或

NUMBER

※根据作为key的字段的类型不同而不同。
※添加/更新时，要从关联的应用中复制的字段，必须设置值为唯一。

  • 获取时的应答数据

作为key的项目为SINGLE_LINE_TEXT时
"<字段代码>": {
    "type": "SINGLE_LINE_TEXT",
    "value": "Code001"
}
作为key的项目为NUMBER 时
"<字段代码>": {
    "type": "NUMBER",
    "value": "10"
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": "Code001"
}
表格SUBTABLE

  • 获取时的应答数据

"<字段代码>": {
    "type": "SUBTABLE",
    "value": [
        {
            "id": "48290",
            "value": {
                "单行文本框_0": {
                    "type": "SINGLE_LINE_TEXT",
                    "value": "范例１"
                },
                "数值_0": {
                    "type": "NUMBER",
                    "value": "1"
                },
                "复选框_0": {
                    "type": "CHECK_BOX",
                    "value": [
                        "选项1"
                    ]
                }
            }
        },
        {
             "id": "48291",
             "value": {
                 "单行文本框__0": {
                     "type": "SINGLE_LINE_TEXT",
                     "value": "范例２"
                 },
                 "数值_0": {
                     "type": "NUMBER",
                     "value": "2"
                 },
                 "复选框_0": {
                     "type": "CHECK_BOX",
                     "value": [
                         "选项2"
                     ]
                 }
             }
        }
    ]
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": [
        {
            "id": "48291", 
            "value": {
                "单行文本框__0": {
                    "value": "范例０"
                },
                "数值_0": {
                    "value": "0"
                }
            }
        },
        {
            "value": {
                "单行文本框__0": {
                    "value": "范例１"
                },
                "数值_0": {
                    "value": "1"
                }
            }
        },
        {
            "value": {
                "单行文本框_0": {
                    "value": "范例２"
                },
                "数值_0": {
                    "value": "2"
                }
            }
        }
    ]
}

  • 请不要在同一个表格添加大量行。
    根据应用的设计，添加大量行有可能导致负载过大，影响处理速度，比如影响在打开记录或执行REST API等操作时的速度。
    关于表格的行数量对记录页面渲染速度的影响的验证结果，请参考kintone表格的行数与记录列表、详细页面的渲染速度的关系（日语）

  • 使用JavaScript进行添加/更新时：

    • 添加、更新表格时，须指定所有行的值。

    • 行按照请求数据的顺序进行排序。

    • 对表格进行添加行或更新时，需要指定字段类型。
      请参考重写字段值。

  • 使用REST API进行添加/更新时：

    • 添加、更新表格时，须指定所有行的值。

    • 如指定行的 "id"，则更新行的值。

    • 行按照请求数据的顺序进行排序。
      如果只是想重新排列行，需要准备对行的 "id"进行重新排序的请求参数。

  • 行添加/删除的描述方法

    • 通过在表格的“value”参数的值数组中添加和删除行对象，可以在表格中添加和删除行。

      例如：
      添加：record['表格']['value'].push(row);
      删除：record['表格']['value'].pop();

选择组织字段

ORGANIZATION_SELECT

  • 获取时的应答数据

"<字段代码>": {
    "type": "ORGANIZATION_SELECT",
    "value": [
        {
            "code": "beijing",
            "name": "开发部"
        },
        {
            "code": "shanghai",
            "name": "人事部"
        }
    ]
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": [
        {
            "code": "beijing"
        },
        {
            "code": "shanghai"
        }
    ]
}


选择组字段

GROUP_SELECT

  • 获取时的应答数据

"<字段代码>": {
    "type": "GROUP_SELECT",
    "value": [
        {
            "code": "project_manager",
            "name": "项目负责人"
        },
        {
            "code": "team_leader",
            "name": "组长"
        }
    ]
}

  • 添加/更新时的请求数据

"<字段代码>": {
    "value": [
        {
            "code": "project_manager"
        },
        {
            "code": "team_leader"
        }
    ]
}
关联记录列表REFERENCE_TABLE在以下 API 中使用。
组合GROUP在以下 API 中使用。
标签LABEL在以下 API 中使用。
空白栏SPACER在以下 API 中使用。
边框HR在以下 API 中使用。

  • ※1 “value”中指定的值是：kintone应用的表单设置里，“项目与顺序”中设置的值。
    另外，这些字段中的选项即使已被删除，也可通过API以及CSV来指定。

  • ※2 关于日期、时间、日期与时间、创建时间、更新时间字段的格式或时区的处理请参考日期的格式。

  • ※3 以下字段只可获取值，不能添加和更新值。

    • 记录编号

    • 记录ID

    • 版本

    • 计算

    • 类别

    • 状态

    • 执行者

    • 通过Lookup输入值的字段

  • ※4 以下字段可获取和添加值，不能更新值。

    • 创建人

    • 创建时间

    • 更新人

    • 更新时间

※5 取决于key字段的字段类型。

表格的操作

使用 JavaScript API 进行添加或更新

  • 对表格进行添加或更新时，需要指定现有的所有行的值。

  • 行的排列顺序和请求数据的顺序一样。

  • 对表格进行添加或更新时，需要指定字段类型。
    详情请参考重写字段的值 。

使用REST API 进行添加或更新

  • 对表格进行添加或更新时，请指定现有所有行的值。

  • 如果指定行id ，则对所指定的行的值进行更新。

    行的排列顺序依照请求的数据的排列顺序。

  • 如果只想改变行的排序，只要对请求数据里的行 id 的排序进行更改。

添加或删除行时

在表格的「value」这个参数值的数组中，添加或删除行的数组，即可对表格添加或删除行。

以下范例代码是使用push() 来添加行。

record['表格']['value'].push(row);

以下范例代码是使用pop() 来删除行。

record['表格']['value'].pop();

字段的值为空时

获取空字段的值时，字段的值如下所示：

字段类型value的值

  • 单行文本框

  • 多行文本框

  • 数值

  • 日期与时间

  • 链接

  • Lookup

"value": ""

  • “记录添加页面”或“记录编辑画面”中使用 JavaScript API 时

"value": undefined

  • 文本编辑框

"value": ""

  • 日期

  • 时间

"value": null

  • “记录添加页面”或“记录编辑画面”中使用 JavaScript API 时

"value": undefined

  • 下拉菜单

"value": ""

  • 使用 REST API 时

"value": null

  • “记录添加页面”或“记录编辑画面”中使用 JavaScript API 时

"value": undefined

  • 单选框

  • 使用 REST API 时

"value": null

  • 使用 JavaScript API 时

"value": ""

  • 复选框

  • 多选

  • 选择用户

  • 选择组织

  • 选择组

  • 附件

  • 表格

  • 类别

  • 执行者

"value": []

字段的值设置为空时

字段的值设置为空时，字段的值如下所示：

字段类型value的值

  • 单行文本框

  • 多行文本框

  • 文本编辑框

  • 下拉菜单

  • 日期与时间

  • 链接

  • Lookup

"value": ""

或者

"value": null
      数值

指定以下其一

"value": ""
"value": undefined
"value": null

  • 日期

  • 时间

"value": null

  • 复选框

  • 多选

  • 选择用户

  • 选择组织

  • 选择组

  • 附件

  • 表格

"value": []

  • 单选框

  • 类别

  • 执行者

无


回复(4)

  • dd000 •

    你可以参考 https://cybozudev.kf5.com/hc/kb/article/205369/

    filekey 是通过k/v1/file.json这个restapi返回获得的。

    谢谢

    引用 closer 的回复：

    请问，附件上传时的数据请求的格式那个“filekey”是怎么定义的？

  • closer •

    请问，附件上传时的数据请求的格式那个“filekey”是怎么定义的？

  • cybozu •

    谢谢你的确认，文章已经修改。

    应该是通过中国时间（CST）指定时，需按照ISO8601的格式指定如下。

      2012-01-11T11:30:00+08:00

    引用 coca 的回复：

    >>通过JST指定时，需按照ISO8601的格式指定如下。>>  2012-01-11T11:30:00+08:00JST和+8时区对应不上。

  • coca •

    >>通过JST指定时，需按照ISO8601的格式指定如下。

    >>  2012-01-11T11:30:00+08:00

    JST和+8时区对应不上。

最多浏览的文档