プラグイン開発入門

kintone プラグインは、JavaScript カスタマイズを再利用可能な形でパッケージング したものです。通常の JavaScript カスタマイズとは異なり、アプリごとにコードを書き直す必要がなく、設定画面を通じて管理者が GUI で設定を変更できるという大きなメリットがあります。

しかし、プラグイン開発には独自のディレクトリ構成やマニフェストファイルの仕組みがあり、初めて取り組む場合はその構造の理解が重要です。

この記事では、プラグインの基本構造からパッケージングまで、入門者向けにステップバイステップで解説します。

プラグインと JavaScript カスタマイズの違い

プラグインのディレクトリ構成

kintone プラグインは、以下のディレクトリ構成で開発します。

my-plugin/
├── manifest.json        # プラグインの定義ファイル（必須）
├── icon.png             # プラグインアイコン（必須）
├── css/
│   ├── config.css       # 設定画面のCSS
│   └── desktop.css      # PC画面のCSS
├── js/
│   ├── config.js        # 設定画面のJavaScript
│   ├── desktop.js       # PC画面のJavaScript
│   └── mobile.js        # モバイル画面のJavaScript
├── html/
│   └── config.html      # 設定画面のHTML
└── image/
    └── icon.png         # プラグインアイコン

manifest.json の書き方

manifest.json はプラグインの定義ファイルです。プラグインの名前、バージョン、使用するファイルなどを記述します。

{
  "manifest_version": 1,
  "version": "1.0.0",
  "type": "APP",
  "name": {
    "ja": "サンプルプラグイン",
    "en": "Sample Plugin"
  },
  "description": {
    "ja": "プラグイン開発の基本を学ぶためのサンプルです。",
    "en": "A sample plugin to learn the basics of plugin development."
  },
  "icon": "image/icon.png",
  "homepage_url": {
    "ja": "https://example.com",
    "en": "https://example.com"
  },
  "desktop": {
    "js": ["js/desktop.js"],
    "css": ["css/desktop.css"]
  },
  "mobile": {
    "js": ["js/mobile.js"]
  },
  "config": {
    "html": "html/config.html",
    "js": ["js/config.js"],
    "css": ["css/config.css"],
    "required_params": ["fieldCode"]
  }
}

主要なプロパティ

設定画面の構築

プラグインの大きな特徴として、設定画面（config）を持てる点があります。設定画面では、管理者がフィールドコードや条件などを GUI で設定できます。

設定画面の HTML

<section class="plugin-config">
  <h2 class="plugin-config-title">プラグインの設定</h2>

  <div class="plugin-config-field">
    <label for="fieldCode">対象フィールドコード:</label>
    <input type="text" id="fieldCode" class="plugin-config-input" placeholder="例: 金額" />
  </div>

  <div class="plugin-config-field">
    <label for="threshold">しきい値:</label>
    <input type="number" id="threshold" class="plugin-config-input" placeholder="例: 10000" />
  </div>

  <div class="plugin-config-field">
    <label for="message">エラーメッセージ:</label>
    <input type="text" id="message" class="plugin-config-input" placeholder="例: 金額がしきい値を超えています" />
  </div>

  <button id="save-button" class="plugin-config-button">保存</button>
  <button id="cancel-button" class="plugin-config-button plugin-config-button--cancel">キャンセル</button>
</section>

設定画面の JavaScript

設定の保存と読み込みには、kintone.plugin.app.setConfig() と kintone.plugin.app.getConfig() を使用します。

(() => {
  'use strict';

  // プラグインIDを取得（自動的に設定される変数）
  const PLUGIN_ID = kintone.$PLUGIN_ID;

  // 既存の設定を読み込む
  const config = kintone.plugin.app.getConfig(PLUGIN_ID);

  // フォームに既存の値をセット
  if (config.fieldCode) {
    document.getElementById('fieldCode').value = config.fieldCode;
  }
  if (config.threshold) {
    document.getElementById('threshold').value = config.threshold;
  }
  if (config.message) {
    document.getElementById('message').value = config.message;
  }

  // 保存ボタンのクリックイベント
  document.getElementById('save-button').addEventListener('click', () => {
    const newConfig = {
      fieldCode: document.getElementById('fieldCode').value,
      threshold: document.getElementById('threshold').value,
      message: document.getElementById('message').value,
    };

    // バリデーション
    if (!newConfig.fieldCode) {
      alert('対象フィールドコードを入力してください。');
      return;
    }

    // 設定を保存（保存後、自動的にプラグイン一覧画面に戻る）
    kintone.plugin.app.setConfig(newConfig);
  });

  // キャンセルボタンのクリックイベント
  document.getElementById('cancel-button').addEventListener('click', () => {
    history.back();
  });
})();

設定画面の CSS

.plugin-config {
  max-width: 600px;
  margin: 24px;
  font-family: 'メイリオ', 'Meiryo', sans-serif;
}

.plugin-config-title {
  font-size: 20px;
  margin-bottom: 20px;
  padding-bottom: 12px;
  border-bottom: 2px solid #3498db;
}

.plugin-config-field {
  margin-bottom: 16px;
}

.plugin-config-field label {
  display: block;
  margin-bottom: 4px;
  font-weight: bold;
  font-size: 14px;
}

.plugin-config-input {
  width: 100%;
  padding: 8px 12px;
  border: 1px solid #ccc;
  border-radius: 4px;
  font-size: 14px;
  box-sizing: border-box;
}

.plugin-config-button {
  padding: 10px 24px;
  font-size: 14px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  margin-right: 8px;
  background: #3498db;
  color: white;
}

.plugin-config-button:hover {
  opacity: 0.8;
}

.plugin-config-button--cancel {
  background: #95a5a6;
}

カスタマイズ JS の実装

設定画面で保存された値を使って、アプリ画面でカスタマイズを実行します。

(() => {
  'use strict';

  const PLUGIN_ID = kintone.$PLUGIN_ID;

  // プラグインの設定を読み込む
  const config = kintone.plugin.app.getConfig(PLUGIN_ID);

  if (!config.fieldCode) {
    return;
  }

  const events = ['app.record.create.submit', 'app.record.edit.submit'];

  kintone.events.on(events, (event) => {
    const record = event.record;
    const fieldCode = config.fieldCode;
    const threshold = Number(config.threshold) || 0;
    const message = config.message || `${fieldCode} がしきい値を超えています`;

    // しきい値チェック
    const value = Number(record[fieldCode].value) || 0;
    if (value > threshold) {
      record[fieldCode].error = message;
    }

    return event;
  });
})();

パッケージングと配布

プラグインの開発が完了したら、ZIP ファイルにパッケージングして kintone に登録します。

@kintone/plugin-packer を使用する（推奨）

公式ツール @kintone/plugin-packer を使うことで、プラグインのパッケージングと署名を一括で行えます。

npm install -g @kintone/plugin-packer

kintone-plugin-packer my-plugin

初回実行時に秘密鍵ファイル（.ppk）が生成されます。このファイルはプラグインの更新に必要なため、大切に保管してください。

kintone-plugin-packer --ppk my-plugin.ppk my-plugin

kintone への登録手順

1. パッケージングで生成された .zip ファイルを用意する
2. kintone システム管理 → プラグイン を開く
3. 「プラグインの読み込み」をクリックし、ZIP ファイルをアップロードする
4. 対象のアプリの設定画面 → プラグイン を開く
5. 登録済みプラグインの一覧から追加し、設定画面で必要な値を入力する

プラグイン開発のベストプラクティス

1. 設定値の JSON 化

setConfig / getConfig で扱えるのは文字列の Key-Value のみです。複雑な設定（配列やオブジェクト）を扱う場合は、JSON.stringify / JSON.parse で変換します。

// 保存
const config = {
  settings: JSON.stringify({
    fields: ['金額', '数量'],
    conditions: [
      { field: '金額', operator: '>', value: 10000 },
    ],
  }),
};
kintone.plugin.app.setConfig(config);

// 読み込み
const savedConfig = kintone.plugin.app.getConfig(PLUGIN_ID);
const settings = JSON.parse(savedConfig.settings);

2. エラーハンドリング

設定が未完了のまま適用された場合に、エラーが発生しないようガードしましょう。

const config = kintone.plugin.app.getConfig(PLUGIN_ID);

// 設定が空の場合は何もしない
if (!config.fieldCode) {
  console.warn('プラグインの設定が完了していません');
  return;
}

3. デバッグ

プラグインのデバッグでは、ブラウザの開発者ツール（DevTools）を活用します。

• Console タブ: console.log で値の確認
• Network タブ: API リクエストの確認
• Sources タブ: ブレークポイントの設置（プラグインソースは暗号化されているため、通常の JS カスタマイズよりデバッグしにくい点に注意）

まとめ

• プラグインは JavaScript カスタマイズを 再利用可能な形でパッケージング したもの
• manifest.json でプラグインの構成（名前、バージョン、使用ファイル）を定義する
• 設定画面は config.html + config.js で構築し、setConfig / getConfig で設定値を保存・読み込みする
• kintone.$PLUGIN_ID でプラグイン固有の ID を取得できる
• パッケージングには公式ツール @kintone/plugin-packer を使用する
• 秘密鍵（.ppk）ファイルはプラグインの更新に必要なため、紛失しないよう管理する

練習問題