【kintone】JavaScriptカスタマイズの基本とイベント一覧

「kintoneでもっと高度なカスタマイズをしたい」「でも、JavaScriptは難しそう…」

そう感じたことはありませんか？

この記事ではkintoneのJavaScriptカスタマイズの基本とよく使うイベント一覧を初心者向けに分かりやすく解説します。

kintoneのJavascriptカスタマイズとは？

kintoneのJavaScriptカスタマイズとは、

JavaScriptやCSSを使って、kintoneの画面や動作を自由に変更できる機能のことです。

追加費用なしで、自分の思い通りにカスタマイズできるのが大きな魅力です。

一方で、プログラミングの知識が必要になるため、初心者の方にとってはハードルが高く感じやすいのも事実です。

JavaScriptカスタマイズの仕組み

ここではJavaScriptカスタマイズがどのような仕組みで動いているのかを解説します。

まず押さえるJavaScriptの基本

kintoneのJavaScriptカスタマイズは、最初に独特のルールを知っておくことが重要です。

ここでは、初心者がつまずきやすい基本ポイントだけを解説します。

イベントの考え方

kintoneのJavaScriptは、常に動いているわけではありません。

決められたタイミング（イベント）が発生したときだけ実行されます。

「画面を開いたとき」「保存する直前」など、

何をしたいかより先に「いつ動かすか」を考えるのがポイントです。

最初は「画面表示時」「保存前」の2つを押さえれば十分です。

recordオブジェクトとは

イベントが発生すると、kintoneは現在のレコード情報を

record（event.record）としてJavaScriptに渡します。

この中には、フィールドの値や入力中のデータが入っています。

JavaScriptカスタマイズでは、このrecordを操作して値を読む・書き換えることを行います。

フィールドコードとは

kintoneのフィールドには、

画面に表示される「フィールド名」と、JavaScriptで使う「フィールドコード」があります。

JavaScriptでは必ずフィールドコードを使用します。

フィールド名をそのまま書いても動かない点に注意しましょう。

フィールドコードは、アプリの設定画面から確認できます。

return event の意味

イベント処理の最後にはreturn event;を記述します。

これは「この内容で処理を続けてOK」とkintoneに伝えるための決まりです。

値を変更した場合でも、returnしないと画面に反映されません。

カスタマイズの適用方法

JavaScriptを書いただけでは、kintone上では動きません。

アプリ設定の「JavaScript / CSSでカスタマイズ」から登録する必要があります。

登録後は、必ずアプリを更新しましょう。

kintoneで使えるイベント一覧

kintoneで使えるイベント一覧を一挙ご紹介します。

画面ごとにどんなイベントが使えるのかを、カテゴリ別にまとめました。

レコード作成画面のイベント

新しくレコードを作成するときに発火するイベントです。

初期値の設定や、保存前の入力チェックなどでよく使われます。

イベント名	発火タイミング	主な用途
app.record.create.show	新規レコード作成画面を表示したとき	初期値設定、表示制御
app.record.create.submit	保存ボタン押下時（保存前）	入力チェック、保存キャンセル
app.record.create.submit.success	レコード保存成功後	通知、後処理

レコード編集画面のイベント

既存レコードを編集する際に発火するイベントです。

編集時のみ処理を分けたい場合によく利用されます。

イベント名	発火タイミング	主な用途
app.record.edit.show	編集画面を表示したとき	編集時の表示制御
app.record.edit.submit	保存ボタン押下時（保存前）	入力チェック
app.record.edit.submit.success	レコード更新成功後	更新後処理

フィールド変更イベント

特定のフィールドの値が変更されたタイミングで発火するイベントです。

値の自動計算や、他フィールドとの連動処理に使われます。

イベント名	発火タイミング	主な用途
app.record.create.change.フィールドコード	新規作成画面で指定フィールド変更時	自動計算、入力補助
app.record.edit.change.フィールドコード	編集画面で指定フィールド変更時	値連動、制御処理

一覧画面（index）のイベント

レコード一覧画面を表示したときに発火するイベントです。

一覧の見た目をカスタマイズしたい場合に使用します。

イベント名	発火タイミング	主な用途
app.record.index.show	レコード一覧画面を表示したとき	行の色付け、一覧カスタマイズ

レコード詳細画面のイベント

レコードの詳細画面を表示したときに発火するイベントです。

ボタンの追加や表示内容のカスタマイズに利用されます。

イベント名	発火タイミング	主な用途
app.record.detail.show	レコード詳細画面を表示したとき	表示装飾、ボタン追加

よくあるつまずきポイント

kintoneのJavaScriptカスタマイズでは、初心者がつまずきやすいポイントがいくつかあります。

ここでは、特に多く見られるつまずきポイントを紹介します。

イベントの仕組みが理解できていない

kintoneのJavaScriptカスタマイズでは、「どの画面で・いつ処理が動くか」を

イベント単位で指定する必要があります。しかし初心者の多くは、

• 一覧・詳細・編集画面の違いが曖昧
• show と submit の役割を混同している

といった状態で書き始めてしまい、「コードは合っているのに動かない」状況に陥ります。

フィールドコード周りでつまずく

kintoneでは、JavaScriptからフィールドを扱う場合、

画面に表示されている名前ではなく「フィールドコード」を使います。

よくあるミスは、

• 表示名をそのままコードに書いてしまう
• 全角・半角や記号の違いに気づかない

サブテーブルの参照方法がわからないといったものです。

書いたコードが反映されない

「値を変更したのに画面が変わらない」という悩みも非常に多いです。

原因の多くは、

• return event; の書き忘れ
• アプリの「更新」をしていない
• スマホ用イベントを書いていない

など、kintone特有のルールを見落としているケースです。

エラーの確認方法がわからない

kintoneのJavaScriptエラーは、画面上にはほとんど表示されません。

そのため、

• エラーが出ていることに気づかない
• どこで止まっているかわからないという状態になりがちです。

まとめ

今回はJavaScriptカスタマイズの基本とイベント一覧を解説しました。

基本を理解すれば、コードも「意味をわかった状態」で使えるようになります。

まずは、よく使うイベントを1つ選び、簡単な表示制御から試してみてください。

その他のkintoneカスタマイズ手法はこちら👇