全体の構造とevents.on

この記事は、kintone で JavaScript カスタマイズを始めようとされている中でも、JavaScript に詳しくない、またはほとんど触ったことのない方向けの内容になります。

JavaScript そのものの入門記事については、私より詳しい方が解説したものがたくさんあると思いますので、基礎的な変数定義や関数についてはここでは割愛致します。

JavaScript の基礎を押さえていただいた上で、kintone でよく利用するコードやイベントなどを解説していきます。

まずは動かしてみましょう

説明に入る前に、実際に kintone で JavaScript カスタマイズがどのように動作するのかを体験してみましょう。

以下のコードをコピーして、sample.jsのように拡張子を.jsに設定し、ファイルに保存してください。

(() => {
  'use strict';

  const events = ['app.record.detail.show'];

  kintone.events.on(events, (event) => {
    alert(`現在表示しているレコードのIDは『${event.recordId}』です。`);
    return event;
  });
})();

保存したファイルを kintone のアプリにアップロードします。反映方法については、Cybozu のドキュメントを参照してください。

カスタマイズの設定

アップロードが完了したら、アプリのレコードを開いてみましょう。

レコード詳細画面を開いた直後に、アラートが画面上に表示されます。

このように、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 つです。

1. kintone.events.on のコールバック関数に含まれる引数から取得する
2. kintone.app.record.get から取得する
3. 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;
});

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 ファイルが想定される動作を実現することができます。

また、即時関数については、別の記事でも詳細をまとめておりますので、詳しく知りたい方はご一読ください。

Javascript の即時関数と省略記法【先頭の！やカッコの意味】