More than 1 year has passed since last update.

kintoneAdvent Calendar 2020

フィールド値変更イベントで気を付けること

Last updated at 2022-06-22Posted at 2020-12-08

今年もあっという間にアドベントカレンダーの季節がやってまいりましたね。
Qiitaに記事を投稿したことがなかったのですが、自身のアウトプットの練習と備忘録を兼ねて
何か記事を書けたらなということで、アドベントカレンダーに参加をしてみました。

2022年04月05日いただいたコメントを記事に反映いたしました。遅くなり申し訳ございません。

はじめに

Qiita初投稿なのでツッコミどころが多いと思う
上記の通り、備忘録でもあるということ
kintoneカスタマイズ初心者に向けた記事かも？
たぶん既出のネタ

と、記事を書いている本人も思っていますので、ある程度手加減していただけると幸いです。

フィールド値変更イベントとは

基本的なkintoneカスタマイズについてお話をしておくと、
サイボウズ様が用意した kintone JavaScript API を利用して、特定のイベントが動作した際に
カスタマイズ処理を動作させるのが、基本的なカスタマイズの方法だと思います。

その中でも今回は、

レコード追加画面のフィールド値変更時イベント
https://developer.cybozu.io/hc/ja/articles/201941984#step3

レコード編集画面のフィールド値変更時イベント
https://developer.cybozu.io/hc/ja/articles/202166270#step3

についての記事になります。

ざっくりと説明すると、特定のフィールドの値が変わった際に、カスタマイズを動かしたい時に使うイベントです。

フィールド値変更イベントの使い方

例えば、ドロップダウンフィールドと文字列１行フィールドをアプリに配置し、前述のフィールド値変更時イベントのカスタマイズを記述します。

const watch = 'ドロップダウン';
const changeEvent = [
  `app.record.create.change.${watch}`,
  `app.record.edit.change.${watch}`
];

kintone.events.on(changeEvent, event => {
  event.record['文字列'].value = 'ヨシ！'
  return event;
});

そして、レコード追加（編集）画面でドロップダウンフィールドを変更すると・・

文字列フィールドに、カスタマイズで文字が挿入されました。
基本的な使い方としてはこんな感じではないでしょうか。

それでは本題に入ります。

本題

基本的な使い方については先ほど説明した通りですが、ある程度カスタマイズに慣れてくると、もっと応用することもあるかと思います。

例えば、ルックアップの 「ほかのフィールドのコピー」でフィールドの値が変更された時に、フィールド値変更イベントを動作させる。 なんてことも可能ですよね。
ただし、この場合に注意しなければいけないことがある。というのが本題です。

実は、ルックアップの「ほかのフィールドのコピー」でフィールド値変更イベントが動作した場合、ハンドラーの引数に渡されるオブジェクトの中身は、ルックアップのフィールドコピーが完了していないものが格納されています。

例えば、

ルックアップフィールドを用意し「ほかのフィールドのコピー」を設定
「ほかのフィールドのコピー」で設定したフィールドに対して、フィールド値変更イベントのカスタマイズを用意

const watch = '担当者名';
const changeEvent = [
  `app.record.create.change.${watch}`,
  `app.record.edit.change.${watch}`
];

kintone.events.on(changeEvent, event => {
  console.log({ event })
  return event;
});

上記のカスタマイズが実行されると、コンソールに event が出力されます。
※ChromeであればF12キーを押すことで、コンソールが表示できます。

では、ルックアップの取得を行い、カスタマイズを動作させてみましょう。

アプリの画面上では、すべてのグレーアウトしているフィールドに値が入っていますが、
イベント発火時にコンソールに出力されたオブジェクトを見ると、ルックアップの「ほかのフィールドのコピー」が
中途半端にしか動いていない（途中である） ことがわかると思います。

画像の例で言うと、ルックアップの取得により担当者名フィールドに値が入ったタイミングで、カスタマイズが動いているようで、その時点では [郵便番号] ～ [住所] までのフィールドには、値のコピーが実施されていない ということです。

これを知らずに、以下のようなカスタマイズを作ったとします。

イベント発火は [担当者名]フィールド のフィールド値変更イベント
[日報]フィールド に [担当者名] と [住所] の値を入れる

const contact = '担当者名';
const address = '住所';
const changeEvent = [
  `app.record.create.change.${contact}`,
  `app.record.edit.change.${contact}`
];

kintone.events.on(changeEvent, event => {
  console.log({ event })
  event.record['日報'].value = ` 担当者名：${event.record[contact].value} 住所：${event.record[address].value}`;
  return event;
});

これを実行すると、前述の説明の通り、[住所]に値がコピーされる前に動作するため、正しく取得することができません。

じゃあどうするの？

どうやら、このルックアップの値コピーについては、画面上の上から順番に値のコピーを行っている（ような気がする）。
なので、カスタマイズソースを修正せずに対応する場合は [担当者名] を下に移動すること。

なので、[担当者名] を下に移動させると・・

引数に渡されたオブジェクトを見ると、ルックアップの**「ほかのフィールドのコピー」がすべて動いた後**に、
イベントが発火していることがわかります。（担当者名が一番最後にコピーされるはずなので。）
また、先ほどは "undefined" となってしまった [日報] に記載の住所、こちらも正しい値が格納できています。

これでほぼ解決かなと思いますが、

[担当者] が当初の配置場所よりも、下のほうに配置することになった

のが少し気になります。

この場合は、フィールドの配置は以前のままで、イベント発火のきっかけとなるフィールドを
[担当者名] → [住所]
に変更してあげることで解決するのですが、これはこれで
住所が入力されてないレコードをルックアップしたとき動かないじゃん。ということになりますので、どちらかの調整が必要
ということですね。

ここまでをまとめると

フィールド値変更イベントの引数に渡されるオブジェクトは、フィールド構成（配置）とイベント発火方法によっては、値が空になっているケースがある
（ルックアップなどで値がコピーされてイベントが発火した場合）
回避するには、イベント発火のきっかけとなるフィールドを下に持ってくる
もしくは、イベント発火のきっかけとなるフィールドを変更する

と、いうことでしょうか。

フィールド値変更イベントで、もう少し難しいこと（非同期処理）をやる場合は

恐らく、みんなこういうコーディングをしているんじゃないでしょうか。（思い込み）

const contact = '担当者名';
const changeEvent = [
  `app.record.create.change.${contact}`,
  `app.record.edit.change.${contact}`
];

kintone.events.on(changeEvent, event => {
  setReport(); // 非同期の関数を呼び出す
  console.log({ event });
});

const setReport = async () => {
  
  /* なにかしらの非同期処理 */

  const event = kintone.app.record.get();
  event.record['日報'].value = "絶対ヨシ！";
  kintone.app.record.set(event);
}

フィールド値変更イベントでは、Promise が使えないので、ハンドラーでは

return event;

を書かずに、関数を呼び出し、最終的に自分で kintone.app.record.set() を使ってレコードの値を変更する。

kintone.app.record.set(event);

確かにこれで動きます。
動きますが、上記例で言うと、setReport関数がとても速く処理された場合、以下のようなエラーが出ます。

エラーメッセージの通り、

イベントハンドラの処理中は、"kintone.app.record.set()" は使えないよ。
※kintone.app.record.get()も同じ

とのこと。

要はこういう時にエラーが起きるんですね。
イベントハンドラが終了する前に、setReport関数の kintone.app.record.set(event) が実行されている。
setReport関数は非同期関数（async）なので、イベントハンドラで呼び出した際に、setReport関数の終了を待たずに
処理が進んでいますが、イベントハンドラの終了の前に、setReport関数内の kintone.app.record.set(event) が
呼ばれると、上記のようなエラーが発生するようです。

ん？これって

フィールド値変更イベントは Promise に対応していない。
　↓
じゃあ、イベントハンドラで非同期関数呼び出して、イベントハンドラでは何も return しなきゃいいんじゃない？
　↓
概ねうまくいくけど、非同期関数が早く終わり過ぎると、エラーが出る。

・・・

フィールド値変更イベントが Promise に対応するアップデートを待つ
※サイボウズ様、よろしくお願いします。

2022年04月05日更新
次項に解決できるソースコードを記載。

2022年04月05日追記

※すみません、いただいたコメントを記事に反映することを失念していました。遅くなり申し訳ございません。

@wv-sumichan さんからいただいたコメントの通り
以下のように呼び出した関数内で「await」記述することで、呼び出し元のイベントハンドラの終了を待ってから
後続の処理を実行させることができるようです。

const contact = '担当者名';
const changeEvent = [
  `app.record.create.change.${contact}`,
  `app.record.edit.change.${contact}`
];

kintone.events.on(changeEvent, event => {
  setReport(); // 非同期の関数を呼び出す
  console.log({ event });
  return event;
});

const setReport = async () => {

  /* なにかしらの非同期処理 */
  await Promise.resolve(); // 既に完了している非同期処理の完了を待つ

  const event = kintone.app.record.get();
  event.record['日報'].value = "絶対ヨシ！";
  kintone.app.record.set(event);
}

または

const setReport = () => {
  return new Promise((res, rej) => {
    res();
  }).then(() => {
    const event = kintone.app.record.get();
    event.record['日報'].value = "絶対ヨシ！";
    kintone.app.record.set(event);
  });
}

処理の順番としては、

イベントハンドラ内の setReport() が実行される。
setReport関数内の await Promise.resolve() が実行される。
イベントハンドラ内の console.log({ event }) が実行される。
イベントハンドラが終了する。
setReport関数内の const event = kintone.app.record.get(); 以降が実行される。

@wv-sumichan さんありがとうございました。

まとめ

イベントハンドラで同期処理しかないケース（先ほどの再掲）

フィールド値変更イベントの引数に渡されるオブジェクトは、フィールド構成（配置）とイベント発火方法によっては、値が空になっているケースがある
（ルックアップなどで値がコピーされてイベントが発火した場合）
回避するには、イベント発火のきっかけとなるフィールドを下に持ってくる
もしくは、イベント発火のきっかけとなるフィールドを変更する

イベントハンドラで非同期処理があるケース

イベントハンドラで非同期関数を呼び出す
~~イベントハンドラの終了よりも、呼び出した非同期関数が先に終わらないように意識する~~
await や .then を使って、呼び出し元であるイベントハンドラの処理を先に終わらせる。
というところでしょうか。
間違っていたらごめんなさい。

あとがき

記事を書くというのは難しいですね。
普段何気なく Qiita で自分の困りごとを解決してくれる記事を読んだりしますが
記事を投稿するのは結構大変ですね。感謝しかないです。

それと、実は私が所属する会社は CybozuDays 2020 東京に出展し、私自身もブースに立っておりました。
ブースに立ち寄ってくださったみなさま、ありがとうございました。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up