ポップオーバー API

ウェブでは、他のコンテンツの上にコンテンツを示し、ユーザーにとって重要な情報や導くべき操作の詳細を示すというのが、とても一般的なパターンです。このコンテンツは、オーバーレイ、ポップアップ、ポップオーバー、ダイアログなど、さまざまな名称で呼ばれます。私たちは、このドキュメントを通して、これらをポップオーバーと呼ぶことにします。一般的に、これらは次のようなものがあります。

• モーダルというのは、ポップオーバーが示されている間、ページの残りの部分は、ポップオーバーが何らかのアクションを起こすまで（例えば、重要な選択がなされるまで）、反応しないようにレンダリングされるということです。
• 非モーダルというのは、ポップオーバーが表示されている間も、ページの残りの部分が反応するようにするということです。

ポップオーバー API を使用して作成されたポップオーバーは常に非モーダルです。モーダルポップオーバーを作成したい場合は、<dialog> 要素を使うのが適切ですが、既定では <dialog> 要素は最上位レイヤーには配置されないので注意してください。ポップオーバーはそうなります。2 つの間には明確な重複があります。ポップオーバーは、持続的なもので、宣言的な HTML を使用して制御したい場合などに作成します。ポップオーバーの制御と最上位の配置をダイアログの意味づけと組み合わせたい場合は、<dialog> 要素をポップオーバーすることもできます。

ポップオーバー API のよくある用途は、アクションメニュー、独自の「トースト」通知、フォーム要素のサジェスト、コンテンツピッカー、チュートリアル UI などのユーザーと対話する要素があります。

ポップオーバーは、2 つの異なる方法で作成することができます。

• 新しい一連の HTML 属性によって、宣言的に作成できます。トグルボタンを持つ単純なポップオーバーは、以下のコードで作成することができます。

  html

  <button popovertarget="mypopover">ポップオーバーの切り替え</button>
  <div id="mypopover" popover>ポップオーバーコンテンツ</div>
  

• JavaScript API から。例えば、HTMLElement.togglePopover() を使用してポップオーバーを表示と非表示のトグル切り替えができます。

また、ポップオーバーのトグルに反応する新しいイベントや、ポップオーバーのスタイル設定を支援する CSS 機能もあります。すべての新しい機能は以下の一覧に掲載されています。

ポップオーバー API の使用で、この API の詳細なガイドを参照してください。

popover

グローバル属性で、ある要素をポップオーバー要素にします。値としてポップオーバー状態（"auto" または "manual"）を取ります。

popovertarget

<button> または <input> 要素をポップオーバー制御ボタンにします。値として、制御するポップオーバー要素の ID を取ります。

popovertargetaction

制御ボタン（<button> または <input>）で制御しているポップオーバー要素に対して行う動作（"hide"、"show"、"toggle" の何れか）を指定します。

::backdrop

擬似要素 ::backdrop は、ポップオーバー要素の後ろに直接配置される全画面要素で、ポップオーバーの背後にあるページコンテンツに必要な効果を追加することができます（ぼかすなど）。

:popover-open

popover-open 擬似クラスは、ポップオーバー要素が表示状態にあるときのみ一致します。これは、ポップオーバー要素が表示されているときのスタイル設定に使用できます。

ToggleEvent

popover 要素の状態が表示と非表示の間で切り替わるときにユーザーに通知するイベントを表します。これは、beforetoggle と toggle イベント用のイベントオブジェクトで、ポップオーバーでその状態が変化するときに発行されます。

HTMLElement.popover

要素のポップオーバー状態を JavaScript で取得または設定し（"auto" または "manual"）、機能検出にも使用することができます。HTML のグローバル属性である popover global を反映します。

HTMLButtonElement.popoverTargetElement および HTMLInputElement.popoverTargetElement

この制御ボタンで制御されるポップオーバー要素を取得または設定します。JavaScript において HTML の popovertarget 属性に相当するものです。

HTMLButtonElement.popoverTargetAction および HTMLInputElement.popoverTargetAction

この制御ボタンが制御するポップオーバー要素に対して行われるアクション（"hide"、"show"、"toggle" の何れか）を設定または取得します。HTML の popovertargetaction 属性を反映します。

HTMLElement.hidePopover()

ポップオーバー要素を最上位レイヤーから削除し、display: none でスタイル設定することにより、ポップオーバー要素を非表示にします。

HTMLElement.showPopover()

ポップオーバー要素を最上位レイヤーに追加して表示します。

HTMLElement.togglePopover()

ポップオーバー要素の表示状態と非表示状態を切り替えます。

HTMLElement の beforetoggle イベント

ポップオーバー要素の表示と非表示の状態が変わる直前、またはその逆で発行されます。

HTMLElement の toggle イベント

ポップオーバー要素の状態が、表示と非表示、またはその逆に変化した直後に発行されます。このイベントは、<details> 要素の状態変化を指示するためにすでに存在しており、ポップオーバー要素のためにこれを拡張することは理にかなっていると考えられています。

ポップオーバー API の例のランディングページに、MDN のポップオーバーの完全な例にアクセスできます。