5
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@ashinohitoooinkintone

【Part2】kintoneのget系APIで画面UIの「今」の状態を読み取ろう！

5
Posted at

はじめに

Part1では、show系APIを使ってUIパーツの表示／非表示を切り替える方法を解説しました。

show系APIの活用やアクセス件の設定により非表示になったUIパーツは、get系APIで今の状態を確認することが出来ます。

2025年7月以降、より多くのget系APIが追加され、さまざまなUIパーツの今の状態をkintone JavaScript APIを使って読み取れるようになりました。
本記事（Part2）では、その中でも「UIパーツの状態取得系API」を使って、画面UIの今の状態を読み取ってから制御する安全な実装パターンを解説します。

UIパーツの状態取得系API一覧（2026年5月時点）

UIパーツの状態取得系APIを、PC版とモバイル版それぞれまとめました。
各APIの詳細は、cybozu developer networkの公式ドキュメントを参照してください。
kintone JavaScript API

PC版

2026年5月時点、PC版のUIパーツの状態取得系APIの一覧表です。
対象UIパーツが分からない場合は、次を参照してください。
Part1のPC版の画像の赤枠

API 対象UIパーツ 有効な画面
kintone.app.getAddRecordButtonDisplayState() レコードの追加ボタン 一覧／詳細／グラフ画面
kintone.app.getAppSettingsButtonDisplayState() アプリの設定ボタン 一覧／詳細／グラフ画面
kintone.app.getDescriptionDisplayState() アプリの説明 一覧／詳細／追加／編集／グラフ画面
kintone.app.getFilterButtonDisplayState() 絞り込みボタン 一覧／グラフ画面
kintone.app.getOptionsButtonDisplayState() アプリのオプションボタン 一覧／詳細／グラフ画面
kintone.app.getReportButtonDisplayState() 集計ボタン 一覧／グラフ画面
kintone.app.getReportSelectorItemsDisplayState() グラフを選択するパーツの選択肢 一覧／グラフ画面
kintone.app.getViewAndReportSelectorDisplayState() 一覧とグラフ選択パーツ 一覧／グラフ画面
kintone.app.getViewSelectorItemsDisplayState() 一覧を選択するパーツの選択肢 一覧／グラフ画面
kintone.app.record.getActionButtonDisplayState() アプリのアクションボタン 詳細画面
kintone.app.record.getChangeAssigneeButtonDisplayState() 「現在の作業者を変更」ボタン 詳細画面
kintone.app.record.getDuplicateRecordButtonDisplayState() レコードの再利用ボタン 詳細画面
kintone.app.record.getEditRecordButtonDisplayState() レコードの編集ボタン 詳細画面
kintone.app.record.getPagerDisplayState() 前／次のレコードに移動するボタン 詳細画面
kintone.app.record.getSideBarDisplayState() サイドバー 詳細／編集画面
kintone.app.record.getStatusActionButtonDisplayState() プロセス管理のアクションボタン 詳細画面

モバイル版

2026年5月時点、モバイル版のUIパーツの状態取得系APIの一覧表です。
対象UIパーツが分からない場合は、次を参照してください。
Part1のモバイル版の画像の赤枠

API 対象UIパーツ 有効な画面
kintone.mobile.app.getAddRecordButtonDisplayState() レコードの追加ボタン 一覧画面
kintone.mobile.app.getFilterButtonDisplayState() 絞り込みボタン 一覧画面
kintone.mobile.app.getOptionsButtonDisplayState() アプリのオプションボタン 詳細画面
kintone.mobile.app.getReportSelectorDisplayState() グラフを選択するパーツ グラフ画面
kintone.mobile.app.getReportSelectorItemsDisplayState() グラフを選択するパーツの選択肢 グラフ画面
kintone.mobile.app.getViewSelectorDisplayState() 一覧を選択するパーツ 一覧画面
kintone.mobile.app.getViewSelectorItemsDisplayState() 一覧を選択するパーツの選択肢 一覧画面
kintone.mobile.app.record.getActionButtonDisplayState() アプリのアクションボタン 詳細画面
kintone.mobile.app.record.getEditRecordButtonDisplayState() レコードの編集ボタン 詳細画面
kintone.mobile.app.record.getPagerDisplayState() 前／次のレコードに移動するボタン 詳細画面
kintone.mobile.app.record.getStatusActionButtonDisplayState() プロセス管理のアクションボタン 詳細画面

ユースケース（UIパーツの今の状態を確認してから制御する）

ユースケース1：ユーザーの権限に応じて表示されるボタンに合わせて説明を表示する

kintone初心者ユーザー向けに「どのボタンが何をするのか」を画面内で案内したい場面を考えてみましょう。
案件管理アプリのように、営業部は追加／編集／再利用ができる一方、他部署は閲覧のみといった組織やユーザーの権限によって操作できる内容が異なることがよくあります。

このときアプリの説明欄に説明を記載すると、情報量が多く、ユーザーに見えていないボタンまで説明してしまい混乱を招きます。
そこで、今ユーザーに表示されているボタンだけを取得し、説明の内容を動的に組み立てます。

次のサンプルコードは、詳細画面のメニューの上部に「アプリの操作方法を見る」ボタンを表示し、クリック時にダイアログで動的に説明を表示する例です。
説明項目は、ログインユーザーに表示されているボタン（追加／編集／再利用）だけに絞られます。

詳細画面のメニューの上部に「アプリの操作方法を見る」ボタンが表示されている

今回は、ライブラリとして次を使用しています。

  • Kintone UI Component v1（v1.25.0）：kintone公式のUIコンポーネントライブラリ
    • ボタンの作成に使用
  • Font Awesome（v7.2.0）：アイコンフォントライブラリ
    • 説明時の装飾に使用
    • 今回はCybozu CDNに掲載バージョン（v7.2.0）を使用

JavaScript/CSSファイルは次の順番に適用しています。

JavaScript/CSSファイルの適用順序

サンプルコードのためエラーハンドリングは省略しています。

(() => {
  'use strict';

  // Kintone UI Component のバージョンに応じて変更してください
  const Kuc = Kucs['1.25.0'];

  kintone.events.on('app.record.detail.show', (event) => {
    // 詳細画面のメニューの上部に「アプリの操作方法を見る」ボタンを追加
    const menuButton = new Kuc.Button({
      text: 'アプリの操作方法を見る',
      type: 'normal',
    });
    const headerMenuSpace = kintone.app.record.getHeaderMenuSpaceElement();
    headerMenuSpace.appendChild(menuButton);

    menuButton.addEventListener('click', async () => {
      // 追加／編集／再利用のボタンの表示状態を取得して、説明項目を組み立てる
      const guideItems = [];
      if ((await kintone.app.getAddRecordButtonDisplayState()) === 'VISIBLE') {
        guideItems.push(
          '<li><i class="fa-solid fa-circle-plus" aria-hidden="true"></i> 追加ボタン：新しいレコードを登録します。</li>',
        );
      }
      if ((await kintone.app.record.getEditRecordButtonDisplayState()) === 'VISIBLE') {
        guideItems.push(
          '<li><i class="fa-solid fa-pen-to-square" aria-hidden="true"></i> 編集ボタン：現在のレコードを更新します。</li>',
        );
      }
      if ((await kintone.app.record.getDuplicateRecordButtonDisplayState()) === 'VISIBLE') {
        guideItems.push(
          '<li><i class="fa-regular fa-paste" aria-hidden="true"></i> 再利用ボタン：現在のレコードを複製して新規作成を始めます。</li>',
        );
      }

      const body = document.createElement('div');
      body.innerHTML =
        guideItems.length === 0
          ? '<div style="padding:12px 16px;"><p style="margin:0;">このユーザーに表示されている操作ボタンはありません。</p></div>'
          : `<div style="padding:12px 16px;"><ul style="margin:0;padding-left:1.2em;line-height:1.8;">${guideItems.join('')}</ul></div>`;

      // ダイアログを作成して表示する
      const dialog = await kintone.createDialog({
        title: 'アイコンと操作の説明',
        body,
        okButtonText: 'OK',
        showCancelButton: false,
        showCloseButton: true,
      });
      await dialog.show();
    });

    return event;
  });
})();

サンプルコードをアプリに適用すると次のようになります。

追加／編集権限がある営業部の田中さんの詳細画面では、「アプリの操作方法を見る」ボタンと追加／編集／再利用ボタンが表示されます。

「アプリの操作方法を見る」ボタンと追加／編集／再利用ボタンが表示されている

「アプリの操作方法を見る」ボタンをクリックすると、ダイアログにそれらのボタンの説明が表示されます。

ダイアログに追加／編集／再利用ボタンの説明が表示されている

一方、閲覧権限のみの他部署の小川さんの詳細画面では、「アプリの操作方法を見る」ボタンのみが表示されます。

「アプリの操作方法を見る」ボタンのみ表示されている

「アプリの操作方法を見る」ボタンをクリックすると、ダイアログに「このユーザーに表示されている操作ボタンはありません」と表示されます。

ダイアログに「このユーザーに表示されている操作ボタンはありません」と表示されている

この例では、次のkintone JavaScript APIを使用しています。

ユースケース2：アプリ管理者にアプリの説明が未設定であることを案内する

環境内の全てのアプリ管理者に対して、アプリの説明を記述するように案内したい場合を考えてみましょう。
kintoneの管理者がすべてのアプリをチェックして、アプリの説明を記述するように呼びかけるのは大変ですよね。

次のサンプルコードは、kintone全体のカスタマイズに適用する内容です。アプリ管理者が一覧／詳細／追加／編集／グラフ画面を開いたときにアプリの説明が未設定の場合、画面上部に「アプリの説明を記述してください」と表示する例です。

画面上部に「アプリの説明を記述してください」と表示されている

サンプルコードのためエラーハンドリングは省略しています。

(() => {
  'use strict';

  const events = [
    'app.record.index.show',
    'app.record.detail.show',
    'app.record.create.show',
    'app.record.edit.show',
    'app.report.show',
  ];

  kintone.events.on(events, async (event) => {
    // アプリ管理者かどうかを取得する
    const permissions = await kintone.app.getPermissions();

    // アプリの説明の表示状態（OPEN / CLOSED / HIDDEN）を取得する
    const currentDisplayState = await kintone.app.getDescriptionDisplayState();

    // アプリ管理者かつ、アプリの説明が未設定（HIDDEN）の場合はメッセージを表示する
    if (permissions.editApp === true && currentDisplayState === 'HIDDEN') {
      await kintone.showNotification(
        'INFO',
        '「アプリの設定 > アイコンと説明」を開き、アプリの説明を記述してください。',
      );
    }

    return event;
  });
})();

kintone全体のカスタマイズにサンプルコードを適用すると、次のようになります。

アプリ管理者が「説明なしアプリ」を開いたときは、画面上部に「アプリの説明を記述してください」と表示されます。

画面上部に「アプリの説明を記述してください」と表示されている

一方、アプリ管理者が「説明ありアプリ」を開いたときは、案内は表示されません。

画面上部に案内が表示されていない

この例では、次のkintone JavaScript APIを使用しています。

おわりに

Part2では、get系APIの中でも「UIパーツの状態取得系API」を活用して、画面UIの今の状態を確認してから制御する安全な実装パターンを解説しました。

get系APIは今回紹介した以外にも、次のような状態も取得できます。

  • 権限／ユーザー／環境／ライセンス情報
  • アプリ／スペース構成
  • プロセス管理／レコード操作
  • ショートカットキー

get系APIやshow系API等を組み合わせることで、複数のイベントが干渉する場面や権限／状態によって分岐が必要な場面でも、堅牢なUIカスタマイズを実現できます。

近日「アンチパターンから学ぶ UI制御」が公開予定です！
公開後にリンクを追記します。お楽しみに！

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

5
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
5
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?