kintoneで始めるjavascript入門【全体の構造、events onの紹介】
この記事は、kintone で JavaScript カスタマイズを始めようとされている中でも、JavaScript に詳しくない、またはほとんど触ったことのない方向けの内容になります。
JavaScript そのものの入門記事については、私より詳しい方が解説したものがたくさんあると思いますので、基礎的な変数定義や関数についてはここでは割愛致します。
JavaScript の基礎を押さえていただいた上で、kintone でよく利用するコードやイベントなどを解説していきます。
javascript ファイルの構造
javascript ファイルを取り込む際、多くの場合、以下のような構造になります。
// サンプル：画面上の特定のフィールドを非表示にする
(() => {
'use strict';
/** JavaScriptを実行する対象となるイベント */
const events = ['app.record.create.show', 'app.record.detail.show', 'app.record.edit.show'];
// 処理をイベントに登録します
kintone.events.on(events, (event) => {
// 対象項目を非表示にします
kintone.app.record.setFieldShown('文字列__1行__0', false);
kintone.app.record.setFieldShown('文字列__1行__1', false);
kintone.app.record.setFieldShown('文字列__1行__2', false);
return event;
});
})();全体をざっくりと説明すると、以下の通りです。
// ↓ 定義した変数の使用できる範囲を限定する(おまじない)
(() => {
// ↓ エラーを気付きやすくする(おまじない)
'use strict';
// ↓ 定義した処理が実行されるタイミングを指定
const events = ['...'];
// ↓ 処理をあらかじめ登録しておく
kintone.events.on(events, (event) => {
// --------------------------------------
// ⛅ 実際の処理はここに記載 ⛅
// --------------------------------------
return event;
});
})();全体を覆っている(() => .... })();の部分と'use strict;'に関しては、「カスタマイズを行う際は必ず記載する」という認識で問題ありません。
それぞれ重要な役割がありますが、覚える優先度は低いです。
(() => .... })();はこのページの最後で説明しているので、気になる方は先にご覧ください。
このページでは、前述したコードを例として解説を進めていきます。
kintone.events.on について
kintone の javascript カスタマイズを使う上で欠かせないのが kintone.events.on 関数です。これは、アプリのどの画面で javascript を適用したいかを設定することができます。
kintone.events.on を使用せず、そのまま記述することもできますが、そうした場合は、対象アプリのあらゆる画面で javascript が適用されます。
「編集画面でだけ動作させたい」
「印刷時の画面レイアウトだけ修正したい」
など、部分的に適用させるためにも、余分な負荷をかけないためにも、kintone.events.on 関数の使用は javascript カスタマイズを行う上で重要となります。
具体的な使い方の紹介です。
kintone.events.on(events, func);- events (文字列または配列) : 後述する関数を実行させたい画面を指定します。
- func (関数) : events で指定した画面で実際に実行する関数を指定します。
javascript は記述方法の自由度が高いので、一度変数に定義してから関数を実行しても良いですし、リテラルと無名関数を利用しても良いです。
// 変数に定義する場合
(() => {
'use strict';
/** JavaScriptを実行する対象となるイベント */
const events = ['app.record.create.show', 'app.record.detail.show', 'app.record.edit.show'];
const func = (event) => {
// 対象項目を非表示にします
kintone.app.record.setFieldShown('文字列__1行__0', false);
kintone.app.record.setFieldShown('文字列__1行__1', false);
kintone.app.record.setFieldShown('文字列__1行__2', false);
return event;
};
// 処理をイベントに登録します
kintone.events.on(events, func);
})();(() => {
'use strict';
kintone.events.on(
['app.record.create.show', 'app.record.detail.show', 'app.record.edit.show'],
(event) => {
// 対象項目を非表示にします
kintone.app.record.setFieldShown('文字列__1行__0', false);
kintone.app.record.setFieldShown('文字列__1行__1', false);
kintone.app.record.setFieldShown('文字列__1行__2', false);
return event;
}
);
})();上記 2 点より、大枠の即時関数と、events.on 関数は定型的に使用して、その中でコードを記述する。という認識で問題ないかと思います。以下のコードを使いまわすイメージです。
(() => {
'use strict';
// ↑↑これ以前は常にコピペ↑↑
/** JavaScriptを実行する対象となるイベント */
const events = [
// ここに実行したい画面(トリガー)
];
const func = function (event) {
// ここに実行したいコード
};
// ↓↓これ以降は常にコピペ↓↓
// 処理をイベントに登録します
kintone.events.on(events, func);
})();アプリレコードの各フィールドの操作について
JavaScript カスタマイズが必要となるのは、多くの場合レコード内の特定のフィールドを操作したい時になると思います。
JavaScript から現在のレコード情報を取得する方法は主に以下の 3 つです。
- kintone.events.on のコールバック関数に含まれる引数から取得する
- kintone.app.record.get から取得する
- REST API を使って取得する
今回は 1 と 2 について説明します。
kintone.events.on のコールバック関数から取得する
kintone の第二引数に指定するコールバック関数では、引数としてオブジェクトを取得できます。
このオブジェクトでは、実行時点のレコード情報をはじめ、様々な環境情報を取得することができます。
以下のコードでは、受け取ったオブジェクトから実行時点のレコード情報を取得しています。
kintone.events.on('app.record.edit.show', (event) => {
/** 実行時点のレコード情報 */
const currentRecord = event.record;
return event;
});取得したレコードの各フィールドの値を修正することで、変更が反映されます。
kintone.events.on('app.record.edit.show', (event) => {
/** 実行時点のレコード情報 */
const currentRecord = event.record;
currentRecord['文字列__1行__0'].value = 'JavaScriptによって変更されました';
return event;
});注意が必要なのは、変更が反映されるのは、コールバック関数から受け取った引数が返却されたタイミングだというところです。
ですので前述のコードでいうと、return event;を記述していないと変更が反映されません。
kintone.app.record.get から取得する
次に、kintone.app.record.get()を使用して取得するケースです。こちらは主に、イベントを登録したタイミングとは別のタイミングのレコードを取得する際に使用します。
以下のコードは、レコード編集時にスペースフィールドにボタンを設置し、ボタンがクリックされた際に処理を動かすサンプルです。
kintone.events.on('app.record.edit.show', (event) => {
/** 設置するボタン */
const button = document.createElement('button');
/** アプリ設定で作成したスペース情報 */
const space = kintone.app.record.getSpaceElement('space_id');
// ボタンを設置
space.append(button);
// ボタンクリック時のイベントを登録
button.addEventListener('click', (clickEvent) => {
// ボタンクリック時点のレコードを取得
const current = kintone.app.record.get();
// フィールドを修正
current.record['文字列__1行__0'].value = 'JavaScriptによって変更されました';
// 変更を適用
kintone.app.record.set(current);
});
return event;
});サンプルコード
「じゃあやりたいことを実現するためにはどうすればいいの？」となってしまわないよう、いくつか具体的なサンプルコードを用意しました。
コード全体を覆っているファンクション
コード全体を覆っている、
(() => {
//・・・略・・・
})();の部分について説明します。これは即時関数と言い、書かなくても挙動に影響はありません。
なぜ記述するのかというと、kintone には今回利用する javascript API の他にも、標準で動作している javascript など複数の js ファイルが動作しています。
そのため、複数 js 間で同じ変数・定数が定義されていると、定義が重複してしまい予期しない動作になる危険性があります。
即時関数は書かなくても動作しますが、書いておくことで、その中で定義された変数・定数のスコープを限定することができます。
これにより、いわゆるグローバル汚染を避けることができ、それぞれの js ファイルが想定される動作を実現することができます。
また、即時関数については、別の記事でも詳細をまとめておりますので、詳しく知りたい方はご一読ください。
