概要

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

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

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

插件的制作流程

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

1. 准备制作插件必要的文件（JavaScript及CSS等）。

2. 制作资源配置文件（manifest.json）。

3. 使用打包工具(plugin-packer)，将插件必要的文件打包。

4. 将制作完的插件文件导入到kintone环境里。

准备插件必要的文件

首先准备要打包的文件。

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

文件夹结构范例

图标文件  

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

• 这个文件是必须的。

• 可使用的文件类型：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文件。

• 在智能手机上不使用插件的情况下可以省略。

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

• 在设定页面的JavaScript文件里，使用kintone.plugin.app.setConfig()来设定的信息可以用kintone.plugin.app.getConfig()来获取。此时获取所需要的插件ID的方法，可以参考 获取插件ID的范例。

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

智能手机专用CSS文件 

智能手机专用的CSS文件。

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

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

设置页面用JavaScript文件

设置页面用的JavaScript文件。

• 可省略。

• 获取插件ID的方法，可以参考 获取插件ID的范例。

• 使用kintone.plugin.app.setConfig()来保存插件的设置。
  

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

• 是在打开插件设置页面时调用的JavaScript文件。

设置页面用CSS文件

设置页面用的CSS文件。

• 可省略。

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

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

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

设置页面用html文件

设置页面用的HTML文件。

• 可省略。

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

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

资源配置文件的制作

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

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

资源配置文件的格式

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

"manifest_version": 1

"version": 1

"version": "1.0"

"version": "1.0.0"

"type":"APP"

"name": { 
    "ja": "サンプルプラグイン",
    "en": "sample plugin",
    "zh": "插件的例子"
  }

"description": { 
    "ja": "これはサンプルプラグインです。",
    "en": "This is sample plugin.",
    "zh": "这是插件的例子"
  }

"icon": "image/sample.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"]
  }
}

可指定的区域

区域设置可指定以下语言代码：

• ja：日语

• en：英语

• zh：中文（简体）

• es：西班牙语

资源配置文件的范例

{
    "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. 按照资源配置文件配置准备好的各文件和资源配置文件。
   
   

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

   
   

   $ cd work

   
   

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

   
   

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

   
   

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

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

再次打包时

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

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

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

导入到kintone环境 

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

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

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

3. 点击“导入”按钮。
   

4. 点击“选择文件”按钮，并选择在打包步骤 4.中生成的插件文件（plugin.zip）。
   
   

5. 点击“导入”按钮。
   
   

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

补充

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

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

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

总结

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

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

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