<div>kintone の JavaScript カスタマイズを実装する際、多くの場合、予め用意されている API である<code>kintone.events.on</code>メソッドを介してアプリを操作します。
メソッド内で想定した通りのデータを受け取り、想定した通りにデータを返却できる限りは問題ありませんが、フィールドコードが変更された場合など、想定しない状態となった場合に備えたコーディングをされているでしょうか？
例えば、操作しているレコード内のフィールドコードは〇〇で、フィールドタイプは △△ だということを前提として処理していませんか？
kintone アプリと JavaScript カスタマイズは独立しているため、ある程度前提とする条件があることは仕方ありませんが、万が一想定しない状態となった場合に備えて例外処理を用意しておくことは大切です。
今回は、kintone の JavaScript カスタマイズにおける例外処理についてまとめます。
<h2 id="エラーを放置するとどうなるのか">エラーを放置するとどうなるのか</h2>
以下のコードは、レコード新規作成時のレコード保存イベントの中で、意図的にエラーを発生させるサンプルです。
<div class="user-token-code-block">カスタマイズでエラーが発生した状態を想定<pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.submit'], (event) =&gt; {
 throw 'テストプログラムで発生したエラー';

 return event; // ここにはたどり着かない
});</code></pre></div>この状態でレコードを新規作成し、保存ボタンをクリックしても、レコードが保存されることはありません。
カスタマイズ中でエラーが発生し、<code>kintone.events.on</code>メソッドのコールバック関数から受け取った<code>event</code>オブジェクトが適切に返却されなかったためです。
コンソールにエラーを通知するログが出力されますが、それ以外に何も影響が起きないため、ユーザーからすると「ボタンを押しているのに反応しない」ということしか分かりません。
<h2 id="エラーの対処">エラーの対処</h2>
kintone には、エラーが発生した場合にユーザーに通知する API もいくつか用意されています。
<code>kintone.events.on</code>メソッドのコールバック関数から受け取った<code>event</code>オブジェクトに<code>error</code>プロパティを追加することで、ユーザーにエラーを通知することが可能です。
また、<code>error</code>プロパティが追加されている場合、保存処理は自動的に中断されます。
<div class="user-token-code-block">エラーをユーザーへ通知<pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.submit'], (event) =&gt; {
 try {
 throw 'テストプログラムで発生したエラー';
 } catch (error) {
 event.error = 'JavaScriptカスタマイズでエラーが発生しました';
 }

 return event; // レコード保存は中断される
});</code></pre></div>これによって、「ボタンを押しているのに反応しない」という状況は避けることができます。
ただ、この後ユーザーがどのように行動すべきなのかこれだけでは判断できないため、表示させるエラーメッセージは工夫しておく必要があります。
<div class="user-token-code-block">エラーをユーザーへ通知<pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.submit'], (event) =&gt; {
 try {
 throw 'テストプログラムで発生したエラー';
 } catch (error) {
 event.error = 'レコード保存時にエラーが発生しました。登録情報に不足がないか確認してください。繰り返しエラーが発生する場合は、管理者までお問い合わせください。';
 }

 return event;
});</code></pre></div>また、開発者がエラーを再現し状態を確認するために、ログを出力しておくことをおすすめします。
<div class="user-token-code-block"><pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.submit'], (event) =&gt; {
 try {
 throw 'テストプログラムで発生したエラー';
 } catch (error) {
 console.error('JavaScriptカスタマイズでエラーが発生しました', error); // 開発者確認用
 event.error =
 'レコード保存時にエラーが発生しました。登録情報に不足がないか確認してください。繰り返しエラーが発生する場合は、管理者までお問い合わせください。'; // ユーザー確認用
 }

 return event;
});</code></pre></div><h3 id="おすすめの対応方法">おすすめの対応方法</h3>
エラーの発生はユーザーにとって、大して重要でないこともあります。そういった場合、管理者へ報告されない可能性もあります。
エラー対応のおすすめの方法は、ユーザーからの報告を待たずして、管理者がエラーに気づくことのできる仕組みづくりです。
具体的には、エラーの発生を記録するアプリを作成し、エラー発生時にエラーの詳細情報を保存するよう設定しておくことです。
<div class="user-token-code-block"><pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.submit'], async (event) =&gt; {
 try {
 throw 'テストプログラムで発生したエラー';
 } catch (error) {
 console.error('JavaScriptカスタマイズでエラーが発生しました', error);
 event.error =
 'レコード保存時にエラーが発生しました。登録情報に不足がないか確認してください。繰り返しエラーが発生する場合は、管理者までお問い合わせください。';
 await createErrorRecord(error);
 }

 return event;
});

/**
 * エラーの詳細をレコードとして保存します
 * @param { string } message エラーメッセージ
 */
const createErrorRecord = (message) =&gt; {
 const app = 999; // エラー保存用アプリのID
 const record = {
 イベント: { value: 'レコード保存時' },
 詳細: { value: message },
 };

 return kintone.api(kintone.api.url('/k/v1/record.json', true), 'POST', { app, record });
};</code></pre></div>上記のレコード作成処理はサンプルなので最低限の項目しかありませんが、その時点で判断できる情報をできる限り多く残しておくことで、より速い問題解決につながります。
チャットツールなどと連携し、自動的に通知が送信されるような仕組みを作っておくとなお良いかと思います。
<h3 id="エラーの有無にかかわらず処理を続行させたい場合">エラーの有無にかかわらず処理を続行させたい場合</h3>
あまりおすすめはしませんが、JavaScript カスタマイズが動作しなくてもアプリに大きな影響を与えないのであれば、エラーをなかったこととして処理を進める事も可能です。
<div class="user-token-code-block">エラーをなかったことにする<pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.submit'], (event) =&gt; {
 try {
 throw 'テストプログラムで発生したエラー'; // 1. エラーが発生する
 } catch (error) {
 // 2.エラーをなかったことにする
 }

 return event; // 3.正しく返却される
});</code></pre></div>ただこれでは、ユーザーもプログラム作成者もエラーに気づくことができないため、適切な対応とは言えません。
とにかくフローの続行だけを優先したい場合など、応急処置的な対応に留めておいた方がよいです。
</div>

kintoneのエラーハンドリング入門

エラーを放置するとどうなるのか

エラーの有無にかかわらず処理を続行させたい場合

<div>kintone における javascript のカスタマイズ例として、チェックボックスをトリガーとしたい場合も多いかと思います。
ここでは javascript カスタマイズを使って、チェックボックスを操作する方法を紹介します。
<h2 id="チェックボックスの仕様について">チェックボックスの仕様について</h2>
cybozu が公開している<a href="https://github.com/kintone/js-sdk/tree/master/packages/dts-gen" rel="ugc nofollow noopener noreferrer" target="_blank">@kintone/dts-gen</a>に含まれている型定義ファイルを見ると、kintone のチェックボックスは以下のように定義されています。
<div class="user-token-code-block">チェックボックスの型定義<pre><code class="user-token-hljs user-token-language-typescript">interface CheckBox {
 type?: 'CHECK_BOX';
 value: string[];
 disabled?: boolean;
 error?: string;
}</code></pre></div>チェックボックスフィールドは複数のチェックボックスを実装できる仕様となっているため、<code>value</code>は配列で定義されているようです。
例えば、「うさぎ」と「かえる」という２つのチェックボックスを実装し、フィールドコードを「動物」としたチェックボックスフィールドが存在する場合、データは以下のように格納されます。
<div class="user-token-code-block">チェックボックスのデータ<pre><code class="user-token-hljs user-token-language-javascript">record['動物'].value = ['うさぎ', 'かえる'];</code></pre></div><h2 id="チェックボックスの操作">チェックボックスの操作</h2>
<h3 id="javascript からチェックを追加する">javascript からチェックを追加する</h3>
前述した「動物」チェックボックスフィールドにチェックを追加する場合のコードです。
<div class="user-token-code-block">チェックボックスにチェックを追加する<pre><code class="user-token-hljs user-token-language-javascript">record['動物'].value.push('かえる');</code></pre></div><h3 id="javascript からチェックを解除する">javascript からチェックを解除する</h3>
javascript において、配列から要素を削除する方法はいくつかありますが、filter を使う方法が kintone の仕様と相性が良いのではないかと思います。
<div class="user-token-code-block">チェックボックスのチェックを解除する<pre><code class="user-token-hljs user-token-language-javascript">record['動物'].value = record['動物'].value.filter((item) =&gt; item === 'かえる');</code></pre></div><h2 id="クエリーでのチェックボックスの操作">クエリーでのチェックボックスの操作</h2>
次に、REST API などで使用するクエリーにおける、チェックボックスの項目の指定方法を紹介します。
<h3 id="チェックが入っている場合">チェックが入っている場合</h3>
チェックボックスフィールドの項目にチェックが入っているレコードを抽出する場合は、以下のように指定します。
<div class="user-token-code-block">チェックが入っているレコードを抽出するクエリー<pre><code class="user-token-hljs user-token-language-bash">動物 in ("かえる")</code></pre></div>フィールドコードにダブルクォーテーションは不要ですが、項目には必ずダブルクォーテーションを付ける必要があります。
たとえ対象のチェックボックスフィールドにチェックボックスが 1 つしか実装されていなかったとしても、上記のように指定します。
<h3 id="チェックが入っていない場合">チェックが入っていない場合</h3>
チェックボックスフィールドの項目にチェックが入っていないレコードを抽出する場合は、以下のように指定します。
<div class="user-token-code-block">チェックが入っていないレコードを抽出するクエリー<pre><code class="user-token-hljs user-token-language-bash">動物 not in ("かえる")</code></pre></div>前述したチェックが入っている場合のクエリーに<code>not</code>を追加しただけです。
</div>

javascriptカスタマイズ、クエリー操作におけるチェックボックスの取り扱い【kintone】

チェックボックスの仕様について

javascript からチェックを追加する

javascript からチェックを解除する

クエリーでのチェックボックスの操作

<div>皆さんは <code>Promise</code>をご存知でしょうか。
<code>Promise</code>を使った非同期処理は、javascript を学ぶ上で 1 つの大きな壁になる部分ではないかと思います。
しかし、IE のサポート終了が決定し、考慮すべき環境がモダンブラウザのみとなった現在では、<code>Promise</code>を使って非同期関数を処理する必要はありません。
<code>async/await</code>を使用することで、非同期処理を同期的な記述で実現することができます。
今回は、IE 廃止時代の kintone における非同期処理の実装方法を紹介します。
<h2 id="記述方法">記述方法</h2>
kintone カスタマイズで最もよく使用するであろう、REST API を使ったレコードの取得を非同期処理の例として使用します。
<div class="user-token-code-block">使用する非同期処理<pre><code class="user-token-hljs user-token-language-javascript">/**
 * 指定したアプリIDのレコードを取得します
 *
 * @param { string | number } app アプリID
 * @return { Promise&lt;any&gt; } REST APIの取得結果
 */
function getRecords(app) {
 return kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', { app });
}</code></pre></div><h3 id="Promise を使った場合">Promise を使った場合</h3>
まず<code>Promise</code>オブジェクトを使用した場合のコードをご覧ください。
レコード作成時に、特定のアプリからレコードを取得してログを出力するサンプルです。
<div class="user-token-code-block">Promiseを使用した場合<pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.show'], (event) =&gt; {
 return getRecords(15)
 .then((response) =&gt; {
 console.log('レコードを取得しました', response);

 return event;
 })
 .catch((error) =&gt; {
 console.error('レコード取得時にエラーが発生しました', error);
 event.error = 'カスタマイズ処理でエラーが発生しました';

 return event;
 });
});</code></pre></div><code>Promise</code>オブジェクトを使用した場合、<code>then</code>,<code>catch</code>メソッドにそれぞれ非同期処理に成功した場合、失敗した場合の処理を記述します。
また、<code>kintone.events.on</code>メソッドの第二引数のコールバック関数は、受け取った<code>event</code>オブジェクトを返却する必要があるため、Promise の各メソッドで<code>event</code>オブジェクトを<code>return</code>させています。
では、非同期処理の完了後に別の非同期処理を実行したい場合はどうでしょうか。
<div class="user-token-code-block">非同期処理が複数回必要な場合<pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.show'], (event) =&gt; {
 return getRecords(15)
 .then((first) =&gt; {
 console.log('アプリID:15のレコードを取得しました', first);

 return getRecords(16);
 })
 .then((second) =&gt; {
 console.log('アプリID:16のレコードを取得しました', second);

 return event;
 })
 .catch((error) =&gt; {
 console.error('アプリID15, 16いずれかのレコード取得時にエラーが発生しました', error);
 event.error = 'カスタマイズ処理でエラーが発生しました';

 return event;
 });
});</code></pre></div><code>then</code>メソッドのコールバック関数内で再度<code>Promise</code>オブジェクトを返すと、次の<code>then</code>メソッドで取得することができます。
このように<code>then</code>、<code>catch</code>で処理をつなげていくことをメソッドチェーンといいます。
今回は結果を受け取った後の処理が簡単なので可読性に大きな影響はないですが、メソッドチェーンのネスト構造や、最終的にどこへ<code>return</code>するのか、辿るのは簡単ではありません。
<h3 id="async/await を使用した場合">async/await を使用した場合</h3>
前述した<code>Promise</code>を使用した、非同期処理が複数回必要な場合のコードを<code>async/await</code>に置き換えると以下のようになります。
<div class="user-token-code-block">async/awaitを使用した場合<pre><code class="user-token-hljs user-token-language-javascript">kintone.events.on(['app.record.create.show'], async (event) =&gt; {
 try {
 const first = await getRecords(15);
 console.log('アプリID:15のレコードを取得しました', first);

 const second = await getRecords(16);
 console.log('アプリID:16のレコードを取得しました', second);
 } catch (error) {
 console.error('アプリID15, 16いずれかのレコード取得時にエラーが発生しました', error);
 event.error = 'カスタマイズ処理でエラーが発生しました';
 }
 return event;
});</code></pre></div>いかかでしょうか、ネスト構造も可読性も改善していると思います。
コールバック関数の先頭に<code>async</code>を追加し、各非同期処理の手前に<code>await</code>を記述しています。
このようにすることで、非同期処理を同期処理とほぼ同様の記述方法で実現することが可能です。
<h2 id="例外">例外</h2>
Promise は非同期処理の作成に限らず、非同期処理に関する多くの機能を包括するオブジェクトです。
非同期処理の同期的な処理は<code>async/await</code>で代替できますが、他の非同期処理を操作するメソッド群は把握しておくと役に立つと思います。
<h3 id="非同期関数の定義">非同期関数の定義</h3>
非同期関数を同期的に処理するだけであれば<code>Promise</code>は不要ですが、自分で非同期処理を定義したい場合は<code>Promise</code>が必要になります。
kintone の javascript カスタマイズではあまり必要になることはありませんが、意図的に遅延を発生させたい場合などに有効です。
以下のコードは画面にボタンを設置し、ボタンクリックから 1 秒経過後に処理を実行するサンプルです。
<div class="user-token-code-block">非同期処理の定義<pre><code class="user-token-hljs user-token-language-javascript">/**
 * 一定時間待機します
 * @param { number } ms 待機する時間(ミリ秒)
 */
function wait(ms) {
 return new Promise((resolve) =&gt; setTimeout(resolve, ms);
}

kintone.events.on('app.record.edit.show', (event) =&gt; {
 const button = document.createElement('button');
 document.body.append(button);

 button.addEventListener('click', async (event) =&gt; {
 // 1秒待機
 await wait(1000);
 console.log("ボタンを押して1秒が経過しました");
 });

 return event;
});</code></pre></div><h3 id="Promise.all">Promise.all</h3>
<code>Promise.all</code>メソッドは引数に <code>Promise</code>オブジェクトを配列で指定し、その全てが完了、またはいずれかがエラーとなったタイミングでデータが返却されます。
分割代入とも相性が良いので、複数の非同期処理結果から後続する処理を実行する必要がある場合に有効です。
<div class="user-token-code-block">Promise.allの使い方<pre><code class="user-token-hljs user-token-language-javascript">async function getFruits() {
 // 非同期処理
}

async function getDishes() {
 // 非同期処理;
}

async function dinner() {
 const [fruits, dishes] = await Promise.all([getFruits(), getDishes()]);

 cooking(fruits, dishes);
}</code></pre></div><h3 id="Promise.allSettled">Promise.allSettled</h3>
<code>Promise.allSettled</code>メソッドは<code>Promise.all</code>と同様に、複数の非同期処理を同時に処理するためのメソッドですが、エラーが発生した場合の挙動に違いがあります。
<code>Promise.all</code>を使用した場合、指定した非同期処理のいずれか１つがエラーが発生した場合、他の非同期処理の終了を待たずしてエラーがスローされます。
<code>Promise.allSettled</code>を使用すると、指定した非同期処理のエラーの発生有無にかかわらず、全ての非同期処理が完了するまで待機します。
返り値にはそれぞれ<code>status</code>と<code>value</code>があり、status から非同期処理でエラーが発生したかどうかを確認できます。
<div class="user-token-code-block">Promise.allSettledの使い方<pre><code class="user-token-hljs user-token-language-javascript">async function getFruits() {
 // 非同期処理
}

async function getDishes() {
 // 非同期処理;
}

async function dinner() {
 const [fruits, dishes] = await Promise.allSettled([getFruits(), getDishes()]);

 if (fruits.status === 'fulfilled' &amp;&amp; dishes.status === 'fulfilled') {
 cooking(fruits.value, dishes.value);
 } else {
 shopping();
 }
}</code></pre></div></div>

kintone

kintoneのエラーハンドリング入門

javascriptカスタマイズ、クエリー操作におけるチェックボックスの取り扱い【kintone】

kintoneのjavascriptカスタマイズにPromiseは要らない