Living Standard — Last Updated 12 December 2024
HTMLユーザーエージェントにおいてすべてのXMLおよびHTML文書は、Document
オブジェクトによって表される。[DOM]
The Document
object's URL is defined in DOM. It is initially set when the Document
object is created, but can change during the lifetime of the Document
object; for example, it changes when the user navigates to a fragment on the page and when the pushState()
method is called with a new URL. [DOM]
対話的なユーザーエージェントは一般にユーザーインターフェイスでDocument
オブジェクトの URL を公開する。これは、サイトが別のものを偽装しようとしているかどうかをユーザーが見分けるための基本メカニズムである。
The Document
object's origin is defined in DOM. It is initially set when the Document
object is created, and can change during the lifetime of the Document
only upon setting document.domain
. A Document
's origin can differ from the origin of its URL; for example when a child navigable is created, its active document's origin is inherited from its parent's active document's origin, even though its active document's URL is about:blank
. [DOM]
When a Document
is created by a script using the createDocument()
or createHTMLDocument()
methods, the Document
is ready for post-load tasks immediately.
文書のリファラーは、Document
が作成された際に設定できる(URLを表す)文字列である。文書のリファラーが明示的に設定されない場合、値は空文字列である。
Document
オブジェクトSupport in all current engines.
DOM defines a Document
interface, which this specification extends significantly.
enum DocumentReadyState { "loading" , "interactive" , "complete" };
enum DocumentVisibilityState { "visible" , "hidden" };
typedef (HTMLScriptElement or SVGScriptElement ) HTMLOrSVGScriptElement ;
[LegacyOverrideBuiltIns ]
partial interface Document {
static Document
parseHTMLUnsafe ((TrustedHTML
or DOMString ) html );
// resource metadata management
[PutForwards =href , LegacyUnforgeable ] readonly attribute Location ? location ;
attribute USVString domain ;
readonly attribute USVString referrer ;
attribute USVString cookie ;
readonly attribute DOMString lastModified ;
readonly attribute DocumentReadyState readyState ;
// DOM tree accessors
getter object (DOMString name );
[CEReactions ] attribute DOMString title ;
[CEReactions ] attribute DOMString dir ;
[CEReactions ] attribute HTMLElement ? body ;
readonly attribute HTMLHeadElement ? head ;
[SameObject ] readonly attribute HTMLCollection images ;
[SameObject ] readonly attribute HTMLCollection embeds ;
[SameObject ] readonly attribute HTMLCollection plugins ;
[SameObject ] readonly attribute HTMLCollection links ;
[SameObject ] readonly attribute HTMLCollection forms ;
[SameObject ] readonly attribute HTMLCollection scripts ;
NodeList getElementsByName (DOMString elementName );
readonly attribute HTMLOrSVGScriptElement ? currentScript ; // classic scripts in a document tree only
// dynamic markup insertion
[CEReactions ] Document open (optional DOMString unused1 , optional DOMString unused2 ); // both arguments are ignored
WindowProxy ? open (USVString url , DOMString name , DOMString features );
[CEReactions ] undefined close ();
[CEReactions ] undefined write ((TrustedHTML
or DOMString )... text );
[CEReactions ] undefined writeln ((TrustedHTML
or DOMString )... text );
// user interaction
readonly attribute WindowProxy ? defaultView ;
boolean hasFocus ();
[CEReactions ] attribute DOMString designMode ;
[CEReactions ] boolean execCommand (DOMString commandId , optional boolean showUI = false , optional DOMString value = "");
boolean queryCommandEnabled (DOMString commandId );
boolean queryCommandIndeterm (DOMString commandId );
boolean queryCommandState (DOMString commandId );
boolean queryCommandSupported (DOMString commandId );
DOMString queryCommandValue (DOMString commandId );
readonly attribute boolean hidden ;
readonly attribute DocumentVisibilityState visibilityState ;
// special event handler IDL attributes that only apply to Document objects
[LegacyLenientThis ] attribute EventHandler onreadystatechange ;
attribute EventHandler onvisibilitychange ;
// also has obsolete members
};
Document includes GlobalEventHandlers ;
Each Document
has a policy container (a policy container), initially a new policy container, which contains policies which apply to the Document
.
Each Document
has a permissions policy, which is a permissions policy, which is initially empty.
Each Document
has a module map, which is a module map, initially empty.
Each Document
has an opener policy, which is an opener policy, initially a new opener policy.
Each Document
has an is initial about:blank
, which is a boolean, initially false.
Each Document
has a during-loading navigation ID for WebDriver BiDi, which is a navigation ID or null, initially null.
As the name indicates, this is used for interfacing with the WebDriver BiDi specification, which needs to be informed about certain occurrences during the early parts of the Document
's lifecycle, in a way that ties them to the original navigation ID used when the navigation that created this Document
was the ongoing navigation. This eventually gets set back to null, after WebDriver BiDi considers the loading process to be finished. [BIDI]
Each Document
has an about base URL, which is a URL or null, initially null.
This is only populated for "about:
"-schemed Document
s.
Each Document
has a bfcache blocking details, which is a set of not restored reason details, initially empty.
DocumentOrShadowRoot
interfaceDOM defines the DocumentOrShadowRoot
mixin, which this specification extends.
partial interface mixin DocumentOrShadowRoot {
readonly attribute Element ? activeElement ;
};
document.referrer
Support in all current engines.
ユーザーが操作したDocument
のURLを返す。ただしブロックされるあるいはそのような文書がない場合を除く。その場合空文字列を返す。
noreferrer
リンク型はリファラーを遮断するために使用されうる。
referrer
属性は文書のリファラーを返さなければならない。
document.cookie [ = value ]
Document
に適用するHTTPクッキーを返す。クッキーが存在しないかクッキーがこのリソースに適用されない場合、空文字を返す。
新しいクッキーをHTTPクッキーの要素に設定が可能である。
If the contents are sandboxed into an opaque origin (e.g., in an iframe
with the sandbox
attribute), a "SecurityError
" DOMException
will be thrown on getting and setting.
Support in all current engines.
The cookie
attribute represents the cookies of the resource identified by the document's URL.
A Document
object that falls into one of the following conditions is a cookie-averse Document
object:
Document
object whose browsing context is null.Document
whose URL's scheme is not an HTTP(S) scheme. On getting, if the document is a cookie-averse Document
object, then the user agent must return the empty string. Otherwise, if the Document
's origin is an opaque origin, the user agent must throw a "SecurityError
" DOMException
. Otherwise, the user agent must return the cookie-string for the document's URL for a "non-HTTP" API, decoded using UTF-8 decode without BOM. [COOKIES]
On setting, if the document is a cookie-averse Document
object, then the user agent must do nothing. Otherwise, if the Document
's origin is an opaque origin, the user agent must throw a "SecurityError
" DOMException
. Otherwise, the user agent must act as it would when receiving a set-cookie-string for the document's URL via a "non-HTTP" API, consisting of the new value encoded as UTF-8. [COOKIES] [ENCODING]
Since the cookie
attribute is accessible across frames, the path restrictions on cookies are only a tool to help manage which cookies are sent to which parts of the site, and are not in any way a security feature.
The cookie
attribute's getter and setter synchronously access shared state. Since there is no locking mechanism, other browsing contexts in a multiprocess user agent can modify cookies while scripts are running. A site could, for instance, try to read a cookie, increment its value, then write it back out, using the new value of the cookie as a unique identifier for the session; if the site does this twice in two different browser windows at the same time, it might end up using the same "unique" identifier for both sessions, with potentially disastrous effects.
document.lastModified
Support in all current engines.
ユーザーのローカルタイムゾーンで"MM/DD/YYYY hh:mm:ss
"由来のサーバーによって報告されるような、文書の最終更新日時を返す。
最終更新日時が不明の場合、代わりに現在の時刻が返される。
The lastModified
attribute, on getting, must return the date and time of the Document
's source file's last modification, in the user's local time zone, in the following format:
The month component of the date.
A U+002F SOLIDUS character (/).
The day component of the date.
A U+002F SOLIDUS character (/).
The year component of the date.
A U+0020 SPACE character.
The hours component of the time.
U+003A COLON文字(:)。
The minutes component of the time.
U+003A COLON文字(:)。
The seconds component of the time.
All the numeric components above, other than the year, must be given as two ASCII digits representing the number in base ten, zero-padded if necessary. The year must be given as the shortest possible string of four or more ASCII digits representing the number in base ten, zero-padded if necessary.
The Document
's source file's last modification date and time must be derived from relevant features of the networking protocols used, e.g. from the value of the HTTP `Last-Modified
` header of the document, or from metadata in the file system for local files. If the last modification date and time are not known, the attribute must return the current date and time in the above format.
document.readyState
Document
が、いったん解析を完了したがまだサブリソースを読み込んでいる時点で"interactive
"を、読み込まれた時点で"complete
"を、読み込み中の間"loading
"を返す。
readystatechange
イベントは、この値が変更したときにDocument
オブジェクトで発火する。
DOMContentLoaded
ベントは、async
script
要素以外のすべてのサブリソースが読み込まれた時点で、"interactive
"に遷移した後で発火するが、"complete
"に遷移する前に発火する。
Support in all current engines.
Each Document
has a current document readiness, a string, initially "complete
".
For Document
objects created via the create and initialize a Document
object algorithm, this will be immediately reset to "loading
" before any script can observe the value of document.readyState
. This default applies to other cases such as initial about:blank
Document
s or Document
s without a browsing context.
The readyState
getter steps are to return this's current document readiness.
To update the current document readiness for Document
document to readinessValue:
If document's current document readiness equals readinessValue, then return.
Set document's current document readiness to readinessValue.
If document is associated with an HTML parser, then:
Let now be the current high resolution time given document's relevant global object.
If readinessValue is "complete
", and document's load timing info's DOM complete time is 0, then set document's load timing info's DOM complete time to now.
Otherwise, if readinessValue is "interactive
", and document's load timing info's DOM interactive time is 0, then set document's load timing info's DOM interactive time to now.
Fire an event named readystatechange
at document.
A Document
is said to have an active parser if it is associated with an HTML parser or an XML parser that has not yet been stopped or aborted.
A Document
has a document load timing info load timing info.
A Document
has a document unload timing info previous document unload timing.
A Document
has a boolean was created via cross-origin redirects, initially false.
The document load timing info struct has the following items:
DOMHighResTimeStamp
valuesThe document unload timing info struct has the following items:
DOMHighResTimeStamp
valuesEach Document
has a render-blocking element set, a set of elements, initially the empty set.
A Document
document allows adding render-blocking elements if document's content type is "text/html
" and the body element of document is null.
A Document
document is render-blocked if both of the following are true:
document's render-blocking element set is non-empty, or document allows adding render-blocking elements.
The current high resolution time given document's relevant global object has not exceeded an implementation-defined timeout value.
An element el is render-blocking if el's node document document is render-blocked, and el is in document's render-blocking element set.
To block rendering on an element el:
Let document be el's node document.
If document allows adding render-blocking elements, then append el to document's render-blocking element set.
To unblock rendering on an element el:
Let document be el's node document.
Remove el from document's render-blocking element set.
Whenever a render-blocking element el becomes browsing-context disconnected, or el's blocking attribute's value is changed so that el is no longer potentially render-blocking, then unblock rendering on el.
要素がhtml
要素である場合、文書のhtml
要素はその文書要素である。そうでなければnullである。
document.head
Support in all current engines.
head
要素を返す。
存在するならば、文書のhead
要素は、html
要素の子である最初のhead
要素である。そうでなければnullである。
取得時に、head
属性は、文書のhead
要素(head
要素またはnull)を返さなければならない。
document.title [ = value ]
HTMLに対してtitle
要素に与えられるおよびSVGに対してSVG title
要素に与えられるものとして、文書のタイトルを返す。
文書のタイトルを更新する設定が可能である。更新する適切な要素が存在しない場合、新しい値は無視される。
存在するならば、文書のtitle
要素は文書での(ツリー順で)最初のtitle
要素である。そうでなければnullである。
Support in all current engines.
取得時に、title
属性は次のアルゴリズムを実行しなければならない:
If the document element is an SVG svg
element, then let value be the child text content of the first SVG title
element that is a child of the document element.
Otherwise, let value be the child text content of the title
element, or the empty string if the title
element is null.
Strip and collapse ASCII whitespace in value.
Return value.
On setting, the steps corresponding to the first matching condition in the following list must be run:
svg
elementIf there is an SVG title
element that is a child of the document element, let element be the first such element.
Otherwise:
Let element be the result of creating an element given the document element's node document, title
, and the SVG namespace.
Insert element as the first child of the document element.
String replace all with the given value within element.
If the title
element is null and the head
element is null, then return.
If the title
element is non-null, let element be the title
element.
Otherwise:
Let element be the result of creating an element given the document element's node document, title
, and the HTML namespace.
Append element to the head
element.
String replace all with the given value within element.
Do nothing.
document.body [ = value ]
Support in all current engines.
body要素を返す。
body要素を置換する設定が可能である。
新しい値がbody
またはframeset
要素でない場合、これは"HierarchyRequestError
" DOMException
例外を投げる。
The body element of a document is the first of the html
element's children that is either a body
element or a frameset
element, or null if there is no such element.
The body
attribute, on getting, must return the body element of the document (either a body
element, a frameset
element, or null). 設定時に、次のアルゴリズムは実行されなければならない:
body
or frameset
element, then throw a "HierarchyRequestError
" DOMException
.HierarchyRequestError
" DOMException
.The value returned by the body
getter is not always the one passed to the setter.
In this example, the setter successfully inserts a body
element (though this is non-conforming since SVG does not allow a body
as child of SVG svg
). However the getter will return null because the document element is not html
.
< svg xmlns = "http://www.w3.org/2000/svg" >
< script >
document. body = document. createElementNS( "http://www.w3.org/1999/xhtml" , "body" );
console. assert( document. body === null );
</ script >
</ svg >
document.images
Support in all current engines.
Document
でimg
要素のHTMLCollection
を返す。
document.embeds
Support in all current engines.
document.plugins
Support in all current engines.
Returns an HTMLCollection
of the embed
elements in the Document
.
document.links
Support in all current engines.
href
属性を持つDocument
でa
およびarea
要素のHTMLCollection
を返す。
document.forms
Support in all current engines.
Returns an HTMLCollection
of the form
elements in the Document
.
document.scripts
Support in all current engines.
Returns an HTMLCollection
of the script
elements in the Document
.
The images
attribute must return an HTMLCollection
rooted at the Document
node, whose filter matches only img
elements.
The embeds
attribute must return an HTMLCollection
rooted at the Document
node, whose filter matches only embed
elements.
The plugins
attribute must return the same object as that returned by the embeds
attribute.
The links
attribute must return an HTMLCollection
rooted at the Document
node, whose filter matches only a
elements with href
attributes and area
elements with href
attributes.
The forms
attribute must return an HTMLCollection
rooted at the Document
node, whose filter matches only form
elements.
The scripts
attribute must return an HTMLCollection
rooted at the Document
node, whose filter matches only script
elements.
collection = document.getElementsByName(name)
Support in all current engines.
The getElementsByName(elementName)
method steps are to return a live NodeList
containing all the HTML elements in that document that have a name
attribute whose value is identical to the elementName argument, in tree order. When the method is invoked on a Document
object again with the same argument, the user agent may return the same as the object returned by the earlier call. In other cases, a new NodeList
object must be returned.
document.currentScript
Support in all current engines.
要素がクラシックスクリプトを表す限り、現在実行している、script
要素またはSVG script
要素を返す。再入可能なスクリプト実行の場合には、直近でまだ実行を完了していないものの中で実行を開始しそれを返す。
(たとえば、実行中のスクリプトは、イベントハンドラー、またはタイムアウトであるため)Document
が現在script
またはSVG script
要素を現在実行していない場合、または現在実行しているscript
またはSVG script
がモジュールスクリプトである場合はnullを返す。
The currentScript
attribute, on getting, must return the value to which it was most recently set. When the Document
is created, the currentScript
must be initialized to null.
このAPIは、APIがグローバルにscript
またはSVG script
要素を公開するので、実装者および標準コミュニティーの支持から離れている。それ自身は、モジュールスクリプトを実行する場合またはシャドウツリーにおけるスクリプトを実行する場合など、新しいコンテキストで利用可能ではない。We are looking into creating a new solution for identifying the running script in such contexts, which does not make it globally available: see issue #1013.
The Document
interface supports named properties. The supported property names of a Document
object document at any moment consist of the following, in tree order according to the element that contributed them, ignoring later duplicates, and with values from id
attributes coming before values from name
attributes when the same element contributes both:
the value of the name
content attribute for all exposed embed
, form
, iframe
, img
, and exposed object
elements that have a non-empty name
content attribute and are in a document tree with document as their root;
the value of the id
content attribute for all exposed object
elements that have a non-empty id
content attribute and are in a document tree with document as their root; and
the value of the id
content attribute for all img
elements that have both a non-empty id
content attribute and a non-empty name
content attribute, and are in a document tree with document as their root.
To determine the value of a named property name for a Document
, the user agent must return the value obtained using the following steps:
Let elements be the list of named elements with the name name that are in a document tree with the Document
as their root.
There will be at least one such element, since the algorithm would otherwise not have been invoked by Web IDL.
If elements has only one element, and that element is an iframe
element, and that iframe
element's content navigable is not null, then return the active WindowProxy
of the element's content navigable.
Otherwise, if elements has only one element, return that element.
Otherwise, return an HTMLCollection
rooted at the Document
node, whose filter matches only named elements with the name name.
Named elements with the name name, for the purposes of the above algorithm, are those that are either:
embed
, form
, iframe
, img
, or exposed object
elements that have a name
content attribute whose value is name, orobject
elements that have an id
content attribute whose value is name, orimg
elements that have an id
content attribute whose value is name, and that have a non-empty name
content attribute present also.An embed
or object
element is said to be exposed if it has no exposed object
ancestor, and, for object
elements, is additionally either not showing its fallback content or has no object
or embed
descendants.
Document
インターフェイス上のdir
属性は、dir
コンテンツ属性と同様に定義される。
HTMLにおける要素、属性、および属性値は、ある意味(セマンティックス)を持つよう(この仕様によって)定義される。たとえば、ol
要素は順序つきリストを表し、lang
属性はコンテンツの言語を表す。
These definitions allow HTML processors, such as web browsers or search engines, to present and use documents and applications in a wide variety of contexts that the author might not have considered.
As a simple example, consider a web page written by an author who only considered desktop computer web browsers:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > My Page</ title >
</ head >
< body >
< h1 > Welcome to my page</ h1 >
< p > I like cars and lorries and have a big Jeep!</ p >
< h2 > Where I live</ h2 >
< p > I live in a small hut on a mountain!</ p >
</ body >
</ html >
HTMLは見栄えよりもむしろ意味を伝えるため、ページを一切変更することなく、同じページが携帯電話上のスモールブラウザーによっても使用できる。たとえば、デスクトップと同様に大きな文字である見出しの代わりに、携帯電話のブラウザーは、ページ全体で同じサイズのテキストを使用するが、太字の見出しを持つかもしれない。
しかし、画面サイズにおける当然の違いよりもさらに言うと、画面上のページを表示する代わりに、同じページが、たとえばヘッドフォンを使用してユーザーにページを読みあげるなど、同等に音声合成ベースのブラウザーを使用する目の不自由なユーザーによって使用される可能性がある。見出し用の大きなテキストの代わりに、音声ブラウザーは異なる音量または遅い音声を使用するかもしれない。
それだけではない。ブラウザーはページのどの部分が見出しであるかを知っているので、"前の見出しにジャンプ"または"次の見出しにジャンプ"キーを使用して、ユーザーが迅速に文書操作するために使用できる文書のアウトラインをブラウザーは作成できる。このような機能は、ユーザーが他の方法で素早くページを操作することが非常に困難な場合に、特に音声ブラウザーでは一般的である。
まさにブラウザーを超えて、ソフトウェアはこの情報を利用できるのである。検索エンジンは、より効果的なインデックスページへ見出しを使用する、あるいはそれらの結果からページのサブセクションへのクイックリンクを提供する。ツールは目次(実際に、まさにこの仕様の目次が生成される方法)を作成するために見出しを使用できる。
この例は見出しに焦点を当てているが、HTMLにおけるセマンティックスのすべてに同じ原理が適用される。
著者は、ソフトウェアがページを正しく処理するのを妨げるような、適切な意図されるセマンティック目的以外の要素、属性、または属性値を使用してはならない。
たとえば、企業サイトの見出しを表すことを意図した、次のスニペットは、2行目がサブセクションの見出しであることを意図しないないため、非準拠であるが、単に小見出しまたは副題(同じセクションの下位の見出し)にすぎない。
< body >
< h1 > ACME Corporation</ h1 >
< h2 > The leaders in arbitrary fast delivery since 1920</ h2 >
...
The hgroup
element can be used for these kinds of situations:
< body >
< hgroup >
< h1 > ACME Corporation</ h1 >
< p > The leaders in arbitrary fast delivery since 1920</ p >
</ hgroup >
...
構文的に正しいにも関わらず、セル内に置かれるデータは明らかに表のデータではなく、cite
要素を誤使用したため、次の例における文書は同様に非準拠である:
<!DOCTYPE HTML>
< html lang = "en-GB" >
< head > < title > Demonstration </ title > </ head >
< body >
< table >
< tr > < td > My favourite animal is the cat. </ td > </ tr >
< tr >
< td >
—< a href = "https://example.org/~ernest/" >< cite > Ernest</ cite ></ a > ,
in an essay from 1992
</ td >
</ tr >
</ table >
</ body >
</ html >
これは、要素のセマンティックスを信頼するソフトウェアを停止させる。たとえば、目の不自由なユーザーに文書内の表の操作を許可された音声ブラウザーは、上記の引用を表として報告し、ユーザーを混乱させる。同様に、ページから作品タイトルを抽出するツールは、実際に人の名前であってタイトルでないにもかかわらず、作品のタイトルとして"Ernest"を抽出する。
この文書の修正版は次のようになる:
<!DOCTYPE HTML>
< html lang = "en-GB" >
< head > < title > Demonstration </ title > </ head >
< body >
< blockquote >
< p > My favourite animal is the cat. </ p >
</ blockquote >
< p >
—< a href = "https://example.org/~ernest/" > Ernest</ a > ,
in an essay from 1992
</ p >
</ body >
</ html >
著者は、将来的に拡張される言語に対して拡張が著しく困難になるため、この仕様または他の適用可能な仕様で許可されない要素、属性、または属性値を使用してはならない。
次の例では、この仕様で許可されていない不適合の属性値("carpet")および不適合の属性("texture")が存在する:
< label > Carpet: < input type = "carpet" name = "c" texture = "deep pile" ></ label >
代替で正しいマークアップ方法はこうなる:
< label > Carpet: < input type = "text" class = "carpet" name = "c" data-texture = "deep pile" ></ label >
ノード文書のブラウジングコンテキストがnullであるDOMノードは、HTML構文の要件およびXML構文の要件以外のすべての文書適合性要件を免除される。
具体的には、template
要素のテンプレートコンテンツのノード文書のブラウジングコンテキストがnullである。たとえば、コンテンツモデルの要件と属性値microsyntaxの要件は、template
要素のテンプレートコンテンツには適用されない。この例では、img
要素は、template
要素の外で無効になるプレースホルダーとなる属性値を持つ。
< template >
< article >
< img src = "{{src}}" alt = "{{alt}}" >
< h1 ></ h1 >
</ article >
</ template >
しかし、上記のマークアップで</h1>
終了タグを省略することは、HTML構文に違反するため、適合性チェッカーでエラーとしてフラグが立てられる。
ユーザーエージェントが文書を処理している間に、スクリプトやその他のメカニズムの使用を介して、属性値、テキスト、文書の全体構造は実際に動的に変更するかもしれない。ある瞬間において文書のセマンティックスは、その瞬間における文書の状態によって表されるものであり、したがって、文書のセマンティックスは、時間の経過とともに変化する。変更が発生したものとして、ユーザーエージェントは、文書の見栄えを更新する。
HTMLは、プログレスバーを表すprogress
要素を持つ。その"value"属性がスクリプトによって動的に更新される場合、ユーザーエージェントは進行状況の変更を表示するためにレンダリングを更新するだろう。
DOMでHTML要素を表すノードは、この仕様の関連セクションで挙げられるインターフェイスを実装しなければならず、スクリプトに公開しなければならない。HTML要素の文書が別のコンテキスト内(たとえばXSLT変換の内側)である場合でも、これはXML文書でのHTML要素を含む。
DOM内の要素は概念を表す。これは、要素がセマンティックとして知られる固有のセマンティックスを持つ。
たとえば、ol
要素は順序つきリストを表す。
要素は、明示的にまたは暗黙的のいずれかの、何らかの方法で参照される(参照する)ことがある。DOMにおける要素を明示的に参照できる方法の1つは、要素にid
属性を与えて、そのid
属性の値をハイパーリンクのhref
属性値のフラグメントとしてハイパーリンクを作成することである。しかし、参照にはハイパーリンクは必須ではない。問題の要素を参照する任意の方法で十分である。
< figure id = "module-script-graph" >
< img src = "module-script-graph.svg"
alt = "Module A depends on module B, which depends
on modules C and D." >
< figcaption > Figure 27: a simple module graph</ figcaption >
</ figure >
ハイパーリンクベースの参照は、a
要素を使用して作成することができる。このように:
As we can see in < a href = "#module-script-graph" > figure 27</ a > , ...
しかし、figure
要素を参照するには、次のような多くの方法がある:
"モジュールA、B、C、およびDの図に描かれているように....."
"Figure 27で..."(ハイパーリンクなしで)
"'単純なモジュールグラフ'の図の内容から..."
"下記の図で..."(しかし、これは勧められない)
すべてのHTML要素のインターフェイスから継承する、および追加の要求のない要素によって使用されなければならない、基本インターフェイスは、HTMLElement
インターフェイスである。
Support in all current engines.
Support in all current engines.
[Exposed =Window ]
interface HTMLElement : Element {
[HTMLConstructor ] constructor ();
// metadata attributes
[CEReactions ] attribute DOMString title ;
[CEReactions ] attribute DOMString lang ;
[CEReactions ] attribute boolean translate ;
[CEReactions ] attribute DOMString dir ;
// user interaction
[CEReactions ] attribute (boolean or unrestricted double or DOMString )? hidden ;
[CEReactions ] attribute boolean inert ;
undefined click ();
[CEReactions ] attribute DOMString accessKey ;
readonly attribute DOMString accessKeyLabel ;
[CEReactions ] attribute boolean draggable ;
[CEReactions ] attribute boolean spellcheck ;
[CEReactions ] attribute DOMString writingSuggestions ;
[CEReactions ] attribute DOMString autocapitalize ;
[CEReactions ] attribute boolean autocorrect ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString innerText ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString outerText ;
ElementInternals attachInternals ();
// The popover API
undefined showPopover (optional ShowPopoverOptions options = {});
undefined hidePopover ();
boolean togglePopover (optional (TogglePopoverOptions or boolean ) options = {});
[CEReactions ] attribute DOMString ? popover ;
};
dictionary ShowPopoverOptions {
HTMLElement source ;
};
dictionary TogglePopoverOptions : ShowPopoverOptions {
boolean force ;
};
HTMLElement includes GlobalEventHandlers ;
HTMLElement includes ElementContentEditable ;
HTMLElement includes HTMLOrSVGElement ;
[Exposed =Window ]
interface HTMLUnknownElement : HTMLElement {
// Note: intentionally no [HTMLConstructor]
};
HTMLElement
インターフェイスは、多数の異なる機能に関係するメソッドおよび属性を保持する。したがって、このインターフェイスのメンバーはこの仕様の異なるセクションでさまざまに説明される。
The element interface for an element with name name in the HTML namespace is determined as follows:
If name is applet
, bgsound
, blink
, isindex
, keygen
, multicol
, nextid
, or spacer
, then return HTMLUnknownElement
.
If name is acronym
, basefont
, big
, center
, nobr
, noembed
, noframes
, plaintext
, rb
, rtc
, strike
, or tt
, then return HTMLElement
.
If name is listing
or xmp
, then return HTMLPreElement
.
Otherwise, if this specification defines an interface appropriate for the element type corresponding to the local name name, then return that interface.
If other applicable specifications define an appropriate interface for name, then return the interface they define.
If name is a valid custom element name, then return HTMLElement
.
Return HTMLUnknownElement
.
The use of HTMLElement
instead of HTMLUnknownElement
in the case of valid custom element names is done to ensure that any potential future upgrades only cause a linear transition of the element's prototype chain, from HTMLElement
to a subclass, instead of a lateral one, from HTMLUnknownElement
to an unrelated subclass.
Features shared between HTML and SVG elements use the HTMLOrSVGElement
interface mixin: [SVG]
interface mixin HTMLOrSVGElement {
[SameObject ] readonly attribute DOMStringMap dataset ;
attribute DOMString nonce ; // intentionally no [CEReactions]
[CEReactions ] attribute boolean autofocus ;
[CEReactions ] attribute long tabIndex ;
undefined focus (optional FocusOptions options = {});
undefined blur ();
};
An example of an element that is neither an HTML nor SVG element is one created as follows:
const el = document.createElementNS("some namespace", "example");
console.assert(el.constructor === Element);
To support the custom elements feature, all HTML elements have special constructor behavior. This is indicated via the [HTMLConstructor]
IDL extended attribute. It indicates that the interface object for the given interface will have a specific behavior when called, as defined in detail below.
The [HTMLConstructor]
extended attribute must take no arguments, and must only appear on constructor operations. It must appear only once on a constructor operation, and the interface must contain only the single, annotated constructor operation, and no others. The annotated constructor operation must be declared to take no arguments.
Interfaces declared with constructor operations that are annotated with the [HTMLConstructor]
extended attribute have the following overridden constructor steps:
Let registry be the current global object's CustomElementRegistry
object.
If NewTarget is equal to the active function object, then throw a TypeError
.
This can occur when a custom element is defined using an element interface as its constructor:
customElements. define( "bad-1" , HTMLButtonElement);
new HTMLButtonElement(); // (1)
document. createElement( "bad-1" ); // (2)
In this case, during the execution of HTMLButtonElement
(either explicitly, as in (1), or implicitly, as in (2)), both the active function object and NewTarget are HTMLButtonElement
. If this check was not present, it would be possible to create an instance of HTMLButtonElement
whose local name was bad-1
.
Let definition be the entry in registry with constructor equal to NewTarget. If there is no such definition, then throw a TypeError
.
Since there can be no entry in registry with a constructor of undefined, this step also prevents HTML element constructors from being called as functions (since in that case NewTarget will be undefined).
Let is value be null.
If definition's local name is equal to definition's name (i.e., definition is for an autonomous custom element), then:
If the active function object is not HTMLElement
, then throw a TypeError
.
This can occur when a custom element is defined to not extend any local names, but inherits from a non-HTMLElement
class:
customElements. define( "bad-2" , class Bad2 extends HTMLParagraphElement {});
In this case, during the (implicit) super()
call that occurs when constructing an instance of Bad2
, the active function object is HTMLParagraphElement
, not HTMLElement
.
Otherwise (i.e., if definition is for a customized built-in element):
Let valid local names be the list of local names for elements defined in this specification or in other applicable specifications that use the active function object as their element interface.
If valid local names does not contain definition's local name, then throw a TypeError
.
This can occur when a custom element is defined to extend a given local name but inherits from the wrong class:
customElements. define( "bad-3" , class Bad3 extends HTMLQuoteElement {}, { extends : "p" });
In this case, during the (implicit) super()
call that occurs when constructing an instance of Bad3
, valid local names is the list containing q
and blockquote
, but definition's local name is p
, which is not in that list.
Set is value to definition's name.
If definition's construction stack is empty, then:
Let element be the result of internally creating a new object implementing the interface to which the active function object corresponds, given the current realm and NewTarget.
Set element's node document to the current global object's associated Document
.
Set element's namespace to the HTML namespace.
Set element's namespace prefix to null.
Set element's local name to definition's local name.
Set element's custom element state to "custom
".
Set element's custom element definition to definition.
Set element's is
value to is value.
Return element.
This occurs when author script constructs a new custom element directly, e.g. via new MyCustomElement()
.
If prototype is not an Object, then:
Let realm be ? GetFunctionRealm(NewTarget).
Set prototype to the interface prototype object of realm whose interface is the same as the interface of the active function object.
The realm of the active function object might not be realm, so we are using the more general concept of "the same interface" across realms; we are not looking for equality of interface objects. This fallback behavior, including using the realm of NewTarget and looking up the appropriate prototype there, is designed to match analogous behavior for the JavaScript built-ins and Web IDL's internally create a new object implementing the interface algorithm.
Let element be the last entry in definition's construction stack.
If element is an already constructed marker, then throw a TypeError
.
This can occur when the author code inside the custom element constructor non-conformantly creates another instance of the class being constructed, before calling super()
:
let doSillyThing = true ;
class DontDoThis extends HTMLElement {
constructor() {
if ( doSillyThing) {
doSillyThing = false ;
new DontDoThis();
// Now the construction stack will contain an already constructed marker.
}
// This will then fail with a TypeError:
super ();
}
}
This can also occur when author code inside the custom element constructor non-conformantly calls super()
twice, since per the JavaScript specification, this actually executes the superclass constructor (i.e. this algorithm) twice, before throwing an error:
class DontDoThisEither extends HTMLElement {
constructor() {
super ();
// This will throw, but not until it has already called into the HTMLElement constructor
super ();
}
}
Perform ? element.[[SetPrototypeOf]](prototype).
Replace the last entry in definition's construction stack with an already constructed marker.
Return element.
This step is normally reached when upgrading a custom element; the existing element is returned, so that the super()
call inside the custom element constructor assigns that existing element to this.
In addition to the constructor behavior implied by [HTMLConstructor]
, some elements also have named constructors (which are really factory functions with a modified prototype
property).
Named constructors for HTML elements can also be used in an extends
clause when defining a custom element constructor:
class AutoEmbiggenedImage extends Image {
constructor( width, height) {
super ( width * 10 , height * 10 );
}
}
customElements. define( "auto-embiggened" , AutoEmbiggenedImage, { extends : "img" });
const image = new AutoEmbiggenedImage( 15 , 20 );
console. assert( image. width === 150 );
console. assert( image. height === 200 );
この仕様において各要素は以下の情報を含む定義を持つ:
要素を使用できる場所の非規範的な記述。この情報は、子として、この要素を許可する要素のコンテンツモデルとともに冗長であり、利便性のためだけに提供される。
簡単のために、最も具体的な期待のみが記載される。
For example, all phrasing content is flow content. Thus, elements that are phrasing content will only be listed as "where phrasing content is expected", since this is the more-specific expectation. Anywhere that expects flow content also expects phrasing content, and thus also meets this expectation.
コンテンツがその要素の子や子孫として含めなければならないものの、規範的な記述。
text/html
構文で、開始タグと終了タグを省略することができるかどうかの非規範的な記述。この情報は、任意タグのセクションで与えられた規範的要件とともに冗長であり、利便性のみの要素の定義に記載される。
(許可しない場合を除く)要素で指定されてもよい属性の規範的なリスト、およびこれら属性の非規範的な説明。(ダッシュの左側のコンテンツが規範的であり、ダッシュの右側のコンテンツがそうでない。)
For authors: Conformance requirements for use of ARIA role
and aria-*
attributes are defined in ARIA in HTML. [ARIA] [ARIAHTML]
For implementers: User agent requirements for implementing accessibility API semantics are defined in HTML Accessibility API Mappings. [HTMLAAM]
そのような要素が実装しなければならないDOMインターフェイスの規範的な定義。
その後、著者および実装に適用されてもよい追加の規範適合基準とともに、要素が何を表すのかの説明が続く。時に例も含まれる。
属性値は、文字列である。特に指定される場合を除き、HTML要素の属性値は、空の文字列を含み、およびそのような属性値を指定することができるテキストに制限はない、任意の文字列値であってもよい。
この仕様で定義される各要素は、要素の期待されるコンテンツの説明となる、コンテンツモデルを持つ。HTML要素は、要素のコンテンツモデルで説明される要求に一致するコンテンツを持たなければならない。要素のコンテンツは、DOMにおけるその子である。
ASCII空白文字は常に要素の間に許可される。ユーザーエージェントは、DOMでText
としてソースマークアップにおける要素間のこれら文字を表す。空のText
ノードおよびそれらの文字の単なる配列から成るText
ノードは、要素間の空白文字と見なされる。
要素間の空白文字、コメントノード、および処理命令ノードは、要素の内容が要素の内容モデルと一致させるかどうかを確立する際に無視されなければならず、文書および要素のセマンティックスを定義するアルゴリズムをたどる際に無視されなければならない。
このように、AとBが同じ親ノードを持ち、それらの間に他の要素ノードまたは(要素間の空白以外の)Text
ノードが存在しない場合、要素Aに2番目の要素Bが先行または後行すると言う。同様に、その要素が要素間の空白、コメントノード、処理命令ノード以外の他のノードが含まない場合、ノードは、要素の唯一の子である。
著者は、各要素に定義された、あるいは明示的に他の仕様によって要求されたものとして明示的に許可される場所以外でHTML要素を使用してはならない。XML複合文書では、それらの要素が関連するコンテキストを提供するものとして定義される場合、これらのコンテキストは、他の名前空間に由来する要素の内部にあるかもしれない。
The Atom Syndication Format defines a content
element. When its type
attribute has the value xhtml
, The Atom Syndication Format requires that it contain a single HTML div
element. Thus, a div
element is allowed in that context, even though this is not explicitly normatively stated by this specification. [ATOM]
さらに、HTML要素は省略されてもよい(すなわち、親ノードをもたない)。
たとえば、td
要素を作成し、スクリプト内のグローバル変数に格納することは、td
要素が別の方法でのみtr
要素の内部で使用されることになっているにもかかわらず、適合する。
var data = {
name: "Banana" ,
cell: document. createElement( 'td' ),
};
要素のコンテンツモデルがnothingである場合、要素は、(要素間の空白文字以外)は、Text
ノードおよび要素ノードを一切含んではならない。
便宜上、ほとんどのHTML要素のコンテンツモデルはまた"nothing"であり、ボイドの要素(HTML構文には終了タグがない要素)。しかし、これらは全く別の概念である。
HTMLにおいて各要素は、0個以上の、類似の特性を持つグループ要素であるカテゴリーに分類される。次の大まかなカテゴリーがこの仕様で使用されている:
一部の要素はまた、本仕様の他の部分で定義される他のカテゴリーに分類される。
これらのカテゴリーは、次のように関連する:
セクショニングコンテンツ、ヘディングコンテンツ、フレージングコンテンツ、エンベディッドコンテンツ、およびインタラクティブコンテンツはすべてフローコンテンツ型である。メタデータは、時にフローコンテンツとなる。メタデータとインタラクティブコンテンツは時にフレージングコンテンツとなる。エンベディッドコンテンツはまた、フレージングコンテンツ型であり、時にインタラクティブコンテンツとなる。
その他のカテゴリーはまた、特定の目的のために使用される。たとえばフォームコントロールは、一般的な要件を定義するために多数のカテゴリーを用いて指定される。一部の要素は固有の要件があり、特定のカテゴリーに属さない。
メタデータコンテンツは、見栄えまたは後のコンテンツの振る舞いを設定する、または他の文書との関係を設定する、または他の"帯域外の"情報を運搬するコンテンツである。
セマンティックスが主としてメタデータに関連する他の名前空間由来の要素(たとえば、RDF)もまた、メタデータコンテンツである。
したがって、XMLシリアライゼーションにおいて、このようにRDFを使用できる:
< html xmlns = "http://www.w3.org/1999/xhtml"
xmlns:r = "http://www.w3.org/1999/02/22-rdf-syntax-ns#" xml:lang = "en" >
< head >
< title > Hedral's Home Page</ title >
< r:RDF >
< Person xmlns = "http://www.w3.org/2000/10/swap/pim/contact#"
r:about = "https://hedral.example.com/#" >
< fullName > Cat Hedral</ fullName >
< mailbox r:resource = "mailto:hedral@damowmow.com" />
< personalTitle > Sir</ personalTitle >
</ Person >
</ r:RDF >
</ head >
< body >
< h1 > My home page</ h1 >
< p > I like playing with string, I guess. Sister says squirrels are fun
too so sometimes I follow her to play with them.</ p >
</ body >
</ html >
しかし、これはHTMLシリアライゼーションでは不可能である。
文書およびアプリケーションのbodyで使用される多くの要素は、フローコンテンツとして分類される。
a
abbr
address
area
(map
要素の子孫の場合)article
aside
audio
b
bdi
bdo
blockquote
br
button
canvas
cite
code
data
datalist
del
details
dfn
dialog
div
dl
em
embed
fieldset
figure
footer
form
h1
h2
h3
h4
h5
h6
header
hgroup
hr
i
iframe
img
input
ins
kbd
label
link
(body内で許可される場合)main
(階層的に正しいmain
要素の場合)map
mark
math
menu
meta
(itemprop
属性が存在する場合)meter
nav
noscript
object
ol
output
p
picture
pre
progress
q
ruby
s
samp
script
search
section
select
slot
small
span
strong
sub
sup
svg
table
template
textarea
time
u
ul
var
video
wbr
セクショニングコンテンツは、header
およびfooter
の範囲を定義するコンテンツである。
ヘディングコンテンツはセクションの見出しを定義する(明示的にセクショニングコンテンツ要素を用いてマークアップされようとなかろうと、またはヘディングコンテンツ自体によって暗黙であろうとなかろうと)。
フレージングコンテンツは、文書のテキストおよび段落内レベルでそのテキストをマークアップする要素である。段落からフレージングコンテンツが続く。
a
abbr
area
(map
要素の子孫の場合)audio
b
bdi
bdo
br
button
canvas
cite
code
data
datalist
del
dfn
em
embed
i
iframe
img
input
ins
kbd
label
link
(body内で許可される場合)map
mark
math
meta
(itemprop
属性が存在する場合)meter
noscript
object
output
picture
progress
q
ruby
s
samp
script
select
slot
small
span
strong
sub
sup
svg
template
textarea
time
u
var
video
wbr
フレージングコンテンツとして分類されるほとんどの要素は、自身がフローコンテンツではなく、フレージングコンテンツとして分類される要素のみを含むことができる。
コンテンツモデルのコンテキストにおいてテキストは、何もないか、Text
ノードのいずれかを意味する。テキストは時に、そのままでコンテンツモデルとして使用されるが、フレージングコンテンツでもあり、要素間の空白文字でもあるかもしれない(Text
ノードが空であるか、単にASCII空白文字を含む場合)。
Text
ノードおよび属性値は、noncharactersおよびASCII空白文字以外の制御文字を除いて、スカラー値から構成されなければならない。この仕様は、明確なコンテキストに応じたText
ノードおよび属性値の正確な値に追加の制限を含む。
エンベディッドコンテンツは、他のリソースから文書に取り込むコンテンツであるか、文書へ挿入される他の語彙由来のコンテンツである。
HTML名前空間以外の名前空間に基づく、メタデータでなくコンテンツを伝える要素は、この仕様で定義されるコンテンツモデルの目的のためのエンベディッドコンテンツである。(For example, MathML or SVG.)
一部のエンベディッドコンテンツ要素は、フォールバックコンテンツを持つこともできる。これは外部リソースが使用できない場合(たとえば、サポートされていないフォーマットであるため)に使用されるコンテンツである。もしあれば、要素の定義はどのようなフォールバックであるかを記載する。
インタラクティブコンテンツは、特にユーザーとの交流を意図するコンテンツである。
a
(href
属性が存在する場合)audio
(controls
属性が存在する場合)button
details
embed
iframe
img
(usemap
属性が存在する場合)input
(type
属性が 状態でない場合)label
select
textarea
video
(controls
属性が存在する場合)一般的な規則として、コンテンツモデルが任意のフローコンテンツまたはフレージングコンテンツを許可する要素は、パルパブルコンテンツであり、かつ 属性が指定されないそのコンテンツで少なくとも1つノードを持つべきである。
Palpable content makes an element non-empty by providing either some descendant non-empty text, or else something users can hear (audio
elements) or view (video
, img
, or canvas
elements) or otherwise interact with (for example, interactive form controls).
しかし、要素が合法的に空にできる多くのケースがあるように、たとえば、スクリプトによって後で埋められるプレースホルダーとして使用される場合、または要素がテンプレートの一部であり、かつほとんどのページで満たされるが、一部のページで関係しない場合、この要件は厳しい要件ではない。
適合性検査は、オーサリングの援助として、この要件を満たせない要素を見つけるためのメカニズムを制作者に提供するよう推奨される。
次の要素はパルパブルコンテンツである:
a
abbr
address
article
aside
audio
(controls
属性が存在する場合)b
bdi
bdo
blockquote
button
canvas
cite
code
data
del
details
dfn
div
dl
(要素の子が少なくとも1つの名前-値グループを含む場合)em
embed
fieldset
figure
footer
form
h1
h2
h3
h4
h5
h6
header
hgroup
i
iframe
img
input
(type
属性が 状態でない場合)ins
kbd
label
main
map
mark
math
menu
(要素の子が少なくとも1つli
要素を含む場合)meter
nav
object
ol
(要素の子が少なくとも1つli
要素を含む場合)output
p
picture
pre
progress
q
ruby
s
samp
search
section
select
small
span
strong
sub
sup
svg
table
textarea
time
u
ul
(要素の子が少なくとも1つli
要素を含む場合)var
video
スクリプトサポート要素は、自分自身で何も表さない(つまりこれらはレンダリングされない)が、たとえばユーザーに機能を提供するために、スクリプトをサポートするために使用される。
次の要素は、スクリプトサポート要素である:
いくつかの要素は透過的といわれる。コンテンツモデルの説明でそれらの要素は"透過的"とされる。透過的な要素のコンテンツモデルは、その親要素のコンテンツモデルを受け継ぐ。"透過的"であるコンテンツモデルの役割で要求される要素は、透過的な要素がある、透過的な親要素のコンテンツモデルの役割で要求されるものと同じ要素である。
たとえば、ins
要素を許可するruby
要素のコンテンツモデルの役割は、フレージングコンテンツを許可する役割であり、かつrt
要素はフレージングコンテンツではないので、ruby
要素の内側でins
要素はrt
要素を含むことはできない。
一部のケースでは、透過的な要素が相互に入れ子になる場合、プロセスを繰り返し適用する必要がある。
次のマークアップ断片を考えてみよう:
< p >< object >< ins >< map >< a href = "/" > Apples</ a ></ map ></ ins ></ object ></ p >
a
要素の内側で"Apples"が許可されるかどうかを確かめるために、コンテンツモデルを分析する。The a
element's content model is transparent, as is the map
element's, as is the ins
element's, as is the object
element's. The object
element is found in the p
element, whose content model is phrasing content. したがって、テキストはフレージングコンテンツなので、"Apples"は許可される。
透過的なコンテンツが親を持たない場合、"透過的"であるそのコンテンツモデルの役割は、代わりに任意のフローコンテンツを受け入れるものとして扱われなければならない。
この節で定義されるような用語段落は、p
要素の正確な定義以上の使われ方をする。ここで定義される段落の概念は、どのように文書を解釈すべきかを説明するために使われる。p
要素は、段落をマークアップするいくつかのうちの1つにすぎない。
典型的な段落は、活版印刷において見られるような、特定の主題を議論する1つ以上の文をもつテキストのブロックを形成する、フレージングコンテンツの連続であるが、より一般の主題に関する分類に対しても用いられる。たとえば、住所もまた段落であり、フォームの一部、署名、詩のスタンザも同様である。
次の例において、セクションに2つの段落がある。段落ではないフレージングコンテンツを含む見出しもある。コメントおよび段落内の空白文字は段落を形成しないことに注意する。
< section >
< h2 > Example of paragraphs</ h2 >
This is the < em > first</ em > paragraph in this example.
< p > This is the second.</ p >
<!-- This is not a paragraph. -->
</ section >
フローコンテンツ内の段落は、中身を複雑にするa
、ins
、del
、map
要素なしで、文書がどのように見えるかに関連して定義される。なぜなら、以下に最初の2つの例で示すように、混成のコンテンツモデルをもつこれらの要素は、段落の境界をまたぐことができるためである。
一般に、段落の境界をまたぐ要素を持つことは避けた方がよい。このようなマークアップを維持することは困難なことがある。
次の例は、前述の例からマークアップを選び、テキストが変更されたことを示すためにそのマークアップの一部の周囲にins
とdel
要素を置く(もっともこの場合、正直なところ変更にあまり意味はないが)。この例は、ins
とdel
要素をよそに、前のものとちょうど同じ段落を持つことに注目する―ins
要素は見出しと最初の段落にまたがっており、del
要素は2つの段落間の境界をまたがっている。
< section >
< ins >< h2 > Example of paragraphs</ h2 >
This is the < em > first</ em > paragraph in</ ins > this example< del > .
< p > This is the second.</ p ></ del >
<!-- This is not a paragraph. -->
</ section >
viewをコンテンツをもつ文書におけるすべてのa
、ins
、del
、およびmap
要素を置換するDOMのビューにする。そして、viewで、他の種類のコンテンツによって中断されることなくフレージングコンテンツノードの各ランのため、フレージングコンテンツだけでなくフレージングコンテンツ以外のコンテンツを受け入れる要素において、firstをランの最初のノードにし、lastをランの最後のノードにする。エンベティッドコンテンツでも要素間空白でもない少なくとも1つのノードで構成するそのような各ランに対して、段落はfirstの直前からlastの直後まで元のDOMに存在する。(このように段落は、a
、ins
、del
、およびmap
要素にまたがることができる。)
Conformance checkers may warn authors of cases where they have paragraphs that overlap each other (this can happen with object
, video
, audio
, and canvas
elements, and indirectly through elements in other namespaces that allow HTML to be further embedded therein, like SVG svg
or MathML math
).
段落を互いに分離するためにフレージングコンテンツ以外のコンテンツが別の方法でないだろう場合、p
要素は個々の段落をワードラップするために使用できる。
次の例において、リンクは第1段落の半分、2つの段落を分離する見出しのすべて、および第2段落の半分にわたる。これは、段落と見出しをまたがっている。
< header >
Welcome!
< a href = "about.html" >
This is home of...
< h1 > The Falcons!</ h1 >
The Lockheed Martin multirole jet fighter aircraft!
</ a >
This page discusses the F-16 Fighting Falcon's innermost secrets.
</ header >
以下はマークアップのもう1つの方法である。今回は、段落を明示し、1つのリンク要素を3つに分割している:
< header >
< p > Welcome! < a href = "about.html" > This is home of...</ a ></ p >
< h1 >< a href = "about.html" > The Falcons!</ a ></ h1 >
< p >< a href = "about.html" > The Lockheed Martin multirole jet
fighter aircraft!</ a > This page discusses the F-16 Fighting
Falcon's innermost secrets.</ p >
</ header >
フォールバックコンテンツを定義する特定の要素を使用する場合、段落は重複してもよい。たとえば、以下のセクションで:
< section >
< h2 > My Cats</ h2 >
You can play with my cat simulator.
< object data = "cats.sim" >
To see the cat simulator, use one of the following links:
< ul >
< li >< a href = "cats.sim" > Download simulator file</ a >
< li >< a href = "https://sims.example.com/watch?v=LYds5xY4INU" > Use online simulator</ a >
</ ul >
Alternatively, upgrade to the Mellblom Browser.
</ object >
I'm quite proud of it.
</ section >
5つの段落が存在する:
object
要素である。最初の段落は他の4つの段落と重複する。"cats.sim"リソースをサポートするユーザーエージェントは、最初の段落のみを表示するが、ユーザーエージェントは、あたかも2番目の段落と同じ段落であったかのように、1段落目の最初の文を表示するという紛らわしいフォールバックを表示し、かつあたかも1段落目の2番目にある文の冒頭であるかのように、最後の段落を表示するだろう。
この混乱を避けるために、明示的にp
要素を使用することができる。たとえば:
< section >
< h2 > My Cats</ h2 >
< p > You can play with my cat simulator.</ p >
< object data = "cats.sim" >
< p > To see the cat simulator, use one of the following links:</ p >
< ul >
< li >< a href = "cats.sim" > Download simulator file</ a >
< li >< a href = "https://sims.example.com/watch?v=LYds5xY4INU" > Use online simulator</ a >
</ ul >
< p > Alternatively, upgrade to the Mellblom Browser.</ p >
</ object >
< p > I'm quite proud of it.</ p >
</ section >
次の属性は共通で、(この仕様で定義されない属性でさえも)すべてのHTML要素で指定してよいものである:
accesskey
autocapitalize
autocorrect
autofocus
contenteditable
dir
draggable
enterkeyhint
inert
inputmode
is
itemid
itemprop
itemref
itemscope
itemtype
lang
nonce
popover
spellcheck
style
tabindex
title
translate
writingsuggestions
これらの属性は、HTML要素に対する属性としてこの仕様でただ単に定義される。この仕様がこれらの属性を持つ要素を参照する場合、これらの属性を持つものとして定義されない名前空間からの要素は、これらの属性をもつ要素であると考えてはならない。
たとえば、次のXML断片において、"bogus
"要素は、リテラル名"dir
"をもつ属性を持つにもかかわらず、この仕様で定義されるようにdir
属性を持たない。よって、最も内側のspan
要素の書字方向は、間接的に"bogus
"要素を通してdiv
要素から継承される、'rtl'となる。
< div xmlns = "http://www.w3.org/1999/xhtml" dir = "rtl" >
< bogus xmlns = "https://example.net/ns" dir = "ltr" >
< span xmlns = "http://www.w3.org/1999/xhtml" >
</ span >
</ bogus >
</ div >
Support in all current engines.
DOM defines the user agent requirements for the class
, id
, and slot
attributes for any element in any namespace. [DOM]
class
、id
およびslot
属性は、すべてのHTML要素に指定されてもよい。
HTML要素で指定される場合、class
属性は、要素が属する様々なクラスを表すスペース区切りトークンの組の値を持たなければならない。
クラスを要素に割り当てることは、クラスのCSSセレクターでのマッチング、DOMにおけるgetElementsByClassName()
メソッド、および他のそのような機能に影響を与える。
著者が使用できるclass
属性のトークンに追加の制限は存在しないが、著者は、コンテンツの期待するプレゼンテーションを記述する値よりもむしろ、コンテンツの性質を記述する値を使用するよう推奨される。
HTML要素で指定される場合、id
属性値は、要素のツリーですべてのIDに共通して固有でなければならず、かつ少なくとも1つの文字を含まなければならない。値は一切のASCII空白文字を含んではならない。
IDを取ることができる形式に制限は存在しない。具体的に、IDは数字のみまたは句読点のみで構成することができ、数字やアンダースコアで開始できる、などである。
要素の固有識別子は様々な目的に使用されうる。中でも注目すべきはフラグメントを用いた文書の特定部分へのリンクする方法として、およびCSS由来の特定要素へのスタイル付けする方法としての目的である。
識別子は不透明な文字列である。固有の意味は、id
属性の値から導出されるべきではない。
slot
属性は、要素にスロットを割り当てるために使用される:slot
属性をもつ要素は、name属性の値がそのslot
属性の値と一致するslot
要素によって作成されたスロットに割り当てられる。ただし、そのslot
要素が、ルートのホストが対応するslot
属性値を持つシャドウツリー内で見つかった場合に限る。
よりきめ細かいインターフェイスを公開できるよう支援技術製品が別の方法でHTML要素と属性で可能にするために、支援技術製品への注釈の組が指定できる(ARIA role
およびaria-*
属性)。[ARIA]
以下のイベントハンドラーコンテンツ属性は任意のHTML要素に指定されてもよい:
onauxclick
onbeforeinput
onbeforematch
onbeforetoggle
onblur
*oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncontextlost
oncontextmenu
oncontextrestored
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
*onfocus
*onformdata
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
*onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize
*onscroll
*onscrollend
*onsecuritypolicyviolation
onseeked
onseeking
onselect
onslotchange
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
これら要素が同じ名前をもつWindow
オブジェクトのイベントハンドラーを公開するため、アスタリスクとともにマークされる属性は、body
要素上で指定される場合、異なる意味を持つ。
これら属性がすべての要素に適用される一方で、属性はすべての要素で役立つわけでない。たとえば、メディア要素のみがユーザーエージェントによって発火されたvolumechange
イベントを受け取るだろう。
カスタムデータ属性(たとえばdata-foldername
やdata-msgid
)は、任意のHTML要素に指定されてよく、ページ特有のカスタムデータ、ステート、アノテーションなどの類似のものを保存可能である。
HTML文書で、HTML名前空間での要素は指定するxmlns
属性を持つかもしれない。もし存在するなら値は正確に"http://www.w3.org/1999/xhtml
"のみを持つ。これはXML文書に当てはまらない。
HTMLにおいて、xmlns
属性は一切影響しない。これは基本的に魔除けである。これはXMLからの移行を少し簡単にするためだけに許可される。HTMLパーサによって解析される場合、XMLの名前空間宣言属性のように"http://www.w3.org/2000/xmlns/
"名前空間ではなく、属性は名前空間なしに終わる。
XMLにおいて、xmlns
属性は名前空間宣言メカニズムの一部であり、要素は実際に名前空間を指定されないxmlns
属性を持つことはできない。
XML also allows the use of the xml:space
attribute in the XML namespace on any element in an XML document. This attribute has no effect on HTML elements, as the default behavior in HTML is to preserve whitespace. [XML]
text/html
構文でHTML要素上のxml:space
属性をシリアル化する方法は存在しない。
title
属性Support in all current engines.
title
属性は、ツールチップに適するような要素に対する助言的な情報を表す。リンクでは、これはタイトルまたは対象リソースの記述であるかもしれない。画像では、画像のタイトルや説明であるかもしれない。段落では、テキストの脚注や解説であるかもしれない。引用では、ソースに関する詳細情報かもしれない。インタラクティブコンテンツでは、要素の用途に対する分類や指示などかもしれない、などである。値はテキストである。
title
属性に依存することは、多くのユーザーエージェントがこの仕様で要求されるようなアクセス可能な方法で属性を公開しないため、現在推奨されない(たとえば、ツールチップを出現させるマウスなどのポインティングデバイスが必要になり、これはモダンな携帯端末やタブレットをもつ人のような、キーボードのみのユーザーとタッチのみのユーザーを締め出す)。
この属性が要素から省略される場合、title
属性をもつ最も近い先祖HTML要素のtitle
属性がその要素にとっても適切であることを意味する。属性を設定することはこれを上書きし、明示的に先祖の助言的な情報がこの要素に関連しないことを示す。空文字列を属性に設定すると、要素は助言的な情報を持たないことを示す。
title
属性値がU+000A LINE FEED(LF)文字を含む場合、コンテンツは複数行に分割される。各U+000A LINE FEED(LF)文字は改行を表す。
警告は、title
属性内の改行の使用について報告される。
たとえば、実際に次の断片は改行とともに省略語の拡張を定義する。
< p > My logs show that there was some interest in < abbr title = "Hypertext
Transport Protocol" > HTTP</ abbr > today.</ p >
link
、abbr
、input
のような一部の要素は、上記で説明されるセマンティックスを越えてtitle
属性に対する追加のセマンティックスを定義する。
要素の助言情報は、一度値が返されれれば中止されるアルゴリズムをもつ、次のアルゴリズムが返す値である。アルゴリズムが空文字列を返す場合、助言情報は存在しない。
If the element has a title
attribute, then return the result of running normalize newlines on its value.
要素が親要素を持つ場合、親要素の助言情報を返す。
空文字列を返す。
要素が勧告情報を持つ場合、ユーザーエージェントは、ユーザーに通知すべきである。そうでなければ情報は発見可能でない。
Support in all current engines.
title
IDL属性は、title
コンテンツ属性を反映しなければならない。
lang
およびxml:lang
属性Support in all current engines.
lang
属性(名前空間なし)は、要素のコンテンツに対する基本言語およびテキストを含むあらゆる要素の属性に対して指定する。その値は妥当なBCP 47言語タグまたは空文字列でなければならない。属性に空文字列を設定することは第一言語が不明であることを指す。[BCP47]
The lang
attribute in the XML namespace is defined in XML. [XML]
If these attributes are omitted from an element, then the language of this element is the same as the language of its parent element, if any (except for slot
elements in a shadow tree).
名前空間のないlang
属性は任意のHTML要素で使用されてもよい。
XML名前空間でのlang
属性は、XML文書でのHTML要素上で使用されてもよい。同様に、関連仕様が許可する(特に、MathMLおよびSVGがそれらの要素で指定されるXML名前空間でlang
属性を許可する)場合、他の名前空間で使用されてもよい。名前空間なしのlang
属性とXML名前空間でのlang
属性の両方が同じ要素に指定される場合、ASCII大文字・小文字不区別で比較したときに、これらは正確に同じ値を持たなければならない。
著者は、HTML文書におけるHTML要素でXML名前空間内でlang
属性を使用してはならない。XMLとの移行を容易にするために、著者は、接頭辞なしで名前空間のない属性、およびHTML文書内のHTML要素にリテラルでローカル名"xml:lang
"を指定してもよいが、名前空間のないlang
属性も指定されている場合、そのような属性のみが指定されなければならず、ASCII大文字・小文字不区別で比較するとき、両方の属性は同じ値を持たなければならない。
接頭辞なしで名前空間のない属性およびリテラルにローカル"xml:lang
"は、言語処理に影響を与えない。
To determine the language of a node, user agents must use the first appropriate step in the following list:
lang
attribute in the XML namespace setUse the value of that attribute.
lang
in no namespace attribute setUse the value of that attribute.
Use the language of that shadow root's host.
Use the language of that parent element.
If there is a pragma-set default language set, then that is the language of the node. If there is no pragma-set default language set, then language information from a higher-level protocol (such as HTTP), if any, must be used as the final fallback language instead. そのような言語情報が何も存在しない場合、かつより高いレベルのプロトコルが複数の言語を報告する場合、ノードの言語は不明であり、かつ対応する言語タグは空文字列である。
結果の値が認識される言語タグでない場合、その他の言語とは異なる、特定の言語タグを持つ未知の言語として扱われなければならない。データを解釈しないようにラウンドトリップや言語タグを期待する他のサービスとの通信に対して、後続のサービスが言語説明の別のタイプとしてデータを解釈しないように、ユーザーエージェントは、変更されていない間に言語タグを渡すべきであり、かつBCP 47言語タグであるとしてタグ付けされるべきである。[BCP47]
従って、たとえば、lang="xyzzy"
をもつ要素は、(たとえばCSSで)セレクター:lang(xyzzy)
にマッチしたことになるが、両者が等しくに不正であるにも関わらず、:lang(abcde)
とマッチしない。Similarly, if a web browser and screen reader working in unison communicated about the language of the element, the browser would tell the screen reader that the language was "xyzzy", even if it knew it was invalid, just in case the screen reader actually supported a language with that tag after all. たとえスクリーンリーダーがBCP 47とエンコーディング言語名の他の構文の両方をサポートし、その別の構文で文字列"xyzzy"がベラルーシ語を意味する手段であっても、スクリーンリーダーは、ベラルーシ語としてテキストを処理開始することは不適切である。なぜなら、"xyzzy"は、ベラルーシ語がBCP 47コードで記述されている手段ではない(BCP 47は、てベラルーシ語に対してコード"be"を使用する)ためである。
結果の値が空文字列である場合、値はノードの言語が明示的に不明であることを意味するものとして解釈されなければならない。
ユーザーエージェントは、(たとえば、辞書の選択のため、または、日付ピッカーなどのフォームコントロールのユーザーインターフェイスのために、適切なフォントや発音の選択において)適切な処理またはレンダリングを決定するために要素の言語を使用してもよい。
Support in all current engines.
lang
IDL属性は、名前空間なしのlang
コンテンツ属性を反映しなければならない。
translate
属性Support in all current engines.
The translate
attribute is used to specify whether an element's attribute values and the values of its Text
node children are to be translated when the page is localized, or whether to leave them unchanged. It is an attribute is an enumerated attribute with the following keywords and states:
キーワード | 状態 | 概要 |
---|---|---|
yes | yes | Sets translation mode to translate-enabled. |
(the empty string) | ||
no | no | Sets translation mode to no-translate. |
The attribute's missing value default and invalid value default are both the inherit state.
(非HTML要素でさえも)各要素は、翻訳可能状態または無翻訳状態のいずれかの翻訳モードを持つ。HTML要素のtranslate
属性がyes状態である場合、その要素の翻訳モードは翻訳可能な状態となる。そうでなければ、要素のtranslate
属性がno状態である場合、その要素の翻訳モードは無翻訳状態となる。Otherwise, either the element's translate
attribute is in the inherit state, or the element is not an HTML element and thus does not have a translate
attribute; in either case, the element's translation mode is in the same state as its parent element's, if any, or in the translate-enabled state, if the element's parent element is null.
要素が翻訳可能状態にある場合、要素の翻訳可能属性とそのText
ノードの子の値は、ページがローカライズされる際に翻訳される。
要素が無翻訳状態にある場合、要素の属性値とそのText
ノードの子の値は、たとえば要素が人物名やコンピュータープログラム名を含むため、ページがローカライズされるときに、そのままで残される。
以下の属性は翻訳可能属性である:
th
要素のabbr
area
、img
、input
要素のalt
name
属性が値に翻訳可能として知られるメタデータ名を指定する場合、meta
要素のcontent
a
およびarea
要素のdownload
optgroup
、 option
、およびtrack
要素のlabel
lang
。翻訳で使用される言語と一致する"翻訳された"ものでなければならない。input
およびtextarea
要素のplaceholder
iframe
要素のsrcdoc
。解析されかつ再帰的に処理されなければならないstyle
。解析されかつ再帰的に処理されなければならない(たとえば'content'プロパティの値)title
type
属性をもつinput
要素のvalue
他の仕様は、翻訳可能な属性でもある他の属性を定義してもよい。For example, ARIA would define the aria-label
attribute as translatable.
取得時に、要素の変換モードが翻訳可能である場合、translate
IDL属性は、trueを返さなければならず、そうでなければfalseを返さなければならない。設定時に、新しい値がtrueである場合、それはコンテンツ属性値を"yes
"に設定しなければならず、そうでなければコンテンツ属性値を"no
"に設定しなければならない。
次の例で、サンプルのキーボード入力とサンプルプログラム出力を除き、ページがローカライズされるときに文書内のすべてが翻訳される:
<!DOCTYPE HTML>
< html lang = en > <!-- default on the document element is translate=yes -->
< head >
< title > The Bee Game</ title > <!-- implied translate=yes inherited from ancestors -->
</ head >
< body >
< p > The Bee Game is a text adventure game in English.</ p >
< p > When the game launches, the first thing you should do is type
< kbd translate = no > eat honey</ kbd > . The game will respond with:</ p >
< pre >< samp translate = no > Yum yum! That was some good honey!</ samp ></ pre >
</ body >
</ html >
dir
属性Support in all current engines.
The dir
attribute is an enumerated attribute with the following keywords and states:
キーワード | 状態 | 概要 |
---|---|---|
ltr | ltr | The contents of the element are explicitly directionally isolated left-to-right text. |
rtl | rtl | The contents of the element are explicitly directionally isolated right-to-left text. |
auto | auto | The contents of the element are explicitly directionally isolated text, but the direction is to be determined programmatically using the contents of the element (as described below). |
The heuristic used by the auto state is very crude (it just looks at the first character with a strong directionality, in a manner analogous to the Paragraph Level determination in the bidirectional algorithm). 著者は、テキストの方向が全く未知である場合、最後の手段としてのみこの値を使用するよう要請し、同様のサーバー側のヒューリスティックを適用できる。[BIDI]
The attribute's missing value default and invalid value default are both the undefined state.
The directionality of an element (any element, not just an HTML element) is either 'ltr' or 'rtl'. To compute the directionality given an element element, switch on element's dir
attribute state:
Return 'ltr'.
Return 'rtl'.
Let result be the auto directionality of element.
If result is null, then return 'ltr'.
Return result.
bdi
elementLet result be the auto directionality of element.
If result is null, then return 'ltr'.
Return result.
input
element whose type
attribute is in the Telephone stateReturn 'ltr'.
Return the parent directionality of element.
dir
属性はHTML要素に対してのみ定義されるので、他の名前空間からの要素では存在し得ない。Thus, elements from other namespaces always end up using the parent directionality.
The auto-directionality form-associated elements are:
input
elements whose type
attribute is in the , Text, Search, Telephone, URL, Email, Password, Submit Button, Reset Button, or Button state, and
textarea
elements.
To compute the auto directionality given an element element:
If element is an auto-directionality form-associated element:
If element is a slot
element whose root is a shadow root and element's assigned nodes are not empty:
For each node child of element's assigned nodes:
Let childDirection be null.
If child is a Text
node, then set childDirection to the text node directionality of child.
Otherwise:
Set childDirection to the contained text auto directionality of child with canExcludeRoot set to true.
If childDirection is not null, then return childDirection.
Return null.
Return the contained text auto directionality of element with canExcludeRoot set to false.
To compute the contained text auto directionality of an element element with a boolean canExcludeRoot:
For each node descendant of element's descendants, in tree order:
If any of
is one of
bdi
elementscript
elementstyle
elementtextarea
elementdir
attribute is not in the undefined statethen continue.
If descendant is a slot
element whose root is a shadow root, then return the directionality of that shadow root's host.
Let result be the text node directionality of descendant.
If result is not null, then return result.
Return null.
To compute the text node directionality given a Text
node text:
If text's data does not contain a code point whose bidirectional character type is L, AL, or R, then return null. [BIDI]
Let codePoint be the first code point in text's data whose bidirectional character type is L, AL, or R.
If codePoint is of bidirectional character type AL or R, then return 'rtl'.
If codePoint is of bidirectional character type L, then return 'ltr'.
To compute the parent directionality given an element element:
Let parentNode be element's parent node.
If parentNode is a shadow root, then return the directionality of parentNode's host.
If parentNode is an element, then return the directionality of parentNode.
Return 'ltr'.
この要素は、双方向アルゴリズムに関わるレンダリング要件を持つ。
属性の文字列が何らかの方法でレンダリングに含まれる際に使用される、HTML要素の属性の方向は、下記リストからステップの最初の適切なセットに従って決定される:
dir
属性がauto状態である場合双方向性文字型L、AL、またはRのある属性値の最初の文字を(論理的な順序で)見つける。[BIDI]
以下の属性は方向可能属性である:
th
要素のabbr
area
、img
、input
要素のalt
name
属性が値に主に機械可読よりむしろ人間可読であることを意図するものを指定する場合、meta
要素のcontent
optgroup
、 option
、およびtrack
要素のlabel
input
およびtextarea
要素のplaceholder
title
document.dir [ = value ]
html
要素のdir
属性値を置換するために、"ltr
"、"rtl
"、"auto
"が設定可能である。
html
要素が存在しない場合、空文字列を返し新しい値を無視する。
Support in all current engines.
The dir
IDL attribute on an element must reflect the dir
content attribute of that element, limited to only known values.
Support in all current engines.
The dir
IDL attribute on Document
objects must reflect the dir
content attribute of the html
element, if any, limited to only known values. If there is no such element, then the attribute must return the empty string and do nothing on setting.
著者は、CSS不在(たとえば、検索エンジンによって解釈されるような)であっても正しく文書のレンダリングが継続するよう、CSSを使用するよりもテキストの方向を示すためのdir
属性を使用するよう強く推奨される。
次のマークアップ断片は、インスタントメッセージの会話である。
< p dir = auto class = "u1" >< b >< bdi > Student</ bdi > :</ b > How do you write "What's your name?" in Arabic?</ p >
< p dir = auto class = "u2" >< b >< bdi > Teacher</ bdi > :</ b > ما اسمك؟</ p >
< p dir = auto class = "u1" >< b >< bdi > Student</ bdi > :</ b > Thanks.</ p >
< p dir = auto class = "u2" >< b >< bdi > Teacher</ bdi > :</ b > That's written "شكرًا".</ p >
< p dir = auto class = "u2" >< b >< bdi > Teacher</ bdi > :</ b > Do you know how to write "Please"?</ p >
< p dir = auto class = "u1" >< b >< bdi > Student</ bdi > :</ b > "من فضلك", right?</ p >
適切なスタイルシートとp
要素へのデフォルトの配置スタイルを与えられる、すなわちテキストを段落の開始端へ揃えることで、結果として生じるレンダリングは以下のようになる:
前述したように、auto
値は万能薬ではない。この例の最後の段落は、アラビア文字で始まるので、右から左へのテキストであると誤って解釈されており、これは"right?"がアラビア語テキストの左側になる原因となる。
style
属性Support in all current engines.
すべてのHTML要素は、指定のstyle
コンテンツ属性をもってもよい。This is a style attribute as defined by CSS Style Attributes. [CSSATTR]
CSSをサポートするユーザーエージェントにおいて、属性が追加されるまたはその値が変更される際に、属性値は、スタイル属性に指定されたルールに従って、解析されなければならない。[CSSATTR]
しかし、属性のelementおよび"style attribute
"で実行される際にelementのインライン挙動はContent Security Policyによってブロックされるべきか?のアルゴリズムが"Blocked
"を返す場合、属性の値で定義されるスタイル規則は要素に適用されてはならない。[CSP]
要素のどこでもstyle
属性を使用する文書は、属性が削除された場合、それでも理解可能でありかつ使用可能でなければならない。
特に、コンテンツを非表示および表示するstyle
属性の使用、または他に文書に含まれない意味の伝達は不適合である。(コンテンツを非表示および表示するには、 属性を用いる。)
element.style
要素のstyle
属性へCSSStyleDeclaration
オブジェクトを返す。
The style
IDL attribute is defined in CSS Object Model. [CSSOM]
次の例で、色を参照する単語は、単語に視覚メディアで関連色を表すようspan
要素とstyle
属性を用いてマークアップされている。
< p > My sweat suit is < span style = "color: green; background:
transparent" > green</ span > and my eyes are < span style = "color: blue;
background: transparent" > blue</ span > .</ p >
data-*
属性をもつカスタム非視覚データの埋め込みSupport in all current engines.
カスタムデータ属性は、文字列"data-
"で始まる名前空間のない名前をもつ属性であり、ハイフンの後に少なくとも1文字を持ち、XML互換であり、ASCII大文字を含まない。
ASCII大文字での制約はそのような文書に影響しないので、HTML文書においてHTML要素のすべての属性名はASCII小文字を自動的に取得する。
カスタムデータ属性は、ページまたはアプリケーションへ私的なカスタムデータ、ステート、アノテーションなど類似のものを記憶することを意図する。これ以上適切な属性や要素は存在しない。
この属性は、属性を使用するサイトの管理者に知られないソフトウェアによる使用を意図しない。複数の独立したツールによって使用される一般的な拡張のために、この仕様は明示的に機能を提供するために拡張されるべきである、またはマイクロデータのような技術は(標準化された語彙で)使用されるべきかのいずれかである。
たとえば、音楽に関するサイトは、各トラックの長さを含むカスタムデータ属性でアルバム内のトラックを表すリスト項目に注釈を付けるかもしれない。その後この情報は、ユーザーがトラックの長さでリストをソートできるようにするため、または一定長さのトラックのリストをフィルターリングするために、サイト自体が使用するかもしれない。
< ol >
< li data-length = "2m11s" > Beyond The Sea</ li >
...
</ ol >
しかし、このデータを見ることで一定の長さの曲を検索するために、ユーザーがその音楽サイトに関連付けられていない一般的なソフトウェアを使用することは、不適当だろう。
これは、この属性がサイトの独自スクリプトによる使用を意図し、公開で利用可能なメタデータのための一般的な拡張メカニズムでないためである。
同様に、ページ著者は、使用しようとしている翻訳ツールに対して情報を提供するマークアップを書くことができる:
< p > The third < span data-mytrans-de = "Anspruch" > claim</ span > covers the case of < span
translate = "no" > HTML</ span > markup.</ p >
この例において、"data-mytrans-de
"属性は、フレーズ"claim"をドイツ語に翻訳する際に使用するためのMyTrans製品に特定のテキストを提供する。しかし、標準translate
属性はすべての言語で翻訳であることを伝えるために使用される。"HTML"は不変のままである。標準属性が使用可能である場合、使用されるカスタムデータ属性に対するニーズは存在しない。
この例において、カスタムデータ属性は、チェックアウトページの異なるスタイル付けをするためにCSSで使用できる、PaymentRequest
の機能検出の結果を格納するために使用される。
< script >
if ( 'PaymentRequest' in window) {
document. documentElement. dataset. hasPaymentRequest = '' ;
}
</ script >
ここでは、data-has-payment-request
属性は事実上 真偽属性として使用されている。属性の有無を確認するだけで十分である。しかし、著者が望む場合、後で何らかの値を持つことができる、制限された機能を示すかもしれない。
各HTML要素は任意の値とともに、任意の数の指定されたカスタムデータ属性を持ってもよい。
属性が無視され、かつ関連するすべてのCSSが破棄された場合、ページがそれでも使用可能であるよう、著者はこのような拡張を慎重に設計すべきである。
ユーザーエージェントは、これらの属性または値からいかなる実装の振る舞いも導出してはならない。ユーザーエージェントのために意図される仕様は、意味のある値を持つようにこれらの属性を定義してはならない。
JavaScriptライブラリーが使用されるページの一部であると考えられるとして、JavaScriptライブラリーはカスタムデータ属性を使用してもよい。多くの著者によって再利用されるライブラリーの著者は、衝突のリスクを軽減するために、属性名にライブラリーの名前を含むよう推奨される。理にかなっている場合には、著者が無意識のうちに同じ名前を選んだライブラリーが同じページ上で使用できるように、そしてバージョンの相互の互換性がない場合でも、特定ライブラリーの複数のバージョンが同じページ上で使用できるように、ライブラリー著者はまた、正確な名前がカスタマイズ可能な属性名に使用されることを推奨される。
たとえば、"DoQuery"と呼ばれるライブラリーはdata-doquery-range
のような属性名を使用するかもしれないし、"jJo"と呼ばれるライブラリーはdata-jjo-range
のような属性名を使用するかもしれない。jJoライブラリーはまた、APIに接頭辞の使用の設定を供給するかもしれない(たとえばJ.setDataPrefix('j2')
が、data-j2-range
のような名前を持つようにする)。
element.dataset
Support in all current engines.
Support in all current engines.
要素のdata-*
属性に対してDOMStringMap
オブジェクトを返す。
ハイフン付き名前はキャメルケースになる。たとえば、data-foo-bar=""
はelement.dataset.fooBar
になる。
dataset
IDL属性は、要素のすべてのdata-*
属性に対する便利なアクセス機構を提供する。On getting, the dataset
IDL attribute must return a DOMStringMap
whose associated element is this element.
The DOMStringMap
interface is used for the dataset
attribute. Each DOMStringMap
has an associated element.
[Exposed =Window ,
LegacyOverrideBuiltIns ]
interface DOMStringMap {
getter DOMString (DOMString name );
[CEReactions ] setter undefined (DOMString name , DOMString value );
[CEReactions ] deleter undefined (DOMString name );
};
To get a DOMStringMap
's name-value pairs, run the following algorithm:
listを名前-値のペアの空のリストにする。
For each content attribute on the DOMStringMap
's associated element whose first five characters are the string "data-
" and whose remaining characters (if any) do not include any ASCII upper alphas, in the order that those attributes are listed in the element's attribute list, add a name-value pair to list whose name is the attribute's name with the first five characters removed and whose value is the attribute's value.
For each name in list, for each U+002D HYPHEN-MINUS character (-) in the name that is followed by an ASCII lower alpha, remove the U+002D HYPHEN-MINUS character (-) and replace the character that followed it by the same character converted to ASCII uppercase.
listを返す。
The supported property names on a DOMStringMap
object at any instant are the names of each pair returned from getting the DOMStringMap
's name-value pairs at that instant, in the order returned.
To determine the value of a named property name for a DOMStringMap
, return the value component of the name-value pair whose name component is name in the list returned from getting the DOMStringMap
's name-value pairs.
To set the value of a new named property or set the value of an existing named property for a DOMStringMap
, given a property name name and a new value value, run the following steps:
If name contains a U+002D HYPHEN-MINUS character (-) followed by an ASCII lower alpha, then throw a "SyntaxError
" DOMException
.
For each ASCII upper alpha in name, insert a U+002D HYPHEN-MINUS character (-) before the character and replace the character with the same character converted to ASCII lowercase.
nameの先頭に文字列data-
を挿入する。
If name does not match the XML Name
production, throw an "InvalidCharacterError
" DOMException
.
Set an attribute value for the DOMStringMap
's associated element using name and value.
To delete an existing named property name for a DOMStringMap
, run the following steps:
For each ASCII upper alpha in name, insert a U+002D HYPHEN-MINUS character (-) before the character and replace the character with the same character converted to ASCII lowercase.
nameの先頭に文字列data-
を挿入する。
Remove an attribute by name given name and the DOMStringMap
's associated element.
This algorithm will only get invoked by Web IDL for names that are given by the earlier algorithm for getting the DOMStringMap
's name-value pairs. [WEBIDL]
If a web page wanted an element to represent a space ship, e.g. as part of a game, it would have to use the class
attribute along with data-*
attributes:
< div class = "spaceship" data-ship-id = "92432"
data-weapons = "laser 2" data-shields = "50%"
data- x = "30" data-y = "10" data-z = "90" >
< button class = "fire"
onclick = "spaceships[this.parentNode.dataset.shipId].fire()" >
Fire
</ button >
</ div >
APIにおいてハイフン付き属性名は、キャメルケースになることに注目すること。
類似の構造とともに以下の引数および要素が与えられるとする:
< img class = "tower" id = "tower5" data- x = "12" data-y = "5"
data-ai = "robotarget" data-hp = "46" data-ability = "flames"
src = "towers/rocket.png" alt = "Rocket Tower" >
1つは関数splashDamage()
がいくつかの引数を取ることが考えられ、第1引数は処理する要素となる:
function splashDamage( node, x, y, damage) {
if ( node. classList. contains( 'tower' ) && // checking the 'class' attribute
node. dataset. x == x && // reading the 'data-x' attribute
node. dataset. y == y) { // reading the 'data-y' attribute
var hp = parseInt( node. dataset. hp); // reading the 'data-hp' attribute
hp = hp - damage;
if ( hp < 0 ) {
hp = 0 ;
node. dataset. ai = 'dead' ; // setting the 'data-ai' attribute
delete node. dataset. ability; // removing the 'data-ability' attribute
}
node. dataset. hp = hp; // setting the 'data-hp' attribute
}
}
innerText
およびouterText
プロパティSupport in all current engines.
element.innerText [ = value ]
"レンダリングの通りに"要素のテキストコンテンツ返す。
指定された値をもつのでなく、br
に変換された改行をもつ要素の子に置換するために、設定することができる。
element.outerText [ = value ]
"レンダリングの通りに"要素のテキストコンテンツ返す。
Can be set, to replace the element with the given value, but with line breaks converted to br
elements.
The get the text steps, given an HTMLElement element, are:
If element is not being rendered or if the user agent is a non-CSS user agent, then return element's descendant text content.
This step can produce surprising results, as when the innerText
getter is invoked on an element not being rendered, its text contents are returned, but when accessed on an element that is being rendered, all of its children that are not being rendered have their text contents ignored.
Let results be a new empty list.
For each child node node of element:
Let current be the list resulting in running the rendered text collection steps with node. Each item in results will either be a string or a positive integer (a required line break count).
Intuitively, a required line break count item means that a certain number of line breaks appear at that point, but they can be collapsed with the line breaks induced by adjacent required line break count items, reminiscent to CSS margin-collapsing.
For each item item in current, append item to results.
Remove any items from results that are the empty string.
Remove any runs of consecutive required line break count items at the start or end of results.
Replace each remaining run of consecutive required line break count items with a string consisting of as many U+000A LF code points as the maximum of the values in the required line break count items.
Return the concatenation of the string items in results.
Support in all current engines.
The innerText
and outerText
getter steps are to return the result of running get the text steps with this.
The rendered text collection steps, given a node node, are as follows:
Let items be the result of running the rendered text collection steps with each child node of node in tree order, and then concatenating the results to a single list.
If node's computed value of 'visibility' is not 'visible', then return items.
If node is not being rendered, then return items. For the purpose of this step, the following elements must act as described if the computed value of the 'display' property is not 'none':
select
elements have an associated non-replaced inline CSS box whose child boxes include only those of optgroup
and option
element child nodes;
optgroup
elements have an associated non-replaced block-level CSS box whose child boxes include only those of option
element child nodes; and
option
element have an associated non-replaced block-level CSS box whose child boxes are as normal for non-replaced block-level CSS boxes.
items can be non-empty due to 'display:contents'.
If node is a Text
node, then for each CSS text box produced by node, in content order, compute the text of the box after application of the CSS 'white-space' processing rules and 'text-transform' rules, set items to the list of the resulting strings, and return items. The CSS 'white-space' processing rules are slightly modified: collapsible spaces at the end of lines are always collapsed, but they are only removed if the line is the last line of the block, or it ends with a br
element. Soft hyphens should be preserved. [CSSTEXT]
If node is a br
element, then append a string containing a single U+000A LF code point to items.
If node's computed value of 'display' is 'table-cell', and node's CSS box is not the last 'table-cell' box of its enclosing 'table-row' box, then append a string containing a single U+0009 TAB code point to items.
If node's computed value of 'display' is 'table-row', and node's CSS box is not the last 'table-row' box of the nearest ancestor 'table' box, then append a string containing a single U+000A LF code point to items.
If node is a p
element, then append 2 (a required line break count) at the beginning and end of items.
If node's used value of 'display' is block-level or 'table-caption', then append 1 (a required line break count) at the beginning and end of items. [CSSDISPLAY]
Floats and absolutely-positioned elements fall into this category.
Return items.
Note that descendant nodes of most replaced elements (e.g., textarea
, input
, and video
— but not button
) are not rendered by CSS, strictly speaking, and therefore have no CSS boxes for the purposes of this algorithm.
This algorithm is amenable to being generalized to work on ranges. Then we can use it as the basis for Selection
's stringifier and maybe expose it directly on ranges. See Bugzilla bug 10583.
The set the inner text steps, given an HTMLElement element, and a string value are:
Let fragment be the rendered text fragment for value given element's node document.
Replace all with fragment within element.
The innerText
setter steps are to run set the inner text steps.
The outerText
setter steps are:
If this's parent is null, then throw a "NoModificationAllowedError
" DOMException
.
Let next be this's next sibling.
Let previous be this's previous sibling.
Let fragment be the rendered text fragment for the given value given this's node document.
If fragment has no children, then append a new Text
node whose data is the empty string and node document is this's node document to fragment.
If next is non-null and next's previous sibling is a Text
node, then merge with the next text node given next's previous sibling.
If previous is a Text
node, then merge with the next text node given previous.
The rendered text fragment for a string input given a Document
document is the result of running the following steps:
Let fragment be a new DocumentFragment
whose node document is document.
Let position be a position variable for input, initially pointing at the start of input.
Let text be the empty string.
While position is not past the end of input:
Collect a sequence of code points that are not U+000A LF or U+000D CR from input given position, and set text to the result.
If text is not the empty string, then append a new Text
node whose data is text and node document is document to fragment.
While position is not past the end of input, and the code point at position is either U+000A LF or U+000D CR:
If the code point at position is U+000D CR and the next code point is U+000A LF, then advance position to the next code point in input.
Advance position to the next code point in input.
Append the result of creating an element given document, br
, and the HTML namespace to fragment.
Return fragment.
To merge with the next text node given a Text
node node:
Let next be node's next sibling.
If next is not a Text
node, then return.
Replace data with node, node's data's length, 0, and next's data.
Remove next.
HTML要素のコンテンツでText
ノードをもつHTML要素におけるテキストコンテンツ、および自由形式のテキストを許可するHTML要素の属性のテキストは、U+202AからU+202Eまでの範囲(双方向アルゴリズムの書式設定文字)の文字を含んでもよい。[BIDI]
著者は、手動で双方向アルゴリズムの書式設定文字を維持するよりもむしろ、dir
属性、bdo
要素、およびbdi
要素を使用するよう推奨される。双方向アルゴリズムの書式設定文字は、CSSと互いに不完全に影響しあう。
User agents must implement the Unicode bidirectional algorithm to determine the proper ordering of characters when rendering documents and parts of documents. [BIDI]
The mapping of HTML to the Unicode bidirectional algorithm must be done in one of three ways. Either the user agent must implement CSS, including in particular the CSS 'unicode-bidi', 'direction', and 'content' properties, and must have, in its user agent style sheet, the rules using those properties given in this specification's rendering section, or, alternatively, the user agent must act as if it implemented just the aforementioned properties and had a user agent style sheet that included all the aforementioned rules, but without letting style sheets specified in documents override them, or, alternatively, the user agent must implement another styling language with equivalent semantics. [CSSGC]
The following elements and attributes have requirements defined by the rendering section that, due to the requirements in this section, are requirements on all user agents (not just those that support the suggested default rendering):
User agent requirements for implementing Accessibility API semantics on HTML elements are defined in HTML Accessibility API Mappings. In addition to the rules there, for a custom element element, the default ARIA role semantics are determined as follows: [HTMLAAM]
Let map be element's internal content attribute map.
If map["role
"] exists, then return it.
Return no role.
Similarly, for a custom element element, the default ARIA state and property semantics, for a state or property named stateOrProperty, are determined as follows:
If element's attached internals is non-null:
If element's attached internals's get the stateOrProperty-associated element exists, then return the result of running it.
If element's attached internals's get the stateOrProperty-associated elements exists, then return the result of running it.
If element's internal content attribute map[stateOrProperty] exists, then return it.
Return the default value for stateOrProperty.
The "default semantics" referred to here are sometimes also called "native", "implicit", or "host language" semantics in ARIA. [ARIA]
One implication of these definitions is that the default semantics can change over time. This allows custom elements the same expressivity as built-in elements; e.g., compare to how the default ARIA role semantics of an a
element change as the href
attribute is added or removed.
For an example of this in action, see the custom elements section.
Conformance checker requirements for checking use of ARIA role
and aria-*
attributes on HTML elements are defined in ARIA in HTML. [ARIAHTML]