kintoneカスタマイズ開発に携わるエンジニアの皆様に関心の大きなアップデート情報のお知らせです。
現在APIラボ（アップデートオプション）にて検討中の新機能として、ルックアップフィールドにおける『フィールドの値を変更したときのイベント』が追加されました。

本記事では、この待望の新機能の概要から、従来の仕様で発生していた問題点、有効化のステップ、配置の注意点、そして即戦力となる5通りの具体的なアプリカスタマイズ事例までを徹底的に解説します。

1. 新機能：ルックアップフィールドの値変更イベントの概要

今回追加された検討中機能により、ルックアップフィールドそのものの値変更をトリガーにして、JavaScriptによるイベントハンドラーを呼び出せるようになりました。具体的には以下のイベントが新しく発火対象となります。

対象イベント一覧

• PC版:
• app.record.create.change.フィールドコード
• app.record.edit.change.フィールドコード
• モバイル版:
• mobile.app.record.create.change.フィールドコード
• mobile.app.record.edit.change.フィールドコード

イベントの発火タイミング

このイベントが発火するのは、ルックアップの検索キーワードを変更した場合、または選択した参照先レコードが変更されたタイミングです。日常のオペレーションにおける具体的な瞬間は以下の通りです。

1. ユーザーが 【取得】ボタン を押して、参照先レコードを確定したとき
2. ルックアップフィールドの横にある 【クリア】ボタン を押して、値を消去したとき
3. ルックアップフィールドに入力した状態で フォーカスが外れた（Blurした） とき

なお、実行順序として、このイベントは「ルックアップによって自動的に値が代入されるコピー先フィールドの変更イベント」よりも 先に発生する という重要な性質を持っています。

拡張されるオブジェクト情報

イベントオブジェクト内から取得できるルックアップフィールドのデータに、新しく2つのプロパティ confirmed と recordId が追加され、状態の判定が劇的に容易になりました。

プロパティ名	型	概要
value	string	ルックアップフィールドに表示されている文字列（コピー元のキー）
confirmed	boolean	参照先レコードが正常に「確定」しているかどうか（true / false）
recordId	string	参照先（コピー元アプリ）のレコードID（未確定・クリア時は null）

2. ルックアップ値変更が検知できない従来の問題点

これまで、kintoneの標準仕様では「ルックアップフィールドコード」をイベント名に指定して change イベントを登録しても、 change イベントは検知されませんでした。この制約が開発現場において不便や課題を生んでいました。

何が不便だったのか？

• コピー先フィールドに依存する不自然なコード設計:
  ルックアップによる値の変動を検知したい場合、代替策として「ルックアップのコピー先として指定している別フィールドのフィールドコード」を change イベントのターゲットにする必要がありました。これはコードの可読性を下げ、「なぜこのフィールドの変更を監視しているのか」が直感的に伝わりにくい原因となっていました。また、通信環境によるコピー先フィールドの値変更のタイミングのズレにより、期待通りに動作しない不具合の発生リスクもありました。
• 未確定状態の判別が不可能:
  ユーザーがルックアップに文字を入力しただけの段階（未確定）なのか、【取得】ボタンを押して正しくマスターからデータを引っ張ってきた段階（確定）なのかをJavaScript側から安全に判別する方法がありませんでした。そのため、中途半端な状態で処理が走りエラーを引き起こすリスクが常に存在していました。
• 参照先レコードIDの直接取得が困難:
  ルックアップのマスター側のレコードIDそのものを取得したい場合、あらかじめコピー先として「文字列フィールド」等を用意して紐付けておく必要があり、アプリのフィールド数が無駄に増加する要因になっていました。

3. 新機能を利用する場合の注意点と有効化手順

本機能は、現在「検討中の新機能（APIラボ）」として提供されている段階です。そのため、本番環境や開発環境でテストするには、管理者によるオプトイン設定が必要です。

💡【設定手順】検討中機能の有効化

kintoneの管理画面 ＞「システム管理」＞「アップデートオプション」を開き、「検討中の新機能」の項目内にある、該当のルックアップ機能のチェックボックスを有効化して保存します。

⚠️ 既存カスタマイズへの影響に関する注意点

二重発火と上書きのリスク: 本機能を有効化しても、従来の「コピー先フィールドの変更イベント」はそのまま動き続けます。そのため、既存のJavaScriptコードでコピー先イベントを使った処理が残っている場合、新イベントと古いイベントの両方が発火し、意図しないデータの二重書き換えや競合が発生する恐れがあります。移行の際は必ず検証を行ってください。

4. 新機能を使ったアプリカスタマイズの事例

ここからは、新機能である「ルックアップ本体のchangeイベント」と、新たに追加された confirmed、recordId を活用した実務直結のカスタマイズパターンを5つご紹介します。

事例1：確定状態に応じたステータス・備考の自動制御

顧客や商品を選択した直後、その確定状態を捉えて「取得済み」「未確定」などのフラグや、参照先IDを別フィールドへ瞬時に書き出します。

(function () {
  'use strict';
  kintone.events.on(['app.record.create.change.Lookup', 'app.record.edit.change.Lookup'], function (event) {
    const record = event.record;

    if (!record.Lookup.value) {
      record.Status.value = '';
      record.Remark.value = '';
      return event;
    }

    if (record.Lookup.confirmed && record.Lookup.recordId) {
      record.Status.value = '取得済み';
      record.Remark.value = `参照先レコードID: ${record.Lookup.recordId}`;
    } else {
      record.Status.value = '未確定';
      record.Remark.value = '【取得】ボタンを押してください';
    }

    return event;
  });
})();

事例2：ルックアップ確定に連動した別入力欄の編集不可（Disabled）制御

特定のマスター（例：大口顧客など）がルックアップで選択・確定された場合のみ、手動入力を防ぐために特定の入力項目を動的に編集不可にします。クリアされたら再編集可能にします。

(function () {
  'use strict';
  kintone.events.on(['app.record.create.change.Lookup', 'app.record.edit.change.Lookup'], function (event) {
    const record = event.record;

    // 参照先が正しく確定している場合、特定の詳細追記欄をロック
    if (record.Lookup.confirmed && record.Lookup.recordId) {
      record.ManualInputBox.disabled = true;
    } else {
      record.ManualInputBox.disabled = false;
    }

    return event;
  });
})();

事例3：顧客ランクに応じたリアルタイムのエラー表示（バリデーション）

ルックアップ確定直後に、選択された顧客の状況をチェック。特定の条件（未確定状態、または不正な組み合わせ）の場合、保存ボタンを押す前の段階でフィールド下にエラーメッセージを即座に表示します。

(function () {
  'use strict';
  kintone.events.on(['app.record.create.change.Lookup', 'app.record.edit.change.Lookup'], function (event) {
    const record = event.record;

    if (record.Lookup.value && !record.Lookup.confirmed) {
      record.Lookup.error = '検索ワードが変更されています。【取得】ボタンを押して確定させてください。';
    } else {
      record.Lookup.error = null;
    }

    return event;
  });
})();

事例4：参照先ID（recordId）をキーにしたREST APIによるサブテーブル自動コピー

標準のルックアップ機能では、別アプリの「サブテーブル」をコピーしてくることはできません。新機能の recordId を使えば、確定した瞬間にREST APIで該当レコードの最新のサブテーブルデータを取得し、自アプリのサブテーブルに一括挿入する高度な連携がスマートに組めます。

(function () {
  'use strict';
  kintone.events.on(['app.record.create.change.Lookup', 'app.record.edit.change.Lookup'], function (event) {
    const record = event.record;

    if (record.Lookup.confirmed && record.Lookup.recordId) {
      const targetId = record.Lookup.recordId;

      // REST APIで参照先アプリから詳細なテーブルデータを取得する処理
      kintone.api(kintone.api.url('/k/v1/record.json', true), 'GET', {
        app: 99, // 参照先アプリID（例）
        id: targetId
      }).then(function(resp) {
        // 現在の画面にサブテーブルを反映させる応用処理をここに記述
      });
    }

    return event;
  });
})();

事例5：モバイル版（スマートフォン・タブレット）への最適化制御

モバイルでの現場入力において、ルックアップがクリアされた場合に無駄な入力フィールドを非表示、あるいはクリアする処理をモバイル専用イベントで安全に並行記述できます。

(function () {
  'use strict';
  const mobileEvents = [
    'mobile.app.record.create.change.Lookup',
    'mobile.app.record.edit.change.Lookup'
  ];

  kintone.events.on(mobileEvents, function (event) {
    const record = event.record;

    if (!record.Lookup.value) {
      // モバイル特有の画面表示負荷を下げるため、クリア時は関連項目をリセット
      record.MobileNote.value = 'ルックアップがクリアされました。';
    }

    return event;
  });
})();

まとめ

ルックアップフィールドにおける「値変更イベント」の追加は、一見すると小さなアップデートのように思えるかもしれませんが、kintoneカスタマイズの設計思想をよりシンプルかつクリーンに変える大きな進化です。

コピー先フィールドの動向を追いかけるという従来のトリッキーな実装から解放され、ルックアップそのものの確定状態（confirmed）や、ダイレクトに取得できる recordId を活用した、意図の明確なコードへとリファクタリングが可能になります。

現在は「検討中機能」であるため、アップデートオプションでの明示的な有効化と、既存のカスタマイズコードとの競合への注意が必要ですが、今後の標準搭載に向けて今から検証・活用を進めておく価値は極めて高いと言えるでしょう。ぜひ皆さんのアプリアプリ開発でも試してみてください！

🌸 アプリテンプレートの販売

本記事でご紹介しているアプリテンプレートを、下記の料金プランで販売しています。
導入をご希望の方は、各プランの「お申込み／お問い合わせ」ボタンからお問い合わせください。

■ 料金プラン

◆単品販売（買取型）は、導入サポート付きの価格です。
　単品動作タイプは60,000円、２アプリ連携タイプは100,000円、3つ以上連携タイプは150,000円です。
◆簡易サポート契約では、当サイトのアプリテンプレートとプラグインを合計6種類までご利用できます。
◆会員サポート契約では、ご利用範囲「無制限」で運用ヘルプデスク対応までフルサービスでご提供します。

🔨 自分でカスタマイズしてみたい方へ

以下のNote記事で本記事のカスタマイズ事例を紹介しています。
記事内で紹介しているカスタマイズコードは、無料で利用できるので是非挑戦してみて下さい。

「note:アプリ活用研究会（キン活）」は、当サイトのメンバーが執筆しています。

kintoneルックアップ値変更イベントの解説｜アプリ活用研究会（キン活）

2026年6月23日のアップデートの紹介で、ルックアップフィールドにおける『フィールドの値を変更したときのイベント』が追加されていました。 現在APIラボ（アップデートオプション）にて提供されている検討中の新機能です。 2026年6月23日にAPIラボで提供を開始するアップデートの紹介 本記事では、この新機能の概要から、これまでの不便だった点、新機能有効化の手順、そして実務で使える5通りのカスタマイズ事例までを要点を絞って解説します。 1. 新機能：ルックアップフィールドの値…

note.com

🏫 kintone人材育成研修

この様なカスタマイズを自分で出来る様になりたい方は、当サイトの「Kintome人材育成」上級コースの受講をご検討して下さい。当サイトのTIPSで紹介しているカスタマイズ例のテンプレートを使えば、簡単に実装出来ます！
上級コースの受講者には、特典で当サイトのカスタマイズテンプレート（3種類まで）と３か月のサポート契約を無償でご提供しています。

研修目的を「カスタマイズテンプレートのアプリ導入」とする研修メニューもご提案可能です。

📣カスタマイズ・導入支援いたします！

本記事の様な「kintoneアプリのカスタマイズ」をご希望の企業様へ
kintoneを便利に活用できるカスタマイズと運用支援は、ぜひ当社にご相談ください！

#kintone #Javascript #カスタマイズ #lookup #値変更イベント