チュートリアル
はじめに
この記事はプラグインの JavaScript ファイルを作成するチュートリアルです。
例として「スケジュール登録変更画面でメモ項目の文字数を取得してラベルに表示するプラグイン」を作成します。
初級編 chainAPI を使用する
1. スケジュール登録変更画面のインスタンスを取得する
はじめにプラグインの実行対象画面のインスタンスを取得します。
今回はスケジュール登録変更画面で動作するプラグインを作成するため、スケジュール登録変更画面のインスタンスを取得しましょう。esmJSPlugin.screen.sheetSaveを使用してスケジュール登録変更画面のインスタンスを取得することが出来ます。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave('schedule')
2. スケジュール登録変更画面の eventHook を指定する
次にプラグインの実行対象画面がどのような状態になったタイミングで処理を行うかを指定します。
今回はスケジュール登録変更画面に遷移したタイミングから動作するプラグインを作成するため、onEnteredを使用します。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {});
3. メモ項目のインスタンスを取得する
次にプラグインの実行対象となるメモ項目のインスタンスを取得します。
今回はメモ項目に対して処理を行うため、メモ項目のインスタンスを取得しましょう。 getSheetItemを使用してメモ項目のインスタンスを取得することが出来ます。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
});
4. chainAPI でメモ項目の eventHook を指定する
次にプラグインの実行対象のメモ項目がどのような状態になったタイミングで処理を行うかを指定します。
ひとまず、メモ項目の値が初期化されたタイミングで処理を実行するため、onMountedを使用します。 chainAPIを使用して記述してみましょう。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
this.useChainAPI(function (chainAPI) {
chainAPI.onMounted(memoItem); // メモ項目の初期化時に処理を実行
});
});
5. chainAPI でメモ項目のインスタンスメソッドを使用する
次にメモ項目に対してインスタンスメソッドを指定します。 今回はメモ項目のラベルに表示される文字列を変更するため、メモ項目のインスタンスメソッドであるsetLabelを使用します。
メモ項目の文字数はmemoItem.lengthで取得できるので、こちらもあわせて使用します。
chainAPIを使用して記述してみましょう。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
this.useChainAPI(function (chainAPI) {
chainAPI.onMounted(memoItem).setLabel(`メモ（${memoItem.length}文字）`); // メモ項目の初期化時にラベルを変更
});
});
ここで一度プラグインを適用してみると、メモ項目のラベル名に文字数が表示されているのが確認できると思います。
ただ、これではメモ項目の入力内容の変更に対応できていません。変更に対応するためにはもう少し追加で処理を記述する必要があります。
6. onUpdated を使用する
メモ項目の入力内容の変更に対応するためには、onUpdatedを使用します。
入力内容が変更された時に実行したい処理は、初期化時に実行したい処理と同じなので、以下のように記述することができます。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
this.useChainAPI(function (chainAPI) {
chainAPI.onMounted(memoItem).setLabel(`メモ（${memoItem.length}文字）`); // メモ項目の初期化時にラベルを変更
chainAPI.onUpdated(memoItem).setLabel(`メモ（${memoItem.length}文字）`); // メモ項目の更新時にラベルを変更
});
});
これで「スケジュール登録変更画面でメモ項目の文字数を取得してラベルに表示するプラグイン」をchainAPIを使用して作成することが出来ました。
上級編 chainAPI で条件分岐を使用する
上級編では「メモ項目の文字数が 50 より大きい場合ラベルを赤色に変更する処理」をchainAPIの条件分岐を使用して作成します。
初級編 chainAPI を使用するで作成したソースコードに処理を追加していきましょう。
7. if...メソッドを使用する
まずは「メモ項目の文字数が 50 より大きい場合」という条件を指定します。
chainAPIでは if...メソッドを使用することが出来ます。 if...メソッドで指定されたインスタンスメソッドの返り値が真値の場合、直後にチェーンされたメソッドが実行されます。 メモ項目の文字数が任意の数値より大きいかどうかは lengthIsGreaterThanメソッドの返り値で判断することが出来ます。lengthIsGreaterThanの返り値をchainAPIで条件として使用する場合は、接頭辞として if を付与したifLengthIsGreaterThanを使用します。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
this.useChainAPI(function (chainAPI) {
chainAPI
.onMounted(memoItem)
.setLabel(`メモ（${memoItem.length}文字）`)
.ifLengthIsGreaterThan(50); // メモ項目の文字数が50より大きい場合
chainAPI
.onUpdated(memoItem)
.setLabel(`メモ（${memoItem.length}文字）`)
.ifLengthIsGreaterThan(50); // メモ項目の文字数が50より大きい場合
});
});
次に「ラベルを赤色に変更する」処理を記述します。setLabelColorを使用することで項目のラベルの色を変更することが出来ます。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
this.useChainAPI(function (chainAPI) {
chainAPI
.onMounted(memoItem)
.setLabel(`メモ（${memoItem.length}文字）`)
.ifLengthIsGreaterThan(50) // メモ項目の文字数が50より大きい場合
.setLabelColor("red"); // ラベルの色を赤色にする
chainAPI
.onUpdated(memoItem)
.setLabel(`メモ（${memoItem.length}文字）`)
.ifLengthIsGreaterThan(50) // メモ項目の文字数が50より大きい場合
.setLabelColor("red"); // ラベルの色を赤色にする
});
});
これでメモ項目の文字数が 50 より大きい場合ラベルを赤色にすることが出来ました。
しかし、これだけでは文字数を 50 文字以下にした場合もラベルが赤色のままとなってしまいます。
文字数を 50 文字以下にした場合、ラベルの色をデフォルトの色にする処理を追加していきましょう。
8. else メソッドを使用する
chainAPIでは if...メソッドの後に else メソッドを使用することが出来ます。
else メソッドの直後にチェーンしたメソッドは、if...メソッドで指定したインスタンスメソッドの返り値が偽値である場合に実行されます。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
this.useChainAPI(function (chainAPI) {
chainAPI
.onMounted(memoItem)
.setLabel(`メモ（${memoItem.length}文字）`)
.ifLengthIsGreaterThan(50) // メモ項目の文字数が50より大きい場合
.setLabelColor("red") // ラベルの色を赤色にする
.else() // メモ項目の文字数が50より大きくない場合
.setLabelColor(null); // ラベルの色をデフォルトの色にする
chainAPI
.onUpdated(memoItem)
.setLabel(`メモ（${memoItem.length}文字）`)
.ifLengthIsGreaterThan(50) // メモ項目の文字数が50より大きい場合
.setLabelColor("red") // ラベルの色を赤色にする
.else() // メモ項目の文字数が50より大きくない場合
.setLabelColor(null); // ラベルの色をデフォルトの色にする
});
});
これで文字数を 50 文字以下にした場合、ラベルの色をデフォルトの色に変更するプラグインを作成することが出来ました。
番外編 chainAPI を使用せず処理を記述する
上級編では、初級編と同じ「スケジュール登録変更画面でメモ項目の文字数を取得してラベルに表示するプラグイン」を chainAPI を使用せずに実装していきます。
初級編の3. メモ項目のインスタンスを取得するまでで作成したソースコードに処理を追加していきましょう。
9. メモ項目の eventHook を指定する
メモ項目に対して処理を行うタイミングを指定します。
メモ項目が初期化された時と、メモ項目の文字数が変わる度に処理を実行する必要があります。それぞれonMounted、onUpdatedメソッドで指定することが出来ます。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
memoItem.onMounted(function () {}); // メモ項目が初期化された時
memoItem.onUpdated(function () {}); // メモ項目の値が変更された時
});
10. メモ項目のインスタンスメソッドを使用する
メモ項目のラベルに文字数を表示します。
初期化および値の変更時に、実行する処理を、それぞれのコールバック関数内に記述します。
メモ項目のラベルはsetLabelメソッドで変更することが出来ます。
const scheduleSaveScreen = esmJSPlugin.screen.sheetSave("schedule");
scheduleSaveScreen.onEntered(function (screen) {
const memoItem = screen.getSheetItem("calendar.schedule.memo");
memoItem.onMounted(function () {
// メモ項目が初期化された時
const memoLength = memoItem.length;
memoItem.setLabel(`メモ（${memoLength}文字）`); // メモ項目のラベルに文字数を表示する
});
memoItem.onUpdated(function () {
// メモ項目の値が変更された時
const memoLength = memoItem.length;
memoItem.setLabel(`メモ（${memoLength}文字）`); // メモ項目のラベルに文字数を表示する
});
});
これでchainAPIを使用せずに「スケジュール登録変更画面でメモ項目の文字数を取得してラベルに表示するプラグイン」を作成することが出来ました。