kintone 插件开发流程

cybozu发表于:2016年11月25日 17:47:16更新于:2023年11月29日 15:22:01

概要

在kintone里,使用“插件”可跟JavaScript自定义一样实现功能扩展及跟第三方产品的整合。
通常的自定义需要根据应用的设置来编写JavaScript文件,但是插件的话可以在插件的设置页面根据各应用的实际情况来进行设置。

插件是指把kintone的自定义文件(比如JavaScript及CSS等)打包后的文件包。

本文章介绍插件的开发步骤和导入到kintone的方法。

插件的制作流程

以下就是制作kintone插件的操作流程。

准备插件必要的文件

首先准备要打包的文件。

要打包的文件夹结构和文件名,大家可以随意安排。

文件夹结构范例

0015f23c1f6ade7292ac643811afe73

图标文件  

显示插件列表和插件设置页面上的图标文件。

  • 这个文件是必须的。

  • 可使用的文件类型:png、jpg、gif、bmp 中的任意一个。

  • 文件大小的上限为 20MB。

PC端专用JavaScript文件

PC页面专用的JavaScript文件。

  • 如果是手机端专用的插件,可以省略。

  • 使用设置页面的设置信息来做成想要执行的处理。

  • 在设定页面的JavaScript文件中,使用kintone.plugin.app.setConfig()来设定的信息可以用kintone.plugin.app.getConfig()来获取。此时所需要的插件ID,主要通过 kintone.$PLUGIN_ID 这个变量来传递。
    ※所谓的插件ID,是制作插件时,向各个插件里分配的唯一的32位的ID。
    例如:hkfgjeehkaajnbmfojmpbgcpfalbfhjn

  • 文件大小的上限为 20MB

获取插件ID的范例

如果在同一个应用里,使用多个插件时,需要多次传递 kintone.$PLUGIN_ID。

因此, 可以像下面这样,使用匿名函数来使用插件ID。

(function(PLUGIN_ID) {
    kintone.plugin.app.getConfig(PLUGIN_ID);
})(kintone.$PLUGIN_ID);

PC端专用CSS文件

PC页面专用的CSS文件。

  • 如果是手机端专用,可以省略。

  • 想要使用kintone 的设计风格的话,请参照样式表的使用

  • 文件大小的上限为 20MB。

智能手机端专用JavaScript文件

智能手机页面专用的JavaScritp文件。

智能手机专用CSS文件 

智能手机专用的CSS文件。

  • 如不用在手机端上使用插件,可以省略。

  • 文件大小的上限为 20MB。

设置页面用JavaScript文件

设置页面用的JavaScript文件。

设置页面用CSS文件

设置页面用的CSS文件。

  • 可省略。

  • 想要使用kintone 的设计风格的话,可以使用kintone 插件设计的指南

  • 文件大小的上限为 20MB。

  • 应用于插件设置页面的CSS文件

设置页面用html文件

设置页面用的HTML文件。

  • 可省略。

  • 文件大小的最大值为 64KB。

  • 用于构筑下图红框部分的HTML文件。
    0015d7746f00351c088160b1e9fcb1d

资源配置文件的制作

创建资源配置文件 (manifest.json)

资源配置文件是指将插件所需的所有文件汇总的设置文件。
资源配置文件(manifest.json)是制作kintone插件必须要有的。

资源配置文件的格式

以下就是资源配置文件的格式。使用json格式来指定各个参数。


参数名称类型必须说明限制指定的范例
manifest_version

Number

※必须整数

必须

插件的资源配置版本

只能指定1。

※当前最新版本为1。

"manifest_version": 1
version

Number

※必须整数

或者
String

※必须“x”、“x.y”和“x.y.z”的格式

必须插件的版本
"version": 1
"version": "1.0"
"version": "1.0.0"
typeString必须插件的种类。
指定字符串"APP"。
 
"type":"APP"


nameObject.<String>必须将地域(ja, en, zh)作为键名的各种语言的插件名
"name": { 
    "ja": "サンプルプラグイン",
    "en": "sample plugin",
    "zh": "插件的例子"
  }
name.<locale>String必须所指定地域的插件名1个字以上64个字以下。name.en 是必须的
descriptionObject.<String>可省略

将地域(ja, en, zh)作为键名的各种语言的描述文

显示在插件列表的说明里

"description": { 
    "ja": "これはサンプルプラグインです。",
    "en": "This is sample plugin.",
    "zh": "这是插件的例子"
  }
description.<locale>String必须所指定地域的描述文字1个字以上200个字以下。有description的时候,description.en是必须的
iconString必须

插件的图标文

显示在插件列表和插件的设置里面上

可以只指定插件里的文件
"icon": "image/sample.png"
homepage_urlObject.<String>可省略

将地域(ja, en, zh)作为键名的各种语言的Web网站URL在插件列表的插件名称旁会增加导航图标,点击该图标会跳转到所指定的网站

 
"homepage_url": { 
    "ja": "https://example.com/jp/",
    "en": "https://example.com/en-us/",
    "zh": "https://example.com/cn/"
  }
homepage_url.<locale>String可省略所指定地域的Web网站URL
desktopObject.<String>可省略将文件的类型(js, css)作为键名的PC端专用的自定义文件
"desktop": {
    "js": [
      "js/customize.js",
      "https://example.com/js/customize.js"
    ],
    "css": [
      "https://example.com/css/customize.css",
      "css/customize.css"
    ]
  }
desktop.jsArray.<String>可省略PC端专用JavaScript文件・URL的数组

30个为止
※有同名文件的话,会报错。


desktop.cssArray.<String>可省略PC端专用CSS文件・URL的数组30个为止
有同名文件的话,会报错

mobileObject.<String>可省略将文件的类型(js)作为键名的智能手机端专用的自定义文件
"mobile": {
    "js": [
      "js/mobile-customize.js",
      "https://example.com/js/mobile-customize.js"
    ]
  }
mobile.jsArray.<String>可省略智能手机端专用的JavaScript文件・URL的数组30个为止
※有同名文件的话,会报错。

mobile.cssArray.<String>可省略智能手机专用CSS文件
URL的数组
最多30个
※如有文件名重复,将报错

configObject.<String>可省略将文件的类型(html, js, css)作为键名的个人设置用文件和设置信息
"config": {
    "html": "html/config.html",
    "js": [
      "https://example.com/js/config.js",
      "js/config.js"
    ],
    "css": [
      "css/config.css",
      "https://example.com/css/config.css"
    ],
    "required_params": ["Param1", "Param2"]
  }
}
config.htmlString可省略设置页面用HTML文件可以只指定插件里的文件
config.jsArray.<String>可省略设置页面用JavaScript文件・URL的数组30个为止
有同名文件的话,会报错

config.cssArray.<String>可省略设置页面用CSS文件・URL的数组30个为止
有同名文件的话,会报错

config.required_paramsArray.<String>可省略设置页面上设置必须的参数数组ASCII码,1个字以上64个字以下。

资源配置文件的范例

{
    "manifest_version": 1,
    "version": 1,
    "type": "APP",
    "name": { 
        "ja": "サンプルプラグイン",
        "en": "sample plugin",
        "zh": "插件的例子"
    },
    "description": { 
        "ja": "これはサンプルプラグインです。",
        "en": "This is sample plugin.",
        "zh": "这是插件的例子"
    },
    "icon": "image/icon.png",
    "homepage_url": { 
        "ja": "https://example.com/jp/",
        "en": "https://example.com/en-us/",
        "zh": "https://example.com/cn/"
    },
    "desktop": {
        "js": [
            "js/customize.js",
            "https://example.com/js/customize.js"
        ],
        "css": [
            "https://example.com/css/customize.css",
            "css/customize.css"
        ]
    },
    "mobile": {
        "js": [
            "js/mobile-customize.js",
            "https://example.com/js/mobile-customize.js"
        ]
    },
    "config": {
        "html": "html/config.html",
        "js": [
            "https://example.com/js/config.js",
            "js/config.js"
        ],
        "css": [
            "css/config.css",
            "https://example.com/css/config.css"
        ],
        "required_params": ["Param1", "Param2"]
    }
}

打包插件所需的所有文件

使用plugin-packer打包插件所需要的文件,生成插件文件。

所谓plugin-packer?

plugin-packer是指将插件所需要的文件打包成zip文件的CLI工具。
plugin-packer 的详情请参考使用plugin-packer打包插件文件(日文)。

此工具须在安装了Node.js版本8或更高版本的环境下才能使用。
关于Node.js的安装方法请参考Node.js的官网

安装方法

执行以下命令,安装plugin-packer。

$ npm install -g @kintone/plugin-packer

打包步骤

按照以下步骤打包插件文件。

  1. 按照资源配置文件配置准备好的各文件和资源配置文件。
    0015f23b6b40c35e48f4fdaf9b8597b

  2. 回到存放要打包文件的上一级目录。
    按照上面例子存放文件的话,就是回到“work”。


    $ cd work


  3. 执行以下命令,即开始自动打包。
    执行成功后,显示成功的信息。


    $ kintone-plugin-packer src
    Succeeded: DIRECTORY_PATH/work/plugin.zip


  4. 在执行目录下生成插件文件 (plugin.zip) 和密钥文件 (ppk文件) 

    密钥文件的文件名和插件ID一样。
    在以下例子中,插件ID为“faabchdodajloackbgnipilddblmkejp”。
    密钥文件在以后再次打包时需要用到,请务必注意保管。
    0015f23c1febc1c1d245cdf88bc2540

再次打包时

再次打包时,可以使用 --ppk 选项来指定第一次打包时生成的密钥文件。
使用同一个密钥文件打包后,插件ID不会变。

$ kintone-plugin-packer --ppk PLUGIN_SECRET_KEY.ppk src

如要更改插件文件的生成目录,或在生成过程中要监控文件,以及其他更多功能,请参考选项功能(日文) 。

导入到kintone环境 

将做好的插件文件导入到kintone。

  1. 打开“业务云系统管理”页面。

  2. 点击“其他”下的“插件”。
    0015d773faf84411c52f17fe8e8f8e9

  3. 点击“导入”按钮。
    0015d773fafd1ecc9337899cb3c299d

  4. 点击“选择文件”按钮,并选择在打包步骤 4.中生成的插件文件(plugin.zip)。
    0015d773fb0028cb7a1e87de4bcda6c

  5. 点击“导入”按钮。
    0015d773fb0120124888e7d90d9e5a4

  6. 如在“导入的插件”列表中显示所创建的插件,即表示成功。
    0015d773fb0032c42851a5186273148

补充

  • 可导入的插件文件最大为100MB。

  • 导入插件ID相同的插件时,将覆盖已导入的插件。
    同时将反映到启用此插件的所有应用中。

  • 在同一个应用中如果设置了多个插件,这些插件可能会相互冲突,可能会产生不可预测的结果。
    在将其应用到正式环境之前,请先进行测试,确保正常运行。

总结

本次介绍了使用打包工具(plugin-packer)制作kintone插件的步骤以及导入到kintone的方法。

使用插件可以轻松地在多个应用中启用kintone自定义的内容。
而且,插件文件的打包步骤也不难,请务必亲自挑战一下吧。

此Tips已在2019年1月版的kintone中确认。

回复(2)

  • betsy_yan

    谢谢提醒,已调整。请尽情阅读吧!

    引用 dd000 的回复:

    >> 资源配置文件的范例范例好像没有显示。

  • dd000

    >> 资源配置文件的范例

    范例好像没有显示。