チュートリアル

はじめようkintone API

戻る

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

目次

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

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

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

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

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

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

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

  1. フィールドの値から、スタイルを変更する条件を判定する。
  2. レコード詳細画面ではkintone.app.record.setFieldStyle()、レコード一覧画面の場合はkintone.app.setRecordListStyle()を使って、フィールドコードとスタイルを指定する。

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

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

それでは、レコード詳細画面でフィールドのスタイルを変更する方法を見ていきましょう。
実装するのは、レコード詳細画面を表示した後に、チェックボックスフィールド（フィールドコード：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', async (event) => {
    const record = event.record;
    const fieldCode = 'Urgent';
    // フィールドコードが「Urgent」のフィールドの値を取得
    const urgentFieldValue = record[fieldCode].value;
    // チェックボックスフィールドは配列で値が返ってくるため、至急が含まれているかを確認する
    const hasUrgent = urgentFieldValue.includes('至急');

    if (hasUrgent) {
      // 文字色を赤色、太字にする
      await kintone.app.record.setFieldStyle(fieldCode, {
        content: {
          color: '#ff0000',
          fontWeight: 'bold'
        }
      });
    }

    return event;
  });
})();

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

  • レコード詳細画面のフィールドのスタイルを変更するAPIを使う。
  • setFieldStyle()で文字色と太字を指定する。
レコード詳細画面のフィールドのスタイルを変更するAPIを使う

レコード詳細画面で特定のフィールドのスタイルを変更するには、 フィールドのスタイルの設定 のkintone.app.record.setFieldStyle()を使います。
第1引数はフィールドコード、第2引数はスタイル設定のオブジェクトを指定します。
このAPIは非同期なAPIのため、async/awaitを使って呼び出します。

12
13
14
15
16
17
18
19
20

    if (hasUrgent) {
      // 文字色を赤色、太字にする
      await kintone.app.record.setFieldStyle(fieldCode, {
        content: {
          color: '#ff0000',
          fontWeight: 'bold'
        }
      });
    }
setFieldStyle()で文字色と太字を指定する

setFieldStyle()では、フィールドのコンテンツに対するスタイルをcontentに指定します。

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

    if (hasUrgent) {
      // 文字色を赤色、太字にする
      await kintone.app.record.setFieldStyle(fieldCode, {
        content: {
          color: '#ff0000',
          fontWeight: 'bold'
        }
      });
    }

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

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

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

なお、ステータスフィールドは、プロセス管理を有効化することで利用できます。
有効化にする手順は、次のヘルプページを参照してください。
基本的なプロセス管理の設定 (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
42
43
44
45
46
47
48
49
50
51
52
53
54
55

(() => {
  'use strict';

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

    records.forEach((record) => {
      const statusFieldValue = record[fieldCode].value;
      let backgroundColor;

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

      if (backgroundColor) {
        body.push({
          recordId: record.$id.value,
          style: [{
            columnType: 'FIELD',
            column: fieldCode,
            background: {
              backgroundColor
            }
          }]
        });
      }
    });

    if (body.length > 0) {
      await kintone.app.setRecordListStyle({body});
    }

    return event;
  });
})();

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

  • レコード一覧画面のフィールドのスタイルを変更するAPIを使う。
  • レコードごとにスタイル設定を組み立て、適用する。
レコード一覧画面のフィールドのスタイルを変更するAPIを使う

レコード一覧画面でフィールドのスタイルを変更するには、 レコードの一覧（表形式）のスタイルの設定 のkintone.app.setRecordListStyle()を使います。
スタイルを適用するレコードは、HTML要素の並び順ではなくレコードIDで指定します。
このAPIは非同期なAPIのため、async/awaitを使って呼び出します。

49
50
51

    if (body.length > 0) {
      await kintone.app.setRecordListStyle({body});
    }
レコードごとにスタイル設定を組み立て、適用する

レコード詳細画面で使用したAPIとの大きな違いは、一覧に表示されている複数レコードへまとめてスタイルを指定することです。
各レコードのスタイルはbody配列に追加し、最後にsetRecordListStyle()へ渡します。
背景色を変更する場合は、backgroundのbackgroundColorへカラーコードを指定します。

 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
42
43
44
45
46
47

    records.forEach((record) => {
      const statusFieldValue = record[fieldCode].value;
      let backgroundColor;

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

      if (backgroundColor) {
        body.push({
          recordId: record.$id.value,
          style: [{
            columnType: 'FIELD',
            column: fieldCode,
            background: {
              backgroundColor
            }
          }]
        });
      }
    });

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

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

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

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

フィールドのHTML要素を取得するAPI（getFieldElement()やgetFieldElements()）を使い、取得した要素のstyleプロパティを直接書き換える方法も、同様にアップデートの影響を受けやすいです。
フィールドのスタイル変更には、次のAPIを使ってください。

tips
補足

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

まとめ

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

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

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

次回は、 レコード詳細画面にボタンを配置してみよう について学習しましょう。

公式コミュニティ

kintone開発者同士で質問や知見を共有し、学び合うことができます。