Edition for Web Developers — Last Updated 29 August 2024
popover
属性Support in all current engines.
すべてのHTML要素はpopover
コンテンツ属性設定を持ってもよい。指定された場合、要素は表示されるまでレンダリングされず、表示されると、他のページ コンテンツの上にレンダリングされる。
popover
属性は、最も関連性の高いセマンティックスをもつ要素にポップオーバー機能を適用できるように、著者に柔軟性を与えるグローバル属性である。
次は、ウェブサイトのグローバルナビゲーション内で、リンクのポップオーバーサブナビゲーションリストを作成する方法を示す。
< ul >
< li >
< a href = ... > All Products</ a >
< button popovertarget = sub-nav >
< img src = down-arrow.png alt = "Product pages" >
</ button >
< ul popover id = sub-nav >
< li >< a href = ... > Shirts</ a >
< li >< a href = ... > Shoes</ a >
< li >< a href = ... > Hats etc.</ a >
</ ul >
</ li >
<!-- other list items and links here -->
</ ul >
popover
をアクセシビリティセマンティクスのない要素、たとえばdiv
要素に使用する場合、著者は適切なARIA属性を使用して、popoverがアクセス可能であることを保証すべきである。
次は、カスタムメニューポップオーバーを作成するための基準のマークアップを示している。ここでは、autofocus
属性の使用によりポップオーバーが呼び出されたとき、最初のmenuitemがキーボードフォーカスを受け取る。矢印キーとアクティブ化動作を使用してmenuitemを操作するには、著者のスクリプトが必要となる。カスタムメニューウィジェットを構築するための追加の要件は、WAI-ARIA仕様で定義される。
< button popovertarget = m > Actions</ button >
< div role = menu id = m popover >
< button role = menuitem tabindex = -1 autofocus > Edit</ button >
< button role = menuitem tabindex = -1 > Hide</ button >
< button role = menuitem tabindex = -1 > Delete</ button >
</ div >
ポップオーバーは、ユーザーが実行したアクションを確認するステータスメッセージをレンダリングするのに役立つ。次に、output
要素内のポップオーバーを見せる方法を示す。
< button id = submit > Submit</ button >
< p >< output >< span popover = manual ></ span ></ output ></ p >
< script >
const sBtn = document. getElementById( "submit" );
const outSpan = document. querySelector( "output [popover=manual]" );
let successMessage;
let errorMessage;
/* define logic for determining success of action
and determining the appropriate success or error
messages to use */
sBtn. addEventListener( "click" , ()=> {
if ( success ) {
outSpan. textContent = successMessage;
}
else {
outSpan. textContent = errorMessage;
}
outSpan. showPopover();
setTimeout( function () {
outSpan. hidePopover();
}, 10000 );
});
</ script >
ポップオーバー要素をoutput
要素に挿入すると、一般的に、スクリーンリーダーは内容が可視である場合にその内容を通知する。コンテンツの複雑さや頻度に応じて、これは、これらの支援技術のユーザーにとって有用である場合もあれば、迷惑である場合もある。output
要素または他のARIAライsブリージョンを使用して最良のユーザーエクスペリエンスを確保する場合、この点に留意すること。
popover
属性は、次のキーワードと状態を持つ列挙属性である:
キーワード | 状態 | 概要 |
---|---|---|
auto | auto | 開いたときに他のポップオーバーを閉じる。簡易非表示を持ち、閉じ要求に応答する。 |
(空文字列) | ||
manual | manual | 他のポップオーバーを閉じない。簡易非表示を持たず、閉じ要求に応答しない。 |
この属性の欠損値のデフォルトはno popover状態であり、不正値のデフォルトはmanual状態である。
Support in all current engines.
popover
IDL属性は、既知の値に制限され、popover属性を反映しなければならない。
すべての HTML要素は、ポップオーバー可視状態を持ち、最初は で、次の潜在的な値をもつ:
非表示
表示
Document
は、ポップオーバーポインターダウンターゲットを持ち、これはHTML要素またはnullであり、最初はnullである。
すべてのHTML要素は、ポップオーバー呼び出しを持ち、これはHTML要素またはnullであり、最初はnullに設定される。
すべてのHTML要素は、表示または非表示のポップオーバーを持ち、これは真偽値で、最初はfalseに設定されている。
すべてのHTML要素ポップオーバートグルタスクトラッカー、これはトグルタスクトラッカーまたはnullで、最初はnullである。
Every HTML element has a popover close watcher, which is a close watcher or null, initially null.
The following attribute change steps, given element, localName, oldValue, value, and namespace, are used for all HTML elements:
If namespace is not null, then return.
If localName is not popover
, then return.
If element's popover visibility state is in the showing state and oldValue and value are in different states, then run the hide popover algorithm given element, true, true, and false.
element.showPopover()
Support in all current engines.
popover
属性がauto stateである場合、トップレベルのポップオーバー祖先アルゴリズムに従ってelementの祖先でない限り、他のすべてのautoポップオーバーも閉じられる。element.hidePopover()
Support in all current engines.
display:none
を適用して非表示にする。element.togglePopover()
Support in all current engines.
The showPopover()
method steps are to run show popover given this, true, and null.
To show popover, given an HTML element element, a boolean throwExceptions, and an HTML element or null invoker:
If the result of running check popover validity given element, false, throwExceptions, and null is false, then return.
Let document be element's node document.
Assert: element's popover invoker is null.
Let nestedShow be element's popover showing or hiding.
Set element's popover showing or hiding to true.
Let cleanupShowingFlag be the following steps:
If nestedShow is false, then set element's popover showing or hiding to false.
If the result of firing an event named beforetoggle
, using ToggleEvent
, with the cancelable
attribute initialized to true, the oldState
attribute initialized to "closed
", and the newState
attribute initialized to "open
" at element is false, then run cleanupShowingFlag and return.
If the result of running check popover validity given element, false, throwExceptions, and document is false, then run cleanupShowingFlag and return.
Check popover validity is called again because firing the beforetoggle
event could have disconnected this element or changed its popover
attribute.
Let shouldRestoreFocus be false.
If element's popover
attribute is in the auto state, then:
Let originalType be the value of element's popover
attribute.
Let ancestor be the result of running the topmost popover ancestor algorithm given element, invoker, and true.
If ancestor is null, then set ancestor to document.
Run hide all popovers until given ancestor, false, and not nestedShow.
If originalType is not equal to the value of element's popover
attribute, then:
If throwExceptions is true, then throw a "InvalidStateError
" DOMException
.
Return.
If the result of running check popover validity given element, false, throwExceptions, and document is false, then run cleanupShowingFlag and return.
Check popover validity is called again because running hide all popovers until above could have fired the beforetoggle
event, and an event handler could have disconnected this element or changed its popover
attribute.
If the result of running topmost auto popover on document is null, then set shouldRestoreFocus to true.
This ensures that focus is returned to the previously-focused element only for the first popover in a stack.
Set element's popover close watcher to the result of establishing a close watcher given element's relevant global object, with:
cancelAction being to return true.
closeAction being to hide a popover given element, true, true, and false.
Set element's previously focused element to null.
Let originallyFocusedElement be document's focused area of the document's DOM anchor.
Add an element to the top layer given element.
Set element's popover visibility state to showing.
Set element's popover invoker to invoker.
Run the popover focusing steps given element.
If shouldRestoreFocus is true and element's popover
attribute is not in the no popover state, then set element's previously focused element to originallyFocusedElement.
Queue a popover toggle event task given element, "closed
", and "open
".
Run cleanupShowingFlag.
To queue a popover toggle event task given an element element, a string oldState, and a string newState:
If element's popover toggle task tracker is not null, then:
Set oldState to element's popover toggle task tracker's old state.
Remove element's popover toggle task tracker's task from its task queue.
Set element's popover toggle task tracker to null.
Queue an element task given the DOM manipulation task source and element to run the following steps:
Fire an event named toggle
at element, using ToggleEvent
, with the oldState
attribute initialized to oldState and the newState
attribute initialized to newState.
Set element's popover toggle task tracker to null.
Set element's popover toggle task tracker to a struct with task set to the just-queued task and old state set to oldState.
The hidePopover()
method steps are:
Run the hide popover algorithm given this, true, true, and true.
To hide a popover given an HTML element element, a boolean focusPreviousElement, a boolean fireEvents, and a boolean throwExceptions:
If the result of running check popover validity given element, true, throwExceptions, and null is false, then return.
Let document be element's node document.
Let nestedHide be element's popover showing or hiding.
Set element's popover showing or hiding to true.
If nestedHide is true, then set fireEvents to false.
Let cleanupSteps be the following steps:
If nestedHide is false, then set element's popover showing or hiding to false.
If element's popover close watcher is not null, then:
Destroy element's popover close watcher.
Set element's popover close watcher to null.
If element's popover
attribute is in the auto state, then:
Run hide all popovers until given element, focusPreviousElement, and fireEvents.
If the result of running check popover validity given element, true, and throwExceptions is false, then run cleanupSteps and return.
Check popover validity is called again because running hide all popovers until could have disconnected element or changed its popover
attribute.
Let autoPopoverListContainsElement be true if document's showing auto popover list's last item is element, otherwise false.
Set element's popover invoker to null.
If fireEvents is true:
Fire an event named beforetoggle
, using ToggleEvent
, with the oldState
attribute initialized to "open
" and the newState
attribute initialized to "closed
" at element.
If autoPopoverListContainsElement is true and document's showing auto popover list's last item is not element, then run hide all popovers until given element, focusPreviousElement, and false.
If the result of running check popover validity given element, true, throwExceptions, and null is false, then run cleanupSteps and return.
Check popover validity is called again because firing the beforetoggle
event could have disconnected element or changed its popover
attribute.
Request an element to be removed from the top layer given element.
Otherwise, remove an element from the top layer immediately given element.
Set element's popover visibility state to .
If fireEvents is true, then queue a popover toggle event task given element, "open
", and "closed
".
Let previouslyFocusedElement be element's previously focused element.
If previouslyFocusedElement is not null, then:
Set element's previously focused element to null.
If focusPreviousElement is true and document's focused area of the document's DOM anchor is a shadow-including inclusive descendant of element, then run the focusing steps for previouslyFocusedElement; the viewport should not be scrolled by doing this step.
Run cleanupSteps.
The togglePopover(force)
method steps are:
If this's popover visibility state is showing, and force is not present or false, then run the hide popover algorithm given this, true, true, and true.
Otherwise, if force is not present or true, then run show popover given this, true, and null.
Otherwise:
Let expectedToBeShowing be true if this's popover visibility state is showing; otherwise false.
Run check popover validity given expectedToBeShowing, true, and null.
Return true if this's popover visibility state is showing; otherwise false.
To hide all popovers until, given an HTML element or Document
endpoint, a boolean focusPreviousElement, and a boolean fireEvents:
If endpoint is an HTML element and endpoint is not in the popover showing state, then return.
Let document be endpoint's node document.
Let closeAllOpenPopovers be an algorithm which performs the following steps:
Let popover be document's topmost auto popover.
While popover is not null:
Run the hide popover algorithm given popover, focusPreviousElement, fireEvents, and false.
Set popover to document's topmost auto popover.
If endpoint is a Document
, then run closeAllOpenPopovers and return.
Let repeatingHide be false.
Perform the following steps at least once:
Let lastToHide be null.
Let foundEndpoint be false.
For each popover of document's showing auto popover list:
If popover is endpoint, then set foundEndpoint to true.
Otherwise, if foundEndpoint is true, then set lastToHide to popover and break.
If foundEndpoint is false, then run closeAllOpenPopovers and return.
While lastToHide is not null and lastToHide's popover visibility state is showing and document's showing auto popover list is not empty:
Run the hide popover algorithm given document's showing auto popover list's last element, focusPreviousElement, fireEvents, and false.
Set repeatingHide to true if document's showing auto popover list contains endpoint and document's showing auto popover list's last element is not endpoint, otherwise false.
If repeatingHide is true, then set fireEvents to false.
and keep performing them while repeatingHide is true.
The hide all popovers until algorithm is used in several cases to hide all popovers that don't stay open when something happens. For example, during light-dismiss of a popover, this algorithm ensures that we close only the popovers that aren't related to the node clicked by the user.
To find the topmost popover ancestor, given a Node
newPopoverOrTopLayerElement, an HTML element or null invoker, and a boolean isPopover, perform the following steps. They return an HTML element or null.
The topmost popover ancestor algorithm will return the topmost (latest in the showing auto popover list) ancestor popover for the provided popover or top layer element. Popovers can be related to each other in several ways, creating a tree of popovers. There are two paths through which one popover (call it the "child" popover) can have a topmost ancestor popover (call it the "parent" popover):
The popovers are nested within each other in the node tree. In this case, the descendant popover is the "child" and its topmost ancestor popover is the "parent".
An invoking element (e.g., a button
) has a popovertarget
attribute pointing to a popover. In this case, the popover is the "child", and the popover subtree the invoking element is in is the "parent". The invoker has to be in a popover and reference an open popover.
In each of the relationships formed above, the parent popover has to be strictly earlier in the showing auto popover list than the child popover, or it does not form a valid ancestral relationship. This eliminates non-showing popovers and self-pointers (e.g., a popover containing an invoking element that points back to the containing popover), and it allows for the construction of a well-formed tree from the (possibly cyclic) graph of connections. Only auto popovers are considered.
If the provided element is a top layer element such as a dialog
which is not showing as a popover, then topmost popover ancestor will only look in the node tree to find the first popover.
If isPopover is true:
Assert: newPopoverOrTopLayerElement is an HTML element.
Assert: newPopoverOrTopLayerElement's popover
attribute is not in the no popover state or the manual state.
Assert: newPopoverOrTopLayerElement's popover visibility state is not in the popover showing state.
Otherwise:
Assert: invoker is null.
Let popoverPositions be an empty ordered map.
indexを0にする。
Let document be newPopoverOrTopLayerElement's node document.
For each popover of document's showing auto popover list:
Set popoverPositions[popover] to index.
Increment index by 1.
If isPopover is true, then set popoverPositions[newPopoverOrTopLayerElement] to index.
Increment index by 1.
Let topmostPopoverAncestor be null.
Let checkAncestor be an algorithm which performs the following steps given candidate:
If candidate is null, then return.
Let candidateAncestor be the result of running nearest inclusive open popover given candidate.
If candidateAncestor is null, then return.
Let candidatePosition be popoverPositions[candidateAncestor].
If topmostPopoverAncestor is null or popoverPositions[topmostPopoverAncestor] is less than candidatePosition, then set topmostPopoverAncestor to candidateAncestor.
Run checkAncestor given newPopoverOrTopLayerElement's parent node within the flat tree.
Run checkAncestor given invoker.
Return topmostPopoverAncestor.
To find the nearest inclusive open popover given a Node
node, perform the following steps. They return an HTML element or null.
Let currentNode be node.
While currentNode is not null:
If currentNode's popover
attribute is in the auto state and currentNode's popover visibility state is showing, then return currentNode.
Set currentNode to currentNode's parent in the flat tree.
Return null.
To find the topmost auto popover given a Document
document, perform the following steps. They return an HTML element or null.
If document's showing auto popover list is not empty, then return document's showing auto popover list's last element.
Return null.
To perform the popover focusing steps for an HTML element subject:
If subject is a dialog
element, then run the dialog focusing steps given subject and return.
If subject has the autofocus
attribute, then let control be subject.
Otherwise, let control be the autofocus delegate for subject given "other
".
If control is null, then return.
Run the focusing steps given control.
Let topDocument be the active document of control's node document's browsing context's top-level browsing context.
If control's node document's origin is not the same as the origin of topDocument, then return.
Empty topDocument's autofocus candidates.
Set topDocument's autofocus processed flag to true.
To check popover validity for an HTML element element given a boolean expectedToBeShowing, a boolean throwExceptions, and a Document
or null expectedDocument perform the following steps. They throw an exception or return a boolean.
If element's popover
attribute is in the no popover state, then:
If throwExceptions is true, then throw a "NotSupportedError
" DOMException
.
falseを返す。
If any of the following are true:
expectedToBeShowing is true and element's popover visibility state is not showing; or
expectedToBeShowing is false and element's popover visibility state is not ,
then return false.
If any of the following are true:
element is not connected;
expectedDocument is not null and element's node document is not expectedDocument;
element is a dialog
element and its is modal flag is set to true; or
element's fullscreen flag is set,
then:
If throwExceptions is true, then throw a "InvalidStateError
" DOMException
.
falseを返す。
Return true.
To get the showing auto popover list for a Document
document:
Let popovers be « ».
For each Element
element in document's top layer: if element's popover
attribute is in the auto state and element's popover visibility state is showing, then append element to popovers.
Return popovers.
ボタンには、次のコンテンツ属性を設定してもよい:
popovertarget
popovertargetaction
指定された場合、popovertarget
属性値は、popovertarget
属性をもつボタンと同じツリー内のpopover
属性をもつ要素のIDでなければならない。
popovertargetaction
属性は、次のキーワードと状態を持つ列挙属性である:
キーワード | 状態 | 概要 |
---|---|---|
toggle | toggle | ターゲットのポップオーバー要素を表示または非表示する。 |
show | show | ターゲットのポップオーバー要素を表示する。 |
hide | hide | ターゲットのポップオーバー要素を非表示にする。 |
この属性の欠損値のデフォルトと不正値のデフォルトは、両方ともtoggle状態である。
可能な限りいつでも、ポップオーバー要素がDOM内のトリガー要素の直後に配置されるようにする。そうすることで、ポップオーバーが、スクリーンリーダーなどの支援技術のユーザーに対して、プログラム上の論理的な読み上げ順序で公開されるようになる。
以下に、ポップオーバーを表示して閉じるために、popovertarget
属性をpopovertargetaction
属性と組み合わせて使用する方法を示す:
< button popovertarget = "foo" popovertargetaction = "show" >
Show a popover
</ button >
< article popover = "auto" id = "foo" >
This is a popover article!
< button popovertarget = "foo" popovertargetaction = "hide" > Close</ button >
</ article >
popovertargetaction
属性が指定されない場合、デフォルトのアクションは、関連付けられたポップオーバーを切り替えることになる。次に、呼び出しボタンにpopovertarget
属性を指定するだけで、手動ポップオーバーを開いた状態と閉じた状態の間で切り替える方法を示す。A manual popover will not respond to light dismiss or close requests:
< input type = "button" popovertarget = "foo" value = "Toggle the popover" >
< div popover = manual id = "foo" >
This is a popover!
</ div >
HTMLButtonElement/popoverTargetElement
Support in all current engines.
HTMLInputElement/popoverTargetElement
Support in all current engines.
popoverTargetElement
IDL属性は、popovertarget
属性を反映しなければならない。
HTMLButtonElement/popoverTargetAction
Support in all current engines.
HTMLInputElement/popoverTargetAction
Support in all current engines.
popoverTargetAction
IDL属性は、既知の値のみに制限される、popoverTargetAction
属性を反映しなければならない。
To run the popover target attribute activation behavior given a Node
node:
Let popover be node's popover target element.
If popover is null, then return.
If node's popovertargetaction
attribute is in the show state and popover's popover visibility state is showing, then return.
If node's popovertargetaction
attribute is in the hide state and popover's popover visibility state is , then return.
If popover's popover visibility state is showing, then run the hide popover algorithm given popover, true, true, and false.
Otherwise, if popover's popover visibility state is and the result of running check popover validity given popover, false, false, and null is true, then run show popover given popover, false, and node.
To get the popover target element given a Node
node, perform the following steps. They return an HTML element or null.
If node is not a button, then return null.
If node is disabled, then return null.
If node has a form owner and node is a submit button, then return null.
Let popoverElement be the result of running node's get the popovertarget
-associated element.
If popoverElement is null, then return null.
If popoverElement's popover
attribute is in the no popover state, then return null.
Return popoverElement.
"Light dismiss" means that clicking outside of a popover whose popover
attribute is in the auto state will close the popover. This is in addition to how such popovers respond to close requests.
To light dismiss open popovers, given an Event
event:
Let target be event's target.
Let document be target's node document.
Let topmostPopover be the result of running topmost auto popover given document.
If topmostPopover is null, then return.
If event is a PointerEvent
and event's type
is "pointerdown
", then: set document's popover pointerdown target to the result of running topmost clicked popover given target.
If event is a PointerEvent
and event's type
is "pointerup
", then:
Let ancestor be the result of running topmost clicked popover given target.
Let sameTarget be true if ancestor is document's popover pointerdown target.
Set document's popover pointerdown target to null.
If ancestor is null, then set ancestor to document.
If sameTarget is true, then run hide all popovers until given ancestor, false, and true.
Light dismiss open popovers will be called by the Pointer Events spec when the user clicks or touches anywhere on the page.
To find the topmost clicked popover, given a Node
node:
Let clickedPopover be the result of running nearest inclusive open popover given node.
Let invokerPopover be the result of running nearest inclusive target popover for invoker given node.
Let getStackPosition be an algorithm which performs the following steps given an HTML element popover:
Let popoverList be popover's node document's showing auto popover list.
If popover is in popoverList, then return the index of popover in popoverList + 1.
Return 0.
If the result of running getStackPosition given clickedPopover is greater than the result of running getStackPosition given invokerPopover, then return clickedPopover.
Return invokerPopover.
To find the nearest inclusive target popover for invoker given a Node
node:
Let currentNode be node.
While currentNode is not null:
Let targetPopover be currentNode's popover target element.
If targetPopover is not null and targetPopover's popover
attribute is in the auto state and targetPopover's popover visibility state is showing, then return targetPopover.
Set currentNode to currentNode's ancestor in the flat tree.