初めて kintone をカスタマイズする人が kintone API の基礎知識を学べるよう、チュートリアルの内容を充実させてリニューアルしました。
リニューアル後のチュートリアルは次のページを参照してください。
はじめよう kintone API

はじめに

今回からは登録済みレコードを取得して利用してみることにしましょう！
ということで、まずは詳細画面（PC 用）での使い方から始めたいと思います。

レコード番号を取得

まずは簡単に、 レコード ID を取得する ことからはじめましょう。
レコード番号とは、アプリごとにゼロからの連番で自動的に振り分けられるユニークな ID です。
レコード番号は、これからもちょくちょく出てくるので覚えておいてくださいね！

利用する関数は kintone.app.record.getId() です。
以下は、メニュー右側の空白部分に置いたボタンを押すとアラートを出す簡単なサンプルです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

(() => {
  'use strict';
  kintone.events.on('app.record.detail.show', (event) => {
    const myMenuButton = document.createElement('button');
    myMenuButton.id = 'my_menu_button';
    myMenuButton.innerText = 'ボタン';
    myMenuButton.onclick = function() {
      // 取得したレコードIDを出力する
      window.alert('id: ' + kintone.app.record.getId());
    };

    kintone.app.record.getHeaderMenuSpaceElement().appendChild(myMenuButton);
  });
})();

簡単にできましたね！
今回も順調な滑り出しです。

レコードの値を取得

次に、レコードの値を取得してみましょう。

利用する関数は、 kintone.app.record.get() です。
モバイル用には、kintone.mobile.app.record.get() を利用することになりますので気を付けてください。
この関数の戻り値は、値の取得に成功した場合 JSON 形式、失敗した場合 null となります。
JSON については Web 上に多くの情報がありますので、説明を省きます。

フィールドコードは、アプリの設定を変更 > フォームの編集から取得したいフィールドの設定で確認/変更できます。

ここまで分かればあまり難しいことはないですね。

それでは、実際に利用してみましょう。

以下は、メニュー右側の空白部分に置いたボタンを押すと、 前回 の記事で利用した「スペースフィールド」に更新日時フィールドから取得した値を表示するサンプルです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const myMenuButton = document.createElement('button');
    myMenuButton.id = 'my_menu_button';
    myMenuButton.innerText = 'ボタン';
    myMenuButton.onclick = function() {
      const mySpaceField = kintone.app.record.getSpaceElement('my_space_field');
      mySpaceField.parentNode.style.width = '400px';

      // 更新日時を取得する
      let updatedAt = '';
      const rec = kintone.app.record.get();
      if (rec) {
        updatedAt = rec.record.更新日時.value;
      }
      kintone.app.record.getSpaceElement('my_space_field').innerText = updatedAt;
    };

    kintone.app.record.getHeaderMenuSpaceElement().appendChild(myMenuButton);
  });
})();

取得したレコードの値は、以下のように、ドット表記法やブラケット表記法で利用できます。

1
2
3
4
5

// ドット表記法
kintone.app.record.get().record.更新日時.value;

// ブラケット表記法
kintone.app.record.get().record['更新日時'].value;

どちらの書き方がよいかは、それぞれに好みやスタイルがあることでしょう。
このあたりについては、実際の処理の内容によって適した書き方ができるようにしておけば、より kintone JavaScript API を使いこなせるようになれそうです。

フィールド型とフォーマット

上記のコードで更新日時の取得と表示ができたと思います。
あらためて結果を見てみましょう。

気付きましたか？
赤で囲んだ 2 つの日時の書式が違っていますね。

フィールド形式 と 日時のフォーマット を確認してください。
このように、Web ページ上に HTML で表示されている書式と API から取得した値で、書式/フォーマットが異なるかもしれません。
実際に自分好みの JavaScript を書いていくときには注意してください。

kintone.app.record.get() における注意点

実際に皆さんが詳細画面でレコードを取得する処理を書くときには、いちいちボタンを置いてそれをトリガーにする、なんてまどろっこしいことはあまりしないと思います。
ページの表示時に取得する方が実用的ですね。

しかし、ここで重要な注意点があります！
レコードの値を取得する に以下の注意事項が記載されています。

制限事項

kintone.events.on() のイベントハンドラー内では実行できません。
このイベントハンドラー内で、レコードのデータを取得するには、ハンドラーに渡される引数のイベントオブジェクトを使用してください。

つまり、次のようなことはできないということです。

1
2
3
4
5
6
7

(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const rec = kintone.app.record.get(); // ここではkintone.app.record.get()が使えない
  });
})();

ハマって何時間も頭を抱える人がいるみたいなので、忘れないようにしてください！

イベントオブジェクト

先ほどの注意事項で「イベントオブジェクト？」と思った方、全然難しくありませんよ！
いつも書いている「event」のことです。

1

kintone.events.on('app.record.detail.show', (event) => {});

イベントオブジェクトについてきちんと理解するため、 レコード詳細画面を表示した後のイベント をもう一度確認してみましょう。 ここにイベントオブジェクトのプロパティについての記載がありますね。

イベントオブジェクトのプロパティ

つまり、レコード詳細画面が表示された時のイベントでのイベントオブジェクトには、すでに kintone.app.record.get() を利用した時の戻り値と同じデータが入っているということです。

イベントオブジェクトによるレコードの値の取得

それではここまでの内容を踏まえて、イベントオブジェクトを利用して更新日時フィールドから取得した値を表示してみましょう。
ここでは、更新日時の値をブラケット表記法で記述してあります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

(() => {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const updatedAt = event.record['更新日時'].value;

    const mySpaceField = kintone.app.record.getSpaceElement('my_space_field');
    mySpaceField.parentNode.style.width = '400px';
    mySpaceField.innerText = updatedAt;
  });
})();

これも簡単でしたね。

最後に

レコード詳細画面でのいじり方の基本については、これでだいたいお分かりいただけたと思います。
住所から地図を表示する 、 （小技）undefined と空文字のスマートな if 文判定 などの記事を参考に、いろいろ試してみてください。

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

デモ環境

デモ環境で実際に動作を確認できます。
https://dev-demo.cybozu.com/k/9/

ログイン情報は cybozu developer network デモ環境 で確認してください。