kintone JavaScript编码指南

cybozu发表于:2016年08月23日 18:38:45更新于:2023年03月01日 16:32:04

Index

概要

使用kintone的“JavaScript / CSS自定义”功能,可以对kintone的各个功能以及应用的操作、页面进行自定义。
这个页面主要对使用Javascript进行kintone自定义过程中需要注意的地方进行说明。

如何使用JavaScript来进行kintone和应用的自定义设置,请参照kintone的用户帮助手册。

编码注意点

文字编码

请使用UTF-8无BOM格式编码。

变量和命名空间

为了kintone能正常运行,请不要覆盖替换既存的全局对象。
不推荐使用全局变量,建议在即时函数内定义变量。

如果不可避免的需要在不同块之间使用同一个变量,请使用以下方法,以防止污染全局。

不使用全局变量

(() => {
  // 不推荐的例子
  globalVariable = 1; // 将变量声明为全局变量
  // 推荐的例子
  const localVariable = 1; // 将变量声明成即时函数内的本地变量
})();

对于既存的全局对象,不覆盖现有属性或向其添加新属性,也不对其进行参照。

(() => {
  // 不推荐的例子
  cybozu.foo = 'bar'; // 对既存的全局对象添加新属性或覆盖现有属性
  const foo = cybozu.foo; // 参照了既存的的全局对象
  // 推荐的例子
  myNameSpace = {}; // 使用空间对象
  myNameSpace.foo = 'bar';
})();

关于在kintone上使用的id和class属性

需要注意的是:kintone上各个元素绑定的id和class属性,可能会变更,一般事先不会有预告通知。另外DOM结构也有可能变更。
在自定义的时候,请不要去更改id和class属性的值或DOM结构。

关于使用 JavaScript API 获取元素的自定义

由于元素的外观可能受 kintone 的 CSS 的影响,因此不能保证其外观不会改变。
有关可以获取元素的 API 的信息,请参阅 JavaScript API 列表中的“获取元素”。 

URL获取

为确保自定义程序在以后的kintone版本也能正常运行,在获取kintone的URL的时候,请使用kintone.api.url()或者kintone.api.urlForGet()方法。

无法使用JavaScript API进行自定义的地方

以下粘贴到空间的正文或者主题的正文中的部分,无法使用JavaScript API进行自定义。

  • 应用记录列表

  • 图表

在多个的浏览器上进行确认

在确认自定义程序是否能正常运行时,建议在多个浏览器上进行确认。

根据浏览器的种类和版本的不同,可能出现无法正常运行的情况。

如上传的自定义程序存在问题,有可能会导致kintone无法正常运行。

因此请对自定义程序进行充分的测试。

使用kintone REST API时的注意事项

如果自定义程序存在问题,可能会导致kintone性能下降,甚至是出现无法使用的情况。

避免在短时间内发送大量请求

如果上传了可自动发送大量请求的程序,或者是可同时并列发送多个请求的程序,会导致服务性能下降,例如应答速度下降等。

对于会给服务器带来负载或者消耗大量资源的请求,也可以会对其进行访问限制。

设置合适的用户代理

为了能够判断是从哪个服务或者工具发来的请求,请设置合理设置用户代理。

关于用户代理的指南,请参考RFC 9110 的“User-Agent”

10.1.5. User-Agent | RFC 9110 

来自kintone版本升级的影响

当kintone版本升级以后,您在应用里上传的JavaScript 和 CSS文件可能无法正常运行。可根据需要重新编辑JavaScript 和 CSS文件后重新上传。
为了减少来自kintone版本升级的影响,请尽量使用在开发者网站上公布的Javascript API。

API式样公开和式样变更方针

安全

为了防止由JavaScript编程而产生的安全问题,请遵照cybozu.cn的安全编码指南