kintone.app.getFormFields()を使って、フィールドコードのハードコーディングをなくそう

Posted at 2026-06-24

はじめに

kintoneのカスタマイズを書いていると、このようなコードを書く場面があります。

const fieldCodes = ['name', 'email', 'phone'];

フィールドコードを直接コードに書く、ハードコーディングです。
手軽ではありますが、アプリでフィールドコードを更新するたびに、コードを書き直す必要があります。

こうした問題を避けるためには、フィールド情報をカスタマイズの実行時にAPIで取得します。
REST APIのフィールドを取得するを使う場合は、次のように書きます。

const params = { app: kintone.app.getId() };
const resp = await kintone.api(
  kintone.api.url('/k/v1/app/form/fields', true), 'GET', params
);
const fields = resp.properties;

2025年7月のアップデートで追加された kintone.app.getFormFields() を使うと、同じフィールド情報をAPIコール数を消費せずに取得できます。
kintone REST APIには、1日に実行できるAPIリクエスト数（スタンダードコース：10,000件、ワイドコース：100,000件）があります。
JavaScript APIの getFormFields() はこのリクエスト数を消費しないため、画面表示のたびにフィールド情報を取得するようなカスタマイズでも、上限を気にせず使えます。

const fields = await kintone.app.getFormFields();

本記事では、getFormFields()を使って、従来のREST APIよりも手軽にフィールド情報を取得する方法を紹介します。

動作イメージ

レコード一覧画面に、数値フィールドを選ぶドロップダウンと合計値を表示する。
ドロップダウンの選択肢は、getFormFields() で取得した数値フィールドから自動生成する。
フィールドを選ぶと、表示中のレコードを対象に合計を計算して表示する。
アプリに数値フィールドを追加・削除しても、ドロップダウンの選択肢が自動で追従する。

kintoneアプリの準備

今回は、次のフィールドを持つ売上管理アプリを例にして紹介します。

フィールドタイプ	フィールド名	フィールドコード
文字列（1行）	案件名	`deal_name`
ドロップダウン	商品カテゴリ	`category`
数値	売上金額	`amount`
数値	数量	`quantity`
日付	受注日	`order_date`

`getFormFields()`でフィールド構成を取得

getFormFields()は、いま開いているアプリのフィールド情報を一括で取得するAPIです。
引数は不要で、戻り値はPromiseで返されます。
フィールドコードをキーとしたオブジェクトが、Promise解決時に得られます。
各フィールドの設定が、フィールドコードごとに格納されています。

const fields = await kintone.app.getFormFields();
console.log(fields);
// {
//   amount:    { type: 'NUMBER', code: 'amount', label: '売上金額', unit: '円', ... },
//   deal_name: { type: 'SINGLE_LINE_TEXT', code: 'deal_name', label: '案件名', ... },
//   quantity:  { type: 'NUMBER', code: 'quantity', label: '数量', unit: '', ... },
//   ...
// }

各フィールドはtype（フィールドの種類）、code（フィールドコード）、label（フィールド名）などを持ちます。
数値フィールドであれば unit（単位記号）も含まれます。
これらを活用すれば、動作イメージのように「数値フィールドだけをドロップダウンの選択肢にし、表示名にはフィールド名（label）を使う」といった処理を、フィールドコードを直接コードに書かなくても実現できます。

サンプルコード

このコードはエラーハンドリングを省いた動作確認用のサンプルです。
集計方法は合計のみに対応しています。

/*
 * Copyright (c) 2026 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
*/
(() => {
  'use strict';

  kintone.events.on('app.record.index.show', async (event) => {
    // すでに描画済みなら一度削除して再描画する
    const existing = document.getElementById('sum-container');
    if (existing) existing.remove();

    // フィールド情報を取得し、数値フィールドだけを抽出する
    const fields = await kintone.app.getFormFields();
    const numberFields = Object.values(fields)
      .filter((field) => field.type === 'NUMBER');

    if (numberFields.length === 0) return event;

    // ドロップダウンを生成（フィールドコードを値、フィールド名を表示名に使う）
    const select = document.createElement('select');
    numberFields.forEach((field) => {
      const option = document.createElement('option');
      option.value = field.code;
      option.textContent = field.label;
      select.appendChild(option);
    });

    const totalDisplay = document.createElement('span');
    totalDisplay.style.marginLeft = '8px';

    const container = document.createElement('div');
    container.id = 'sum-container';
    container.appendChild(select);
    container.appendChild(totalDisplay);
    kintone.app.getHeaderMenuSpaceElement().appendChild(container);

    // 表示中レコードの合計を計算して表示する
    const updateTotal = () => {
      const selectedCode = select.value;
      const sum = event.records.reduce((total, record) => {
        const field = record[selectedCode];
        return total + (field ? Number(field.value || 0) : 0);
      }, 0);
      const unit = fields[selectedCode].unit ? ` ${fields[selectedCode].unit}` : '';
      totalDisplay.textContent = `合計: ${sum.toLocaleString()}${unit}`;
    };

    select.addEventListener('change', updateTotal);
    updateTotal(); // 初期表示

    return event;
  });
})();

なお、数値フィールドであっても集計対象から除外したい場合は、filter の条件にフィールドコードの指定を追加することで制御できます。

実際に利用する際は、try-catchによるエラーハンドリングや、デザインの調整を行ってください。
また、getHeaderMenuSpaceElement() で取得した要素は、kintoneのアップデートにより見た目が変わる場合があります。

サンプルコードのポイント

このコードのポイントは、フィールドコード・フィールド名・単位をコードに書いていないことです。
集計対象の絞り込みは、type === 'NUMBER'で行い、ドロップダウンの表示名はlabel、単位はunitのように、すべてgetFormFields()の戻り値から得ています。
売上金額を選ぶと「合計：964,000 円」、数量を選ぶと「合計：56」のように、フィールドに応じた単位付きで合計が表示されます。

この書き方のメリットは、アプリのフィールドが変更されても自動で追従できることです。
例えば、売上管理アプリに「原価」という数値フィールドを追加すると、コードを更新する必要なく、ドロップダウンの選択肢に自動的に「原価」が追加されます。
フィールドコードを直接コードに書いていた場合は、次のようにフィールド追加や変更をするたびに書き直す必要が出てきます。

// ハードコーディングした場合：フィールドを追加・変更するたびに、この配列を書き直す
const targetFields = [
  { code: 'amount', label: '売上金額', unit: '円' },
  { code: 'quantity', label: '数量', unit: '' },
  // 「原価」を追加したら、ここにも追記しないと選択肢に出ない
];

あわせて知っておきたいkintone JavaScript APIの紹介

getFormFields()と同じ要領で、レイアウト / 一覧 / グラフの設定もkintone JavaScript APIで取得できます。

◼︎`kintone.app.getFormLayout()`

フォームのレイアウトを取得する（REST API）と同等の情報をJavaScript APIで取得できます。
行・グループ・テーブルなどの構造と並び順が配列で返されます。

◼︎`kintone.app.getViews()`

一覧の設定を取得する（REST API）の代わりに使えます。
ただし取得できるのは type・builtinType・name・idなどの基本情報のみで、絞り込み条件などは含まれません。
詳細な設定が必要な場合はREST APIを使います。

◼︎`kintone.app.getReports()`

アプリのグラフの設定を取得する（REST API）の代わりに使えます。
ただし取得できるのは name・id・chartType・periodicReportなどの基本情報のみで、集計方法や絞り込み条件などは含まれません。
詳細な設定が必要な場合はREST APIを使います。

REST APIとJavaScript APIの使い分け

大まかな使い分けの基準は次のとおりです。

	REST API	JavaScript API
対象アプリ	任意のアプリ（アプリIDを指定）	現在開いているアプリのみ
APIコール数	消費する	消費しない
記述量	URL・パラメータの組み立てが必要	メソッド1つで取得できる
速度	やや遅い（サーバー通信が発生する）	やや速い（追加の通信がない）

現在開いているアプリの設定を取得する用途であれば、JavaScript APIが手軽です。
APIコール数を消費しない点も、リクエスト数の上限を気にするカスタマイズではメリットになります。
一方、別アプリの設定を取得したい場合はREST APIを使います。

ただし、前のセクションで紹介した通り、取得できるプロパティがREST APIより少ないJavaScript APIもあります。
どのプロパティが取得できるかは、各APIのドキュメントで確認してください。

おわりに

本記事では、kintone.app.getFormFields() を使って、フィールド情報をREST APIより手軽に取得し、フィールドコードのハードコーディングをなくす方法を紹介しました。

あわせて紹介した getFormLayout()・getViews()・getReports() も同じ要領で使えます。

アプリ設定をコードに書かないことで、アプリ側の変更にカスタマイズが自動で追従し、メンテナンスのコストも下げられます。ぜひ活用してみてください！

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

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up