---
title: "kintone一覧カスタマイズの実装手順｜JavaScriptで色分け・ボタン・独自ビューを作る"
url: "https://www.issoh.co.jp/tech/details/18885/"
published: 2026-10-25
updated: 2026-10-25
categories: ["業務システム"]
publisher: "株式会社一創"
---

# kintone一覧カスタマイズの実装手順｜JavaScriptで色分け・ボタン・独自ビューを作る

kintoneの一覧画面は、表示フィールドや絞り込み・並び順までは画面操作で設定できますが、値に応じた色分けやメニューへのボタン追加、独自レイアウトの一覧はJavaScriptの出番です。2026年4月の定期メンテナンスで、表形式の一覧にスタイルを当てる専用APIが加わり、色分けの書き方は大きく変わりました。この記事では、一覧表示イベントの仕様、setRecordListStyleによる条件付き色分け、ボタン配置と絞り込み条件の受け渡し、カスタマイズビュー、cli-kintoneでの適用までを、cybozu developer networkの一次情報とコピーして動かせるコードで解説します。

## まとめ｜kintone一覧カスタマイズは公式APIだけで組むのが長持ちの条件

一覧画面のカスタマイズは、`app.record.index.show`イベントの中で公式のJavaScript APIを呼ぶ構成が基本です。色分けは2026年4月追加の`kintone.app.setRecordListStyle()`、ボタンは`kintone.app.getHeaderMenuSpaceElement()`、絞り込み条件の受け渡しは`kintone.app.getQueryCondition()`と使う部品が決まっています。

避けるべきはkintone内部のclass名やDOM構造を直接たどる書き方です。公式のコーディングガイドラインは、id・class属性やDOM構造が予告なく変わると明記しています。適用はcli-kintoneの`customize apply`でコード管理に乗せ、要件が複数アプリへ広がった段階でプラグイン化か外注を検討する、という順番が手戻りの少ない進め方です。

## kintoneの一覧画面をJavaScriptでカスタマイズする前の前提と準備

コードを書き始める前に、標準機能で済む範囲か、契約と権限の条件を満たすか、そしてイベントがいつ発火するかを確認しておきます。kintone自体の選定や料金体系から検討している段階なら、親ガイドの[kintoneでできること・料金・内製判断の解説](https://www.issoh.co.jp/column/details/15084/)が前提整理に向いています。

### 標準の一覧設定で足りる範囲とJavaScriptが必要になる境界の見分け方

一覧の設定画面でできるのは、表示するフィールドと列順、絞り込み条件、ソート順、表示形式（表・カレンダー・カスタマイズ）の選択までです。ここで要件が満たせるなら、コードは書かないほうが保守は楽になります。

JavaScriptが必要になるのは、次のような要件が出たときです。

- ステータスや期限の値に応じて、セルの文字色や背景色を変えたい
- 一覧のメニュー横に、表示中のレコードを処理するボタンを置きたい
- 絞り込み結果の件数や合計を、ページ送りに関係なく表示したい
- カード型や集計表など、表形式とは別のレイアウトで見せたい

どれにも当たらない「見た目を少し整えたい」程度の要望は、まず列の並べ替えと一覧の分割で解決できないかを試すのが先です。

### スタンダードコース以上・システム管理権限など契約と権限の前提

JavaScript／CSSによるカスタマイズは、[kintoneの料金ページ](https://kintone.cybozu.co.jp/price/)で拡張機能の項目にまとめられており、スタンダードコースとワイドコースで利用でき、ライトコースは非対応です（2026年10月時点）。ライトコースで一覧の色分け要件が出た場合は、コース変更の費用を含めて判断する順番になります。

権限面では、アプリの「JavaScript／CSSでカスタマイズ」にファイルを登録するにはアプリ管理権限が要ります。表示形式「カスタマイズ」の一覧を作成・編集する場合は、[カスタマイズビューのTips](https://cybozu.dev/ja/kintone/tips/development/customize/record-list-customize/customize-view-using-getquery/)にあるとおりkintoneシステム管理権限が必要です。現場担当者だけで進めると、ここで作業が止まりがちです。

### app.record.index.showが発火するタイミングとイベントオブジェクト

一覧画面のカスタマイズはほぼすべて、[レコード一覧画面を表示した後のイベント](https://cybozu.dev/ja/kintone/docs/js-api/events/idx/index-show-event/)（PCは`app.record.index.show`、モバイルは`mobile.app.record.index.show`）から始まります。発火するのは最初の表示時だけではありません。ページ送り、絞り込み条件の適用、カテゴリーの変更、表形式での列ソートのたびに再実行されます。

| プロパティ       | 表形式（list） | カレンダー形式（calendar） | カスタマイズ（custom）  |
| ----------- | --------- | ----------------- | --------------- |
| records     | レコードの配列   | 日付キーのオブジェクト       | ページネーション有効時のみ配列 |
| offset／size | 数値        | null              | 無効時は0           |
| date        | null      | 表示中の月             | null            |

処理の冒頭で`event.viewType`と`event.viewId`を見て、対象外の一覧では何もせず`event`を返すのが定石です。再実行される前提で、要素の追加処理は二重に走っても壊れない形にしておきます。

## レコード一覧の行と列をsetRecordListStyleで条件付きに色分けする手順

値に応じた色分けは、一覧カスタマイズで最も依頼の多い要件です。2026年4月を境に推奨される書き方が変わったので、古い記事のコードをそのまま写す前に違いを押さえておきます。

### 2026年4月追加の色分けAPIと従来のセル要素取得APIの使い分け

[2026年4月12日のkintone APIアップデート](https://cybozu.dev/ja/kintone/news/api-updates/2026-04/)で、表形式の一覧のスタイルを変更・取得する`kintone.app.setRecordListStyle()`と`getRecordListStyle()`が追加されました（モバイル版も同時追加）。それまでは[getFieldElements](https://cybozu.dev/ja/kintone/docs/js-api/app/get-record-list-field-elements/)でセルの要素を取り、`style`属性を直接書き換える方法が一般的でした。

現在のgetFieldElementsのリファレンスは、フィールドのスタイル変更にはスタイル設定APIを使うよう推奨し、要素の内部構造を変えるとバージョンアップ後に動かなくなる可能性があると注記しています。新規に書くならsetRecordListStyle一択です。getFieldElementsは、セル内にアイコンを差し込むなど、スタイル指定では表現できない装飾に限って使うのが妥当な線引きです。

### ステータスと期限で一覧を色分けするサンプルコードと設定値の書き方

次のコードは、ステータスが「未着手」のセルを赤の太字にし、期限を過ぎたレコードの期限セルに背景色を付けます。フィールドコード「ステータス」「期限」は自分のアプリに合わせて置き換えてください。

```
(() => {
  'use strict';
  // 端末のローカル日付をYYYY-MM-DD形式で作る（toISOStringはUTCになるため使わない）
  const d = new Date();
  const today = [d.getFullYear(), String(d.getMonth() + 1).padStart(2, '0'), String(d.getDate()).padStart(2, '0')].join('-');

  kintone.events.on('app.record.index.show', async (event) => {
    if (event.viewType !== 'list' || event.records.length === 0) {
      return event;
    }
    const body = event.records.map((record) => {
      const style = [];
      if (record['ステータス'].value === '未着手') {
        style.push({ columnType: 'FIELD', column: 'ステータス', content: { color: '#d32f2f', fontWeight: 'bold' } });
      }
      if (record['期限'].value && record['期限'].value < today) {
        style.push({ columnType: 'FIELD', column: '期限', background: { backgroundColor: '#fff3e0' } });
      }
      return { recordId: record.$id.value, style };
    }).filter((row) => row.style.length > 0);

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

[setRecordListStyleのリファレンス](https://cybozu.dev/ja/kintone/docs/js-api/app/set-record-list-style/)によると、引数の`body`はレコードIDごとに列のスタイルを持つ配列で、色は6桁の16進カラーコードで指定します。戻り値はPromiseなので`await`で待ち、全スタイルを外すときは文字列`'DEFAULT'`を渡してください。日付フィールドの値は`YYYY-MM-DD`形式の文字列なので、同じ形式の文字列同士で比較できます。

### setRecordListStyleで装飾できないフィールドと表示崩れの注意点

PC版では、関連レコード・グループ・罫線・ラベル・スペース・テーブル内のフィールドにスタイルを当てられません。リッチエディターとテーブルは文字装飾（content）が非対応で、ラジオボタンとチェックボックスは枠線色と背景色の設定が効きません。

もう1つ紛らわしいのが`content.backgroundColor`と`content.borderColor`で、これはインライン編集中にだけ反映される設定です。通常表示のセル背景を変えたいときは、上のコードのように`background.backgroundColor`を使います。リファレンスには、装飾の組み合わせによって軽微な表示崩れが起きうること、製品アップデートで装飾範囲が変わる可能性があることも書かれています。色を3色以上に増やす前に、利用者が意味を覚えられるかを確認しておくほうが運用を安定させやすいでしょう。

## 一覧のメニュー右側へボタンを置き絞り込み条件を処理に渡す実装

一覧に「この条件のレコードを処理する」ボタンを置く要件では、配置場所の取得と、表示中の絞り込み条件の受け渡しがセットになります。

### getHeaderMenuSpaceElementでボタンを配置し増殖を防ぐ書き方

[kintone.app.getHeaderMenuSpaceElement()](https://cybozu.dev/ja/kintone/docs/js-api/app/get-record-list-header-menu-element/)は、一覧のメニュー（集計アイコン）の右側の要素を返すPC専用のAPIです。前述のとおり一覧表示イベントはソートやページ送りのたびに再実行されるため、何も考えずに`appendChild`するとボタンが1つずつ増えていきます。

[公式のボタン配置Tips](https://cybozu.dev/ja/kintone/tips/development/customize/record-list-customize/add-buttons-to-record-list/)は、ボタンに固有のidを付け、`document.getElementById()`で既に存在すれば処理を抜ける方法で増殖を防いでいます。idは他のカスタマイズと衝突しないよう、`issoh-count-button`のように接頭辞を付けた名前にしておくと安全です。

### getQueryConditionで絞り込み条件を取りREST APIで件数を数える例

次のコードは、メニュー右側にボタンを置き、押すと現在の絞り込み条件に一致する全件数をREST APIで取得して表示します。画面の表示件数やページ位置に関係なく、条件に合う総数が分かります。

```
(() => {
  'use strict';
  const BUTTON_ID = 'issoh-count-button';

  kintone.events.on('app.record.index.show', (event) => {
    if (document.getElementById(BUTTON_ID) !== null) {
      return event; // 再実行時はボタンを足さない
    }
    const button = document.createElement('button');
    button.id = BUTTON_ID;
    button.textContent = '条件に一致する件数';
    button.addEventListener('click', async () => {
      const condition = kintone.app.getQueryCondition(); // order by／limit／offsetを含まない
      const resp = await kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', {
        app: kintone.app.getId(),
        query: `${condition} limit 1`,
        fields: ['$id'],
        totalCount: true
      });
      window.alert(`${resp.totalCount}件`);
    });
    kintone.app.getHeaderMenuSpaceElement().appendChild(button);
    return event;
  });
})();
```

[getQueryCondition](https://cybozu.dev/ja/kintone/docs/js-api/app/get-record-list-query/)は絞り込み条件だけを返し、未絞り込みなら空文字列です。並び順や表示範囲まで欲しいときは、`limit`・`offset`・`order by`を含めて返す[getQuery](https://cybozu.dev/ja/kintone/docs/js-api/app/get-record-list-query-with-order-by-limit-offset/)を使います。[複数のレコードを取得するAPI](https://cybozu.dev/ja/kintone/docs/rest-api/records/get-records/)は1回最大500件、`offset`の上限は10,000件で、`totalCount`の戻り値は数値ではなく文字列です。合計金額のように全件の値が要る処理へ広げる場合は、この上限を超える前提でカーソルAPIを使う設計に切り替えます。

なお、削除済みのユーザーや選択肢を含む絞り込み条件では、getQueryCondition自体がエラーになります。古い一覧設定を引き継いだアプリでは、ボタンが無反応に見える原因になりやすい箇所です。

## カスタマイズビューでHTMLの独自一覧を作り特定の一覧だけに適用する

表形式では表現できないレイアウト、たとえば勤続年数の一覧表や予算と実績の集計表は、表示形式「カスタマイズ」の一覧（カスタマイズビュー）で作ります。

### 表示形式「カスタマイズ」とページネーション設定の関係と使い分け

一覧の設定で表示形式に「カスタマイズ」を選ぶと、入力したHTMLが一覧画面のデータ表示部分に置き換わります。HTMLには行を差し込む`tbody`などの枠だけを書き、中身はJavaScriptで埋める分担です。

分かれ目は「ページネーションを表示する」のチェックです。有効にすると、イベントオブジェクトの`records`に表示中のレコードが入り、標準のページ送りもそのまま使えます。無効にすると`records`は空配列になるため、REST APIで自前に取得する実装が必要です。全件を集計する表なら無効、通常の一覧を見た目だけ変えたいなら有効、と選ぶと実装量が最小になります。

### event.viewIdで対象の一覧を判定しほかの一覧へ影響させない書き方

アプリに登録したJavaScriptは、そのアプリの全一覧で読み込まれます。[任意のカスタマイズビューだけに適用するTips](https://cybozu.dev/ja/kintone/tips/development/customize/record-list-customize/display-employee-tenure-list-custom-view/)と同じく、冒頭で`event.viewId`を比較し、対象外なら即座に`event`を返します。

```
const TARGET_VIEW_ID = 5520001; // 実際の値はconsole.log(event.viewId)で確認する

kintone.events.on('app.record.index.show', (event) => {
  if (event.viewId !== TARGET_VIEW_ID) {
    return event;
  }
  const tbody = document.getElementById('issoh-view-body');
  tbody.textContent = '';
  event.records.forEach((record) => {
    const tr = document.createElement('tr');
    ['社員番号', '氏名', '入社日'].forEach((code) => {
      const td = document.createElement('td');
      td.textContent = record[code].value; // innerHTMLではなくtextContentで差し込む
      tr.appendChild(td);
    });
    tbody.appendChild(tr);
  });
  return event;
});
```

カスタマイズビューのHTML欄には、`<table><tbody id="issoh-view-body"></tbody></table>`のように、JavaScriptが参照するidを付けた枠を書いておきます。一覧IDは環境ごとに変わるため、検証環境から本番へ移すときは定数も移行先の一覧IDへ書き換えてください。レコードの値は`innerHTML`ではなく`textContent`で差し込むと、入力値に含まれる記号がHTMLとして解釈される事故を防げます。

## cli-kintoneで一覧カスタマイズのJavaScriptとCSSを適用・管理する手順

ファイルを画面からアップロードする運用は、どの版がどのアプリに入っているかが追えなくなります。コマンドで適用し、マニフェストとコードをGitで管理する形に早めに寄せておきます。

### customize-manifest.jsonの設定項目と一覧への適用手順

[cli-kintoneのカスタマイズ適用チュートリアル](https://cybozu.dev/ja/kintone/tutorials/hello-cli-kintone/customize/)（cli-kintone 1.19.1と2026年3月版kintoneで動作確認）では、次の形式のマニフェストを用意します。モバイル用のファイルが無くても、空の配列を書く必要があります。

```
{
  "scope": "ALL",
  "desktop": {
    "js": ["./js/list-style.js", "./js/count-button.js"],
    "css": ["./css/list.css"]
  },
  "mobile": {
    "js": [],
    "css": []
  }
}
```

適用は`cli-kintone customize apply --base-url https://example.cybozu.com/ --app 123 --username <ログイン名> --password <パスワード> --input customize-manifest.json`の形で実行します。`customize init`で空のマニフェストを作り、`customize export`で既存アプリの適用内容をマニフェストとして書き出せるので、画面から入れてきた既存カスタマイズの棚卸しにも使えます。

### customize-uploaderからcli-kintoneへ移す際に確認する2点

以前の定番だったcustomize-uploaderは、2026年2月版の定期メンテナンスで同等機能がcli-kintoneに入り、2026年8月版の定期メンテナンスで保守終了と案内されています。既存プロジェクトで確認するのは2点です。

1. npm scriptsやCIに残る`kintone-customize-uploader`の呼び出しを、`cli-kintone customize apply`へ置き換える
2. マニフェストのファイルパスと`scope`が、置き換え後も同じ意味で解釈されるかを検証環境で1回適用して確かめる

本番アプリへいきなり適用せず、`customize export`で現状を書き出してから差分を見るのが安全です。検証用のkintone環境は、cybozu developer networkの開発者ライセンスで用意できます。

検証環境の用意から、環境変数で接続先を切り替えて本番へ反映するまでの流れは、[kintone開発環境の作り方（開発者ライセンスとcli-kintone）](https://www.issoh.co.jp/tech/details/18887/)にまとめています。

## 一覧カスタマイズを自作で続けるかプラグイン化・外注するかの判断基準

一覧カスタマイズは最初の1本が手軽なぶん、気づくとアプリごとに少しずつ違うコードが散らばります。どこで書き方を改め、どこで作り方を変えるかは、あらかじめ条件で決めておくとよいでしょう。手段の全体像や費用相場から比べたい場合は、判断側の[kintoneカスタマイズ・開発の手段と費用相場、内製外注の判断](https://www.issoh.co.jp/column/details/15784/)を併せて読むと位置づけが分かります。

### DOMのclass名に依存したカスタマイズがアップデートで壊れる失敗パターン

よくある失敗は、ブラウザの開発者ツールで見つけた`.recordlist-row-gaia`のようなkintone内部のclass名をセレクタにして、行の色や列幅を変える書き方です。動いているうちは問題が見えませんが、[kintoneコーディングガイドライン](https://cybozu.dev/ja/kintone/docs/guideline/coding-guideline/)はid・class属性とDOM構造が予告なく変わると明記しており、月例の定期メンテナンス後に一斉に崩れる原因になります。

既存アプリにこの種のコードが残っているなら、色分けはsetRecordListStyleへ、ボタン配置はgetHeaderMenuSpaceElementへ置き換えるのが先決です。CSSも、自分で作った要素に付けたidやclassだけを対象にします。公式APIで置き換えられない装飾は、「アップデートで消えても業務が止まらないか」で残すか捨てるかを決めます。

### 一覧カスタマイズの自作を続ける条件とプラグイン化・外注へ切り替える目安

自作のJavaScriptで続けてよいのは、対象が1〜2アプリで、フィールドコードを直書きしても差し替えが数分で済み、コードを読める担当者が社内に1人以上いる場合です。この条件なら、本記事のコードをcli-kintoneで管理するだけで十分に回ります。

切り替えを考えるのは、同じ色分けを5アプリ以上へ展開したい、フィールドコードや色を管理者が画面から変えられるようにしたい、基幹システムとのデータ連携が絡む、のいずれかに当たったときです。設定画面付きのプラグインにすれば、コードを触らずにアプリごとの条件を変えられます。作り方は[kintoneプラグイン開発のmanifest構成から配布までの手順](https://www.issoh.co.jp/tech/details/15327/)で手順ごとに確認できる構成です。社内に担い手がいない、または要件が複数部署にまたがる場合は、一創の[kintoneプラグイン開発](https://www.issoh.co.jp/service/erp%5Fcrm/kintone-plugin/)で、既存カスタマイズの棚卸しからプラグイン化まで相談できます。

## よくある質問

kintoneの一覧カスタマイズについて、実装前によく出る疑問に答えます。

### kintoneの一覧画面で行全体の背景色を変えられますか？

setRecordListStyleは列単位でスタイルを指定する仕組みなので、行全体を塗りたい場合は、そのレコードの表示中の全フィールド列に同じ`background.backgroundColor`を指定します。関連レコードやテーブル内フィールドなど非対応の列は塗れません。内部のclass名を使って行要素を直接塗る方法は、アップデートで崩れるため避けてください。

### 一覧のカスタマイズはモバイル版にも反映されますか？

自動では反映されません。モバイルは`mobile.app.record.index.show`イベントと`kintone.mobile.app.setRecordListStyle()`など別のAPIを使い、マニフェストの`mobile`側にファイルを登録します。メニュー右側にボタンを置くgetHeaderMenuSpaceElementはPC専用で、モバイルではヘッダー下側の要素を返す別APIを使います。

### カスタマイズビューで100件を超えるレコードを表示できますか？

表示できます。ページネーションを有効にした場合は、標準のページ送りで全件を辿れる仕組みです。ページネーションを無効にしてREST APIで取得する場合は、1回の取得上限が500件、`offset`の上限が10,000件なので、件数が多いアプリではカーソルAPIで分割取得する実装にします。

### JavaScriptを書かずに一覧の色分けはできませんか？

標準の一覧設定には条件付き書式がないため、色分けにはJavaScriptかプラグインが必要です。要件が「ステータスごとに色を変える」程度なら、既製のプラグインで足りるかを先に確かめ、足りない条件が出てから自作に進む順番が早道です。いずれを選ぶ場合も、スタンダードコース以上で利用することを前提に検討してください。

### 一覧カスタマイズが突然動かなくなったときはどこを確認しますか？

まずブラウザの開発者ツールのコンソールでエラーを確認します。多い原因は、フィールドコードの変更、絞り込み条件に削除済みの選択肢やユーザーが残っていること、内部class名に依存した記述が定期メンテナンスで効かなくなったことの3つです。cybozu developer networkのAPIアップデート情報で、直近の変更点も照合してください。

## 関連記事

- [kintoneカスタマイズ・開発とは？できること・手段・費用相場と内製外注の判断](https://www.issoh.co.jp/column/details/15784/)：一覧カスタマイズを含むkintone拡張の手段と費用を比べる判断ガイド
- [kintoneプラグイン開発とは｜manifest構成から配布・内製外注の判断まで](https://www.issoh.co.jp/tech/details/15327/)：一覧の色分けやボタンを設定画面付きのプラグインへ移すときの実装手順
- [kintoneのデータ連携を実装視点で選ぶ｜4方式の判定表とAPI制限の設計](https://www.issoh.co.jp/tech/details/17178/)：一覧のボタンから外部システムへデータを送る処理を設計するときのAPI制限の考え方
- [kintoneの無料プラグインはどこまで使える？選び方と有償・自作へ切り替える境界](https://www.issoh.co.jp/column/details/18145/)：条件書式などを自作する前に、既製プラグインで足りるかを見極める材料
- [kintoneとは？できること・料金・プラグインからノーコードで内製する判断まで解説](https://www.issoh.co.jp/column/details/15084/)：kintoneの機能・料金・コース差を確認する親ガイド

---

出典: [kintone一覧カスタマイズの実装手順｜JavaScriptで色分け・ボタン・独自ビューを作る](<https://www.issoh.co.jp/tech/details/18885/>)（株式会社一創）