第 5 回 レコードの値を取得してみよう(一覧画面編)

著者名: 落合 雄一 (External link)

目次

information

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

はじめに

今回は、レコードを取得して利用する一覧画面編です。

それでは、PC 用の一覧画面で特定のレコードの表示する色を変更してみましょう。
とりあえずアプリの準備からです。
以下は、信号機の色をラジオボタンで登録するアプリを作成したときの設定です。
詳細画面のときと同様、「フィールドコード」に設定した値はあとで使います。

イベントオブジェクトからの取得

表を出力するときに取得した値を利用するときには、イベントオブジェクトを利用します。
これについては、 前回 の詳細画面編でも使ったので分かりますね。

取得できるイベントオブジェクトについては、 レコード一覧画面を表示した後のイベントevent オブジェクトのプロパティから、内容を確認してみましょう。

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

以下の表は一部を書略しています。
PC とモバイルで同一の内容です。

プロパティ名 説明
viewType 文字列 レコード一覧の表示形式
  • list:表形式
  • calendar:カレンダー形式
  • custom:カスタマイズ
records 配列またはオブジェクト レコード情報
viewType の値によって異なります。
  • 「list」のとき:レコードのデータの配列
  • 「calendar」のとき:キーを日付文字列にもつレコードのデータの配列のオブジェクト
  • 「custom」で、ページネーションが true のとき:レコードのデータの配列
  • 「custom」で、ページネーションが false のとき:空配列
レコードのデータの詳細は、 フィールド形式 を参照してください。

この表を見てお分かりのとおり、viewType が「list」の場合は records プロパティにレコードオブジェクトの配列が入ってきます。
レコードオブジェクト…そう、前回詳細画面でやったのと同じです。
つまり、x 番目のレコードの信号の色を利用するには以下のように書けばよいわけです。

1
event.records[x].信号の色.value;

以下は、取得したレコードの内容を以前にも紹介した レコード一覧のメニューの下側の要素 に出力する viewType=list 用のサンプルです。

 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
/*
 * Tutorial sample (Show record content in menu)
 * Copyright (c) 2014 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

(() => {
  'use strict';

  kintone.events.on('app.record.index.show', (event) => {
    // 0件Hit対策
    if (!event.size) {
      return;
    }

    const myListTable = document.createElement('table');
    myListTable.id = 'my_list_table';
    myListTable.style.border = '1px solid';
    myListTable.style.width = '600px';

    const records = event.records;
    // 取得レコードループ
    for (let i = 0; i < records.length; i++) {
      const record = records[i];

      // レコード番号
      const myRecordTd1 = document.createElement('td');
      myRecordTd1.id = 'my_record_td_' + i + '_1';
      myRecordTd1.style.border = '1px solid';
      myRecordTd1.innerText = record.レコード番号.value;

      // 信号の色
      const myRecordTd2 = document.createElement('td');
      myRecordTd2.id = 'my_record_td_' + i + '_2';
      myRecordTd2.style.border = '1px solid';
      myRecordTd2.innerText = record.信号の色.value;

      // 作成日時
      const myRecordTd3 = document.createElement('td');
      myRecordTd3.id = 'my_record_td_' + i + '_3';
      myRecordTd3.style.border = '1px solid';
      myRecordTd3.innerText = record.作成日時.value;

      const myRecordTr = document.createElement('tr');
      myRecordTr.id = 'my_record_tr_' + i;
      myRecordTr.appendChild(myRecordTd1);
      myRecordTr.appendChild(myRecordTd2);
      myRecordTr.appendChild(myRecordTd3);

      myListTable.appendChild(myRecordTr);
    }

    const myHeaderSpace = kintone.app.getHeaderSpaceElement();
    myHeaderSpace.innerText = '';
    myHeaderSpace.appendChild(myListTable);
  });
})();

取得した結果は、 フィールド形式 によって違う書式になることがあります。
これも前回の 詳細画面編 と同じですが、結構忘れがちなことなのでもう一度触れておきますね。
以下の例では作成日時が書式/タイムゾーンともに異なっています。
詳しくは 日時のフォーマット を確認してください。

上記サンプルを一覧で実際に動かして、並び替えや表示件数の変更、検索機能の利用やページングをいろいろ操作しながら元の表と内容を比較してみてください。
取得したデータ、件数、並び順いずれも一覧画面に表示されている内容と同じになっていますね。
このようにイベントオブジェクトは、一覧画面で表示した値を再利用するのに非常に有効です。
一覧だからと言っても何も難しいことはありませんね。

フィールド要素を取得する

次に、実際に表示している HTML の DOM 要素を取得します。
これも特に難しいことはありません。
信号の色を表示している レコード一覧のフィールド要素を取得する API では、このように書けば済みます。

1
kintone.app.getFieldElements('信号の色');

ただし、以下の注意点に気を付けてくださいね。

戻り値

  • フィールド要素の配列または null が返ります。
  • 利用できない画面では null が返ります。
  • レコードが 1 件もない場合は空配列が返ります。
  • 該当するフィールドがない場合、表示されていないフィールドを指定した場合は null が返ります。

取得する信号の色の「フィールド要素の配列」は、以下図の赤線で囲った部分のオブジェクトのリストになります。
実際の画面でも確認してみてください。

一覧画面のカスタマイズ

それでは、ここまでの 2 つを利用して、値によって一覧画面の表示をカスタマイズしてみましょう。
テーマとしては、 レコード一覧で条件書式を設定する のサンプルが秀逸ですので、これと同じようなものを作ってみました。
これ自体内容としては簡単なものですが、皆さんのアプリに合わせて応用してみてください。

 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
/*
 * Tutorial sample (Condition format)
 * Copyright (c) 2014 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

(() => {
  'use strict';

  kintone.events.on('app.record.index.show', (event) => {
    if (!event.size) {
      return;
    }

    const records = event.records;
    const signalColorParts = kintone.app.getFieldElements('信号の色');
    for (let i = 0; i < records.length; i++) {
      // 値の取得
      const color = records[i].信号の色.value;

      // DOM要素の取得
      const part = signalColorParts[i];

      // 値ごとに表示分け
      if (color === '赤') {
        part.style.fontWeight = 'bold';
        part.style.color = '#ffffff';
        part.style.backgroundColor = '#ff0000';

      } else if (color === '青') {
        part.style.fontWeight = 'bold';
        part.style.color = '#ffffff';
        part.style.backgroundColor = '#0000ff';

      } else if (color === '黄') {
        part.style.fontWeight = 'bold';
        part.style.color = '#ffffff';
        part.style.backgroundColor = '#ffd700';
      }
    }
  });
})();

一覧画面のデータを利用してのカスタマイズに成功しました。

最後に

ここまで振り返ってみて、いかがでしょうか?
これで皆さんは、 kintone 3分 JS カスタマイズ (External link) と同じようなものをご自身の手で作成できるようになっているはずです!

kintone JavaScript API のサンプルページ にある他のサンプルにも目を通してみてください。
コードを読んでも以前よりグッと理解できるようになっているのではないでしょうか。

information

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

デモ環境

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

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