はじめよう kintone API

フィールドの装飾をしてみよう

目次

kintoneのレコードのフィールドの文字色や背景色を変更するといった、フィールドを装飾するユースケースはよくあります。
たとえば、条件付き書式のように特定の条件に一致したときだけフィールドのスタイルを変更するといった例です。
kintoneにはフィールドの装飾に対応するためのkintone JavaScript APIが用意されています。
今回は、kintone JavaScript APIを使ってkintoneのフィールドを装飾する方法や、DOM操作によるkintoneアップデートへの影響について学びます。

カスタマイズを適用するアプリ

固定リンクがコピーされました

アプリストアの 総務への依頼受付 (External link) を使います。

フィールドのスタイルを変更するまでの処理の流れ

固定リンクがコピーされました

レコードのフィールドのスタイルを変更したい場合、次の流れで処理を実装します。

  1. kintone JavaScript APIを使って、フィールドのHTML要素を取得する。
  2. 取得したHTML要素のstyleプロパティを変更する。

とてもシンプルですね。

レコード詳細画面でフィールドのスタイルを変更する

固定リンクがコピーされました

それでは、レコード詳細画面でフィールドのスタイルを変更する方法を見ていきましょう。
実装するのは、レコード詳細画面を表示した後に、チェックボックスフィールド（フィールドコード：Urgent）の文字色を変更するカスタマイズです。
条件付き書式のように、チェックボックスの値に「至急」が選択されていたら、フィールドの文字を赤色かつ太字に変更します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const record = event.record;
    const fieldCode = 'Urgent';

    // フィールドコードが「Urgent」のフィールド要素を取得
    const element = kintone.app.record.getFieldElement(fieldCode);
    // フィールドコードが「Urgent」のフィールドの値を取得
    const urgentFieldValue = record[fieldCode].value;
    // チェックボックスフィールドは配列で値が返ってくるため、至急が含まれているかを確認する
    const hasUrgent = urgentFieldValue.includes('至急');

    if (hasUrgent) {
      // 文字色を赤色にする
      element.style.color = '#ff0000';
      // 太文字にする
      element.style.fontWeight = 'bold';
    }

    return event;
  });
})();

このカスタマイズを適用すると、レコード詳細画面で、「至急」フィールドの「至急」の文字が赤色かつ太文字に変わります。

このカスタマイズのポイントは次の2つです。

  • レコード詳細画面のフィールド要素を取得するAPIを使って、フィールドのHTML要素を取得する。
  • styleプロパティを使ってスタイルを変更する。

レコード詳細画面のフィールド要素を取得する API を使って、フィールドの HTML 要素を取得する

固定リンクがコピーされました

レコード詳細画面で特定のフィールドのHTML要素を取得するには、 レコード詳細画面のフィールド要素を取得する APIのkintone.app.record.getFieldElement()を使います。
APIの引数には、HTML要素を取得したいフィールドのフィールドコードを指定します。

6
7
8
9

    const fieldCode = 'Urgent';

    // フィールドコードが「Urgent」のフィールド要素を取得
    const element = kintone.app.record.getFieldElement(fieldCode);

styleプロパティを使ってスタイルを変更する

固定リンクがコピーされました

kintone.app.record.getFieldElement()の戻り値は、フィールドのHTML要素です。
スタイルの変更は、取得したHTML要素のstyleプロパティを使って行います。

  • 文字色の変更：colorにカラーコードを指定する。
  • 太文字：fontWeightにboldを指定する。
15
16
17
18
19
20

    if (hasUrgent) {
      // 文字色を赤色にする
      element.style.color = '#ff0000';
      // 太文字にする
      element.style.fontWeight = 'bold';
    }

レコード一覧画面でフィールドのスタイルを変更する

固定リンクがコピーされました

次に、レコード一覧画面でフィールドのスタイルを変更する方法を見ていきましょう。
実装するのは、レコード一覧を表示した後に、ステータスフィールド（フィールドコード：ステータス）の文字色を変更するカスタマイズです。
ステータスフィールドの値によって背景色を変更します。

なお、ステータスフィールドは、プロセス管理を有効化することで利用できます。
有効化にする手順は、次のヘルプページを参照してください。
kintone ヘルプ：基本的なプロセス管理を設定する (External link) 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

(() => {
  'use strict';

  kintone.events.on('app.record.index.show', (event) => {
    const records = event.records;
    const fieldCode = 'ステータス';

    // フィールドコードが「ステータス」のフィールド要素を取得
    const elements = kintone.app.getFieldElements(fieldCode);

    elements.forEach((element, i) => {
      // 何行目のレコードかを表す配列のインデックス番号を使って、レコードの値を取得する
      const record = records[i];
      const statusFieldValue = record[fieldCode].value;

      // ステータスフィールドの値によって、背景色を変更する
      switch (statusFieldValue) {
        case '未着手':
          // 赤色にする
          element.style.backgroundColor = '#ff0000';
          break;
        case '処理中':
          // 青色にする
          element.style.backgroundColor = '#0000ff';
          break;
        case '依頼者確認中':
          // 黄色にする
          element.style.backgroundColor = '#ffff00';
          break;
        case '完了':
          // 緑色にする
          element.style.backgroundColor = '#00ff00';
          break;
        default:
          break;
      }
    });

    return event;
  });
})();

このカスタマイズを適用すると、レコード一覧画面で、ステータスの値によって「ステータス」フィールドの背景色が変わります。

このカスタマイズのポイントは次の2つです。

  • レコード一覧画面のフィールド要素を取得するAPIを使って、フィールドのHTML要素を取得する。
  • 繰り返し処理を使って取得した要素のスタイルを変更する。

レコード一覧画面のフィールド要素を取得する API を使って、フィールドの HTML 要素を取得する

固定リンクがコピーされました

レコード一覧画面で、特定のフィールドのHTML要素を取得するには、 レコード一覧画面のフィールド要素を取得する APIのkintone.app.getFieldElements()を使います。
APIの引数には、HTML要素を取得したいフィールドのフィールドコードを指定します。

6
7
8
9

    const fieldCode = 'ステータス';

    // フィールドコードが「ステータス」のフィールド要素を取得
    const elements = kintone.app.getFieldElements(fieldCode);

繰り返し処理を使って取得した要素のスタイルを変更する

固定リンクがコピーされました

レコード詳細画面で使用したAPIとの大きな違いは、kintone.app.getFieldElements()の戻り値がフィールドのHTML要素の配列になっていることです。
そのため、繰り返し処理を使って取得したHTML要素のスタイルを変更します。
背景色を変更するには、取得したHTML要素のstyleプロパティのbackgroundColorに、カラーコードを指定します。

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

    elements.forEach((element, i) => {
      // 何行目のレコードかを表す配列のインデックス番号 i を使って、レコードの値を取得する
      const record = records[i];
      const statusFieldValue = record[fieldCode].value;

      // ステータスフィールドの値によって、背景色を変更する
      switch (statusFieldValue) {
        case '未着手':
          // 赤色にする
          element.style.backgroundColor = '#ff0000';
          break;
        case '処理中':
          // 青色にする
          element.style.backgroundColor = '#0000ff';
          break;
        case '依頼者確認中':
          // 黄色にする
          element.style.backgroundColor = '#ffff00';
          break;
        case '完了':
          // 緑色にする
          element.style.backgroundColor = '#00ff00';
          break;
        default:
          break;
      }
    });

DOM 操作と kintone アップデートの影響

固定リンクがコピーされました

JavaScriptに馴染みがある人は、document.querySelector()などのブラウザーのAPIを使ってkintone製品のHTMLのクラス名を指定し、HTML要素を取得する方法を思い付くかもしれません。
いわゆるDOM操作と呼ばれる方法です。

しかし、DOM操作はkintoneのアップデートに影響を受けやすくなるリスクを伴っています。
kintoneのアップデートで、製品のHTMLの構造が変更される可能性もあるからです。
たとえば、document.querySelector()で製品のHTMLのクラス名を指定していると、アップデートで製品のHTMLのクラス名が変わった場合にHTML要素を取得できなくなります。
スタイル変更が効かなくなるほか、実装方法によってはJavaScriptの実行時にエラーが発生して、カスタマイズ全体が動かなくなることもあります。

アップデートの影響を受けにくいカスタマイズを行うには、kintone APIドキュメントに記載されている方法で実装することが重要です。
たとえば、kintoneの画面のHTML要素を取得するAPIの一覧は、次のページで確認できます。
kintone JavaScript API｜要素の取得
フィールド要素の場合には、スタイル変更のみがAPIドキュメントに準じた方法です。

tips
補足

アップデートの影響を受けにくいカスタマイズの詳細は、次の記事を参考にしてください。
そのカスタマイズ大丈夫？ アップデートの影響を受けにくいカスタマイズ Tips

まとめ

固定リンクがコピーされました

今回は、kintone JavaScript APIを使ってフィールドのスタイルを変更する方法や、DOM操作によるkintoneアップデートへの影響について学びました。

フィールドを装飾することで、ユーザーが見落としてしまいがちな情報を強調表示できます。
また、アップデートの影響を受けにくいカスタマイズ方法は、kintoneカスタマイズを行う上で重要なポイントです。
「ある日突然カスタマイズが動かなくなった！」を防ぐためにも、DOM操作のリスクを理解しておきましょう。

次回は、 イベントオブジェクトを使ったフィールドの値を書き換えてみようについて学習しましょう。