KintoneのJavaScriptカスタマイズ基礎と実践ガイド

2026年7月26日

Contents

1 Kintone JavaScriptカスタマイズの基礎と目的
2 KintoneアプリケーションへのJavaScript埋め込み方法
- 2.1 カスタムJavaScriptの追加手順
- 2.2 コードの配置場所とベストプラクティス
3 イベントハンドラの記述パターンと注意点
- 3.1 代表的なイベント一覧
- 3.2 実装例とデバッグ時の落とし穴
4 データベース操作時のセキュリティ対策
- 4.1 Kintone APIエンドポイントの使用方法
- 4.2 権限チェックの実装方法
5 カスタムフィールドとの連携方法
- 5.1 フィールド型別の値取得処理
- 5.2 複数フィールドの同期ロジック
6 ブラウザコンソールでのデバッグ手順
- 6.1 エラーメッセージの読み方
- 6.2 実行環境の確認方法
7 まとめ

スポンサードリンク

Kintone JavaScriptカスタマイズの基礎と目的

Kintoneは、クラウド型アプリケーションプラットフォームとして、JavaScriptを活用した高度なカスタマイズが可能です。特に、公式APIとJavaScript埋め込み機能を通じて、業務フローの自動化や独自ロジックの実装が可能となり、企業のデジタルトランスフォーメーション（DX）に大きく貢献します。本記事では、Kintoneのカスタマイズ可能性を体系的に解説し、実務で即戦力となる知識をお伝えします。

KintoneアプリケーションへのJavaScript埋め込み方法

KintoneでのJavaScript埋め込みは、アプリケーションに柔軟な機能拡張をもたらす重要な手段です。公式提供の「JavaScriptを追加する」機能を中心に、手順やベストプラクティスを解説します。

カスタムJavaScriptの追加手順

JavaScriptの埋め込みは、アプリケーションの設定画面から行います。以下に基本的な手順を示します。

Kintoneアプリケーションを開き、設定 → アプリケーションの設定 を選択します。
「JavaScriptを追加する」 タブを選択し、「カスタムJSを追加」ボタンをクリックします。
JavaScriptコードを直接入力またはファイルからアップロードします。

注意: ブラウザのセキュリティポリシーにより、外部ホストからのスクリプトは読み込まれません。公式ドキュメントに記載されている方法で、アプリケーション内でのみ有効なコードを記述してください。

コードの配置場所とベストプラクティス

KintoneにおけるJavaScriptの配置および記述には以下のポイントが重要です。

項目	値	補足
配置場所	アプリ設定画面の「JavaScriptを追加する」セクション	他のユーザーが編集できないように、管理者専用領域に限定
コードの分離	ファンクションごとにファイル化	読みやすさとメンテナンス性向上
イベントハンドラの統一管理	グローバル変数やオブジェクトでまとめた構造を採用	関数名の重複を防ぐ

イベントハンドラの記述パターンと注意点

Kintoneでは、onLoadやonChangeなどのイベント処理を通じて、アプリケーションの挙動をカスタマイズできます。しかし、イベント処理の順序や競合によって予期せぬ動作を引き起こす可能性があるため、注意が必要です。

代表的なイベント一覧

Kintoneで利用可能な主要なイベントハンドラは以下の通りです。

onLoad：ページが読み込まれたときに実行される
onChange：フィールド値が変更されたときに実行される
onRender：レコードの表示時に実行される

以下に、onLoadで初期値を設定する例を示します。

kintone.events.on('app.record.index.show', function(event) {
  // レコード一覧が読み込まれた際に処理を実行
  const records = event.records;
  console.log(records);
});

kintone.events.on('app.record.index.show', function(event) {

// レコード一覧が読み込まれた際に処理を実行

const records = event.records;

console.log(records);

});

実装例とデバッグ時の落とし穴

イベントハンドラの記述には以下の点に注意が必要です。

イベントオブジェクトの使い方：event.recordやevent.appIdなど、引数に含まれる情報を活用することで、動的な処理が可能になります。
競合回避のための設計：複数のスクリプトで同じイベントを登録した場合、実行順序によって予期せぬ挙動が生じることがあります。event.preventDefault()を使用して既存処理を上書きするなど、競合を意識した設計が重要です。
非推奨な return false; の使用：一部のケースでは動作しない可能性があるため、代わりに event.preventDefault() またはイベントハンドラの登録順序で管理することをおすすめします。

データベース操作時のセキュリティ対策

Kintoneでのデータベース操作は、kintone.api を用いた公式APIを通じて行われます。不正なアクセスや情報漏洩を防ぐために、権限チェックやデータの検証が重要です。

Kintone APIエンドポイントの使用方法

KintoneのAPIは、パラメータ指定ではなくパス埋め込み形式が非推奨とされています。正しい記述例は以下の通りです。

const recordId = '12345';
kintone.api(`/k/v1/records?recordId=${recordId}`, 'GET', {}, function(err, res) {
  if (err) {
    console.error('Error fetching record:', err);
  } else {
    const data = res.record;
    // 取得したデータを処理
  }
});

const recordId = '12345';

kintone.api(`/k/v1/records?recordId=${recordId}`, 'GET', {}, function(err, res) {

if (err) {

console.error('Error fetching record:', err);

} else {

const data = res.record;

// 取得したデータを処理

}

});

重要: レコードアクセス時に、ユーザーの権限（kintone.auth.getRoles()）をチェックします。ただし、公式APIに該当メソッドは存在しない可能性があるため、代替手段（例: kintone.getLoginUser()）でロール情報取得を行う必要があります。

権限チェックの実装方法

レコードへのアクセス権限を管理するには以下のようなロジックが必要です。

アプリケーションレベル：kintone.app.getId()で現在のアプリIDを取得し、対象レコードが同一アプリに所属しているかを確認
レコードレベル：kintone.getLoginUser().rolesなど代替手段でロール情報を取得し、アクセス権があるかを判断

カスタムフィールドとの連携方法

カスタムフィールドは、Kintoneアプリケーションの柔軟性を高める重要な要素です。テキストやチェックボックス、選択肢などのフィールド型に対応したJavaScript処理が必要になります。

フィールド型別の値取得処理

カスタムフィールドから値を取得する際の正しい記法は以下の通りです。

テキストフィールド：event.record.フィールドコード.value
チェックボックス：event.record.フィールドコード.value.split(',')
選択肢フィールド：event.record.フィールドコード.value.label

複数フィールドの同期ロジック

以下は、2つのテキストフィールド間で値を自動反映する例です。

kintone.events.on('app.record.edit.change.フィールドA', function(event) {
  const value = event.record.フィールドA.value;
  kintone.app.setFieldValue('フィールドB', value);
});