kintone プラグイン開発手順
はじめに
kintone では、「プラグイン」を利用して、JavaScript カスタマイズと同等の機能拡張や他サービスとの連携を実現できます。
通常のカスタマイズではアプリに合わせて JavaScript ファイルを編集する必要がありますが、プラグインを使うと、プラグインの設定画面でそれぞれのアプリに合わせた設定ができます。
プラグインは、kintone をカスタマイズするための JavaScript や CSS ファイルをパッケージングしたものです。
この記事では、プラグインの作成手順と kintone へのインストール方法について説明します。
プラグイン作成の流れ
プラグイン作成の手順は、以下のとおりです。
- プラグイン作成に必要なファイル(JavaScript, CSS ファイルなど)を準備します。
- マニフェストファイル(manifest.json)を作成します。
- パッケージツール(plugin-packer)を利用して、プラグイン作成に必要なファイルをパッケージングします。
- 作成したプラグインファイルを kintone 環境にインストールします。
プラグイン作成に必要なファイルの準備
パッケージングするファイルを準備します。
パッケージングするファイルのディレクトリー構成およびファイル名は自由です。
以下は一例です。
アイコンファイル
プラグイン一覧、プラグイン設定画面で表示されるプラグインアイコン用のファイルです。
- 必須ファイルです。
- 利用可能なファイルタイプは、png/jpg/gif/bmp のいずれかです。
- ファイルサイズの上限値は、20MB です。
PC 用 JavaScript ファイル
PC 画面用の JavaScript ファイルです。
- モバイル専用のプラグインの場合、省略可能です。
- 設定画面で設定した情報を使い、実装したい処理を記述します。
- 設定画面用の JavaScript ファイルで
プラグインの設定情報を保存する API を利用して設定した情報は、
プラグインの設定情報を取得する API を利用して取得します。
このとき必要なプラグイン ID は、kintone.$PLUGIN_ID
という変数に出力されます。
プラグイン ID は、プラグイン作成時に各プラグインへ一意に割り当てられる 32 桁の ID です。
例:faabchdodajloackbgnipilddblmkejp - ファイルサイズの上限値は、20MB です。
プラグイン ID の参照例
1 アプリで複数のプラグインを利用する場合、kintone.$PLUGIN_ID
は複数回代入されます。
そのため、以下のように即時実行関数でプラグイン ID を補足して利用してください。
|
|
PC 用 CSS ファイル
PC 画面用の CSS ファイルです。
- モバイル専用のプラグインの場合、省略可能です。
- kintone のデザインに合わせたい場合は、 51-modern-default を利用してください。
- ファイルサイズの上限値は、20MB です。
モバイル用 JavaScript ファイル
モバイル用の JavaScript ファイルです。
- モバイルでプラグインを利用しない場合、省略可能です。
- 設定画面から設定した情報を使い、実装したい処理を記述します。
- 設定画面用の JavaScript ファイルで
プラグインの設定情報を保存する API を利用して設定した情報は、
プラグインの設定情報を取得する API を利用して取得します。
このとき必要なプラグイン ID の参照方法は、 プラグイン ID の参照例 を参照してください。 - ファイルサイズの上限値は、20MB です。
モバイル用 CSS ファイル
モバイル画面用の CSS ファイルです。
- モバイルでプラグインを利用しない場合、省略可能です。
- ファイルサイズの上限値は、20MB です。
設定画面用 JavaScript ファイル
設定画面用の JavaScript ファイルです。
- 省略可能です。
- プラグイン ID の参照方法は、 プラグイン ID の参照例 を参照してください。
- プラグインの設定情報を保存する API を利用して、プラグインの設定値を保存できます。
- ファイルサイズの上限値は、20MB です。
- プラグイン設定画面を開いた際に実行される JavaScript ファイルです。
設定画面用 CSS ファイル
設定画面用の CSS ファイルです。
- 省略可能です。
- kintone のデザインに合わせたい場合は、 51-modern-default を利用してください。
- ファイルサイズの上限値は、20MB です。
- プラグイン設定画面に対し適用される CSS ファイルです。
設定画面用 HTML ファイル
設定画面用の HTML ファイルです。
- 省略可能です。
- ファイルサイズの上限値は、64KB です。
- 下図の赤枠部分を構成する HTML ファイルです。
マニフェストファイルの作成
マニフェストファイル(manifest.json
)を作成します。
マニフェストファイルは、プラグイン作成に必要なファイル情報をまとめた設定ファイルです。
このファイルは、kintone プラグイン作成に必須です。
マニフェストファイルのフォーマット
マニフェストファイルは、JSON 形式のファイルです。
各パラメーターの詳細は以下のとおりです。
パラメーター名 | 型 | 必須 | 説明 | 制限 | 指定例 |
---|---|---|---|---|---|
type | 文字列 | 必須 | プラグインの種類 「APP」を指定してください。 |
なし | "type": "APP" |
manifest_version | 数値 | 必須 | プラグインのマニフェストバージョン 「1」を指定してください。 |
なし | "manifest_version": 1 |
version | 数値 または 文字列 |
必須 | プラグインのバージョン 数値を指定する場合は整数のみです。 文字列を指定する場合、「x」「x.y」「x.y.z」の形式のみです。 |
なし | 数値の場合"version": 1文字列の場合 "version": "1.0" "version": "1.0.0" |
name | オブジェクト | 必須 | ロケール をキーとする各言語のプラグイン名 | なし | "name": { |
name.<locale> | 文字列 | 必須 | 指定されたロケールのプラグイン名 | 1 文字以上 64 文字以下name.en は必須です。 |
|
description | オブジェクト | 省略可 |
ロケール をキーとする各言語の説明文 プラグイン一覧での説明文として表示されます。 |
なし | "description": { |
description.<locale> | 文字列 | 必須 | 指定されたロケールの説明文 | 1 文字以上 200 文字以下 description がある場合、 description.en は必須です。 |
|
icon | 文字列 | 必須 | プラグインのアイコンファイル プラグイン一覧画面とプラグイン設定画面で表示されます。 |
プラグイン内のファイルのみ指定可能です。 | "icon": "image/icon.png" |
homepage_url | オブジェクト | 省略可 |
ロケール をキーとする Web サイト URL プラグイン一覧のプラグイン名横にナビゲーションアイコンが追加されます。 アイコンをクリックすると、指定した Web サイトに遷移します。 |
なし | "homepage_url": { |
homepage_url.<locale> | 文字列 | 省略可 | 指定されたロケールの Web サイト URL | なし | |
desktop | オブジェクト | 省略可 | ファイルの種類 (js/css) をキーとする PC 用カスタマイズファイル | なし | "desktop": { |
desktop.js | 配列(文字列) | 省略可 | PC 用 JavaScript ファイル URL の配列 |
30 個まで 同一名のファイルがある場合、エラーになります。 |
|
desktop.css | 配列(文字列) | 省略可 | PC 用 CSS ファイル URL の配列 |
30 個まで 同一名のファイルがある場合、エラーになります。 |
|
mobile | オブジェクト | 省略可 | ファイルの種類 (js) をキーとするモバイル用カスタマイズファイル | なし | "mobile": { |
mobile.js | 配列(文字列) | 省略可 | モバイル用 JavaScript ファイル URL の配列 |
30 個まで 同一名のファイルがある場合、エラーになります。 |
|
mobile.css | 配列(文字列) | 省略可 | モバイル用 CSS ファイル URL の配列 |
30 個まで 同一名のファイルがある場合、エラーになります。 |
|
config | オブジェクト | 省略可 | ファイルの種類 (js/css/html) をキーとする設定画面用カスタマイズファイルと設定情報 | なし | "config": { |
config.html | 文字列 | 省略可 | 設定画面用 HTML ファイル | プラグイン内のファイルのみ指定可能 | |
config.js | 配列(文字列) | 省略可 | 設定画面用 JavaScript ファイル URL の配列 |
30 個まで 同一名のファイルがある場合、エラーになります。 |
|
config.css | 配列(文字列) | 省略可 | 設定用 CSS ファイル URL の配列 |
30 個まで 同一名のファイルがある場合、エラーになります。 |
|
config.required_params | 配列(文字列) | 省略可 | 設定画面で設定必須とするパラメーターの配列 | ASCII で 1 文字以上 64 文字以下 |
指定できるロケール
ロケールには、次の言語コードを指定できます。
ja
:日本語en
:英語zh
:中国語(簡体字)es
:スペイン語
マニフェストファイルの例
|
|
プラグインに必要なファイルのパッケージング
「plugin-packer」を利用してプラグインに必要なファイルをパッケージングし、プラグインファイルを生成します。
plugin-packer とは
plugin-packer は、プラグイン作成で必要なファイルを zip ファイルにパッケージングする CLI ツールです。
plugin-packer の詳細は、
plugin-packer を参照してください。
このツールを利用するには、Node.js が必要です。
Node.js のインストーラーは、
Node.js 公式サイト
より入手してください。
必要な Node.js のバージョンの確認方法は、
plugin-packer | 下準備 を参照してください。
インストール方法
以下のコマンドを実行し、plugin-packer をインストールします。
|
|
パッケージ手順
以下の手順で、プラグインファイルをパッケージングします。
-
マニフェストファイルに沿って、作成した各ファイルとマニフェストファイルを配置します。
-
パッケージングしたいファイルをまとめたディレクトリー(src)の、ひとつ上のディレクトリーに移動します。
上記のファイル配置例の場合、「work」に移動します。1
cd work
-
次のコマンドを実行すると、自動でパッケージングが開始されます。
実行に成功すると、成功メッセージが表示されます。1 2 3
$ kintone-plugin-packer src Succeeded: DIRECTORY_PATH/work/plugin.zip
-
実行したディレクトリーに、プラグインファイル(plugin.zip)と秘密鍵ファイル(ppk ファイル)が生成されます。
秘密鍵ファイルのファイル名は、プラグイン ID と同じです。
次の例では、プラグイン ID が「faabchdodajloackbgnipilddblmkejp」です。秘密鍵ファイルは、2 回目以降のパッケージングで利用します。なくさないでください。
2回目以降のパッケージング
2 回目以降のパッケージングは、 --ppk
オプションを使って、1 回目のパッケージングで生成された秘密鍵ファイルを指定します。
同じ秘密鍵ファイルを使ってパッケージングすると、プラグイン ID は同じになります。
|
|
プラグインファイルの出力先ディレクトリーを変更したい場合や、ファイル監視しながらパッケージングしたい場合など、その他の機能については、 plugin-packer REAME の Options を参照してください。
kintone 環境へのインストール
作成したプラグインファイルを kintone へインストールします。
-
「kintone システム管理」を開きます。
-
「その他」の「プラグイン」をクリックします。
-
「読み込む」ボタンをクリックします。
-
「参照」ボタンをクリックし、パッケージ手順 4. で生成したプラグインファイル(plugin.zip)を選択します。
-
「読み込む」ボタンをクリックします。
-
「インストールされたプラグイン」に、作成したプラグインが表示されれば成功です。
補足
- インストールできるプラグインファイルのサイズ上限値は、100MB です。
- 同じプラグイン ID をもつプラグインファイルをアップロードすると、自動的に上書きインストールされます。
そのプラグインを利用しているアプリにも即時適用されます。 - アプリに複数のプラグインを適用する場合、プラグイン同士が競合し、意図しない挙動をすることがあります。
運用に支障がないことを検証したうえで、プラグインを適用してください。
おわりに
今回は、パッケージツール(plugin-packer)を利用した kintone プラグインの作成手順と、kintone へのインストール方法について説明しました。
プラグインを使うと、kintone カスタマイズの内容を簡単に複数のアプリへ適用できます。
プラグインファイルのパッケージング手順も簡単なので、ぜひプラグイン作成に挑戦してみてください。
この Tips は、2019 年 1 月版 kintone で動作を確認しています。