Agregar campos de formulario

Agrega campos a un formulario de una aplicación.

Esta API actualiza la configuración previa a la puesta en marcha.
Después de usar esta API, use la siguiente API para implementar la configuración en la aplicación activa:
Implementar la configuración de la aplicación

MétodoPOST
URLhttps://{subdomain}.kintone.com/k/v1/preview/app/form/fields.json
URL (espacio de invitado)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/app/form/fields.json
Autenticación Autenticación de contraseña , Autenticación de token de API , Autenticación de sesión
Content-Typeapplication/json

Contenido

Permisos

  • Se necesita permiso para administrar la aplicación.

Parámetros de solicitud

Los parámetros que se ignoren no se actualizarán.

Parámetro Tipo Obligatorio Descripción
app Integer o String El identificador de la aplicación.
properties Objeto Un objeto con datos de la configuración del campo.
properties.{fieldcode} Object Un objeto con datos de la configuración de campo del campo especificado en {fieldcode}.
Para actualizar un código de campo, indique el código de campo actual en {fieldcode} y escriba el nuevo código de campo en properties.{fieldcode}.code.
Para conocer los caracteres que se pueden utilizar para los códigos de campo, consulte el siguiente documento:
Caracteres válidos (External link)
properties.{fieldcode}.label String El nombre del campo.
properties.{fieldcode}.code String El código de campo del campo.
Los códigos de campo tienen las siguientes limitaciones:
  • El límite máximo de caracteres es de 128
  • No pueden existir códigos de campo duplicados
  • _ es el único símbolo que se puede utilizar
  • Los números no se pueden usar para iniciar un código de campo
properties.{fieldcode}.type Cuerda El tipo de campo.
  • GROUP: Grupo
  • GROUP_SELECT: Selección de grupos
  • CALC: Calculado
  • CHECK_BOX: Casilla de verificación
  • DATE: Fecha
  • DATETIME: Fecha y hora
  • DROP_DOWN: Menú desplegable
  • FILE: Archivo adjunto
  • LINK: Enlace
  • MULTI_LINE_TEXT: Área de texto
  • MULTI_SELECT: Opción múltiple
  • NUMBER: Número
  • ORGANIZATION_SELECT: Selección de departamentos
  • RADIO_BUTTON: Botón de opción
  • RECORD_NUMBER: Número de registro
  • REFERENCE_TABLE: Registros relacionados
  • RICH_TEXT: Texto enriquecido
  • SINGLE_LINE_TEXT: Mensaje de texto
  • SUBTABLE: Mesa
  • TIME: Hora
  • USER_SELECT: Selección de usuarios
En Campos de búsqueda, especifique en función del tipo de campo clave que se esté buscando.
properties.{fieldcode}.noLabel Booleano o cadena La opción Ocultar nombre de campo.
  • true: El nombre del campo se ocultará.
  • false: Se mostrará el nombre del campo.
Si se ignora, false se establecerá.
properties.{fieldcode}.required Booleano o cadena La opción Campo obligatorio.
  • true: El campo será un campo obligatorio.
  • false: El campo no será obligatorio.
Si se ignora, false se establecerá.
properties.{fieldcode}.unique Booleano o cadena La opción Prohibir valores duplicados.
  • true: Se prohibirán los valores duplicados.
  • false: No se prohibirán los valores duplicados.
Si se ignora, false se establecerá.
properties.{fieldcode}.maxValue Entero o cadena El número máximo de caracteres para el campo.
properties.{fieldcode}.minValue Entero o cadena El número mínimo de caracteres para el campo.
properties.{fieldcode}.maxLength Entero o cadena El número máximo de dígitos para el campo.
properties.{fieldcode}.minLength Entero o cadena El número mínimo de dígitos para el campo.
properties.{fieldcode}.defaultValue String o Array El valor predeterminado.
En el caso de los campos que pueden establecer varios valores predeterminados, especifique el valor como una matriz.
El defaultNowValue tendrá prioridad si también se especifica.
Para los campos Selección de usuario, Selección de grupo y Selección de departamento, una matriz de objetos que incluye code y type es necesario.
properties.{fieldcode}.defaultValue[].type String Condicional Tipo del valor predeterminado del campo Selección de usuario, Selección de grupo o Selección de departamento.
Obligatorio, si se establece el parámetro defaultValue parámetro.
  • USER: Usuario
  • GROUP: Grupo
  • ORGANIZATION: Departamento
  • FUNCTION: Función
properties.{fieldcode}.defaultValue[].code String Condicional El código para el valor predeterminado de los campos Selección de usuario, Selección de grupo o Selección de departamento.
Obligatorio, si se establece el parámetro defaultValue parámetro.
  • En Campo de selección de usuario, se puede especificar uno de los siguientes valores:
    • El código de usuario (nombre de inicio de sesión).
    • El código de grupo.
    • El código del departamento.
    • Nombre de la función LOGINUSER()
    Los departamentos no se pueden especificar en las aplicaciones de espacio de invitados.
  • En Campo de selección de grupo, se puede especificar un código de grupo.
  • Para el campo de selección Departamento, se puede especificar uno de los siguientes valores:
    • El código del departamento.
    • Nombre de la función PRIMARY_ORGANIZATION()
No se puede especificar el Usuario/Grupo/Departamento eliminado o inactivo.
properties.{fieldcode}.defaultNowValue Booleano o cadena La opción Por defecto a la fecha de creación del registro.
  • true: La fecha de creación del registro se utilizará como valor predeterminado.
  • false: La fecha de creación del registro no se utilizará como valor predeterminado.
Si se ignora, false se establecerá.
properties.{fieldcode}.options Object Condicional Un objeto que incluye datos de las opciones del campo.
Obligatorio para los campos que permiten selecciones, como el botón Opción.
properties.{fieldcode}.options.{optionname} Object Condicional Un objeto con datos de la configuración de las opciones.
Especifique los nombres de opción actuales para este parámetro. Las opciones que no estén especificadas se eliminarán.
Obligatorio, si se establece el parámetro properties.{fieldcode}.options parámetro.
Si se especifica una nueva opción para este parámetro, se tratará como una nueva opción.
properties.{fieldcode}.options.{optionname}.label String Condicional El nombre para mostrar de la opción.
Especifique el mismo valor que {optionname}.
Obligatorio, si se establece el parámetro properties.{fieldcode}.options parámetro.
properties.{fieldcode}.options.{optionname}.index Entero o cadena Condicional El orden de visualización (ascendente) de la opción, cuando aparece con las otras opciones.
Obligatorio, si se establece el parámetro properties.{fieldcode}.options parámetro.
properties.{fieldcode}.align String El diseño de las opciones.
  • HORIZONTAL: Las opciones se enumerarán horizontalmente.
  • VERTICAL: Las opciones se enumerarán verticalmente.
Si se ignora, HORIZONTAL se establecerá.
properties.{fieldcode}.expression String Condicional Expresión de fórmula utilizada en el campo.
Obligatorio en el campo Calculado.
properties.{fieldcode}.hideExpression Booleano o cadena La configuración de Ocultar fórmula para el campo.
  • true: La fórmula estará oculta.
  • false: Se mostrará la fórmula.
Si se ignora, false se establecerá.
properties.{fieldcode}.digit Booleano o cadena La opción Usar separadores de miles.
  • true: Se mostrarán separadores de miles para el número.
  • false: Los separadores de miles no se mostrarán para el número.
Si se ignora, false se establecerá.
properties.{fieldcode}.thumbnailSize Entero o cadena El tamaño de la miniatura de la imagen en píxeles.
Especifique una de las siguientes opciones:
  • 50
  • 150
  • 250
  • 500
properties.{fieldcode}.protocol String Condicional La configuración del tipo de vínculo para el campo.
Obligatorio en el campo Vínculo.
  • WEB: URL
  • CALL: Número de teléfono
  • MAIL: Dirección de correo electrónico
properties.{fieldcode}.format String El formato de visualización de los campos con cálculos:
  • NUMBER: Número (p. ej.: 1000)
  • NUMBER_DIGIT: Número con separador de miles (p. ej.: 1,000)
  • DATETIME: Fecha y hora (p. ej.: 06 de agosto de 2012 14:03)
  • DATE: Fecha (p. ej.: 06 de agosto de 2012)
  • TIME: Tiempo (p. ej.: 14:03)
  • HOUR_MINUTE: Horas y minutos (p. ej.: 29 horas 47 minutos)
  • DAY_HOUR_MINUTE: Días y horas y minutos (p. ej.: 1 día 5 horas 47 minutos)
Si se ignora, NUMBER se establecerá.
properties.{fieldcode}.displayScale Entero o cadena El número de decimales que se mostrarán para el campo.
properties.{fieldcode}.unit String La configuración de moneda del campo.
properties.{fieldcode}.unitPosition String La posición de visualización de la moneda.
  • BEFORE: La moneda se mostrará antes del valor del campo.
  • AFTER: La moneda se mostrará después del valor del campo.
Si se ignora, BEFORE se establecerá.
properties.{fieldcode}.entities Matriz de objetos Matriz que enumera los usuarios preestablecidos para los campos Selección de usuario, Selección de grupo y Selección de departamento.
properties.{fieldcode}.entities[].code Cuerda Condicional El código del usuario/grupo/departamento.
Obligatorio si se establece el parámetro entities.
  • En Campo de selección de usuario, se puede especificar uno de los siguientes valores:
    • El código de usuario (nombre de inicio de sesión).
    • El código de grupo.
    • El código del departamento.
    Los departamentos no se pueden especificar en las aplicaciones de espacio de invitados.
  • En Campo de selección de grupo, se puede especificar un código de grupo.
  • Para el campo de selección de departamento, se puede especificar un código de departamento.
No se puede especificar el Usuario/Grupo/Departamento eliminado o inactivo.
properties.{fieldcode}.entities[].type Cuerda Condicional El tipo de entidad.
  • USER: Usuario
  • GROUP: Grupo
  • ORGANIZATION: Departamento

Obligatorio, si se establece el parámetro entities parámetro.
properties.{fieldcode}.referenceTable Object Condicional Objeto que contiene la configuración del campo Registros relacionados.
Obligatorio al agregar un campo Registros relacionados.
properties.{fieldcode}.referenceTable.relatedApp Object Condicional Un objeto que contiene datos de la configuración Aplicación de origen de datos.
Si se especifica este parámetro, todas las configuraciones de este campo Registros relacionados, excepto la configuración "Aplicación de origen de datos", volverán a la configuración predeterminada.
Obligatorio, si se establece el parámetro referenceTable parámetro.
properties.{fieldcode}.referenceTable.relatedApp.app Entero o cadena Condicional El identificador de aplicación de la aplicación de origen de datos.
Si el relatedApp se especifica, ya sea este parámetro o properties.{fieldcode}.referenceTable.relatedApp.code será necesario.
Si se establecen ambos parámetros, properties.{fieldcode}.referenceTable.relatedApp.code tendrá prioridad.
properties.{fieldcode}.referenceTable.relatedApp.code Cuerda Condicional El código de la aplicación de origen de datos.
Si el relatedApp se especifica, ya sea este parámetro o properties.{fieldcode}.referenceTable.relatedApp.app será necesario.
Si se establecen ambos parámetros, properties.{fieldcode}.referenceTable.relatedApp.code tendrá prioridad.
properties.{fieldcode}.referenceTable.condition Object Condicional Un objeto que contiene datos de la configuración Criterios de captura.
Obligatorio, si se establece el parámetro referenceTable parámetro.
properties.{fieldcode}.referenceTable.condition.field String Condicional El código de campo del campo seleccionado para Campo en esta aplicación.
Obligatorio, si se establece el parámetro referenceTable parámetro.
properties.{fieldcode}.referenceTable.condition.relatedField String Condicional El código de campo del campo seleccionado para Campo en la aplicación de origen de datos.
Obligatorio, si se establece el parámetro referenceTable parámetro.
properties.{fieldcode}.referenceTable.filterCond String La configuración Filtro, en un formato de consulta.
Para obtener más datos sobre los formatos de consulta, consulte el siguiente documento:
Cadena de consulta
properties.{fieldcode}.referenceTable.displayFields Matriz de cadenas Condicional Una lista de códigos de campo de los campos especificados en la configuración Campos de la aplicación de origen de datos para mostrar.
Obligatorio, si se establece el parámetro referenceTable parámetro.
properties.{fieldcode}.referenceTable.sort String Condicional La configuración Orden de visualización, en formato de consulta.
Para obtener más datos sobre los formatos de consulta, consulte el siguiente documento:
Cadena de consulta
properties.{fieldcode}.referenceTable.size Integer o String La configuración Número máximo de registros que se mostrarán a la vez.
Especifique una de las siguientes opciones:
  • 1
  • 3
  • 5
  • 10
  • 20
  • 30
  • 40
  • 50
Si se ignora, 5 se establecerá.
properties.{fieldcode}.lookup Object Objeto que contiene la configuración del campo Búsqueda.
Obligatorio si se agrega un campo de búsqueda.
properties.{fieldcode}.lookup.relatedApp Objeto Condicional Un objeto que contiene la configuración de la aplicación relacionada de la Búsqueda campo.
Obligatorio, si se establece el parámetro lookup parámetro.
properties.{fieldcode}.lookup.relatedApp.app Entero o cadena Condicional El ID de aplicación de la aplicación relacionada de la Búsqueda campo.
Este parámetro o el parámetro lookup.relatedApp.code es necesario si se establece el parámetro lookup parámetro. Si se establecen ambos parámetros, el lookup.relatedApp.code tiene prioridad.
properties.{fieldcode}.lookup.relatedApp.code Cuerda Condicional El código de la aplicación de la aplicación relacionada de la Búsqueda campo. Este parámetro o el parámetro lookup.relatedApp.app es necesario si se establece el parámetro lookup parámetro. Si se establecen ambos parámetros, este parámetro tiene prioridad.
properties.{fieldcode}.lookup.relatedKeyField Cuerda Condicional El código de campo del campo Búsqueda.
Obligatorio, si se establece el parámetro lookup parámetro.
properties.{fieldcode}.lookup.fieldMappings Matriz de objetos Una lista de conjuntos de datos para la configuración Asignaciones de campos.
properties.{fieldcode}.lookup.fieldMappings[].field Cuerda Condicional El código de campo del campo establecido para el punto de conexión de asignación.
Obligatorio, si se establece el parámetro lookup.fieldMappings[] parámetro.
properties.{fieldcode}.lookup.fieldMappings[].relatedField Cuerda Condicional El código de campo del campo establecido para el origen de asignación.
Obligatorio, si se establece el parámetro lookup.fieldMappings[] parámetro.
properties.{fieldcode}.lookup.lookupPickerFields Matriz de cadenas Una lista de códigos de campo de campos establecidos para la configuración Campos mostrados en el selector de búsqueda.
properties.{fieldcode}.lookup.filterCond String La consulta de filtro predeterminada para la configuración Filtro.
Especifique en formato de consulta. Para obtener más datos sobre los formatos de consulta, consulte el siguiente documento:
Cadena de consulta
properties.{fieldcode}.lookup.sort String El criterio de clasificación predeterminado para la configuración Filtro.
Especifique en formato de consulta. Para obtener más datos sobre los formatos de consulta, consulte el siguiente documento:
Cadena de consulta
properties.{fieldcode}.openGroup Booleano o cadena La opción Mostrar campos de este grupo.
  • true: El campo Grupo se mostrará abierto de forma predeterminada.
  • false: El campo Grupo se mostrará cerrado de forma predeterminada.
Si se ignora, false se establecerá.
properties.{fieldcode}.fields Object Objeto que contiene datos de campos de una tabla.
Los parámetros de este objeto son los mismos que los de la función properties parámetro.
Obligatorio al agregar un nuevo gráfico.
revision Entero o cadena Especifique el número de revisión de la configuración que se implementará.
Se producirá un error en la solicitud si el número de revisión no es la última revisión.
La revisión no se comprobará si se ignora este parámetro o si se especifica -1.

Solicitud de muestra

JavaScript using kintone.api()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
var body = {
  'app': 1,
  'properties': {
    'Text__single_line_1': {
      'type': 'SINGLE_LINE_TEXT',
      'code': 'Text__single_line_1',
      'label': 'Text (single-line)',
      'noLabel': false,
      'required': true,
      'unique': true,
      'maxLength': 64,
      'minLength': 0,
      'defaultValue': '',
      'expression': '',
      'hideExpression': false
    },
    'Number': {
      'type': 'NUMBER',
      'code': 'Number',
      'label': 'Number',
      'noLabel': true,
      'required': false,
      'unique': false,
      'maxValue': 64,
      'minValue': 0,
      'defaultValue': '12345',
      'digit': true,
      'displayScale': '',
      'expression': '',
      'unit': '$',
      'unitPosition': 'BEFORE'
    }
  }
};

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

XMLHttpRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
var body = {
  'app': 1,
  'properties': {
    'Text__single_line_1': {
      'type': 'SINGLE_LINE_TEXT',
      'code': 'Text__single_line_1',
      'label': 'Text (single-line)',
      'noLabel': false,
      'required': true,
      'unique': true,
      'maxLength': 64,
      'minLength': 0,
      'defaultValue': '',
      'expression': '',
      'hideExpression': false
    },
    'Number': {
      'type': 'NUMBER',
      'code': 'Number',
      'label': 'Number',
      'noLabel': true,
      'required': false,
      'unique': false,
      'maxValue': 64,
      'minValue': 0,
      'defaultValue': '12345',
      'digit': true,
      'displayScale': '',
      'expression': '',
      'unit': '$',
      'unitPosition': 'BEFORE'
    }
  },
  // CSRF TOKEN: used for all APIs that have an HTTP method of POST, PUT and DELETE on Kintone.
  '__REQUEST_TOKEN__': kintone.getRequestToken()
};

var url = 'https://{subdomain}.kintone.com/k/v1/preview/app/form/fields.json';
var xhr = new XMLHttpRequest();
xhr.open('POST', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send(JSON.stringify(body));

Parámetros de respuesta

Parámetro Tipo Descripción
revision String El número de revisión de la configuración de la aplicación.

Ejemplo de respuesta

1
2
3
{
  "revision": "1"
}

Limitaciones

No se pueden agregar los códigos de campo de los siguientes campos:

  • Status
  • Cesionario
  • Categoría