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

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

（著者：落合 雄一）

はじめに

今回は、レコードを取得して利用する一覧画面編です。はりきっていきましょぅΣ(σ｀･ω･´)σ！

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

eventオブジェクトからの取得

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

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

eventオブジェクトのプロパティ

PC、モバイルで同一の内容となります。

プロパティ名	型	説明
appId	数値	アプリID
viewType	文字列	'list' または 'calendar' または 'custom'
viewId	数値	ビューID
viewName	文字列	ビュー名
records	配列 またはオブジェクト	viewType によって下記の値となる ・list ： レコードオブジェクト※の配列 ・calendar ： キーを日付文字列、値をレコードオブジェクトの配列としたオブジェクト。 例： { "2013-12-01": [record1, record2], "2013-12-20": [record1] }  Copyクリップボードにコピーしました ・custom かつ ページネーションがtrue ： レコードオブジェクト※の配列 ・custom かつ ページネーションがfalse ： 空配列 ※レコードオブジェクトとは、フィールドコードとフィールドの値などのレコードの情報を含むオブジェクトです。 フィールドの値は、フィールドの形式によって異なります。詳細はフィールド形式をご確認ください。
offset	数値	viewType によって下記の値となる ・list ： 一覧のオフセット数 ・calendar ： null ・custom かつ ページネーションがtrue ： 一覧のオフセット数 ・custom かつ ページネーションがfalse ： 0
size	数値	viewType によって下記の値となる ・list ： 一覧のレコード数 ・calendar ： null ・custom かつ ページネーションがtrue ： 一覧のレコード数 ・custom かつ ページネーションがfalse ： 0
date	文字列	viewType によって下記の値となる ・calendar ： カレンダービューの表示月。2013年 6月なら "2013-06" ・calendar以外 ： null
type	文字列	イベントタイプ

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

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

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

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

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

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

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

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

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

返り値

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

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

一覧画面のカスタマイズ

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

んー、なんか目がちかちかしますがご勘弁のほど・・・・(+ω+;)
ですが、ばっちり！一覧画面のデータを利用してのカスタマイズに成功しました！Σd=(・ω-｀o)ｸﾞｯ♪

最後に

ここまで振り返ってみて、いかがでしょうか？
これで皆さんは、kintone 3分 JS カスタマイズと同じようなものをご自身の手で作成できるようになっているはずです！m9っ`･ω･´)ﾋﾞｼｯ!!

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

それでは、また第6回でお会いしましょう(^^)

Let’s kintoneカスタマイズ＼(^o^)／

このTipsは、2022年6月版で確認したものになります。

<<第4回 レコードの値を取得してみよう（詳細画面編）  | 第6回 テーブルの値を利用する>>

デモ環境

こちらのデモ環境から実際に動作を確認できます。
https://dev-demo.cybozu.com/k/10/

デモ環境の利用は、事前に cybozu developer network のメンバー登録が必要です。画面右上の「サインイン」ボタンよりご登録ください。
デモ環境アカウントとパスワードは、サインイン後にこちらのページでご確認ください。