Living Standard — Last Updated 24 March 2023
popover
属性すべてのHTML要素はpopover
コンテンツ属性設定を持ってもよい。指定された場合、要素は表示されるまでレンダリングされず、表示されると、他のページ コンテンツの上にレンダリングされる。
The popover
attribute is a global attribute that allows authors flexibility to ensure popover functionality can be applied to elements with the most relevant semantics.
The following demonstrates how one might create a popover sub-navigation list of links, within the global navigation for a website.
< 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 >
When using popover
on elements without accessibility semantics, for instance the div
element, authors should use the appropriate ARIA attributes to ensure the popover is accessible.
The following shows the baseline markup to create a custom menu popover, where the first menuitem will receive keyboard focus when the popover is invoked due to the use of the autofocus
attribute. Navigating the menuitems by arrow keys, and activation behaviors would still need author scripting.
< button popovertarget = menu aria-haspopup = menu > Actions</ button >
< div role = menu id = menu popover >
< button role = menuitem tabindex = -1 autofocus > Edit</ button >
< button role = menuitem tabindex = -1 > Hide</ button >
< button role = menuitem tabindex = -1 > Delete</ button >
</ div >
A popover can be useful for rendering a status message, confirming the action performed by the user. The following demonstrates how one could reveal a popover in an output
element.
< 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 >
Inserting a popover element into an output
element will generally cause screen readers to announce the content when it becomes visible. Depending on the complexity or frequency of the content, this could be either useful or annoying to users of these assistive technologies. Keep this in mind when using the output
element or other ARIA live regions to ensure the best user experience.
popover
属性は、次のキーワードと状態を持つ列挙属性である:
キーワード | 状態 | 概要 |
---|---|---|
auto | auto | 開いたときに他のポップオーバーを閉じる。簡易非表示を持つ。 |
空文字列 | ||
manual | manual | 他のポップオーバーを閉じない。簡易非表示を持たない。 |
popover
属性の不正値のデフォルトはmanual状態であり、その欠損値のデフォルトはポップオーバーなし状態である。
popover
IDL属性は、既知の値に制限され、popover属性を反映しなければならない。
すべての HTML要素は、ポップオーバー可視状態を持ち、最初は で、次の潜在的な値をもつ:
非表示
表示
Document
は、自動ポップオーバーリストを持つ。これは、Document
の最上位レイヤーにあるすべての要素のリストであり、そのpopover
属性は、同じ順序でauto状態にある。
Document
は、ポップオーバーポインターダウンターゲットを持ち、これはHTML要素またはnullであり、最初はnullである。
すべてのHTML要素は、ポップオーバー呼び出しを持ち、これはHTML要素またはnullであり、最初はnullに設定される。
すべてのHTML要素は、ポップオーバートリガータスクを持ち、最初はnullであり、これはnullまたは以下を持つ構造体のいずれかである:
ToggleEvent
を発火するタスク。oldState
属性のタスクのイベントの値を表す文字列。The following attribute change steps are used for all HTML elements:
If namespace is not null, then return.
If localName is not popover
, then return.
If oldValue and value are in different states, then run the hide popover algorithm given element, true, true, and false.
element.showPopover()
popover
属性がauto stateである場合、トップレベルのポップオーバー祖先アルゴリズムに従ってelementの祖先でない限り、他のすべてのautoポップオーバーも閉じられる。element.hidePopover()
display:none
を適用して非表示にする。element.togglePopover()
The showPopover()
method steps are:
Run show popover given this and true.
To show popover, given an HTML element element and a boolean throwExceptions:
If the result of running check popover validity given element, false, and throwExceptions is false, then return.
Assert: element is not in element's node document's top layer.
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 return.
If the result of running check popover validity given element, false, and throwExceptions is false, then return.
Check popover validity is called again because firing the beforetoggle
event could have disconnected this element or changed its popover
attribute.
Let document be element's node document.
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.
If ancestor is null, then set ancestor to document.
Run hide all popovers until given ancestor, false, and true.
If originalType is not equal to the value of element's popover
attribute, or if the result of running check popover validity given element, false, and throwExceptions is false, then 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 called showPopover()
on this element.
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 previously focused element to null.
Let originallyFocusedElement be document's focused area of the document's DOM anchor.
Add element to document's top layer.
Set element's popover visibility state to showing.
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
".
To queue a popover toggle event task given an element element, a string oldState, and a string newState:
If element's popover toggle task is not null, then:
Set oldState to element's popover toggle task's old state.
Remove element's popover toggle task's task from its task queue.
Set element's popover toggle task to null.
Queue an element task given the user interaction task source and element to run the following steps:
fire an event named toggle
, using ToggleEvent
, with the oldState
attribute initialized to oldState, and the newState
attribute initialized to newState at element.
Set element's popover toggle task to null.
Set element's popover toggle task 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, and throwExceptions is false, then return.
Let document be element's node document.
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 return.
Check popover validity is called again because running hide all popovers until could have disconnected element or changed its popover
attribute.
Assert: the last item in document's auto popover list is element.
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 the result of running check popover validity given element, true, and throwExceptions is false, then return.
Check popover validity is called again because firing the beforetoggle
event could have disconnected element or changed its popover
attribute.
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, then run the focusing steps for previouslyFocusedElement; the viewport should not be scrolled by doing this step.
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 and true.
To hide all popovers until, given an HTML element or Document
endpoint, a boolean focusPreviousElement, and a boolean fireEvents:
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 lastToHide be null.
Let foundEndpoint be false.
For each popover in document's 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 auto popover list is not empty:
Run the hide popover algorithm given document's auto popover list's last element, focusPreviousElement, fireEvents, and false.
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 hide all popovers, given a Document
document, run hide all popovers until given document, false, and false.
To find the topmost popover ancestor, given a Node
newPopover, perform the following steps. They return an HTML element or null.
The topmost popover ancestor algorithm will return the topmost (latest in the auto popover list) ancestor popover for the provided popover. 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 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 with an anchor attribute that points back to the same popover), and it allows for the construction of a well-formed tree from the (possibly cyclic) graph of connections. For example, if two popovers have anchors pointing to each other, the only valid relationship is that the first one to open is the "parent" and the second is the "child". Only auto popovers are considered.
Let popoverPositions be an empty map.
indexを0にする。
Let document be newPopover's node document.
For each popover in document's auto popover list:
Set popoverPositions[popover] to index.
Increment index by 1.
Set popoverPositions[newPopover] 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 the result of running nearest inclusive open popover given newPopover's parent node within the flat tree.
For each button invoker that is a descendant of newPopover's root, in tree order:
If invoker's popover target element is newPopover, then 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 auto popover list is not empty, then return document's auto popover list's last element.
Return null.
To perform the popover focusing steps for an HTML element subject:
Let control be the focus delegate of subject given "other
" and true.
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 and a boolean throwExceptions, 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 one of the following conditions is true
element is not connected
expectedToBeShowing is true and element's popover visibility state is not showing
expectedToBeShowing is false and element's popover visibility state is not
element's fullscreen flag is set
then:
If throwExceptions is true, then throw a "InvalidStateError
" DOMException
.
falseを返す。
Return true.
ボタンには、次のコンテンツ属性を設定してもよい:
popovertarget
popovertargetaction
指定された場合、popovertarget
属性値は、popovertarget
属性をもつボタンと同じツリー内のpopover
属性をもつ要素のIDでなければならない。
popovertargetaction
属性は、次のキーワードと状態を持つ列挙属性である:
キーワード | 状態 | 概要 |
---|---|---|
toggle | toggle | ターゲットのポップオーバー要素を表示または非表示する。 |
show | show | ターゲットのポップオーバー要素を表示する。 |
hide | hide | ターゲットのポップオーバー要素を非表示にする。 |
popovertargetaction
属性の不正値のデフォルトと欠損値のデフォルトの両方は、トグル状態である。
Whenever possible ensure the popover element is placed immediately after its triggering element in the DOM. Doing so will help ensure that the popover is exposed in a logical programmatic reading order for users of assistive technology, such as screen readers.
The following shows how the popovertarget
attribute in combination with the popovertargetaction
attribute can be used to show and close a popover:
< button popovertarget = "foo" popovertargetaction = "show" >
Show a popover
</ button >
< article popover = auto id = "foo" >
This is a popover article!
< button popovertarget = "foo" popovertargetaction = "close" > Close</ button >
</ article >
If a popovertargetaction
attribute is not specified, the default action will be to toggle the associated popover. The following shows how only specifying the popovertarget
attribute on its invoking button can toggle a manual popover between its opened and closed states. A manual popover will not light dismiss:
< input type = "button" popovertarget = "foo" value = "Toggle the popover" >
< div popover = manual id = "foo" >
This is a popover!
</ div >
interface mixin PopoverInvokerElement {
[CEReactions ] attribute Element ? popoverTargetElement ;
[CEReactions ] attribute DOMString popoverTargetAction ;
};
popoverTargetElement
IDL属性は、popovertarget
属性を反映しなければならない。
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, and false is true:
Set popover's popover invoker to node.
Run show popover given popover and false.
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 node's 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.
"簡易非表示"とは、Escキーを押すか、popover
属性がauto状態のポップオーバーの外側をクリックするとポップオーバーが閉じることを意味する。
ポップオーバーのキャンセル:Document
に最上位の自動ポップオーバーが表示されている場合、ユーザー エージェントは、アクティブ化時に、最上位の自動ポップオーバー、trueおよびfalseが指定されたユーザーインタラクションタスクソースで要素タスクをキューに入れ、最上位の自動ポップオーバーが指定された非表示のポップオーバーアルゴリズムを実行するユーザーインターフェイスを提供してもよい。
To light dismiss open popovers, given an Event
event:
Let target be event's target.
Let topmostPopover be the result of running topmost auto popover given target.
If topmostPopover is null, then return.
Let document be target's node document.
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 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.
ToggleEvent
インターフェイス[Exposed =Window ]
interface ToggleEvent : Event {
constructor (DOMString type , optional ToggleEventInit eventInitDict = {});
readonly attribute DOMString oldState ;
readonly attribute DOMString newState ;
};
dictionary ToggleEventInit : EventInit {
DOMString oldState = "";
DOMString newState = "";
};
event.oldState
クローズからオープンに遷移する場合は"closed
"に設定し、オープンからクローズに遷移する場合は"open
"に設定する。
event.newState
クローズからオープンに遷移する場合は"open
"に設定し、オープンからクローズに遷移する場合は"closed
"に設定する。
oldState
属性は、初期化された値を返さなければならない。popover
属性のポップオーバー可視性状態をもつ要素が表示の場合は"open
"に初期化され、そうでなければ"closed
"に初期化される。
newState
属性は、初期化された値を返さなければならない。popover
属性のポップオーバー可視性状態をもつ要素が表示の場合は"closed
"に初期化され、そうでなければ"open
"に初期化される。