kintone JavaScript APIを使ってみよう

サイボウズ社が提供している「kintone」はJavaScriptやAPIを使用することで、標準機能からさらに便利な機能へと作り変えることが可能です。
kintoneのカスタマイズにはプラグイン（拡張機能）を利用する方法と、JavaScriptを利用する方法があります。

そこで本記事では、「kintone JavaScript API」を使ったカスタマイズ方法について解説します。JavaScriptやAPIについて、これから学ぼうとお考えの方はぜひご参考になさってください。

kintoneのJavaScriptカスタマイズについて、下記記事で詳細を解説していますので、併せてご覧ください。
▼kintoneでJavaScriptを活用し、さらなる業務改善へ！

そもそもAPIとは、「アプリケーション・プログラミング・インターフェース」の略称で、アプリケーションやソフトウェア、Webシステム同士を連携する接点となるものです。
APIのプロセスは、API利用者による“リクエスト”とAPI提供者の“レスポンス”で構成されます。リクエストとレスポンスのルールはAPI提供者が決定します。したがって、API提供者が設計段階で考え、実装・利用可能になった状態のAPIを、API利用者は「どんなリクエストに対してどんなレスポンスが返されるのか」を判断して利用することになります。

そのようなAPIを応用したのが「kintone JavaScript API」です。kintone JavaScript APIを使用すれば、kintoneのブラウザ（画面）上の情報を取得・操作できるようになります。

関連記事をご用意しております。
▼kintoneのAPI機能で外部システムと連携する

kintone JavaScript APIを使うには、以下の環境が必要です。

• kintone
  kintone開発者ライセンスを取得していればそのままkintoneを利用できますが、開発者ライセンス未取得の方は、「kintone 開発者ライセンス（開発環境）」にアクセスし開発者ライセンスを申し込む必要があります。
• Webブラウザ
  cybozu.comの推奨ブラウザをご確認ください。
• テキストエディター
  Visual Studio Code、Sublime Textなど、普段使い慣れたツールで問題ありません。

本章では、比較的使用頻度の高いkintone JavaScript APIをご紹介します。

kintoneには独自のイベントがあります。JavaScriptではaddEventListener()を使ってイベントと関数を紐付けますが、kintoneでは「kintone.events.on()」を利用します。

kintoneのイベントが発生すると、情報が格納された「イベントオブジェクト」が作られます。例えば、以下のサンプルコードの中にある「event」がイベントオブジェクトになります。

kintone.events.on('app.record.detail.show', (event) => { 
  event.record['加工したいフィールドコード'].value = '加工したい内容';
  return event;
});

関数の中でイベントオブジェクトを加工した後、returnすることで加工内容をkintoneに反映できるのです。

イベントオブジェクトの取得・操作で、以下の内容が可能となります。

• フィールド値の書き換え
• フィールドの編集可／不可設定
• フィールドとレコードにエラーの表示
• 変更されたフィールド、テーブル内の行オブジェクトの取得
• ルックアップの自動取得
• ルックアップのコピー先のフィールド値を自動でクリア

kintone.app.getId()は、kintoneで開いているアプリのIDを取得するメソッドです。
例えば、直接ID名を取得すると、kintoneの環境やアプリが変わったときにID名も変わってしまうためコードの書き直しが必要となりますが、このメソッドを使用すればその手間を省けます。

kintone.getLoginUser()は、kintoneのログインユーザーの情報を取得するメソッドです。ログインユーザーのログイン名・表示名・メールアドレスなどを取得できます。

例えば、先ほど紹介したイベントオブジェクトと組み合わせることで、「ログインユーザーによって表示させる情報を変える」というようなカスタマイズが可能です。

kintone.app.getHeaderMenuSpaceElement()は、kintoneのアプリ詳細画面にてメニュー上部にある余白部分の要素を取得するメソッドです。

例えば、このメソッドで取得した要素に、任意のボタンやテキスト情報を配置することができます。

それでは前章で紹介したメソッドを実際に使用した、サンプルコードを紹介します。

例えば、ログインユーザーに応じ、アプリのヘッダー上部に表示させる情報を変更する場合、以下のコードで表示可能です。

(() => {
  'use strict';
  kintone.events.on('app.record.index.show', (event) => {
    // ログインユーザーのコードを取得
    const loginUser = kintone.getLoginUser().code;

    // 表示するユーザーを設定
    const permission = ['taro'];

    if (permission.includes(loginUser)) {
      // ログインユーザーに応じた処理をここに記述
      kintone.app.getHeaderSpaceElement().textContent = 'こんにちは！あなたはログインしました';
    }
    return event;
  });
})();

※参考：cybozu developer network「kintone JavaScript API」

前章でも紹介したkintone.getLoginUser()ですが、「kintone.getLoginUser().code」では「ログイン名」を取得します。表示名を取得したければcodeを「name」に、メールアドレスであれば「email」とします。詳しくはこちらをご確認ください。

その次の行にある「const permission = ['taro'];」で表示するユーザーを指定します。['taro', '○○', '○○', '○○'～～]と表示させるユーザーを複数人選ぶことも可能です。

前項のコードは、ログインユーザーが「taro」であればヘッダー上部に「こんにちは！あなたはログインしました」のテキストが表示される、という仕組みです。

アプリ内にあるラジオボタンを選択した項目によって、フィールドを表示させたり非表示にさせたり切り替えることが可能です。

例えば、下記のサンプルコードでは、「申請済」のラジオボタンを選択すると、「申請日」と「申請確認者」のフィールドが表示されるようになります。

(() => {
  'use strict';
  // 表示非表示を切り替えるフィールドコードを指定
  const fields = ['申請日', '申請確認者'];
  // 制御するラジオボタンを指定
  const radio = '申請ステータス';
  // 制御するラジオボタンの値を指定
  const radioValue = '申請済';

  // ラジオボタンの値に応じてフィールドを表示する処理
  kintone.events.on([
    'app.record.create.show',
    'app.record.edit.show',
    `app.record.create.change.${radio}`,
    `app.record.edit.change.${radio}`
  ], (event) => {
    if (event.record[radio].value !== radioValue) {
      fields.forEach((field) => {
        kintone.app.record.setFieldShown(field, false);
      });
    } else {
      fields.forEach((field) => {
        kintone.app.record.setFieldShown(field, true);
      });
    }
    return event;
  });
})();

※参考：cybozu developer network「kintone JavaScript API」

kintone.app.record.setFieldShown()は、フィールドの表示／非表示を切り替えるメソッドです。

kintone.app.record.setFieldShown(fieldCode,isShown)

fieldCodeには、フィールドのフィールドコードを記述します。テーブル内の指定したフィールドを非表示にする場合は、非表示にしたいフィールドのフィールドコードを記述し、テーブル内すべてのフィールドを非表示にしたい場合は、テーブルのフィールドコードを記述してください。

isShownは、フィールドに表示するかどうかの引数です。trueはフィールドに表示し、falseはフィールドを非表示にします。

フィールドコードの詳細や確認方法については、こちらをご参考にしてください。

kintone JavaScriptのカスタマイズが初めての方に向けたチュートリアルサイトが、cybozu developer networkから提供されています。
JavaScriptやkintone API、kintoneコマンドラインツール（cli-kintone）の基礎知識や使い方を学べるコンテンツです。JavaScriptを編集したことがない方や、APIを使用したカスタマイズなど勉強を始めようと思っている方はぜひ、こちらを使用してみることをおすすめします。kintoneカスタマイズの全体像がつかめるはずです。

チュートリアルサイトはこちらから。

ここで紹介したサンプルコードはごく一部のものです。様々なkintone JavaScript APIを組み合わせれば、カスタマイズの範囲は広がり、より便利なkintoneを構築できるでしょう。

しかし、高度な実装になるほど、kintone JavaScript APIの記述するコードも専門性が高くなり、普段JavaScriptやAPIの扱いになれているエンジニアでないと難しいケースも出てくるかもしれません。
そんなときはサイボウズ公認パートナー企業へ、カスタマイズを依頼するのもひとつの手です。テクバンもパートナー企業であり、お客様のkintone導入・運用をサポートしています。ぜひお気軽にご相談ください。

※本記事の内容は2024年2月時点のものです。kintoneの仕様や利用環境は変更する場合があります。