Index
イベント
eventオブジェクトで実行できる操作
- フィールドの値を書き換える
- フィールドの編集可／不可を設定する
- フィールドにエラーを表示する
- レコードにエラーを表示する
- ルックアップを自動取得する
- ルックアップのコピー先のフィールドの値を自動でクリアする
- 変更されたフィールド、テーブル内の行オブジェクトを取得する
その他
イベント
レコード追加画面の表示後イベント
レコード追加画面が表示された後に発生するイベントです。
- PCとモバイルで利用できるイベントです。
- スペースに貼りつけたアプリにはこのイベントは発生しません。
- kintone.Promiseオブジェクトをreturnすると、非同期処理の完了を待って次の処理を開始します。
イベントタイプ
| 環境 | イベントタイプ | イベントが発生するタイミング |
|---|---|---|
| PC | app.record.create.show |
|
| モバイル | mobile.app.record.create.show |
|
eventオブジェクトのプロパティ
PC、モバイルで同一の内容となります。
| プロパティ名 | 型 | 説明 |
|---|---|---|
| appId | 数値 | アプリID |
| reuse | 真偽値 | 再利用の場合は true。通常の追加画面は false。 |
| record | オブジェクト |
レコード登録画面表示時のデータ（フォームの初期値）を保持したレコードオブジェクト※ ※レコードオブジェクトとは、フィールドコードとフィールドの値などのレコードの情報を含むオブジェクトです。 |
| type | 文字列 | イベントタイプ |
eventオブジェクトで実行できる操作
- フィールドの値を書き換える をご参照ください。
- フィールドの編集可／不可を設定する をご参照ください。
- フィールドにエラーを表示する をご参照ください。
- レコードにエラーを表示する をご参照ください。
- ルックアップを自動取得する をご参照ください。
- ルックアップのコピー先のフィールドの値を自動でクリアする をご参照ください。
非同期処理の完了を待って次の処理を行う
kintone.Promiseオブジェクトをreturnすることで、非同期処理の完了を待ってからフィールドの値に応じた制御を実行できます。
同じイベントに複数のイベントハンドラが登録されているとき、エラーなどが発生してThenableオブジェクトが棄却された場合には、後続のイベントハンドラの処理は実行されません。
記述方法はkintoneにおけるPromiseの書き方の基本を参考にしてください。
サンプル
レコード追加画面の表示時にメッセージを表示します。
レコード追加画面のフィールド値変更時イベント
- PCとモバイルで利用できるイベントです。
- スペースに貼りつけたアプリにはこのイベントは発生しません。
- トリガーとなった値の変更はキャンセルされません。
イベントタイプ
| 環境 | イベントタイプ | イベントが発生するタイミング |
|---|---|---|
| PC | app.record.create.change.<フィールドコード> |
|
|
モバイル
|
mobile.app.record.create.change.<フィールドコード> |
|
フィールドコードに指定可能なフィールド
<フィールドコード>に存在するフィールドコード、かつ次の種類のフィールドを指定した場合のみハンドラーが実行されます。 存在しないフィールドコード、または下記の種類以外のフィールドを指定した場合は何も発生しません。
- ラジオボタン
- ドロップダウン
- チェックボックス
- 複数選択
- ユーザー選択
- 組織選択
- グループ選択
- 日付
- 時刻
- 日時
- 文字列(1行)
- 数値
- テーブル
※文字列(1行)と数値フィールドに関して、イベントが発生するタイミングは以下の通りです。ブラウザによって少し挙動が異なります。
- コントロールからフォーカスが外れたタイミング
- ルックアップで値がコピーされたタイミング
- 文字列(1行)フィールドで「自動計算する」設定になっている場合は、自動計算が反映されたタイミング（レコード一覧画面の編集時は、自動計算処理自体が無効なため対象外）
※テーブルフィールドに関して、イベントが発生するタイミングは以下の通りです。
- テーブルの行追加、行削除ボタンがクリックされたタイミング
eventオブジェクトのプロパティ
PC、モバイルで同一の内容となります。
| プロパティ名 | 型 | 説明 |
|---|---|---|
| appId | 数値 | アプリID |
| record | オブジェクト |
イベント発生時点のユーザー入力のデータを保持したレコードオブジェクト※ ※レコードオブジェクトとは、フィールドコードとフィールドの値などのレコードの情報を含むオブジェクトです。 |
| changes | オブジェクト | 変更されたオブジェクト |
| changes.field | オブジェクト | 変更されたフィールドのオブジェクト |
| changes.row | オブジェクト | 変更されたテーブル行のオブジェクト
|
| type | 文字列 | イベントタイプ |
eventオブジェクトで実行できる操作
- フィールドの値を書き換える をご参照ください。
- フィールドの編集可／不可を設定する をご参照ください。
- フィールドにエラーを表示する をご参照ください。
- レコードにエラーを表示する をご参照ください。
- ルックアップを自動取得する をご参照ください。
- ルックアップのコピー先のフィールドの値を自動でクリアする をご参照ください。
- 変更されたフィールドやテーブル内の行オブジェクトを取得するをご参照ください。
注意事項
イベント処理の記述方法の注意事項をご確認下さい。
制限事項
以下のイベントでは、添付ファイルフィールドの情報が取得できません。
- app.record.create.change.<フィールドコード>
- mobile.app.record.create.change.<フィールドコード>
レコード追加画面の保存実行前イベント
- PCとモバイルで利用できるイベントです。
- スペースに貼りつけたアプリには利用できません。
- false を return すると保存処理をキャンセルできます。
- フィールドにエラーを表示するやレコードにエラーを表示するのようにerrorプロパティに値を設定したeventオブジェクトをreturnすると保存処理をキャンセルできます。
- kintone.Promiseオブジェクトをreturnすると、非同期処理の完了を待って次の処理を開始します。
イベントタイプ
| 環境 | イベントタイプ | イベントが発生するタイミング |
|---|---|---|
| PC | app.record.create.submit |
|
|
モバイル
|
mobile.app.record.create.submit |
|
eventオブジェクトのプロパティ
PC、モバイルで同一の内容となります。
| プロパティ名 | 型 | 説明 |
|---|---|---|
| appId | 数値 | アプリID |
| record | オブジェクト |
ユーザー入力のデータを保持したレコードオブジェクト※ ※レコードオブジェクトとは、フィールドコードとフィールドの値などのレコードの情報を含むオブジェクトです。 |
| type | 文字列 | イベントタイプ |
eventオブジェクトで実行できる操作
- フィールドの値を書き換える をご参照ください。
- フィールドにエラーを表示する をご参照ください。
- レコードにエラーを表示する をご参照ください。
非同期処理の完了を待って次の処理を行う
kintone.Promiseオブジェクトをreturnすることで、非同期処理の完了を待ってからフィールドの値に応じた制御を実行できます。
同じイベントに複数のイベントハンドラが登録されているとき、エラーなどが発生してThenableオブジェクトが棄却された場合には、後続のイベントハンドラの処理は実行されません。
記述方法はkintoneにおけるPromiseの書き方の基本を参考にしてください。
注意事項
イベント処理の記述方法の注意事項をご確認下さい。
制限事項
以下のイベントでは、添付ファイルフィールドの情報が取得できません。
- app.record.create.submit
- mobile.app.record.create.submit
レコード追加画面の保存成功後イベント
レコード追加画面もしくは、再利用画面で保存ボタンをクリックし、サーバーの保存が成功した後に発生します。
- PCとモバイルで利用できるイベントです。
- スペースに貼りつけたアプリには利用できません。
- kintone.Promiseオブジェクトをreturnすると、非同期処理の完了を待って次の処理を開始します。
- 保存が失敗した場合にはイベントが実行されません。
イベントタイプ
| 環境 | イベントタイプ | イベントが発生するタイミング |
|---|---|---|
| PC | app.record.create.submit.success |
|
|
モバイル
|
mobile.app.record.create.submit.success |
|
eventオブジェクトのプロパティ
| プロパティ名 | 型 | 説明 |
|---|---|---|
| appId | 数値 | アプリID |
| recordId | 文字列 | レコードID |
| record | オブジェクト |
ユーザー入力のデータを保持したレコードオブジェクト※ ※レコードオブジェクトとは、フィールドコードとフィールドの値などのレコードの情報を含むオブジェクトです。 追加したレコードに対して閲覧権限がない場合には、null が返されます。 |
| type | 文字列 | イベントタイプ |
urlプロパティの指定
eventオブジェクトにurlプロパティを指定してeventをreturnすると、イベント処理後にそのURLに遷移します。
url プロパティの指定なし、またはnullを指定した場合は、通常通りレコード詳細画面に遷移します。
例えば、次のように記載すると、保存成功後に画面が「http://cybozu.co.jp/」に遷移します。
eventオブジェクトで実行できる操作
ありません。
サンプル
eventオブジェクトで実行できる操作
フィールドの値を書き換える
ハンドラーが record オブジェクトのフィールドの値を書き換えて event オブジェクトを return した場合、その値でフィールドの値を更新します。
- PCとモバイルで利用できます。
- スペースに貼りつけたアプリには利用できません。
- フィールドの編集を不可にしても、値を書き換えることができます。
- 編集権限のないフィールドの値を書き換えた場合はフォームには反映されません。
- 最後のハンドラーが return しない場合、フィールドの値を更新しません。
- 複数のハンドラーが登録されている場合、最後のハンドラーが return した戻り値を基準に反映されます。
サンプル
レコード追加画面を開いた時に「文字列_0」 フィールド、テーブル「Table」の1行目の「文字列_1」フィールドに初期値をセットし、さらにテーブルの末尾に行を追加します。
※テーブルの行追加にはフィールドタイプの指定が必要です。PCとモバイルで利用できます。
書き換えできないフィールド
以下のフィールドは、保存実行前イベントのハンドラーでフィールドの値を書き換えて return しても、フォームには反映されません。
- レコード番号
- 作成者
- 作成日時
- 更新者
- 更新日時
- ステータス
- 作業者
- 計算
- 自動計算にした文字列1行
- 添付ファイル
- ルックアップ
- ルックアップコピー先フィールド
フィールドの編集可／不可を設定する
ハンドラーが record オブジェクトのフィールドの disabled に true/falseを代入して event オブジェクトを return した場合は、そのフィールドは編集不可／可になります。
- PCとモバイルで利用できます。
- スペースに貼りつけたアプリには利用できません。
- 編集権限のないフィールドを編集可能（disabled を false）にしても反映されません。
サンプル
「ドロップダウン_0」フィールドの値が変更になった時に、「文字列_0」 フィールドを編集不可にします。
編集可／不可にできないフィールド
以下のフィールドの値を編集可／不可を設定して return しても、フォームには反映されません。
- レコード番号
- 作成者
- 作成日時
- 更新者
- 更新日時
- ステータス
- 作業者
- 自動計算にした文字列1行
- 計算
フィールドにエラーを表示する
ハンドラーが record オブジェクトのフィールドの error にエラーメッセージを代入して event オブジェクトを return した場合、 フォームの値の書き換えと編集可／不可の設定はキャンセルされ、フィールドにエラーメッセージが表示されます。
- PCとモバイルで利用できます。
- スペースに貼りつけたアプリには利用できません。
- フィールドの error に null を代入し event オブジェクトを return した場合、そのフィールドに表示されていたエラーを消すことができます。
サンプル
「文字列_0」フィールドとテーブル「Table」の1行目の「文字列_1」フィールドにエラーを表示します。
以下のフィールドは、エラー値を設定しても、フィールドにエラーは表示されません。
- レコード番号
- 作成者
- 作成日時
- 更新者
- 更新日時
- ステータス
- 作業者
- 計算
レコードにエラーを表示する
ハンドラーが event オブジェクトの error にエラーメッセージを代入して event オブジェクトを return した場合、フィールドの値の書き換えと編集可／不可の設定はキャンセルされ、画面の上部にエラーメッセージが表示されます。
- PCとモバイルで利用できます。
- スペースに貼りつけたアプリには利用できません。
ルックアップを自動取得する
ルックアップフィールドの lookupプロパティに 'UPDATE' または trueを指定すると、ルックアップの取得を自動で行います。
- ルックアップの検索結果が１件の場合のみ、自動取得できます。
- PCとモバイルで利用できます。
- スペースに貼りつけたアプリには利用できません。
サンプル
レコード追加画面を開いた時に「ルックアップ」フィールドに値を入れてデータを取得します。
ルックアップのコピー先のフィールドの値を自動でクリアする
ルックアップフィールドの lookupプロパティに 'CLEAR' を指定すると、コピー先のフィールドの値を空にします。
- PCとモバイルで利用できます。
- スペースに貼りつけたアプリには利用できません。
サンプル
レコード追加画面を開いた時に「ルックアップ」フィールドのコピー先のフィールドの値をクリアします。
変更されたフィールドやテーブル内の行オブジェクトを取得する
変更のあったテーブル内の行オブジェクト、テーブル外のフィールドを取得できます。
- PCとモバイルで利用できます
- スペースに貼りつけたアプリには利用できません。
- rowオブジェクトは、テーブル内のイベント時のみ取得できます。
- テーブル内の行を削除した際には、rowオブジェクトは null になります。
その他
関連Tips
「ルックアップの取得を自動で行う」について質問です。
例えば、ルックアップの参照先データが以下とします。
あいうえお
あいうえ
この場合、以下としても取得されません。
「あいうえ」で検索し、「あいうえお」「あいうえ」がヒットするためと思われます。
kintone.events.on('app.record.create.show', function(event) {
var record = event.record;
record['ルックアップ']['value'] = 'あいうえ'; // ルックアップフィールドの値
record['ルックアップ']['lookup'] = true;
return event;
});
「あいうえ」を指定すると「あいうえ」で取得される方法はあるでしょうか。
よろしくお願いします。
ルックアップの絞り込みは「次のキーワードを含む」検索が可能で、検索関係はこちらに準拠していると思います。
過去にコミュニティでの回答をこちらにお知らせします。
https://cybozudev.zendesk.com/hc/ja/community/posts/202216884
完全一致で検索したい場合、検索キーワードをダブルクォーテーション（"）で囲みます。
とありますが、"あいうえ"と囲っても「あいうえお」「あいうえ」がヒットします。
仕様でしょうか？
イベント発生時に実行できる操作
【書き換えできないフィールド】
・ルックアップ
・ルックアップコピー先フィールド
なぜルックアップが書き換えできない仕様になっているのですか？
正直ルックアップのよくわからない仕様によって、コード量が無駄に３倍以上必要になるケースがあります。
せめて、ユニークが確定しているレコード番号で更新できるようにする等、もう少し改善できないのでしょうか。
いいかげんルックアップの設計にうんざりしてきました・・・。
西尾様
いつもお世話になっております。
ルックアップの仕様の件でご不便をおかけしております。
いただいたご意見は社内にフィードバックいたします。
また、すでにご存知かもしれませんが、6月のアップデートで、製品に関するフィードバックが可能になりました。
カスタマイズに関するご要望を送ることも可能ですので、ぜひご活用いただければと思います。
フィードバック画面へのアクセス方法: kintone画面の右上の？マークをクリック > 「kintone の改善に協力」をクリック
今後ともよろしくお願いいたします。
失礼します。
ルックアップフィールドの要素が検索先に復数あり、他の重複しない条件で絞る場合の書式はあるのでしょうか？
record['ルックアップ']['value'] = '0001';// 0001とそれ以外の検索条件を付加する場合
ルックアップフィールドが手入力（おぼろげな記憶から復数を選択したい）の場合と、他のアプリからのアクションボタンで起動する場合（100%決め打ち）があるので、ある程度ルックアップフィールドのキーに曖昧性を持たせてあり、別途IDというキーフィールドがあります。
また、ルックアップフィールドを第三のアプリから参照させています。
向井様
仕様についてのご質問ですが、以下の点確認させていただけますでしょうか。
>ルックアップフィールドのキーに曖昧性を持たせてあり、別途IDというキーフィールドがあります。
>record['ルックアップ']['value'] = '0001';// 0001とそれ以外の検索条件を付加する場合
-> '0001'にあたる部分では、検索結果が複数出てしまうため、別途IDというキーフィールド（ルックアップのキーではない）で絞りたいということでしょうか？
ご回答ありがとうございます。
はい。
そうです。
人が記憶に頼ってルックアップの検索に依存して入力します。
IDを記憶する事は困難なので一発で辿り着けません。
record['ルックアップ']['value'] = '0001'
の書式で他の要素で絞れるなら少しの修正で完了するので質問させて頂きました。
向井様
開発部門にも確認いたしましたが、他の条件の記述はできない仕様ということでした。お役に立てず申し訳ありません。
左様でしたか。
ありがとうございました。
冒頭（以下）の質問ですが、現在も完全一致で絞込み不可でしょうか？
ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー
「あいうえ」を指定すると「あいうえ」で取得される方法はあるでしょうか。
ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー
候補が１つの場合、自動で取得しますが、枝番等で候補が複数あると何も取得しません。
よろしくお願いします。
Hiroshi 様
お世話になっております。developer network事務局です。
申し訳ございませんが、現在も絞り込みは不可となっております。
手動によるルックアップ時に候補が複数出る場合は
こちらのカスタマイズを行った場合でも何も取得されません。
その場合、ルックアップフィールドに値は自動で入りますので、その後手動で候補から選択いただく形となります。
よろしくお願いいたします。
レコードIDを文字フィールドへコピーしたいのですが、良い方法はありますでしょうか？
※使用したいプラグインの仕様でレコードIDが使用できないため
レコードIDが割り振られるタイミングとしては、[レコード追加画面の保存成功後イベント]かと思います。
そのため、文字フィールドへの書き込みができそうにありませんでした。。
アドバイスなど頂けましたら助かります。。
溝田綾介 様
お世話になっております。cybozu developer network 事務局です。
誤認識の通り、レコードID及びレコード番号はレコードの保存後に割り振られます。
利用する（文字列フィールドへコピーしたい）データがレコード番号である必要性あるということであれば、
保存実行後にREST APIを利用してレコード更新をかけていただくという方法があります。
詳細な実現方法のご質問は、コミュニティをご活用ください。
コミュニティでご質問いただく際は、文字列フィールドに保存した値をどのように利用したいか、などの
ご質問背景を詳細に記載いただきますと、どのような実現方法が良いか回答がつきやすくなるかと思います。
以上、よろしくお願いいたします。
アドバイス頂きありがとうございます！
コミュニティにて解決しました。
レコード追加する際、レコード番号をフィールドにコピペする
御世話になっております。
ルックアップの自動取得ですが、テーブル内に設定したルックアップを自動取得するにはどのようにすれば良いでしょうか。
アクションで他アプリからデータを移行させた際に、テーブル内に設定したルックアップを自動取得させたいです。
テーブル以外のルックアップフィールドでは自動取得できたのですが、テーブル内のルックアップがうまくいきません。
お忙しいところに大変恐縮でございますが、アドバイスを頂ければ助かります。
鵜沼 巧 様
お世話になっております。cybozu developer network 運営でございます。
恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
記事から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。
ご質問と似たような投稿もございましたので、こちらも合わせて参考にしてみてください。
テーブルのルックアップの自動取得
よろしくお願い致します。
お世話になっております。
レコードがフォームなどから自動追加された際のイベントタイプはありますでしょうか。
手動で「保存」ボタンを押した際に動作は確認したのですが、自動で追加されたものは通知が来ない状況です。
よろしくお願いいたします。
しんご 様
お世話になっております。cybozu developer network 運営でございます。
自動で追加とは何をさしますでしょうか？
レコード追加に関しては、この記事に示すイベント以外はありません。
kintone内に限らず外部のシステムなどを用いレコードが作成されたのをきっかけになにかをしたい場合は、
Webhookをご利用いただく方法もあるとおもいます。詳しくは下記ヘルプをご参考ください。
https://jp.cybozu.help/k/ja/user/app_settings/set_webhook/webhook.html
また、恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
記事から派生した技術的なご質問はcybozu developer コミュニティをご活用ください。
よろしくお願い致します。
こちらのレコード追加イベントにつきまして、REST APIを用いたレコード追加の際にも発火しますでしょうか。
このページの説明文をレコード追加画面での操作に対して発火するイベントと自分は解釈したため、上記が気になり質問させていただきました。
青野圭哲 様
お世話になっております。cybozu developer network 運営でございます。
ご認識の通りレコード追加画面での操作に対してのイベントとなりますので、REST APIを用いたレコード追加とは関係しません。
（参考として、REST APIなども含んだレコードが追加されたときなどに外部サービスに連携するためのWebhookという別に機能もございます）
恐れ入りますが、こちらのコメント欄は記事内容のフィードバック目的となっているため、
その他記事から派生した技術的なご質問がございましたらcybozu developer コミュニティをご活用ください。
よろしくお願い致します。