kintone プラグイン開発手順

はじめに

kintoneでは、「プラグイン」を利用して、JavaScriptカスタマイズと同等の機能拡張や他サービスとの連携を実現できます。
通常のカスタマイズではアプリに合わせてJavaScriptファイルを編集する必要がありますが、プラグインを使うと、プラグインの設定画面でそれぞれのアプリに合わせた設定ができます。

プラグインは、kintoneをカスタマイズするためのJavaScriptやCSSファイルをパッケージングしたものです。

この記事では、プラグインの作成手順と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です。
  　例：faabchdodajloackbgnipilddblmkejp
• ファイルサイズの上限値は、20MBです。

プラグインIDの参照例

1アプリで複数のプラグインを利用する場合、kintone.$PLUGIN_ID は複数回代入されます。
そのため、以下のように即時実行関数でプラグインIDを補足して利用してください。

PC用CSSファイル

PC画面用の CSS ファイルです。

• スマートフォン専用のプラグインの場合、省略可能です。
• kintone のデザインに合わせたい場合は、スタイルシートの利用をご利用ください。
• ファイルサイズの上限値は、20MBです。

スマートフォン用JavaScriptファイル

スマートフォン用のJavaScriptファイルです。

• スマートフォンでプラグインを利用しない場合、省略可能です。
• 設定画面から設定した情報を使い、実装したい処理を記述します。
• 設定画面用の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 のデザインに合わせたい場合は、スタイルシートの利用をご利用ください。
• ファイルサイズの上限値は、20MBです。
• プラグイン設定画面に対し適用される CSS ファイルです。

設定画面用HTMLファイル

設定画面用のHTMLファイルです。

• 省略可能です。
• ファイルサイズの上限値は、64KB です。
• 下図の赤枠部分を構成する HTML ファイルです。
  

マニフェストファイルの作成

マニフェストファイル (manifest.json)を作成します。
マニフェストファイルは、プラグイン作成に必要なファイル情報をまとめた設定ファイルです。
このファイルは、kitoneプラグイン作成に必須です。

マニフェストファイルのフォーマット

マニフェストファイルは、JSON 形式のファイルです。各パラメータの詳細は以下のとおりです。

パラメータ名	型	必須	説明	制限	指定例
type	String	必須	プラグインの種類 APP を指定してください。	なし	"type": "APP"
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"
name	Object <String>	必須	ロケール(ja/en/zh)をキーとする各言語のプラグイン名	なし	"name": { "ja": "サンプルプラグイン", "en": "sample plugin", "zh": "插件的例子" }
name.<locale>	String	必須	指定されたロケールのプラグイン名	1文字以上64文字以下 name.en は必須です。
description	Object <String>	省略可	ロケール(ja/en/zh)をキーとする各言語の説明文 プラグイン一覧での説明文として表示されます。	なし	"description": { "ja": "これはサンプルプラグインです。", "en": "This is sample plugin.", "zh": "这是插件的例子" }
description.<locale>	String	必須	指定されたロケールの説明文	1文字以上200文字以下 description がある場合、description.en は必須です。
icon	String	必須	プラグインのアイコンファイル プラグイン一覧、プラグイン設定画面で表示されます。	プラグイン内のファイルのみ指定可能です。	"icon": "image/icon.png"
homepage_url	Object <String>	省略可	ロケール(ja/en/zh)をキーとするWebサイトURL プラグイン一覧のプラグイン名横にナビゲーションアイコンが追加されます。アイコンをクリックすると、指定したWebサイトに遷移します。	なし	"homepage_url": { "ja": "https://example.com/jp/", "en": "https://example.com/en-us/", "zh": "https://example.com/cn/" }
homepage_url.<locale>	String	省略可	指定されたロケールのWebサイトURL	なし
desktop	Object <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.js	Array <String>	省略可	PC用JavaScriptファイル URLの配列	30個まで ※同一名のファイルが有る場合、エラーになります
desktop.css	Array <String>	省略可	PC用CSSファイル URLの配列	30個まで ※同一名のファイルが有る場合、エラーになります
mobile	Object <String>	省略可	ファイルの種類 (js) をキーとするスマートフォン用カスタマイズファイル	なし	"mobile": { "js": [ "js/mobile-customize.js", "https://example.com/js/mobile-customize.js" ],   "css": [ "https://example.com/css/customize.css", "css/customize.css" ] }
mobile.js	Array <String>	省略可	スマートフォン用JavaScriptファイル URLの配列	30個まで ※同一名のファイルが有る場合、エラーになります
mobile.css	Array <String>	省略可	スマートフォン用CSSファイル URLの配列	30個まで ※同一名のファイルが有る場合、エラーになります
config	Object <String>	省略可	ファイルの種類 (js/css/html) をキーとする設定画面用カスタマイズファイルと設定情報	なし	"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.html	String	省略可	設定画面用HTMLファイル	プラグイン内のファイルのみ指定可能
config.js	Array <String>	省略可	設定画面用JavaScriptファイル URLの配列	30個まで ※同一名のファイルが有る場合、エラーになります
config.css	Array <String>	省略可	設定用CSSファイル URLの配列	30個まで ※同一名のファイルが有る場合、エラーになります
config.required_params	Array <String>	省略可	設定画面で設定必須とするパラメータの配列	ASCIIで1文字以上64文字以下

マニフェストファイルの例

プラグインに必要なファイルのパッケージング 

plugin-packer を利用してプラグインに必要なファイルをパッケージングし、プラグインファイルを生成します。

plugin-packer とは

plugin-packer は、プラグイン作成に必要なファイルをzipファイルにパッケージングする CLI ツールです。
plugin-packer の詳細は、plugin-packerを使ってプラグインファイルをパッケージングしよう！をご参照ください。

このツールを利用するには、Node.js バージョン 8 以上 が必要です。
Node.js のインストーラは、Node.js 公式サイトより入手してください。

インストール方法

以下のコマンドを実行し、plugin-packer をインストールします。

パッケージ手順

以下の手順で、プラグインファイルをパッケージングします。

1. マニフェストファイルに沿って、作成した各ファイルとマニフェストファイルを配置します。
   
2. パッケージングしたいファイルをまとめたディレクトリ（src）の、ひとつ上のディレクトリに移動します。
   上記のファイル配置例の場合、「work」に移動します。
3. 下記のコマンドを実行すると、自動でパッケージングが開始されます。
   実行に成功すると、成功メッセージが表示されます。
4. 実行したディレクトリに、プラグインファイル (plugin.zip) と秘密鍵ファイル (ppkファイル) が生成されます。
   秘密鍵ファイルのファイル名は、プラグインIDと同じです。
   下記の例では、プラグインIDが「faabchdodajloackbgnipilddblmkejp」です。
   秘密鍵ファイルは、2回目以降のパッケージングで利用するので、なくさないようご注意ください。
   

2回目以降のパッケージング

2回目以降のパッケージングは、 --ppk オプション を使って、1回目のパッケージングで生成された秘密鍵ファイルを指定します。
同じ秘密鍵ファイルを使ってパッケージングすると、プラグインIDは同じになります。

プラグインファイルの出力先ディレクトリを変更したい場合や、ファイル監視しながらパッケージングしたい場合など、その他の機能については、オプション機能 をご参照ください。

kintone 環境へのインストール

作成したプラグインファイルを kintone へインストールします。

1. 「kintoneシステム管理」を開きます。
2. 「その他」の「プラグイン」をクリックします。
   
3. 「読み込む」ボタンをクリックします。
   
4. 「参照」ボタンをクリックし、パッケージ手順 4. で生成したプラグインファイル（plugin.zip）を選択します。
   
5. 「読み込む」ボタンをクリックします。
   
6. 「インストールされたプラグイン」に、作成したプラグインが表示されれば成功です。
   

補足

• インストールできるプラグインファイルのサイズ上限値は、100MB です。
• 同じプラグインIDを持つプラグインファイルをアップロードすると、自動的に上書きインストールされます。
  そのプラグインを利用しているアプリにも即時適用されます。
• 複数のプラグインを設定している場合、プラグイン同士が競合し、意図しない挙動をすることがあります。
  同時に使いたい場合は、複数のプラグインのコードを1ファイルにまとめ、Promise で処理をつないでください。
  Promise 処理については、kintone API で Promise を使ってみよう！をご参照ください。

おわりに

今回は、パッケージツール(plugin-packer)を利用した kintone プラグインの作成手順と、kintone へのインストール方法について説明しました。

プラグインを使うと、kintone カスタマイズの内容を簡単に複数のアプリへ適用できます。
プラグインファイルのパッケージング手順も簡単なので、ぜひプラグイン作成に挑戦してみてください。

このTipsは、2019年1月版 kintoneで確認したものになります。