HTML: The Living Standard
Edition for Web Developers — Last Updated 27 January 2023
Edition for Web Developers — Last Updated 27 January 2023
details要素Support in all current engines.
summary要素に続くフローコンテンツ。open — detailsが可視かどうかHTMLDetailsElementを使用する。details要素は、ユーザーが追加情報やコントロールを得ることができるディスクロージャーウィジェットを表す。
details要素は、脚注には適さない。脚注をマークアップする方法の詳細については、脚注のセクションを参照のこと。
要素の子summary要素がもしあれば、detailsの要約または凡例を表す。
要素のコンテンツの残り部分は、追加情報やコントロールを表す。
openコンテンツ属性は、真偽属性である。存在する場合、この属性は要約と追加情報の両方がユーザーに表示されることを示す。属性が存在しない場合、要約のみが表示されるようになる。
The ancestor details revealing algorithm is to run the following steps on currentNode:
While currentNode has a parent node within the flat tree:
次の例は、details要素が進捗報告書で技術的な詳細を非表示にするために使用される様子を示す。
< section class = "progress window" >
< h1 > Copying "Really Achieving Your Childhood Dreams"</ h1 >
< details >
< summary > Copying... < progress max = "375505392" value = "97543282" ></ progress > 25%</ summary >
< dl >
< dt > Transfer rate:</ dt > < dd > 452KB/s</ dd >
< dt > Local filename:</ dt > < dd > /home/rpausch/raycd.m4v</ dd >
< dt > Remote filename:</ dt > < dd > /var/www/lectures/raycd.m4v</ dd >
< dt > Duration:</ dt > < dd > 01:16:27</ dd >
< dt > Color profile:</ dt > < dd > SD (6-1-6)</ dd >
< dt > Dimensions:</ dt > < dd > 320×240</ dd >
</ dl >
</ details >
</ section > 以下は、details要素がデフォルトで一部のコントロールを非表示にするために使用できる様子を示す：
< details >
< summary >< label for = fn > Name & Extension:</ label ></ summary >
< p >< input type = text id = fn name = fn value = "Pillar Magazine.pdf" >
< p >< label >< input type = checkbox name = ext checked > Hide extension</ label >
</ details > これは、ユーザーがそれぞれを開くことができる機能とともに、見出しの小さな集合にフィールドの集合を折りたたむことができるよう、リスト内の他のdetailsとともにこれを使用できる。
これらの例において、要約はコントロールが変更できるものをまとめたものであり、理想に満たない実際値ではない。
ユーザーがコントロールを操作するために自動的にopen属性が追加および削除されるので、この属性の状態に基づく異なる、この属性CSSで要素に使用できる。ここでは、スタイルシートを使用して、要素を開いたり閉じたりしたときのsummaryの色をアニメーションさせている：
< style >
details > summary { transition : color 1 s ; color : black ; }
details [ open ] > summary { color : red ; }
</ style >
< details >
< summary > Automated Status: Operational</ summary >
< p > Velocity: 12m/s</ p >
< p > Direction: North</ p >
</ details > summary要素Support in all current engines.
details要素の最初の子として。HTMLElementを使用する。summary要素はsummary要素の親details要素に属する残りの内容のキャプションまたは凡例を表す。
コマンドは、メニュー項目、ボタン、リンクの背後に抽象化したものである。一度コマンドが定義されると、インターフェイスの他の部分は、Disabled状態のようなファセットを共有するために単一の機能へ多くのアクセスポイントを許可し、同じコマンドを参照できる。
コマンドは、次のファセットを持つように定義される：
ユーザーエージェントは、次の条件に一致するコマンドを公開してもよい：
ユーザーエージェントは、ユーザーにこれらのキーを通知するための方法として、アクセスキーを持つコマンドのために特にこれを行うことが推奨される。
たとえば、そのようなコマンドは、ユーザーエージェントのメニューバーにリストされるかもしれない。
dialog要素Support in all current engines.
open — ダイアログボックスが見えるかどうかHTMLDialogElementを使用する。The dialog element represents a transitory part of an application, in the form of a small window ("dialog box"), which the user interacts with to perform a task or gather information. Once the user is done, the dialog can be automatically closed by the application, or manually closed by the user.
Especially for modal dialogs, which are a familiar pattern across all types of applications, authors should work to ensure that dialogs in their web applications behave in a way that is familiar to users of non-web applications.
As with all HTML elements, it is not conforming to use the dialog element when attempting to represent another type of control. For example, context menus, tooltips, and popup listboxes are not dialog boxes, so abusing the dialog element to implement these patterns is incorrect.
An important part of user-facing dialog behavior is the placement of initial focus. The dialog focusing steps attempt to pick a good candidate for initial focus when a dialog is shown, but might not be a substitute for authors carefully thinking through the correct choice to match user expectations for a specific dialog. As such, authors should use the autofocus attribute on the descendant element of the dialog that the user is expected to immediately interact with after the dialog opens. If there is no such element, then authors should use the autofocus attribute on the dialog element itself.
In the following example, a dialog is used for editing the details of a product in an inventory management web application.
< dialog >
< label > Product Number < input type = "text" readonly ></ label >
< label > Product Name < input type = "text" autofocus ></ label >
</ dialog > If the autofocus attribute was not present, the Product Number field would have been focused by the dialog focusing steps. Although that is reasonable behavior, the author determined that the more relevant field to focus was the Product Name field, as the Product Number field is readonly and expects no user input. So, the author used autofocus to override the default.
Even if the author wants to focus the Product Number field by default, they are best off explicitly specifying that by using autofocus on that input element. This makes the intent obvious to future readers of the code, and ensures the code stays robust in the face of future updates. (For example, if another developer added a close button, and positioned it in the node tree before the Product Number field).
Another important aspect of user behavior is whether dialogs are scrollable or not. In some cases, overflow (and thus scrollability) cannot be avoided, e.g., when it is caused by the user's high text zoom settings. But in general, scrollable dialogs are not expected by users. Adding large text nodes directly to dialog elements is particularly bad as this is likely to cause the dialog element itself to overflow. Authors are best off avoiding them.
The following terms of service dialog respects the above suggestions.
< dialog style = "height: 80vh;" >
< div style = "overflow: auto; height: 60vh;" autofocus >
< p > By placing an order via this Web site on the first day of the fourth month of the year
2010 Anno Domini, you agree to grant Us a non-transferable option to claim, for now and for
ever more, your immortal soul.</ p >
< p > Should We wish to exercise this option, you agree to surrender your immortal soul,
and any claim you may have on it, within 5 (five) working days of receiving written
notification from this site or one of its duly authorized minions.</ p >
<!-- ... etc., with many more <p> elements ... -->
</ div >
< form method = "dialog" >
< button type = "submit" value = "agree" > Agree</ button >
< button type = "submit" value = "disagree" > Disagree</ button >
</ form >
</ dialog > Note how the dialog focusing steps would have picked the scrollable div element by default, but similarly to the previous example, we have placed autofocus on the div so as to be more explicit and robust against future changes.
In contrast, if the p elements expressing the terms of service did not have such a wrapper div element, then the dialog itself would become scrollable, violating the above advice. Furthermore, in the absence of any autofocus attribute, such a markup pattern would have violated the above advice and tripped up the dialog focusing steps's default behavior, and caused focus to jump to the Agree button, which is a bad user experience.
open属性は、真偽属性である。指定される場合、dialog要素はアクティブであり、ユーザーが操作できることを示す。
open属性を削除すると、通常ダイアログが非表示になる。しかし、そのようにすると、いくつかの奇妙な追加の結果となる：
closeイベントは発火しない。
close()メソッドとユーザーエージェントが提供する取り消しインターフェイスは、もはやダイアログを閉じることができなくなる。
showModal()メソッドを使用してダイアログが表示された場合、Documentはブロックされる。
これらの理由から、open属性を手動で削除しない方が一般的には良い方法である。代わりに、ダイアログを閉じるためにclose()メソッドを使用する、または非表示にするために属性を使用する。
tabindex属性は、dialog要素で指定されてはならない。
dialog.show()dialog要素を表示する。
dialog.showModal()dialog要素を表示し、一番上のモーダルダイアログにする。
この方法は、autofocus属性を履行する。
dialog.close([ result ])dialog要素を閉じる。
引数が与えられた場合、戻り値を提供する。
dialog.returnValue [ = result ]dialogの戻り値を返す。
戻り値を更新する設定が可能である。
次の制約により、表示する/隠す（show/hide）や開く/閉じる（open/close）などの対義語として一般的に考えられている動詞のペアとは対照的に、dialog要素の動詞として表示する/閉じる（show/close）を使用する：
ダイアログを非表示にすることは、ダイアログを閉じることとは異なる。ダイアログを閉じると、戻り値が返され、イベントが発火し、他のダイアログのページのブロックが解除される、などする。ダイアログを非表示にすることは純粋に視覚的なプロパティであり、属性を使用するか、open属性を削除することですでに実行できることである。（open属性を削除すること、およびそのようにダイアログを非表示にすることは一般的に望ましくないことについては、上記の注も参照。）
ダイアログを表示することは、ダイアログを開くこととは異なる。ダイアログを開くことは、そのダイアログを作成して、表示することである（window.open()が新しいウィンドウを作成して表示する方法と同様である）。ダイアログの表示は、すでにDOMにあるdialog要素を取得し、それをインタラクティブにしてユーザーに可視にするプロセスである。
上記にもかかわらずdialog.open()メソッドがあるとすれば、dialog.openプロパティと競合するだろう。
さらに、dialog要素のもとのデザインと同時代の他の多くのUIフレームワークの調査により、表示する/閉じる（show/close）の動詞のペアがかなり一般的であることが明らかになった。
要約すると、特定の動詞の意味、およびそれらの動詞が技術的なコンテキストでどのように使用されるかは、ダイアログの表示と閉じるなどのペアの動作が必ずしも対義語として表現できるとは限らないことがわかる。
このダイアログボックスは、いくつかの小さなプリントを持つ。strong要素は、より重要な部分にユーザーの注意を引くために使用される。
< dialog >
< h1 > Add to Wallet</ h1 >
< p >< strong >< label for = amt > How many gold coins do you want to add to your wallet?</ label ></ strong ></ p >
< p >< input id = amt name = amt type = number min = 0 step = 0.01 value = 100 ></ p >
< p >< small > You add coins at your own risk.</ small ></ p >
< p >< label >< input name = round type = checkbox > Only add perfectly round coins</ label ></ p >
< p >< input type = button onclick = "submit()" value = "Add Coins" ></ p >
</ dialog >