← 返回首页

HTMLDialogElement - Web API | MDN

Toggle sidebar

Theme

OS default
Light
Dark

日本語

Remember language Learn more

HTMLDialogElement

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2022年3月.

* Some parts of this feature may have varying levels of support.

HTMLDialogElement インターフェイスは <dialog> 要素を操作するメソッドを提供します。 HTMLElement インターフェイスからプロパティとメソッドを継承しています。

EventTarget Node Element HTMLElement HTMLDialogElement

In this article

インスタンスプロパティ

親インターフェイスである 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イベント名プロパティにイベントリスナーを代入することによって待ち受けます。

ダイアログを閉じるリクエスト（エスケープキーや HTMLDialogElement.requestClose() メソッドなど）が行われた際に発行されます。

エスケープキー、HTMLDialogElement.close() メソッド、または method="dialog" でダイアログ内のフォームを送信することによって、このダイアログが閉じられたときに発行されます。

例

モーダルダイアログを開く

以下の例はボタンを表示し、クリックすると、 HTMLDialogElement.showModal() 関数を使用してフォームの入ったモーダルダイアログ (<dialog>) を開きます。

開いている間、モーダルダイアログのコンテンツ以外はすべて不活性になります。そこから［キャンセル］ボタンを押して（HTMLDialogElement.close() 関数で）ダイアログを閉じるか、［確認］ボタンでフォームを送信するかします。

この例は、ダイアログ上で発生可能なすべての「状態変更」イベント、cancel と close、および継承されたイベント beforetoggle と toggle の使用方法を示しています。

HTML

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() 関数を呼び出すリスナーを追加します。

js
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 に設定されます。

js
// 選択がある場合、確認ボタンはダイアログを閉じる
confirmButton.addEventListener("click", () => {
  if (selectElement.value) {
    // dialog.returnValue を選択された値に設定
    dialog.close(selectElement.value);
  }
});

// ダイアログボックスを閉じるフォームキャンセルボタン
cancelButton.addEventListener("click", () => {
  dialog.close(); // dialog.returnValue を null に設定
});

close() を呼び出しすと、 close イベントも発生します。下記でダイアログの返値をログ出力することでこれを実装します。［確認］ボタンがクリックされた場合、このこれはダイアログで選択された値であるべきです。そうでない場合は null であるべきです。

js
dialog.addEventListener("close", (event) => {
  log(`close_event: (dialog.returnValue: "${dialog.returnValue}")`);
});

cancel イベント

cancel イベントは、Esc キーなど「プラットフォーム特定の方法」が使用されてダイアログが閉じられる際に発行されます。 HTMLDialogElement.requestClose() メソッドが呼び出された場合にも発生します。このイベントは「キャンセル可能」です。つまり、ダイアログが閉じるのを阻止するために使用できます。ここではキャンセル操作を「閉じる」操作として扱い、設定された可能性のある値をクリアするために HTMLDialogElement.returnValue を "" にリセットします。

js
dialog.addEventListener("cancel", (event) => {
  log(`cancel_event: (dialog.returnValue: "${dialog.returnValue}")`);
  dialog.returnValue = ""; // 値をリセット
});

toggle イベント

toggleイベント（HTMLElement から継承）は、ダイアログが開かれるか閉じられた直後（ただし close イベントの前）に発生します。

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

メモ: toggle および beforetoggle イベントは、すべてのブラウザーでダイアログ要素に対して発行されるとは限りません。対応していないバージョンのブラウザーでは、代わりにダイアログを開いた/閉じた後、HTMLDialogElement.open プロパティを調べることで確認できます。

js
dialog.addEventListener("toggle", (event) => {
  log(`toggle_event: Dialog ${event.newState}`);
});

beforetoggle イベント

beforetoggleイベント（HTMLElementから継承）は、ダイアログが開く直前または閉じる直前に発行される、キャンセル可能なイベントです。必要があれば、この要素はダイアログの表示を阻止するために使用できますし、ダイアログの開閉状態に影響を受ける他の要素に対して措置を実行するために使用できます。例えば、アニメーションを起動するためにそれらの要素にクラスを追加するといった操作が可能です。

この場合、単に古い状態と新しい状態をログ出力します。

js
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

Enable JavaScript to view this browser compatibility table.

api.HTMLElement.beforetoggle_event.dialog_elements

Enable JavaScript to view this browser compatibility table.

api.HTMLElement.toggle_event.dialog_elements

Enable JavaScript to view this browser compatibility table.

関連情報

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

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 2025年9月20日 by MDN contributors.

View this page on GitHub • Report a problem with this content

HTML DOM API
HTMLDialogElement
インスタンスプロパティ
インスタンスメソッド
イベント
1. cancel
2. close
継承
HTML DOM に関連するページ
ガイド
1. JavaScript で queueMicrotask() によるマイクロタスクの使用
2. In depth: Microtasks and the JavaScript runtime environment