cybozu developer network

カテゴリー内の他の記事

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

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

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

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

kintone 環境へのインストール

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

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

補足

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

おわりに

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

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

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

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

Avatar
ponkichi31
ponkichi31により編集されました
Avatar
細谷 崇

「customize.js.js 」と拡張しが二つ付いている箇所があります!

Avatar
cybozu Development team

To Hosoya san

フォルダ構成の部分で、誤記がありましたので修正しました。
ご報告をいただきましてありがとうございます。

Avatar
細谷 崇

kintone.plugin.getConfig(PLUGIN_ID);  の記述があります!
正しくは、「kintone.plugin.app.getConfig(PLUGIN_ID);」かなと思います!

Avatar
cybozu Development team

Hosoya さま

PC用JavaScriptファイル > プラグインIDの参照例

の箇所で kintone.plugin.getConfig(PLUGIN_ID); の記述があったため、

「kintone.plugin.app.getConfig(PLUGIN_ID);」に修正いたしました。ご指摘をありがとうございます。

Avatar
kazuhisa ishidao

記事中段の

「取得したパッケージングツールを配置します。」

の”パッケージングツール”のリンク先が誤っています。

上記の箇所だけNot Foundになってしまうので修正していただければと。

Avatar
cybozu Developer team

kazuhisa ishidao 様

お世話になっております。
cybozu developer network事務局です。

ご指摘いただきありがとうございます。
内部にフィードバックし、修正いたします。

今後ともcybozu developer networkのほど、よろしくお願い致します。

Avatar
cybozu Developer team

kazuhisa ishidao 様

ご指摘いただいた内容を修正いたしました。
ご報告をいただきましてありがとうございます。

Avatar
Toshi Akazawa

リンクの存在がわからないようなスタイル指定の箇所がありますので、改善いただけますでしょうか。具体的には以下のとおりです。

---

「設定画面用CSSファイル」の項に「kintone プラグインデザインのガイドラインをご利用ください」との記述があります。

マウスカーソルを「kintone プラグインデザインのガイドライン」に当てますと、アンダーラインが引かれ、リンクがあるのがわかります。しかし、通常は、他の平文と同じで黒く表示されており、リンクがあるのかどうかがわかりません。

少し調べてみますと、「kintone プラグインデザインのガイドライン」のリンクについては、なぜか「class="wysiwyg-color-black"」の指定がなされており、これが原因で黒い文字として表示されていることがわかりました。

このリンクを黒く表示しなければならない理由は無いように思いますので、他のリンク文と同様に青っぽく(上記クラス指定を除去)していただけないでしょうか。

Avatar
cybozu Development team

Toshi Akazawa 様

お世話になっております。
cybozu developer network事務局です。

ご指摘いただいた点を修正いたしました。
ご報告いただきましてありがとうございます。

cybozu Development teamにより編集されました
Avatar
Toshi Akazawa

「パッケージ手順」の手順2で、次の説明書きがあります。

パッケージングしたいファイルをまとめたディレクトリの、ひとつ上のディレクトリに移動します。
上記のファイル配置例の場合、「work」に移動します。
cd work

しかし、「上記の・・・」の上の図には、workというディレクトリは記載されていないため、何のことかわかりにくいです。cd src と書くべきところを typoしたのかなという印象でした。

図にも work ディレクトリを書き添えたものにされた方がよいのではないでしょうか。

あるいは、図はそのままとするのであれば、「パッケージングしたいファイルをまとめたディレクトリ src の、」というように、src も書き加え、続く一文も「上記のファイル配置の src のひとつ上のディレクトリが「work」であるとして、その「work」に移動します」としてはいかがでしょうか。

Toshi Akazawaにより編集されました
Avatar
cybozu Development team

Toshi Akazawa 様

お世話になっております。cybozu developer network 運営局です。

フィードバックくださり、ありがとうございます。
ご指摘いただいた内容について、記事を修正いたしました。

今後とも、cybozu developer network をよろしくお願いいたします。

サインインしてコメントを残してください。