kintoneのスペースをAPIを使ってカスタマイズしてみよう

目次

はじめに

kintoneのスペーストップ画面は、「お知らせ」欄にスペースの説明を表示したり、アプリを貼り付けてレコードの一覧を表示するなど、使用用途に合わせて自由に設定できます。
さらにスペースをカスタマイズするAPIを使うと、ポータルカスタマイズのように文字を表示したり、ボタンを設置したりできます。
本記事では、kintone JavaScript APIのスペースAPIを使った簡単なkintoneカスタマイズを紹介します。

スペースAPIでできること

スペースAPIを使うことで、ボタンを設置したり、リンクを動的に設置するなどのカスタマイズができます。

スペース系API

スペースに関するJavaScript APIは2025年7月現在、以下のものがあります。

完成イメージ

スペースの上側部分に出勤・退勤ボタンを設置します。
それぞれのボタンを押すと、タイムカードアプリにレコードが追加・更新されます。

JavaScriptを利用したスペースのカスタマイズ方法

このTipsのカスタマイズは、kintone全体にカスタマイズを適用します。
そのため、kintoneシステム管理者の権限が必要です。

下準備

  1. kintoneのポータル画面からスペースを作成します。

    • 作成するスペースは、「スペースのポータルと複数にスレッドを使用する」を有効にしてください。
    • JavaScriptカスタマイズで使用するため、作成したスペースIDを控えておきます。
      スペースIDは、ブラウザーでスペースを表示した際のURLで確認できます。
      以下のURLの場合、スペースIDは8です。
      https://{subdomain}.cubozu.com/k/#/space/8
  2. 1. で作成したスペース内にタイムカードアプリを作成します。

    • タイムカードアプリ (External link) は、kintoneアプリストアから追加してください。
    • タイムカードアプリのフィールドを次のように設定します。
      フィールド名 設定内容
      承認者 「必須項目にする」のチェックを外す。
      出勤時刻 「レコード登録時の時刻を初期値にする」のチェックを外す。
      退勤時刻 「レコード登録時の時刻を初期値にする」のチェックを外す。
      レコードタイトル 「自動計算する」のチェックを外し、「値の重複を禁止する」にチェックを入れる。
    • JavaScriptカスタマイズで使用するため、作成したアプリIDを控えておきます。
      アプリIDは、ブラウザーでアプリを表示した際のURLで確認できます。
      以下のURLの場合、アプリIDは245です。
      https://{subdomain}.cybozu.com/k/245/

ライブラリの入手

  • kintone UI Component v1.21.0
    ファイルは https://github.com/kintone-labs/kintone-ui-component/releases/tag/v1.21.0 (External link) よりダウンロードしてください。

    1. 「Assets」の「kintone-ui-component-1.21.0.tgz」をダウンロードします。
    2. アーカイブファイルを解凍し、「umd」ディレクトリ下のkuc.min.jsを利用します。
  • Luxon
    Cybozu CDNで配信されている Luxon を使用します。
    本記事では、2025年7月7日時点でのCybozu CDNで配信されている最新バージョンのURLで動作を確認しています。
    Luxonを導入する際は、 Cybozu CDNのページで配信されているバージョン を確認し、必要に応じて変更してください。

  • sweetalert2
    Cybozu CDNで配信されている sweetalert2 を使用します。
    本記事では、2025年7月7日時点でのCybozu CDNで配信されている最新バージョンのURLで動作を確認しています。
    sweetalert2を導入する際は、 Cybozu CDNのページで配信されているバージョン を確認し、必要に応じて変更してください。

カスタマイズ例:スペースの上部に出勤・退勤ボタンを設置する

それではさっそく、スペースの上側に出勤・退勤ボタンを設置し、タイムカードアプリに登録するカスタマイズをしていきましょう。

kintoneへのカスタマイズ適用

スペースのカスタマイズは、kintoneシステム管理画面から行います。
詳しい設定方法については、kintoneヘルプ「 JavaScript / CSSファイルを取り込む (External link) 」を確認してください。
設定は以下のようになります。

  • PC用のJavaScriptファイル

    • https://js.cybozu.com/luxon/3.6.1/luxon.min.js
    • https://js.cybozu.com/sweetalert2/v11.22.1/sweetalert2.min.js
    • kuc.min.js
    • sample.js
  • PC用のCSSファイル

    • https://js.cybozu.com/sweetalert2/v11.22.1/sweetalert2.min.css
    • sample.css

サンプルコード
sample.js

出勤・退勤ボタンを設置し、ボタンを押したときにタイムカードアプリへレコードを追加・更新するためのスクリプトファイルです。
ご自身の環境に応じてつぎのとおり内容を変更してください。

  • 12行目{YOUR_CUSTOM_SPACE_ID}:「下準備1.」で控えたスペースIDに変更
  • 13行目{TIMECARD_APP_ID}:「下準備2.」で控えたタイムカードアプリのIDに変更
  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
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
/*
 * sample.js
 * Copyright (c) 2025 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

(() => {
  'use strict';
  kintone.events.on('space.portal.show', (event) => {
    const SPACE_ID = '{YOUR_CUSTOM_SPACE_ID}'; // ボタンを設置するスペースIDに変更してください
    const TIMECARD_APP_ID = '{TIMECARD_APP_ID}'; // タイムカードアプリのアプリIDに変更してください
    if (event.spaceId !== SPACE_ID) {
      return event;
    }

    const toastObj = Swal.mixin({
      toast: true,
      position: 'top',
      showConfirmButton: false,
      timer: 3000,
      timerProgressBar: true,
      didOpen: function(toast) {
        toast.addEventListener('mouseenter', Swal.stopTimer);
        toast.addEventListener('mouseleave', Swal.resumeTimer);
      },
    });

    // スペース上側の要素を取得
    const el = kintone.space.portal.getContentSpaceElement();

    const Kuc = Kucs['1.21.0']; // Kucのバージョンを指定
    // 出勤・退勤ボタンの設定
    const startButton = new Kuc.Button({
      text: '出勤',
      type: 'submit',
      id: 'startButton',
    });

    const endButton = new Kuc.Button({
      text: '退勤',
      type: 'alert',
      id: 'endButton',
    });

    // 日付表示の設定
    const today = luxon.DateTime.local();
    const todayStr = today.setLocale('ja').toFormat('yyyy年M月d日(EEE)');
    const displayDateDiv = document.createElement('div');
    displayDateDiv.id = 'displayDate';
    displayDateDiv.innerText = todayStr;

    // 今日の日付と出勤・退勤ボタンを設置
    el.appendChild(displayDateDiv);
    el.appendChild(startButton);
    el.appendChild(endButton);

    const upsertTimecard = (fieldName) => {
      // 現在時刻を取得
      const currentDate = luxon.DateTime.local();
      const currentDateStr = currentDate.setLocale('ja').toFormat('yyyy-MM-dd');
      const currentTimeStr = currentDate.toFormat('HH:mm');

      // updateKeyを定義 ログインユーザー名 申請日付
      const updayteKeyValue = `${
        kintone.getLoginUser().name
      } ${currentDateStr}`;
      const paramsUpsert = {
        app: TIMECARD_APP_ID,
        upsert: true,
        records: [
          {
            updateKey: {
              field: 'Text',
              value: updayteKeyValue,
            },
            record: {
              [fieldName]: {
                value: currentTimeStr,
              },
            },
          },
        ],
      };
      return kintone.api(
        kintone.api.url('/k/v1/records.json', true),
        'PUT',
        paramsUpsert,
        (resp) => {
          toastObj.fire({
            icon: 'success',
            title: `${fieldName}を登録/更新しました!`,
          });
        },
        (error) => {
          toastObj.fire({
            icon: 'error',
            title: `${fieldName}の登録/更新に失敗しました。`,
          });
        }
      );
    };

    // 出勤ボタンを押したときの関数
    startButton.addEventListener('click', () => {
      upsertTimecard('出勤時刻');
    });

    // 退勤ボタンを押したときの関数
    endButton.addEventListener('click', () => {
      upsertTimecard('退勤時刻');
    });

    return event;
  });
})();
sample.css

出勤・退勤ボタンの表示位置を調整するためのCSSです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
/*
 * sample.css
 * Copyright (c) 2025 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

#displayDate {
  padding: 10px 20px 0px 30px;
  font-size: 20pt;
  font-weight: 500;
}

#startButton {
  padding: 10px 20px 20px 30px;
}

#endButton {
  padding: 10px 20px 20px 10px;
}
JavaScriptカスタマイズのポイント
11〜14行目

スペース表示イベントが実行されたときに、ボタンを表示したいスペースかどうかをスペースIDで判断します。
スペースカスタマイズではkintone全体にカスタマイズを適用しているため、if文を使ってボタンの表示/非表示を切り替えています。

30〜56行目

スペースの上側の空白要素を取得し、今日の日付と出勤・退勤ボタンをセットしています。
出勤・退勤ボタンは、kintone UI Component v1を利用してkintoneライクなボタンを設置しています。

61〜62行目

Luxonを使って、出勤ボタンを押したときの時間を時刻フィールドの書式にフォーマットしています。

135〜153行目

出勤ボタンを押し忘れて退勤ボタンだけを押した場合、退勤時刻のみ登録されます。
ユーザーに出勤時刻を登録してもらうようにメッセージを追加しています。
ボタンを押したあとに表示されるメッセージはSweetAlert2を使用して表示しています。

おわりに

スペースAPIを使って、出退勤のボタンを設置するカスタマイズを紹介しました。
部署やグループごとでスペースを使い分けて、出退勤を管理したいシーンにおすすめです。
cybozu developer networkでは ポータルの上部に出勤・退勤ボタンを設置するカスタマイズ も紹介しています。
スペースAPIを活用して、お好みのスペースカスタマイズをお試しください。

information

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