kintone API

アンチパターンから学ぶ 条件書式の実装(詳細・編集・追加画面)

目次

はじめに

レコードの追加・編集・詳細画面で、フィールドの値に応じて背景色を変えたり、期限が近いフィールドを赤くしたりする「条件書式」を実装することがあります。 こうしたスタイル変更のカスタマイズには、一見動作しているように見えても、リスクを抱える実装パターンが存在します。

この記事では、フィールドのスタイルを変更するカスタマイズについて、以下の2つを解説します。

  • アンチパターンとそのリスク
    たとえば、DOM操作でスタイルを変更するカスタマイズは、ある日突然kintoneのUI刷新で動作しなくなるリスクや、モバイル対応の困難さといった課題を抱えています。
  • 推奨される実装方法とその利点
    スタイルを設定・取得するAPIを使用することで、DOM構造に依存しない安全なスタイル制御を可能にしたり、モバイル対応がしやすくなります。

アンチパターンと推奨される実装方法を、サンプルコードを交えて比較しながら紹介します。 既存のカスタマイズのリスク確認や、新たに実装する際の参考にしてください。

information

一覧画面のスタイル制御については、以下の記事を参照してください。
アンチパターンから学ぶ 条件書式の実装(一覧画面)

今回紹介するAPI

API 概要
kintone.app.record.setFieldStyle() フィールドのスタイルを設定
kintone.app.record.getFieldStyle() フィールドのスタイルを取得

次の画像はレコード詳細画面で、期限日を過ぎたフィールドにスタイルを適用し、入力欄を赤く強調した例です。

この見た目を、DOM操作で実現する方法と、APIで実現する方法の2つのアプローチで比較します。

サンプルコードでは、以下のフィールドを使用しています。

フィールド名 フィールドコード フィールドタイプ
期限日 期限日 日付
重要度 重要度 ドロップダウン

アンチパターン1:getElementsByClassName()のDOM操作によるスタイル変更

フィールドの見た目を変更する方法として、document.getElementsByClassName()でkintoneのDOM要素を直接操作するパターンがあります。

warning
注意

以下のコードはAPIを使った実装に置き換えることが推奨される書き方です。
新規のカスタマイズでは、後述するsetFieldStyle()を使用してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// 非推奨: この書き方は setFieldStyle() を使った実装への置き換えを推奨します
(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const deadline = new Date(event.record['期限日'].value);
    const today = new Date();

    if (deadline < today) {
      // kintoneのDOM要素をクラス名で直接取得
      const fields = document.getElementsByClassName('control-value-gaia');
      for (const field of fields) {
        if (field.textContent.includes(event.record['期限日'].value)) {
          field.style.backgroundColor = '#ffcccc';
          field.style.color = '#cc0000';
          field.style.fontWeight = 'bold';
        }
      }
    }

    return event;
  });
})();

このアプローチには以下のリスクがあります。

リスク 説明
DOM構造への完全な依存 control-value-gaiaのようなクラス名はkintoneが実装上の都合でつけた名前であり、外部からの利用を想定していません。
フロントエンド刷新によって予告なく変更される可能性があり、カスタマイズの動作が停止するリスクを伴います。
また、DOM要素のスタイルを直接変更することには以下のリスクもあります。
・kintoneの標準機能が動作しなくなる可能性がある
・イベントの発行タイミングでDOMが再描画された際に、適用したスタイルがリセットされる
フィールドの特定が困難 クラス名だけではどのフィールドかを判別できないため、テキスト内容との突き合わせなど不安定な方法に頼る必要があります。
その結果、意図しないフィールドにスタイルが適用されるリスクがあります。
たとえば上記のサンプルでは、期限日と同じ値をもつ別のフィールドが存在する場合、そのフィールドにもスタイルが適用されてしまいます。
スタイルの復元が煩雑 条件変更時、元のスタイルへ戻すには変更前の値を自前で保持する必要があります。
管理が煩雑になるにつれて、コードが難読化して、バグが混入するリスクが高まります。
モバイル非対応 PC版とモバイル版ではDOM構造が異なるため、スタイル操作のコードを別途書く必要があります。
管理するコードが増えることで、保守コストの増大やバグが混入するリスクが高まります。
レコード追加/編集画面での制約 レコード追加/編集画面ではDOM構造が詳細画面と異なるため、同じセレクターで要素を取得できず、予期せぬ動作を起こすリスクがあります。
そのため、画面ごとにDOM操作のコードを書き分ける必要が生じ、コードが難読化してバグが混入するリスクが高まります。

アンチパターン2:getFieldElement()のDOM操作によるスタイル変更

フィールドの見た目を変更する別の方法として、kintone.app.record.getFieldElement()でkintoneのDOM要素を直接操作するパターンもあります。

warning
注意

以下のコードはsetFieldStyle()を使った実装に置き換えることが推奨される書き方です。
新規のカスタマイズでは、後述するsetFieldStyle()を使用してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
// 非推奨: この書き方は setFieldStyle() を使った実装への置き換えを推奨します
(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const deadline = new Date(event.record['期限日'].value);
    const today = new Date();

    if (deadline < today) {
      // getFieldElement()でフィールドのDOM要素を取得
      const fieldEl = kintone.app.record.getFieldElement('期限日');
      if (fieldEl) {
        fieldEl.style.backgroundColor = '#ffcccc';
        fieldEl.style.color = '#cc0000';
        fieldEl.style.fontWeight = 'bold';
      }
    }

    return event;
  });
})();

前述のアンチパターン1とは違い、クラス名に依存せずDOM要素を取得できます。
しかしながら、このアプローチには以下のリスクがあります。

リスク 説明
標準機能への悪影響 取得した要素の内部構造を直接変更すると、kintoneの標準機能が動作しなくなるリスクがあります。
今は動作していても、kintoneのアップデート後も動作するとは限りません。
スタイルの意図しないリセット イベントの発行タイミングでDOMが再描画された際に、適用したスタイルがリセットされるリスクがあります。
レコード追加/編集画面での制約 getFieldElement()はレコード追加/編集画面では使用できないため、それらの画面でのスタイル制御には対応できません。
対応するにはアンチパターン1で紹介したクラス名によるDOM操作を併用する必要があり、そのリスクも合わせて抱えることになります。

後述のsetFieldStyle()を使った実装でこれらのリスクを回避できます。

推奨される実装方法:setFieldStyle()によるスタイル制御

kintone.app.record.setFieldStyle()を使用することで、フィールドコードとスタイル設定のオブジェクトを渡すだけでスタイルを適用できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', async (event) => {
    const deadline = new Date(event.record['期限日'].value);
    const today = new Date();

    if (deadline < today) {
      await kintone.app.record.setFieldStyle('期限日', {
        content: {
          backgroundColor: '#ffcccc',
          color: '#cc0000',
          fontWeight: 'bold'
        }
      });
    }

    return event;
  });
})();

DOM操作によるスタイル変更と比較して、以下の点が改善されています。

改善点 説明
DOM構造に依存しない フィールドコードを指定するだけで、kintoneが適切な範囲にスタイルを適用します。
フロントエンド基盤の変更に影響を受けません。
スタイルの復元が簡単 'DEFAULT'を指定するだけで、すべてのスタイルを初期状態に戻せます。
変更前の値を自前で保持する必要はありません。
レコード追加/編集/詳細画面で利用可能 画面ごとにDOM操作のコードを書き分ける必要がなく、同じAPIでスタイル制御ができます。
フィールドコードで対象を特定 DOM要素の探索やテキスト内容の突き合わせが不要です。
フィールドコードを指定するだけで、対象のフィールドに確実にスタイルを適用できます。
PC/モバイルで統一されたAPI PC版はkintone.app.record.setFieldStyle()、モバイル版はkintone.mobile.app.record.setFieldStyle()です。
スタイル設定のオブジェクト構造は同じため、コードを書き分ける必要がありません。

スタイル設定APIの使い方

ここでは、setFieldStyle()でできることをさらに詳しく説明します。設定できるプロパティの種類、スタイルの解除方法に加えて、getFieldStyle()と組み合わせた使い方も紹介します。

setFieldStyle()で設定できるプロパティ

setFieldStyle()では、フィールドの入力要素(content)、フィールド背景(background)、フィールド名(label)の3つの領域に対してスタイルを設定できます。
各領域で指定可能なプロパティの詳細は、以下を参照してください。
setFieldStyle()のAPIリファレンス

スタイルの適用の解除

各プロパティに'DEFAULT'を指定すると、そのプロパティだけ初期状態に戻せます。
フィールド全体のスタイルを一括で初期化するには、第2引数に文字列'DEFAULT'を渡します。

1
2
3
4
5
6
7
8
9
// 特定のプロパティだけ初期化
await kintone.app.record.setFieldStyle('期限日', {
  content: {
    backgroundColor: 'DEFAULT' // 背景色だけ戻す
  }
});

// フィールド全体のスタイルを初期化
await kintone.app.record.setFieldStyle('期限日', 'DEFAULT');

getFieldStyle()で現在のスタイルを確認する

getFieldStyle()を使えば、現在適用されているスタイルを取得できます。
setFieldStyle()で設定したプロパティは、そのままgetFieldStyle()の戻り値に反映されます。
リセット済みのプロパティは値が'DEFAULT'として返されます。

このしくみを利用すると、「すでにスタイルが適用されていたら解除する」というトグルパターンも実装できます。
次のコードは、クリックするたびに重要度フィールドのラベルスタイルが切り替わるボタンを配置しています。

 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
(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const spaceEl = kintone.app.record.getSpaceElement('space');
    if (!spaceEl) {
      return event;
    }

    const button = document.createElement('button');
    button.textContent = 'ハイライト切替';
    button.onclick = async () => {
      const currentStyle = await kintone.app.record.getFieldStyle('重要度');
      const labelColor = currentStyle?.label?.color;
      const isHighlighted = labelColor !== undefined && labelColor !== 'DEFAULT';

      if (isHighlighted) {
        await kintone.app.record.setFieldStyle('重要度', 'DEFAULT');
      } else {
        await kintone.app.record.setFieldStyle('重要度', {
          label: {
            color: '#cc0000',
            fontWeight: 'bold',
            textDecoration: 'underline'
          }
        });
      }
    };

    spaceEl.appendChild(button);
    return event;
  });
})();

実装時に押さえておきたいこと

APIを使用する際に知っておきたい制限事項、非同期処理やモバイル対応について案内します。事前に把握しておくことで、実装後のトラブルを未然に防げます。

APIの制限事項

対応フィールドと指定可能なプロパティ

setFieldStyle()には、対応していないフィールドやcontentを設定できないフィールドなどの制約があります。
また、DOM操作では任意のCSSプロパティを設定できましたが、APIではcontentbackgroundlabelの領域ごとに指定可能なプロパティが決まっています。
詳細は以下を参照してください。
フィールドのスタイルの設定 - 制限事項

一覧画面のスタイル制御

setFieldStyle()はレコードの追加・編集・詳細画面で使用するAPIです。
表形式の一覧画面でのスタイル制御にはsetRecordListStyle()/getRecordListStyle()を使用してください。
詳しくは以下の記事を参照してください。
アンチパターンから学ぶ 条件書式の実装(一覧画面)

非同期処理の活用について

setFieldStyle()getFieldStyle()は非同期なAPIです。
async/awaitを使用して処理してください。
詳しくは次のページを参照してください。

モバイル版での利用について

モバイル版ではkintone.mobile名前空間のAPIを使用してください。

PC版 モバイル版
kintone.app.record.setFieldStyle() kintone.mobile.app.record.setFieldStyle()
kintone.app.record.getFieldStyle() kintone.mobile.app.record.getFieldStyle()

まとめ

  • setFieldStyle()で、DOM操作に頼らずフィールドのスタイルを制御できます。
  • getFieldStyle()で、現在のスタイルを取得し、トグルや条件分岐に活用できます。
  • フィールドコードで対象を特定するため、DOM構造への依存を排除し、kintoneのUI刷新に影響を受けない保守性の高いカスタマイズを実現できます。

フィールドのスタイル制御APIを使用することで、kintoneカスタマイズの信頼性が向上します。
条件書式のカスタマイズでは積極的にこれらのAPIを活用してください。

getFieldStyle()setFieldStyle()については、以下の記事も参考にしてください。
setFieldStyleを使ってフィールドの見た目を動的に変更する

information

このTipsは、2026年4月版kintoneで動作を確認しています。