获取表单的设置

aki发表于:2016年12月22日 13:51:52更新于:2024年09月18日 10:33:46

获取应用的表单的设置。
获取表单的设置时,根据如下两个操作的不同,要使用的API也不一样。

获取字段的列表

URI

获取正式环境的设置时所使用的URI跟获取测试环境设置时不一样。

获取正式环境的设置时

https://(子域名).cybozu.cn/k/v1/app/form/fields.json

来宾空间内的应用:https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/app/form/fields.json

获取测试环境的设置时

https://(子域名).cybozu.cn/k/v1/preview/app/form/fields.json

来宾空间内的应用:https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/preview/app/form/fields.json

HTTP 方法

GET

必要的访问权限

获取正式环境的设置时,需要以下至少其中一个访问权限。

  • 应用的记录查看权限

  • 应用的记录添加权限

  • 应用的管理权限

获取测试环境的设置时

  • 应用的管理权限

※从2020年2月版本开始可以使用API令牌来执行此API。

请求参数

参数名称要指定的值必须说明
app数值或字符串必须指定应用的ID。
lang字符串
给字段或选项的名称设置了多语言的情况,需要指定要获取的名称的语言。
  • 获取日语的名称时:ja

  • 获取英语的名称时:en

  • 获取中文的名称时:zh

  • 登录用户的语言设置:user
    ※当登录用户的语言设置为“遵循Web浏览器的设置”时,如果头部中指定“Accept-Language”,则使用该设置。如果不指定“Accept-Language”,则使用cybozu.cn系统管理的“本地化设置”中的语言设置。

  • 获取默认的名称时:default

省略时,获取默认名称。

请求的范例

要发送的请求根据参数发送方式的不同而不同。以下是指定参数“app”和“lang”的请求的例子。

URL中包含参数时

GET /k/v1/app/form/fields.json?app=8&lang=zh HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

请求正文中包含参数时
头部

GET /k/v1/app/form/fields.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json

正文

{
  "app": 1,
  "lang": "default"
}

应答

参数

参数名称值的类型说明
properties对象字段设置的对象。
properties.(字段代码).label字符串字段名称。
properties.(字段代码).code字符串字段代码。
properties.(字段代码).type字符串字段的类型。
  • CALC:计算

  • CATEGORY:类别

  • CHECK_BOX:复选框

  • CREATED_TIME:创建时间

  • CREATOR:创建人

  • DATE:日期

  • DATETIME:日期与时间

  • DROP_DOWN:下拉菜单

  • FILE:附件

  • GROUP:组

  • GROUP_SELECT:选择组

  • LINK:链接

  • MODIFIER:更新人

  • MULTI_LINE_TEXT:多行文本框

  • MULTI_SELECT:多选

  • NUMBER:数值或lookup *

  • ORGANIZATION_SELECT:选择组织

  • RADIO_BUTTON:单选框

  • RECORD_NUMBER:记录编号

  • REFERENCE_TABLE:关联记录列表

  • RICH_TEXT:文本编辑框

  • SINGLE_LINE_TEXT:单行文本框或lookup *

  • STATUS:流程管理功能的状态

  • STATUS_ASSIGNEE:流程管理功能的执行者

  • SUBTABLE:表格

  • TIME:时间

  • UPDATED_TIME:更新时间

  • USER_SELECT:选择用户

*: lookup字段被视为与所参照的字段相同类型。
properties.(字段代码).noLabel布尔值设置是否隐藏字段名称。
  • true:隐藏

  • false:显示

properties.(字段代码).required布尔值设置是否必填。
  • true:必填

  • false:任意

properties.(字段代码).unique布尔值设置是否值为唯一。
  • true:值为唯一

  • false:允许重复

properties.(字段代码).maxValue字符串最大值。未设置时为空。
properties.(字段代码).minValue字符串最小值。未设置时为空。
properties.(字段代码).maxLength字符串最大字符数。未设置时为空。
properties.(字段代码).minLength字符串最小字符数。未设置时为空。
properties.(字段代码).defaultValue字符串或数组初始值。可设置多个初始值的字段,将以数组的形式返回。
properties.(字段代码).defaultNowValue布尔值设置是否将添加记录时的日期作为初始值。
  • true:将添加记录时的日期作为初始值

  • false:不将添加记录时的日期作为初始值

properties.(字段代码).options对象用于存放选项设置的对象。
properties.(字段代码).options.(选项名).label字符串选项名称。
properties.(字段代码).options.(选项名).index字符串选项的顺序(升序)。
properties.(字段代码).align字符串选项的排列。
  • HORIZONTAL:横

  • VERTICAL:纵

properties.(字段代码).expression字符串自动计算公式。未设置时为空。
properties.(字段代码).hideExpression布尔值设置是否隐藏计算字段的计算公式。
  • true:隐藏

  • false:显示

properties.(字段代码).digit布尔值设置是否显示数值的千位分隔符。
  • true:显示千位分隔符

  • false:不显示千位分隔符

properties.(字段代码).thumbnailSize字符串图片的缩略图大小(单位是像素)。
properties.(字段代码).protocol字符串链接的种类。
  • WEB:Web网站

  • CALL:电话号码

  • MAIL:邮箱地址

properties.(字段代码).format字符串计算字段的显示形式。
  • NUMBER:数值(例:1000)

  • NUMBER_DIGIT:数值(例:1,000)

  • DATETIME:日期与时间(例:2012-08-06 2:03)

  • DATE:日期(例:2012-08-06)

  • TIME:时间(例:2:03)

  • HOUR_MINUTE:小时分(例:26小时3分)

  • DAY_HOUR_MINUTE:天小时分(例:1日2小时3 分)

properties.(字段代码).displayScale字符串小数点以下显示位数。未设置时为空。
properties.(字段代码).unit字符串单位符号。
properties.(字段代码).unitPosition字符串单位符号的显示位置。
  • BEFORE:放在字段前

  • AFTER:放在字段后

properties.(字段代码).entities数组用于存放选项中的用户的数组。未设置时为空。
properties.(字段代码).entities[].code字符串选项中的用户、组或组织的代码。
properties.(字段代码).entities[].type字符串值的种类。
  • USER:用户

  • GROUP:组

  • ORGANIZATION:组织

properties.(字段代码).referenceTable对象用于存放关联记录列表字段的设置的对象。参照的应用没有访问权限时为null。
properties.(字段代码).referenceTable.relatedApp对象用于存放“要引用的应用”的设置的对象。
properties.(字段代码).referenceTable.relatedApp.app字符串“要引用的应用”中指定的应用ID。
properties.(字段代码).referenceTable.relatedApp.code字符串“要引用的应用”中指定的应用的代码。应用代码未设置时为空。
properties.(字段代码).referenceTable.condition对象用于存放“设置要显示的记录”中的设置的对象。
properties.(字段代码).referenceTable.condition.field字符串“设置要显示的记录”中指定的、与关联记录列表字段同一应用的字段的代码。
properties.(字段代码).referenceTable.condition.relatedField字符串在“设置要显示的记录”中指定的、关联记录列表字段所参照的应用内的字段的代码。
properties.(字段代码).referenceTable.fliterCond字符串“更多筛选条件”的设置。用查询形式显示。查询形式请参考以下页面。
批量获取记录(在查询中指定条件)
properties.(字段代码).referenceTable.displayFields数组用于存放“要显示的字段”中指定的字段的代码的数组。
properties.(字段代码).referenceTable.sort字符串设置记录的排序。用查询形式显示。关于查询形式,请参照以下页面。
批量获取记录(在查询中指定条件)
properties.(字段代码).referenceTable.size字符串一次最多可显示的最大记录数。
properties.(字段代码).lookup对象用于存放lookup设置的对象。无参照的应用的访问权限时为null。
properties.(字段代码).lookup.relatedApp对象用于存放“要关联的应用”的设置的对象。
properties.(字段代码).lookup.relatedApp.app字符串要关联的应用的ID。
properties.(字段代码).lookup.relatedApp.code字符串要关联的应用的代码。应用代码未设置时为空。
properties.(字段代码).lookup.relatedKeyField字符串“复制来源字段”中指定的字段的代码。
properties.(字段代码).lookup.fieldMappings数组用于存放“其他要复制的字段”的设置的数组。未设置时为空。
properties.(字段代码).lookup.fieldMappings[].field字符串“其他要复制的字段”的复制到的字段中指定的字段的代码。
properties.(字段代码).lookup.fieldMappings[].relatedField字符串“其他要复制的字段”的复制来源字段中指定的字段的代码。
properties.(字段代码).lookup.lookupPickerFields数组用于存放“要在搜选列表中显示的字段”中设置的字段的字段代码的数组。未设置时为空。
properties.(字段代码).lookup.filterCond字符串筛选的初始设置。用查询形式显示。关于查询形式,请参照以下页面。
批量获取记录(在查询中指定条件)
properties.(字段代码).lookup.sort字符串排序的初始设置。用查询形式显示。关于查询形式,请参照以下页面。
批量获取记录(在查询中指定条件)
properties.(字段代码).openGroup布尔值设置是否显示组合内字段。
  • true:显示

  • false:隐藏

properties.(字段代码).fields对象用于存放表格内字段的对象。对象的参数和“properties”参数一样。
properties.(字段代码).enabled布尔值

设置是否启用功能。这个参数仅可用于状态字段和类别字段。

  • 状态字段

    • true:启用流程管理功能

    • false:禁用流程管理功能

  • 类别

    • true:启用类别功能

    • false:禁用类别功能

revision字符串应用的设定的修订号。 

应答的范例

{
    "properties": {
        "单行文本框": {
            "type": "SINGLE_LINE_TEXT",
            "code": "单行文本框",
            "label": "单行文本框",
            "noLabel": false,
            "required": true,
            "unique": true,
            "maxLength": "64",
            "minLength": "0",
            "defaultValue": "",
            "expression": "",
            "hideExpression": false
        },
        "数值": {
            "type": "NUMBER",
            "code": "数值",
            "label": "数值",
            "noLabel": true,
            "required": false,
            "unique": false,
            "maxValue": "64",
            "minValue": "0",
            "defaultValue": "12345",
            "expression": "",
            "digit": true,
            "displayScale": "",
            "unit": "$",
            "unitPosition": "BEFORE"
        },
        "单选框": {
            "type": "RADIO_BUTTON",
            "code": "单选框",
            "label": "单选框",
            "noLabel": false,
            "required": true,
            "defaultValue": "sample2",
            "options": {
                "sample1": {
                    "label": "sample1",
                    "index": "0"
                },
                "sample2": {
                    "label": "sample2",
                    "index": "1"
                },
                "sample3": {
                    "label": "sample3",
                    "index": "2"
                }
            },
            "align": "horizontal"
        },
        "复选框": {
            "type": "CHECK_BOX",
            "code": "复选框",
            "label": "复选框",
            "noLabel": false,
            "required": false,
            "defaultValue": [
                "sample1",
                "sample3"
            ],
            "options": {
                "sample1": {
                    "label": "sample1",
                    "index": "0"
                },
                "sample2": {
                    "label": "sample2",
                    "index": "2"
                },
                "sample3": {
                    "label": "sample3",
                    "index": "1"
                }
            },
            "align": "horizontal"
        },
        "日期": {
            "type": "DATE",
            "code": "日期",
            "label": "日期",
            "noLabel": false,
            "required": false,
            "unique": true,
            "defaultValue": "",
            "defaultNowValue": true
        },
        "日期与时间": {    
            "type": "DATETIME",    
            "code": "日期与时间",    
            "label": "日期与时间",    
            "noLabel": false,    
            "required": false,    
            "unique": false,    
            "defaultValue": "2012-07-19T00:00:00.000Z",    
            "defaultNowValue": false    
        },    
        "附件": {
            "type": "FILE",
            "code": "附件",
            "label": "附件",
            "noLabel": true,
            "required": false,
            "thumbnailSize": "150"
        },
        "链接": {
            "type": "LINK",
            "code": "链接",
            "label": "链接",
            "noLabel": true,
            "required": false,
            "unique": false,
            "defaultValue": "http://hoge.xxx",
            "maxLength": "64",
            "minLength": "0",
            "protocol": "WEB"
        },
        "选择用户": {
            "type": "USER_SELECT",
            "code": "选择用户",
            "label": "选择用户",
            "noLabel": true,
            "required": false,
            "defaultValue": [
                {
                    "code": "user1",
                    "type": "USER"
                },
                {
                    "code": "group1",
                    "type": "GROUP"
                },
                {
                    "code": "org1",
                    "type": "ORGANIZATION"
                },
                {
                    "code": "LOGINUSER()",
                    "type": "FUNCTION"
                }
            ],
            "entities": [
                {
                    "code": "user1",
                    "type": "USER"
                },
                {
                    "code": "group1",
                    "type": "GROUP"
                }
            ]
        },
        "关联记录列表": {
            "type": "REFERENCE_TABLE",
            "code": "关联记录列表",
            "label": "关联记录列表",
            "noLabel": true,
            "referenceTable": {
                "relatedApp": {
                    "app": "3",
                    "code": "参照的应用"
                },
                "condition": {
                    "field": "当前应用的字段",
                    "relatedField": "要参照的应用的字段"
                },
                "filterCond": "数值 > 10 and 数值2 > 20",
                "displayFields": [
                    "要显示的字段1",
                    "要显示的字段2"
                ],
                "sort": "排序字段1 desc, 排序字段2 asc",
                "size": "5"
            }
        },
        "lookup": {
            "type": "SINGLE_LINE_TEXT",
            "code": "lookup",
            "label": "lookup",
            "noLabel": true,
            "required": false,
            "lookup": {
                "relatedApp": {
                    "app": "100",
                    "code": "复制来源应用的应用代码"
                },
                "relatedKeyField": "复制来源字段",
                "fieldMappings": [
                    {
                        "field": "要复制到的字段",
                        "relatedField": "复制来源字段"
                    }
                ],
                "lookupPickerFields": [
                    "选择lookup时显示的字段1"
                ],
                "filterCond": "数值 > 10 and 数值2 > 20",
                "sort": "排序字段1 desc, 排序字段2 asc"
            }
        },
        "组": {
            "type": "GROUP",
            "code": "组",
            "label": "组",
            "noLabel": true,
            "openGroup": true
        },
        "表格": {
            "type": "SUBTABLE",
            "code": "表格",
            "label": "表格",
            "noLabel": false,
            "fields": {
                "单行文本框_表格": {
                    "type": "SINGLE_LINE_TEXT",
                    "code": "单行文本框_表格",
                    "label": "单行文本框_表格",
                    "noLabel": false,    
                    "required": true,    
                    "unique": false,    
                    "maxLength": "64",    
                    "minLength": "0",    
                    "defaultValue": "",    
                    "expression": "",    
                    "hideExpression": false    
                }    
            }    
        },    
        "状态": {
            "type": "STATUS",
            "code": "状态",
            "label": "状态",
            "enabled": "true"
        },
        "执行者": {
            "type": "STATUS_ASSIGNEE",
            "code": "执行者",
            "label": "执行者",
            "enabled": "true"
        },
        "类别": {
            "type": "CATEGORY",
            "code": "类别",
            "label": "类别",
            "enabled": "true"
        }
    },
    "revision": "2"
}

JavaScript 范例

使用API请求发送 kintone REST API 请求

var body = {
    "app": 1
};

kintone.api(kintone.api.url('/k/v1/app/form/fields', true), 'GET', body, function(resp) {
    // success
    console.log(resp);
}, function(error) {
    // error
    console.log(error);
});

使用 XMLHttpRequest 请求

var url = 'https://{subdomain}.cybozu.cn/k/v1/app/form/fields.json?app=1';
 
var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
    if (xhr.status === 200) {
        // success
        console.log(JSON.parse(xhr.responseText));
    } else {
        // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send();


获取表单的布局

URI

获取正式环境的设置时所使用的URI跟获取测试环境设置时不一样。

获取正式环境的设置时

https://(子域名).cybozu.cn/k/v1/app/form/layout.json

来宾空间内的应用:https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/app/form/layout.json

获取测试环境的设置时

https://(子域名).cybozu.cn/k/v1/preview/app/form/layout.json

来宾空间内的应用:https://(子域名).cybozu.cn/k/guest/(空间的ID)/v1/preview/app/form/layout.json

HTTP 方法

GET

必要的访问权限

获取正式环境的设置时,需要以下至少其中一个访问权限。

  • 应用的记录查看权限

  • 应用的记录添加权限

获取测试环境的设置时

  • 应用的管理权限

※从2020年2月版本开始可以使用API令牌来执行此API。

请求参数

参数名称要指定的值必须说明
app数值或字符串必须指定应用的ID。

请求的范例

要发送的请求根据参数的发送方式不同而不同。以下是指定参数“app”时的请求范例。

URL中包含参数时

GET /k/v1/app/form/layout.json?app=8 HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

请求正文中包含参数时
头部

GET /k/v1/app/form/layout.json HTTP/1.1
Host: example.cybozu.cn:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json

正文

{
  "app": "8"
}

应答

参数

参数名称值的类型说明
layout数组用于存放表单各行的布局的数组。
layout[].type字符串行的种类。
  • ROW:标准行。

  • SUBTABLE:表格。

  • GROUP:组合字段。

layout[].code字符串表格或组合的代码。如果都不是这两者的话,该参数不输出。
layout[].fields数组用于存放行里的字段的数组。
layout[].fields[].type字符串字段的类型。
  • CALC:计算

  • CHECK_BOX:复选框

  • CREATED_TIME:创建时间

  • CREATOR:创建人

  • DATE:日期

  • DATETIME:日期与时间

  • DROP_DOWN:下拉菜单

  • FILE:附件

  • GROUP_SELECT:选择组

  • HR:边框

  • LABEL:标签

  • LINK:链接

  • MODIFIER:更新人

  • MULTI_LINE_TEXT:多行文本框

  • MULTI_SELECT:多选

  • NUMBER:数值或lookup *

  • ORGANIZATION_SELECT:选择组织

  • RADIO_BUTTON:单选框

  • RECORD_NUMBER:记录编号

  • REFERENCE_TABLE:关联记录列表

  • RICH_TEXT:文本编辑框

  • SINGLE_LINE_TEXT:单行文本框或lookup *

  • SPACER:空白栏

  • TIME:时间

  • UPDATED_TIME:更新时间

  • USER_SELECT:选择用户

*: lookup字段被视为与所参照的字段相同类型。
layout[].fields[].code字符串字段代码。
layout[].fields[].label字符串标签名。作为标签字段输出。
layout[].fields[].elementId字符串元素ID。作为空白栏字段输出。
layout[].fields[].size对象

用于存放字段大小的对象

※此处获取的是PC版的字段大小。移动端上显示的字段大小不可获取。

layout[].fields[].size.width字符串以像素为单位的字段宽度。
layout[].fields[].size.heigit字符串包含字段名称在内的、以像素为单位的字段长度。
layout[].fields[].size.innerHeight字符串除了字段名称之外的、以像素为单位的字段长度。
layout[].layout数组用于存放组合内的字段的布局的数组。
revision字符串应用的设定的修订号。

应答的范例

{
    "revision": "2",
    "layout": [
        {
            "type": "ROW",
            "fields": [
                {
                    "type": "SINGLE_LINE_TEXT",
                    "code": "单行文本框",
                    "size": {
                        "width": "200"
                    }
                },
                {
                    "type": "MULTI_LINE_TEXT",
                    "code": "多行文本框",
                    "size": {
                        "width": "200",
                        "innerHeight": "100"
                    }
                },
                {
                    "type": "LABEL",
                    "label": "label",
                    "size": {
                        "width": "200"
                    }
                },
                {
                    "type": "SPACER",
                    "elementId": "spacer",
                    "size": {
                        "width": "200",
                        "height": "100"
                    }
                },
                {
                    "type": "HR",
                    "size": {
                        "width": "200"
                    }
                }
            ]
        },
        {
            "type": "SUBTABLE",
            "code": "表格",
            "fields": [
                {
                    "type": "NUMBER",
                    "code": "数值",
                    "size": {
                        "width": "200"
                    }
                }
            ]
        },
        {
            "type": "GROUP",
            "code": "组",
            "layout": [
                {
                    "type": "ROW",
                    "fields": [
                        {
                            "type": "NUMBER",
                            "code": "数值2",
                            "size": {
                                "width": "200"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

JavaScript 范例

使用API请求发送 kintone REST API 请求

var body = {
    "app": 1
};

kintone.api(kintone.api.url('/k/v1/app/form/layout', true), 'GET', body, function(resp) {
    // success
    console.log(resp);
}, function(error) {
    // error
    console.log(error);
});

使用 XMLHttpRequest 请求

var url = 'https://{subdomain}.cybozu.cn/k/v1/app/form/layout.json?app=1';
 
var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
    if (xhr.status === 200) {
        // success
        console.log(JSON.parse(xhr.responseText));
    } else {
        // error
        console.log(JSON.parse(xhr.responseText));
    }
};
xhr.send();