createDialogとshowConfirmDialogの使い分け
はじめに
kintoneでは、ダイアログを表示するためのAPIとして、kintone.showConfirmDialogとkintone.createDialogの2つが提供されています。
- 確認ダイアログを表示する(kintone.showConfirmDialog) : ユーザーに確認を求めるシンプルなダイアログを表示するAPI
- ダイアログを作成する(kintone.createDialog) : HTML要素を自由に配置できる、カスタマイズ性の高いAPI
どちらもダイアログを表示するAPIですが、「どちらを使えばよいのか?」 と迷う方も多いのではないでしょうか。
この記事では、2つのAPIの違いと使い分けのポイントを解説します。
2つのAPIの基本的な違い
まず、2つのAPIの主な違いを表にまとめます。
| 項目 | kintone.showConfirmDialog | kintone.createDialog |
|---|---|---|
| 本文の指定方法 | 文字列(\nで改行) |
Elementオブジェクト(HTML要素) |
| カスタマイズ性 | シンプル(テキストのみ) | 高い(自由にHTMLを構築可能) |
| 戻り値 | Promise(ユーザーの選択結果) | Promise(ダイアログオブジェクト) |
| 表示方法 | 関数呼び出しで直接表示 | show()メソッドで表示 |
| 閉じる前の制御 | 不可 | beforeClose関数で制御可能 |
| プログラムから閉じる | 不可 | close()メソッドで可能 |
| 用途 | シンプルな確認ダイアログ | フォーム入力、複雑なUI |
kintone.showConfirmDialogの使い方
kintone.showConfirmDialogは、シンプルなテキストベースの確認ダイアログを表示するAPIです。
ユーザーに「はい/いいえ」を問いかけるような、単純な確認に適しています。
基本的な使い方
次のコードは、レコード一覧画面にボタンを配置し、ボタンクリック時に確認ダイアログを表示する例です。
|
|
このAPIは、関数を呼び出すとすぐにダイアログを表示し、ユーザーの選択結果('OK'、'CANCEL'、'CLOSE')をPromiseで返します。
kintone.createDialogが適しているケース
- レコードの削除確認
- レコード保存前の確認
- シンプルな警告メッセージの表示
- テキストのみで完結する確認ダイアログ
kintone.createDialogの使い方
kintone.createDialogは、ダイアログの本文にHTML要素を自由に配置できる、カスタマイズ性の高いAPIです。
フォーム入力やプログレス表示など、複雑なUIが必要な場合に適しています。
基本的な使い方
次のコードは、レコード詳細画面にボタンを配置し、クリック時にテキスト入力フォームを含むダイアログを表示する例です。
|
|
このAPIは、まずダイアログオブジェクトを作成し、show()メソッドでダイアログを表示する2段階の方式です。
beforeClose関数で閉じる前の処理を制御する
kintone.createDialogの特徴的な機能として、beforeClose関数があります。
この関数を使うと、ダイアログを閉じる前にバリデーションを行い、条件を満たさない場合はダイアログを閉じないようにできます。
このコードでは、OKボタンが押されたときに入力値を検証し、未入力の場合はメッセージを表示して、falseを返すことでダイアログを閉じないようにしています。
基本的な使い方のコードにbeforeCloseオプションを追加すると、次のようになります。
|
|
beforeClose関数は、ユーザーが選択した操作('OK'、'CANCEL'、'CLOSE')を引数に受け取ります。
関数がfalseを返すと、ダイアログは閉じられません。
close()メソッドでプログラムから閉じる
kintone.createDialogでは、close()メソッドを使ってプログラムからダイアログを閉じることもできます。
これは、非同期処理の完了後に自動的にダイアログを閉じたい場合などに便利です。
このコードは、一覧画面にボタンを追加し、非同期処理が完了すると自動でダイアログを閉じます。
|
|
この例では、OKボタン、キャンセルボタン、閉じるボタンをすべて非表示とし、処理完了後はclose()で自動的に閉じています。
createDialogが適しているケース
- フォーム入力が必要なダイアログ
- 入力値のバリデーションが必要な場合
- プログレスバーやローディング表示
- リストやテーブルを表示するダイアログ
- プログラムから任意のタイミングでダイアログを閉じたい場合
使い分けのポイント
どちらのAPIを使うべきか迷ったときは、次の表を参考にしてください。
| やりたいこと | 使用するAPI |
|---|---|
| テキストのみの確認ダイアログを表示したい | showConfirmDialog |
| 入力フォームを含むダイアログを表示したい | createDialog |
| 閉じる前にバリデーションしたい | createDialog |
| プログラムからダイアログを閉じたい | createDialog |
基本的に、シンプルな確認ならkintone.showConfirmDialog、カスタマイズや細かい制御が必要な場合はkintone.createDialog と覚えておくとよいでしょう。
注意事項
セキュリティに関する注意
kintone.createDialogのbodyパラメーターに指定したElementオブジェクトは、そのままダイアログ本文の要素として組み込まれます。
ユーザー入力を含む場合は、XSS(クロスサイトスクリプティング)攻撃を防ぐため、必要に応じてサニタイズ処理を行ってください。
詳しくは次のページを参照してください。
kintoneセキュアコーディングガイドライン | クロスサイトスクリプティングやCSSインジェクションを防ぐ
|
|
非同期処理について
どちらのAPIも非同期なAPIです。
同期的に処理したい場合は、async/awaitを使用してください。
詳しくは次のページを参照してください。
まとめ
kintone.showConfirmDialogは、シンプルなテキストベースの確認ダイアログに適しています。kintone.createDialogは、HTML要素を自由に配置でき、入力フォームや複雑なUIが必要な場合に適しています。beforeClose関数を使うと、閉じる前のバリデーションや処理を実装できます。close()メソッドを使うと、プログラムから任意のタイミングでダイアログを閉じられます。- ユーザー入力を表示する場合は、セキュリティに注意してサニタイズ処理を行いましょう。
おわりに
2つのダイアログAPIの違いと使い分けのポイントを解説しました。
用途に応じて適切なAPIを選択することで、より使いやすいkintoneカスタマイズを実現できます。
ダイアログを活用して、ユーザーフレンドリーなアプリを作成してください。
このTipsは、2025年1月版kintoneで動作を確認しています。
