kintoneで始めるjavascript入門【全体の構造、events onの紹介】
2021-11-30
2021-9-2
この記事は、kintoneでjavascriptカスタマイズを始めようとされている中でも、javascriptに詳しくない、またはほとんど触ったことのない方向けに作成しました。
ただ、javascriptそのものの入門記事については、私より詳しい方が解説したものがたくさんあると思いますので、基礎的な変数定義や関数についてはここでは割愛致します。
javascriptの基礎を押さえていただいた上で、kintoneでよく利用するコードやイベントなどを解説していきます。
javascriptファイルの構造
javascriptファイルを取り込む際、多くの場合、以下のような構造になります。
// サンプル：画面上の特定のフィールドを非表示にする
(function() {
'use strict';
// 対象イベントを設定します
var events = [
'app.record.create.show',
'app.record.detail.show',
'app.record.edit.show'
];
// 処理をイベントに登録します
kintone.events.on(events, function(event) {
// 対象項目を非表示にします
kintone.app.record.setFieldShown('文字列__1行__0', false);
kintone.app.record.setFieldShown('文字列__1行__1', false);
kintone.app.record.setFieldShown('文字列__1行__2', false);
});
})();上記のコードを例として解説していきます。
コード全体を覆っているファンクション
まず、コード全体を覆っている、
(function() {
//・・・略・・・
})();の部分について説明します。これは即時関数と言い、書かなくても挙動に影響はありません。
なぜ記述するのかというと、kintoneには今回利用するjavascript APIの他にも、標準で動作しているjavascriptなど複数のjsファイルが動作しています。
そのため、複数js間で同じ変数・定数が定義されていると、定義が重複してしまい予期しない動作になる危険性があります。
即時関数は書かなくても動作しますが、書いておくことで、その中で定義された変数・定数のスコープを限定することができます。
これにより、いわゆるグローバル汚染を避けることができ、それぞれのjsファイルが想定される動作を実現することができます。
また、即時関数については、別の記事でも詳細をまとめておりますので、詳しく知りたい方はご一読してみてください。
Javascriptの即時関数と省略記法【先頭の！やカッコの意味】
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は記述方法の自由度が高いので、一度変数に定義してから関数を実行しても良いですし、リテラルと無名関数を利用しても良いです。
// 変数に定義する場合
(function() {
'use strict';
// 対象イベントを設定します
var events = [
'app.record.create.show',
'app.record.detail.show',
'app.record.edit.show'
];
var func = function(event) {
// 対象項目を非表示にします
kintone.app.record.setFieldShown('文字列__1行__0', false);
kintone.app.record.setFieldShown('文字列__1行__1', false);
kintone.app.record.setFieldShown('文字列__1行__2', false);
};
// 処理をイベントに登録します
kintone.events.on(events, func);
})();(function() {
'use strict';
kintone.events.on([
'app.record.create.show',
'app.record.detail.show',
'app.record.edit.show'
], function(event) {
// 対象項目を非表示にします
kintone.app.record.setFieldShown('文字列__1行__0', false);
kintone.app.record.setFieldShown('文字列__1行__1', false);
kintone.app.record.setFieldShown('文字列__1行__2', false);
});
})();上記2点より、大枠の即時関数と、events.on関数は定型的に使用して、その中でコードを記述する。という認識で問題ないかと思います。以下のコードを使いまわすイメージです。
(function() {
'use strict';
// ↑↑これ以前は常にコピペ↑↑
// 対象イベントを設定します
var events = [
// ここに実行したい画面
];
var 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のコールバック関数から取得する
これはどういうことかというと、以下のコードのeventにあたる部分からレコードを取得するということです。
kintone.events.on("app.record.edit.show", function (event) {
// 実行時点のレコード情報
var currentRecord = event.record;
return event;
});取得したレコードの各フィールドの値を修正することで、変更が反映されます。
kintone.events.on("app.record.edit.show", function (event) {
// 実行時点のレコード情報
var 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", function (event) {
// ボタンを作成
var button = document.createElement("button");
// アプリ設定で作成したスペース情報を取得
var space = kintone.app.record.getSpaceElement("space_id");
// ボタンを設置
space.append(button);
// ボタンクリック時のイベントを登録
button.onclick = function (clickEvent) {
// ボタンクリック時点のレコードを取得
var current = kintone.app.record.get();
// フィールドを修正
current.record["文字列__1行__0"].value = "JavaScriptによって変更されました";
// 変更を適用
kintone.app.record.set(current);
};
return event;
});サンプルコード
「じゃあやりたいことを実現するためにはどうすればいいの？」となってしまわないよう、いくつか具体的なサンプルコードを用意しました。