HTMLDialogElement

インスタンスプロパティ

親インターフェイスである 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 id="favDialog"> <form method="dialog"> <p> <label for="favAnimal">好きな動物:</label> <select id="favAnimal" name="favAnimal"> <option></option> <option>アルテミア</option> <option>レッサーパンダ</option> <option>クモザル</option> </select> </p> <div> <button id="cancel" type="reset">キャンセル</button> <button id="submit" type="submit">確認</button> </div> </form> </dialog> <div> <button id="updateDetails">詳細を更新</button> </div> 

<pre id="log"></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 イベントの前）に発生します。

ここでは、ダイアログが開くためのリスナーと閉じられたときのログ出力するリスナーを追加します。

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 イベントを発生することに注意してください。また、結果は選択されたダイアログオプションを反映するはずです。

仕様書

ブラウザーの互換性

api.HTMLDialogElement

api.HTMLElement.beforetoggle_event.dialog_elements

api.HTMLElement.toggle_event.dialog_elements

関連情報

• このインターフェイスを実装している HTML 要素: <dialog>