このページはコミュニティーの尽力で英語から翻訳されました。MDN Web Docsコミュニティーについてもっと知り、仲間になるにはこちらから。
HTMLDialogElement
HTMLDialogElement インターフェイスは<dialog> 要素を操作するメソッドを提供します。HTMLElement インターフェイスからプロパティとメソッドを継承しています。
インスタンスプロパティ
親インターフェイスであるHTMLElement から継承したプロパティもあります。
HTMLDialogElement.closedBy<dialog>要素のclosedby属性の値を設定または返す文字列。この属性は、ダイアログを閉じるために使用できるユーザー操作の種類を示します。HTMLDialogElement.open論理値で、ダイアログが操作可能であることを示す
open属性の値を反映します。HTMLDialogElement.returnValue文字列で、ダイアログの返値を設定または返却します。
インスタンスメソッド
親インターフェイスであるHTMLElement から継承したメソッドもあります。
HTMLDialogElement.close()ダイアログを閉じます。任意で引数として文字列を渡すことができ、これがダイアログの
returnValueを更新します。HTMLDialogElement.requestClose()ダイアログを閉じるリクエストをします。オプションの文字列引数を渡すことで、ダイアログの
returnValueを更新することができます。HTMLDialogElement.show()ダイアログをモードレスで開きます。すなわち、その間にダイアログの外のコンテンツが操作できます。
HTMLDialogElement.showModal()ダイアログをモーダルで、他のダイアログがあればその最も上に表示します。ダイアログの外の操作はブロックされます。ダイアログの外はすべてinert となり、ダイアログの外の操作はブロックされます。
イベント
親インターフェイスであるHTMLElement から継承したイベントがあります。
これらのイベントをaddEventListener() を使用して、またはこのインターフェイスのonイベント名 プロパティにイベントリスナーを代入することによって待ち受けます。
cancelダイアログを閉じるリクエスト（エスケープキーや
HTMLDialogElement.requestClose()メソッドなど）が行われた際に発行されます。closeエスケープキー、
HTMLDialogElement.close()メソッド、またはmethod="dialog"でダイアログ内のフォームを送信することによって、このダイアログが閉じられたときに発行されます。
例
モーダルダイアログを開く
以下の例はボタンを表示し、クリックすると、HTMLDialogElement.showModal() 関数を使用してフォームの入ったモーダルダイアログ (<dialog>) を開きます。
開いている間、モーダルダイアログのコンテンツ以外はすべて不活性になります。そこから［キャンセル］ボタンを押して（HTMLDialogElement.close() 関数で）ダイアログを閉じるか、［確認］ボタンでフォームを送信するかします。
この例は、ダイアログ上で発生可能なすべての「状態変更」イベント、cancel とclose、および継承されたイベントbeforetoggle とtoggle の使用方法を示しています。
HTML
<!-- フォームが入ったポップアップダイアログボックス --><dialog> <form method="dialog"> <p> <label for="favAnimal">好きな動物:</label> <select name="favAnimal"> <option></option> <option>アルテミア</option> <option>レッサーパンダ</option> <option>クモザル</option> </select> </p> <div> <button type="reset">キャンセル</button> <button type="submit">確認</button> </div> </form></dialog><div> <button>詳細を更新</button></div><pre></pre>#log { height: 150px; overflow: scroll; padding: 0.5rem; border: 1px solid black;}const logElement = document.querySelector("#log");function log(text) { logElement.innerText = `${logElement.innerText}${text}\n`; logElement.scrollTop = logElement.scrollHeight;}JavaScript
ダイアログの表示
コードはまず、<button> 要素、<dialog> 要素、<select> 要素のオブジェクトを取得します。次に、［更新］ボタンがクリックされたときにHTMLDialogElement.showModal() 関数を呼び出すリスナーを追加します。
const updateButton = document.getElementById("updateDetails");const confirmButton = document.getElementById("submit");const cancelButton = document.getElementById("cancel");const dialog = document.getElementById("favDialog");const selectElement = document.getElementById("favAnimal");// 更新ボタンを押すとモーダルダイアログが開くupdateButton.addEventListener("click", () => { dialog.showModal();});キャンセルおよび確認ボタン
次に、［確認］ボタンと［キャンセル］ボタンのclick イベントにリスナーを追加します。ハンドラーは、選択値（存在する場合）と値なしの状態でHTMLDialogElement.close() を呼び出します。これにより、ダイアログの返値 (HTMLDialogElement.returnValue) がそれぞれ選択値とnull に設定されます。
// 選択がある場合、確認ボタンはダイアログを閉じるconfirmButton.addEventListener("click", () => { if (selectElement.value) { // dialog.returnValue を選択された値に設定 dialog.close(selectElement.value); }});// ダイアログボックスを閉じるフォームキャンセルボタンcancelButton.addEventListener("click", () => { dialog.close(); // dialog.returnValue を null に設定});close() を呼び出しすと、close イベントも発生します。下記でダイアログの返値をログ出力することでこれを実装します。［確認］ボタンがクリックされた場合、このこれはダイアログで選択された値であるべきです。そうでない場合はnull であるべきです。
dialog.addEventListener("close", (event) => { log(`close_event: (dialog.returnValue: "${dialog.returnValue}")`);});cancel イベント
cancel イベントは、Esc キーなど「プラットフォーム特定の方法」が使用されてダイアログが閉じられる際に発行されます。HTMLDialogElement.requestClose() メソッドが呼び出された場合にも発生します。このイベントは「キャンセル可能」です。つまり、ダイアログが閉じるのを阻止するために使用できます。ここではキャンセル操作を「閉じる」操作として扱い、設定された可能性のある値をクリアするためにHTMLDialogElement.returnValue を"" にリセットします。
dialog.addEventListener("cancel", (event) => { log(`cancel_event: (dialog.returnValue: "${dialog.returnValue}")`); dialog.returnValue = ""; // 値をリセット});toggle イベント
toggleイベント（HTMLElement から継承）は、ダイアログが開かれるか閉じられた直後（ただしclose イベントの前）に発生します。
ここでは、ダイアログが開くためのリスナーと閉じられたときのログ出力するリスナーを追加します。
メモ:toggle およびbeforetoggle イベントは、すべてのブラウザーでダイアログ要素に対して発行されるとは限りません。対応していないバージョンのブラウザーでは、代わりにダイアログを開いた/閉じた後、HTMLDialogElement.open プロパティを調べることで確認できます。
dialog.addEventListener("toggle", (event) => { log(`toggle_event: Dialog ${event.newState}`);});beforetoggle イベント
beforetoggleイベント（HTMLElementから継承）は、ダイアログが開く直前または閉じる直前に発行される、キャンセル可能なイベントです。必要があれば、この要素はダイアログの表示を阻止するために使用できますし、ダイアログの開閉状態に影響を受ける他の要素に対して措置を実行するために使用できます。例えば、アニメーションを起動するためにそれらの要素にクラスを追加するといった操作が可能です。
この場合、単に古い状態と新しい状態をログ出力します。
dialog.addEventListener("beforetoggle", (event) => { log( `beforetoggle event: oldState: ${event.oldState}, newState: ${event.newState}`, ); // event.preventDefault() を呼び出すと、ダイアログが開くのを阻止する /* if (shouldCancel()) { event.preventDefault(); } */});結果
下の例を試してみてください。確認 ボタンとキャンセル ボタンの両方でclose イベントを発生することに注意してください。また、結果は選択されたダイアログオプションを反映するはずです。
仕様書
| Specification |
|---|
| HTML # htmldialogelement |
| HTML # event-beforetoggle |
| HTML # event-toggle |
ブラウザーの互換性
api.HTMLDialogElement
api.HTMLElement.beforetoggle_event.dialog_elements
api.HTMLElement.toggle_event.dialog_elements
関連情報
- このインターフェイスを実装している HTML 要素:
<dialog>