<dialog>: ダイアログ要素
=================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
**`<dialog>`** は HTML の要素で、ダイアログボックスや、消すことができるアラート、インスペクター、サブウィンドウ等のような対話的コンポーネントを表します。

属性
--

この要素にはグローバル属性があります。

**警告:** `tabindex` 属性を `<dialog>` 要素で使用してはいけません。

`open`

 ダイアログがアクティブで操作で使用できることを示します。 `open` 属性が設定されていないときは、ダイアログはユーザーに表示する*べきではありません*。
 ダイアログを表示するには、`open` 属性ではなく `.show()` または `.showModal()` メソッドを使用することが推奨されます。もし `<dialog>` が `open` 属性を使用して開かれた場合、そのダイアログはモーダルになりません。


アクセシビリティの考慮
-----------

モーダルダイアログの作成には、HTMLネイティブの `<dialog>` 要素を使用しましょう。これは、ユーザビリティとアクセシビリティの機能を提供するためで、他の要素を同様の目的で使用する場合は、それを再現しなければなりません。ダイアログを表示するには、`.showModal()` または `.show()` メソッドのうち適切な方を使用してください。独自のダイアログの実装を作成する場合は、期待される既定の動作にすべて対応していること、適切なラベル付けが行われていることを確認してください。

ダイアログを実装する際には、ユーザーのフォーカスを設定する場所として最も適切な場所を検討することが重要です。autofocus 属性を使用して初期フォーカスの配置を明確に示すと、特定のダイアログに対して最適な初期フォーカスの配置とみなされる要素に初期フォーカスが設定するのに役立ちます。ダイアログの初期フォーカスがどこに設定されるか常にわからない場合、特にダイアログのコンテンツが呼び出されたときに動的に描画される場合、必要であれば `<dialog>` 要素そのものにフォーカスを当てることが、初期フォーカスの配置として最適と判断されるかもしれません。`<dialog>` を開くための`HTMLDialogElement.showModal()`を使用すると、最初にネストしたフォーカス可能な要素にフォーカスが設定されます。

ユーザーがダイアログを閉じることができる機構を確実に用意してください。すべてのユーザーが確実にダイアログを閉じることができるようにする最も確実な方法は、閉じるための明確なボタンを記載することです。例えば、確認、キャンセル、閉じるなどのボタンが適切です。また、キーボードを使用する端末では、`Esc` キーでモーダルダイアログも閉じられると考えるのが一般的です。既定では、`showModal()` メソッドによって呼び出された `<dialog>` は、`Esc` によって閉じることができます。非モーダルダイアログでは、既定では `Esc` キーで閉じませんし、非モーダルダイアログが表すものによっては、この動作が望ましくない場合があります。複数のモーダルダイアログが開いている場合、`Esc` は最後に示されたダイアログのみを閉じるようにします。`<dialog>` を使用した場合、この動作はブラウザーによって提供されます。

`<dialog>` 要素は、ARIA の role="dialog" 属性を使用したカスタムダイアログと同じような形で、ブラウザーが提供します。`<dialog>` 要素が `showModal()` メソッドで呼び出された場合、暗黙のうちに aria-modal="true" (en-US) となり、一方 `<dialog>` が `show()` メソッド、または `open` 属性を使用して表示されたり `<dialog>` の既定の `display` を変更した場合は `[aria-modal="false"]` として表示されます。モーダルダイアログを実装する際には、`<dialog>` とそのコンテンツ以外は `inert` 属性を使って不活性化する必要があります。`<dialog>` を `HTMLDialogElement.showModal()` メソッドで使用した場合、この動作はブラウザーが提供します。

使用上の注意
------

* `<form>` 要素は `method="dialog"` 属性が指定されていれば、ダイアログを閉じることができます。そのようなフォームが送信されると、 `returnValue` プロパティにフォーム送信するために使用されたボタンの `value` が設定されて、ダイアログが閉じられます。
* CSS の `::backdrop` 擬似要素を使用して、 `<dialog>` 要素が `HTMLDialogElement.showModal()` で表示されたときの背後のスタイルを設定することができます。例えば、モーダルダイアログの背後にある操作できないコンテンツを暗くするなどです。
例
-

### シンプルな例

以下は、非モーダル、つまりモーダルレスなダイアログを表示します。"OK" ボタンは、起動時にダイアログを閉じられるようになっています。


```html
<dialog open>
  <p>Greetings, one and all!</p>
  <form method="dialog">
    <button>OK</button>
  </form>
</dialog>
```


#### 結果

このダイアログは `open` 属性によって開かれたので、モーダルではありません。この例では、ダイアログが閉じられたとき、それを再び開くためのメソッドは提供されていません。`HTMLDialogElement.show()` でダイアログを開く方が、論理属性の `open` 属性を切り替えるより望ましいです。

### 高度な例

この例では、"Show the dialog" ボタンをクリックすると、モーダルダイアログを開きます。ダイアログには `<select>` と 2 つの `<button>` 要素があり、これらは `type="submit"` に既定値として設定されています。`<select>` の値を更新すると、「確認」ボタンの値も更新されます。この値は `returnValue` です。`Esc`キーでダイアログが閉じられた場合、返値はありません。ダイアログが閉じられた場合、返値は「ダイアログを表示」ボタンの下に表示されます。

#### HTML


```html
<!-- フォームを含むモーダルダイアログ -->
<dialog id="favDialog">
  <form>
    <p>
      <label>
        Favorite animal:
        <select>
          <option value="default">Choose…</option>
          <option>Brine shrimp</option>
          <option>Red panda</option>
          <option>Spider monkey</option>
        </select>
      </label>
    </p>
    <div>
      <button value="cancel" formmethod="dialog">Cancel</button>
      <button id="confirmBtn" value="default">Confirm</button>
    </div>
  </form>
</dialog>
<p>
  <button id="showDialog">Show the dialog</button>
</p>
<output></output>
```


#### JavaScript


```js
const showButton = document.getElementById("showDialog");
const favDialog = document.getElementById("favDialog");
const outputBox = document.querySelector("output");
const selectEl = favDialog.querySelector("select");
const confirmBtn = favDialog.querySelector("#confirmBtn");

// "Show the dialog" ボタンで <dialog> をモーダルに開く
showButton.addEventListener("click", () => {
  favDialog.showModal();
});

// "Favorite animal" 入力で、送信ボタンの値を設定する
selectEl.addEventListener("change", (e) => {
  confirmBtn.value = selectEl.value;
});

// "Cancel" ボタンで [formmethod="dialog"] による送信を行わずにダイアログを閉じ、close イベントを発行する
favDialog.addEventListener("close", (e) => {
  outputBox.value =
    favDialog.returnValue === "default"
      ? "No return value."
      : `ReturnValue: ${favDialog.returnValue}.`; // 空文字列ではなく、既定値かどうかを調べる必要がある
});

// ［確認］ボタンが既定でフォームを送信しないようにし、`close()` メソッドでダイアログを閉じ、"close" イベントを発生させる
confirmBtn.addEventListener("click", (event) => {
  event.preventDefault(); // この偽フォームを送信しない
  favDialog.close(selectEl.value); // ここで選択ボックスの値を送る必要がある
});
```

### 結果

 このモーダルダイアログは、3 つの方法で閉じることができます。キーボードユーザーの場合、モーダルダイアログは `Esc` キーで閉じることができます。この例では、［キャンセル］ボタンは `dialog` フォームメソッドで、［確認］ボタンは `HTMLDialogElement.close()` メソッドでダイアログを閉じます。
 ［キャンセル］ボタンには `formmethod="dialog"` が含まれており、 `<form>` の既定の `GET` メソッド (`method`) を上書きします。フォームのメソッドが `dialog` の場合、フォームの状態は送信されずに保存され、ダイアログは閉じられます。
 `action` がない場合、既定の `GET` メソッドでフォームを送信すると、ページの再読み込みが発生します。JavaScript を使用して、送信を阻止し、ダイアログを閉じるために、それぞれ `event.preventDefault()` と `HTMLDialogElement.close()` メソッドを使用しています。

すべての `dialog` 要素に閉じるための仕組みを提供することが重要です。既定では、非モーダルのダイアログは `Esc` キーでは閉じませんし、ユーザーが物理キーボードにアクセスすることも想定してはいけません（たとえば、キーボードにアクセスできないタッチスクリーン端末を使用している人もいます）。

技術的概要
-----

|  |  |
| --- | --- |
| コンテンツカテゴリー | フローコンテンツ,
 区分化ルート |
| 許可された内容 | フローコンテンツ |
| タグの省略 | 不可。開始と終了タグの両方が必要。 |
| 許可された親要素 | フローコンテンツを受け入れるあらゆる要素 |
| 暗黙の ARIA ロール | dialog |
| 許可された ARIA ロール | `alertdialog` |
| DOM インターフェイス | `HTMLDialogElement` |

仕様書
---

| Specification |
| --- |
| HTML Standard # the-dialog-element |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `close` イベント
* `cancel` イベント
* HTML フォームガイド
* `::backdrop` 擬似要素
* dialog-polyfill