1. 基盤
この仕様は Infra Standard [INFRA] に依存する。 This specification depends on the Infra Standard. [INFRA]
この仕様の一部の用語は、 次に挙げる仕様にて定義される :[ENCODING], [SELECTORS4], [WEBIDL], [XML], [XML-NAMES] Some of the terms used in this specification are defined in Encoding, Selectors, Web IDL, XML, and Namespaces in XML. [ENCODING] [SELECTORS4] [WEBIDL] [XML] [XML-NAMES]
拡張が必要になったときは、 それに則って DOM 標準が更新されるか,あるいは 適用可能な仕様† 用に供される拡張用フックを利用するような,新たな標準が書かれ得る。 When extensions are needed, the DOM Standard can be updated accordingly, or a new standard can be written that hooks into the provided extensibility hooks for applicable specifications.
【† [HTML] に定義される同じ名前の用語と同様 — この仕様自身も含まれる。 】
【この訳に特有な表記規約】
この訳において(主にアルゴリズム内で)利用される各種記号( ε, ← , IF, THROW, 等々)の意味や定義の詳細は、共通な慣用表現, アルゴリズムに共通して利用される表記を参照されたし。
加えて,次に挙げる表記も利用される:
1.1. ツリー
ツリー とは、 有限かつ階層的なツリー構造である。 ツリー順序 は、 深さ優先かつ前順による辿りに基づく。 A tree is a finite hierarchical tree structure. In tree order is preorder, depth-first traversal of a tree.
【 深さ優先, 前順 】: この方式によるツリーの辿りは、 HTML や XML 文書のソーステキスト表現における,要素の開始タグやテキスト内容 (より一般には文字データノード) が現れる順序を表現する (ゆえに, “文書順序” と称されることもある)。
例えば、
次のソース
(単純にするため,(架空の) e
要素とテキスト内容のみからなる)
から生成される DOM ツリーは:
<e><e></e>ソースに<e>現れる<e>順序が</e><e>そのまま<e>ツリー順序に</e></e>なる</e></e>
次のような模式図として可視化できる:
図の左端がソースの先頭, 右端が末尾に対応する。 図の横線が,ツリーの中の各ノードとそれがソース内を占める範囲 (要素の開始タグ〜終了タグ / 文字データの先頭〜末尾) を表し、 それらの上下関係がツリーの階層(ノードの入れ子階層)を表す。 図の中の各文字は文字データの各文字に対応し,それらが成す各赤色区間が文字データノードが占める範囲を表す。 ノードの順序はこれらの横線の左端の位置から決定される。 最上層の横線がこのツリーの根ノード(根元)を表し,この順序における先頭になる。
ツリーに 関与 ( participate )している各オブジェクトは、 次に挙げるものを有する: An object that participates in a tree\
- 親 ( parent ) : null / あるオブジェクト has a parent, which is either null or an object,\
- 子群 ( children ) :オブジェクトたちが成す有順序集合 and has children, which is an ordered set of objects.\
オブジェクト A の親 B ≠ null ならば、 A は B の子である。 An object A whose parent is object B is a child of B.
【 A は B の “子である” という句は、[ A ∈ B の子群 ]を満たすことをいう。 】【 B には “子が在る” のような句は、[ B の子群は空でない ]ことをいう。 】【 同じオブジェクトが同時に複数のオブジェクトの子になることはない。 】
オブジェクト A の 根 ( root )とは、[ A の親 = null ]ならば A であり,他の場合は A の親の根である。 ツリーの根は、 そのツリーに関与しているオブジェクトであって,[ 親 = null ]を満たすものである。 The root of an object is itself, if its parent is null, or else it is the root of its parent. The root of a tree is any object participating in that tree whose parent is null.
【 この定義は、 親を順々に辿った結果は循環しない(自身には戻らない)ことも含意している。 同様に,子を順々に辿った結果も循環しない。 】
オブジェクト A がオブジェクト B の 子孫 ( descendant )であるとは、 次が満たされることをいう :[ A は B の子である ]∨[ A は B のある子孫の子である ] An object A is called a descendant of an object B, if either A is a child of B or A is a child of an object C that is a descendant of B.
【 上述したように循環しないので、 A 自身が A の子孫になることはない。 】
オブジェクト A がオブジェクト B の 広義子孫 ( inclusive descendant )であるとは、 次が満たされることをいう :[ A = B ]∨[ A は B の子孫である ] An inclusive descendant is an object or one of its descendants.
【 “広義” という対訳は,よいとは言えないが、 より忠実に “自身も含めた子孫” などと訳すのでは,用語として定義する意義 — 他から簡潔に参照できるようにする — も失われる(単に “自身または子孫” と記すのと同じことになる)。 】
オブジェクト A がオブジェクト B の 先祖 ( ancestor )であるとは、 次が満たされることをいう :B は A の子孫である An object A is called an ancestor of an object B if and only if B is a descendant of A.
オブジェクト A がオブジェクト B の 広義先祖 ( inclusive ancestor )であるとは、 次が満たされることをいう :[ A = B ]∨[ A は B の先祖である ] An inclusive ancestor is an object or one of its ancestors.
オブジェクト A がオブジェクト B の 同胞 ( sibling )であるとは、 次が満たされることをいう :[ A の親 ≠ null ]∧[ A の親 = B の親 ] An object A is called a sibling of an object B, if and only if B and A share the same non-null parent.
【 定義により, A 自身も 親が null でないならば A の同胞になる。 この仕様の中では、 この点について特に注意を要する箇所は(現時点では)ないが。 例えば、 この同胞の定義を “A と B は同じでない” と解釈したとしても,この仕様の残りの部分には影響しない。 】【 “兄弟” と訳されることが多いが、 対訳として “同胞” を選んだ理由は,包括的(中立的)な文言が選好されるからである。 】
オブジェクト A がオブジェクト B の 広義同胞 ( inclusive sibling )であるとは、 次が満たされることをいう :[ A = B ]∨[ A は B の同胞である ] An inclusive sibling is an object or one of its siblings.
【 A 自身は,親が null であっても A の広義同胞になる点で、 同胞の定義と異なる。 この定義は、 もっぱら他の仕様用にあり,この仕様内では利用されない。 】
オブジェクト A がオブジェクト B に 先行 ( precede )するとは、 次が満たされることをいう :[ A と B は同じツリーに関与する ]∧[ ツリー順序において A は B より前に在る ] An object A is preceding an object B if A and B are in the same tree and A comes before B in tree order.
オブジェクト A がオブジェクト B に 後続 ( follow )するとは、 次が満たされることをいう :[ A と B は同じツリーに関与する ]∧[ ツリー順序において A は B より後に在る ] An object A is following an object B if A and B are in the same tree and A comes after B in tree order.
オブジェクト A の 最初の子? ( first child )とは、 A の子のうち,最初のもの?である。 The first child of an object is its first child or null if it has no children.
オブジェクト A の 最後の子? ( last child )とは、 A の子のうち,最後のもの?である。 The last child of an object is its last child or null if it has no children.
オブジェクト A の 直前の同胞? ( previous sibling )とは、 A に先行する同胞のうち,最後のもの?である。 The previous sibling of an object is its first preceding sibling or null if it has no preceding sibling.
オブジェクト A の 直後の同胞? ( next sibling )とは、 A に後続する同胞のうち,最初のもの?である。 The next sibling of an object is its first following sibling or null if it has no following sibling.
オブジェクト A の index とは、 A に先行する同胞の個数である(なければ 0 になる)。 The index of an object is its number of preceding siblings, or 0 if it has none.
【 A の親 ≠ null ならば、[ A = A の親の子群[ A の index ] ]が満たされることになる。 】
1.2. 有順序集合
有順序集合として構文解析する ときは、 所与の ( 文字列 入力 ) に対し,次を走らす: The ordered set parser takes a string input and then runs these steps:
- 入力トークン群 :← ASCII 空白で分割する( 入力 ) Let inputTokens be the result of splitting input on ASCII whitespace.
- トークン群 :← 新たな有順序集合 Let tokens be a new ordered set.
- 入力トークン群 を成す 各( トークン ) に対し :トークン群 に トークン を付加する For each token in inputTokens, append token to tokens.
- RETURN トークン群 Return tokens.
1.3. 選択子
ノード の 視野の下で選択子を照合する ときは、 所与の ( 文字列 選択子 ) に対し,次を走らす: To scope-match a selectors string selectors against a node, run these steps:
- S :← 選択子として構文解析する( 選択子 ) [SELECTORS4] Let s be the result of parse a selector selectors. [SELECTORS4]
-
IF[
S = 失敗
]
:THROW
SyntaxError
If s is failure, then throw a "SyntaxError" DOMException. - RETURN ツリーに対し選択子を照合する( 選択子 S, 根要素たちが成す集合 { ノード の根 }, 視野根たちが成す集合 { ノード } ) [SELECTORS4] Return the result of match a selector against a tree with s and node’s root using scoping root node. [SELECTORS4].
注記: 選択子の中の名前空間用のサポートは、 計画されておらず,追加されることはない。 Support for namespaces within selectors is not planned and will not be added.
1.4. 名前空間
有修飾名として検証する
ときは、
所与の
( 名前 )
に対し,次を走らす
:IF[
名前 は QName
生成規則に合致しない
]
:THROW InvalidCharacterError
To validate a qualifiedName, throw an "InvalidCharacterError" DOMException if qualifiedName does not match the QName production.
検証して抽出する ときは、 所与の ( 名前空間, 名前 ) に対し,次を走らす: To validate and extract a namespace and qualifiedName, run these steps:
- IF[ 名前空間 = 空文字列 ] :名前空間 ← null If namespace is the empty string, then set it to null.
- 有修飾名として検証する( 名前 ) Validate qualifiedName.
- 接頭辞 :← null Let prefix be null.
- 局所名 :← 名前 Let localName be qualifiedName.
-
IF[ 名前 は U+003A (:) を包含する ]: If qualifiedName contains a U+003A (:):
- 分割結果 :← 区切子で厳密に分割する( 名前, U+003A (:) ) Let splitResult be the result of running strictly split given qualifiedName and U+003A (:).
-
Assert:
分割結果 のサイズ = 2
— 名前 は、
PrefixedName
生成規則に合致し, U+003A (:) を 1 個しか包含しないので。 【この段は、この訳による補完。】 - 接頭辞 ← 分割結果[ 0 ] Set prefix to splitResult[0].
- 局所名 ← 分割結果[ 1 ] Set localName to splitResult[1].
-
IF[ ∨↓ ]… ↓
- [ 名前空間 = null ]∧[ 接頭辞 ≠ null ] If prefix is non-null and namespace is null, then throw a "NamespaceError" DOMException.
-
[
名前空間 ≠ XML 名前空間
]∧[
接頭辞 = "
xml
" ] If prefix is "xml" and namespace is not the XML namespace, then throw a "NamespaceError" DOMException. -
[
名前空間 ≠ XMLNS 名前空間
]∧[[
名前 = "
xmlns
" ]∨[ 接頭辞 = "xmlns
" ]] If either qualifiedName or prefix is "xmlns" and namespace is not the XMLNS namespace, then throw a "NamespaceError" DOMException. -
[
名前空間 = XMLNS 名前空間
]∧[
名前 ≠ "
xmlns
" ]∧[ 接頭辞 ≠ "xmlns
" ] If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "xmlns", then throw a "NamespaceError" DOMException.
…ならば :THROW
NamespaceError
↑ - RETURN ( 名前空間, 接頭辞, 局所名 ) Return namespace, prefix, and localName.
2. イベント
2.1. “DOM Events” 序論
web プラットフォームを全体を通して、
イベントは
— 何かが生じたことを通達するために —
オブジェクトに向けて配送される
— ネットワーク活動や利用者によるやりとりなど。
これらのオブジェクトは EventTarget
インタフェースを実装し,
その addEventListener()
を call することにより
イベントを観測するためのイベントリスナを追加できる:
Throughout the web platform events are dispatched to objects to signal an occurrence, such as network activity or user interaction. These objects implement the EventTarget interface and can therefore add event listeners to observe events by calling addEventListener():
obj.addEventListener("load", imgFetched)
function imgFetched(ev) {
/*
成功裡に load できた
great success */
…
}
イベントリスナは、 次のいずれかにより除去できる: ↓
-
removeEventListener()
メソッドにaddEventListener()
と同じ引数たちを渡すことにより。 Event listeners can be removed by utilizing the removeEventListener() method, passing the same arguments. -
addEventListener()
に[ あるAbortController
controller の通達 ]を渡して, controller のabort()
を call することにより。 Alternatively, event listeners can be removed by passing an AbortSignal to addEventListener() and calling abort() on the controller owning the signal.
イベントもまたオブジェクトであり,
Event
インタフェース(またはその派生インタフェース)を実装する。
上の例では、
ev がイベントである。
ev は、
イベントリスナの callback
(概して上に示したような JavaScript Function )
に引数として渡される。
イベントリスナは、
まず,イベントの type
属性値(上の例では "load
" )をその制御に利用する。
イベントの target
属性値はイベントの配送先のオブジェクト(上の例の obj )を返す。
Events are objects too and implement the Event interface (or a derived interface). In the example above ev is the event. ev is passed as an argument to the event listener’s callback (typically a JavaScript Function as shown above). Event listeners key off the event’s type attribute value ("load" in the above example). The event’s target attribute value returns the object to which the event was dispatched (obj above).
イベントは、 概して,利用者によるやりとりや何らかのタスク完了の結果,UA により配送されるが、 アプリ自身も,合成なイベントとよく称されるものを利用してイベントを配送できる: Although events are typically dispatched by the user agent as the result of user interaction or the completion of some task, applications can dispatch events themselves by using what are commonly known as synthetic events:
/* カスタムイベントリスナを追加する add an appropriate event listener */ obj.addEventListener("cat", function(e) { process(e.detail) }) /* イベントを作成して配送する create and dispatch the event */ var event = new CustomEvent("cat", {"detail":{"hazcheeseburger":true}}) obj.dispatchEvent(event)
通達時の他にも、
イベントは,演算の中で次に起きる出来事をアプリに制御させる目的で利用されることがある。
例えば,フォーム提出の一環として、
type
属性が "submit
" にされたイベントが配送される。
このイベントの preventDefault()
メソッドが呼び出されると,フォームは提出されずに終了されることになる。
アプリにより配送されるイベント(合成なイベント)を通して,この機能性を利用する場合、
dispatchEvent()
メソッドの返り値も利用できる:
Apart from signaling, events are sometimes also used to let an application control what happens next in an operation. For instance as part of form submission an event whose type attribute value is "submit" is dispatched. If this event’s preventDefault() method is invoked, form submission will be terminated. Applications who wish to make use of this functionality through events dispatched by the application (synthetic events) can make use of the return value of the dispatchEvent() method:
if(obj.dispatchEvent(event)) {
/*
イベントは取り消されなかった。手品の時間だ。
event was not canceled, time for some magic */
…
}
イベントがツリーに関与しているオブジェクト(例えば要素)に向けて配送される場合、 そのイベントは,そのオブジェクトの先祖のイベントリスナにも到達し得る: When an event is dispatched to an object that participates in a tree (e.g., an element), it can reach event listeners on that object’s ancestors too.\
- まず、 オブジェクトの各 広義先祖に対し,ツリー順序で :そのイベントリスナ†のうち[ 捕捉するか = true ]を満たすものが呼び出される Effectively, all the object’s inclusive ancestor event listeners whose capture is true are invoked, in tree order.\
-
次に,[
イベントの
bubbles
= true ]ならば、 オブジェクトの各 広義先祖に対し,今度はツリー順序の逆順で :そのイベントリスナ†のうち[ 捕捉するか = false ]を満たすものが呼び出される And then, if event’s bubbles is true, all the object’s inclusive ancestor event listeners whose capture is false are invoked, now in reverse tree order.
【†
当の広義先祖のイベントリスナリスト内のイベントリスナのうち,その型は イベントの type
に合致するもの。
該当するイベントリスナが呼び出される順序は、
このリストが管理する。
】
イベントがツリー内で働く様子を例で示す: Let’s look at an example of how events work in a tree:
<!doctype html> <html> <head> <title>つまらない例</title> </head> <body> <p>Hello <span id=x>world</span>!</p> <script> function test(e) { debug(e.target, e.currentTarget, e.eventPhase); // A } document.addEventListener("hey", test, {capture: true}); // B document.body.addEventListener("hey", test); // C var ev = new Event("hey", {bubbles:true}) document.getElementById("x").dispatchEvent(ev); </script> </body> </html>
debug
関数( A )は 2 回呼び出されることになる。
2 回とも、
イベントの target
属性値は span
要素 になる。
1 回目での currentTarget
属性値は文書になり( B ),
eventPhase
属性の値が CAPTURING_PHASE
から BUBBLING_PHASE
に切り替わった後,
2 回目では body
要素になる( C )。
もしイベントリスナが span
要素にも登録されていたなら、
eventPhase
属性の値は AT_TARGET
にも切り替わることになる。
The debug function will be invoked twice. Each time the event’s target attribute value will be the span element. The first time currentTarget attribute’s value will be the document, the second time the body element. eventPhase attribute’s value switches from CAPTURING_PHASE to BUBBLING_PHASE. If an event listener was registered for the span element, eventPhase attribute’s value would have been AT_TARGET.
2.2. Event
インタフェース
[Exposed=*]
interface Event {
constructor(DOMString type, optional EventInit eventInitDict = {});
readonly attribute DOMString type;
readonly attribute EventTarget? target;
readonly attribute EventTarget? srcElement; // 旧来
readonly attribute EventTarget? currentTarget;
sequence<EventTarget> composedPath();
const unsigned short NONE = 0;
const unsigned short CAPTURING_PHASE = 1;
const unsigned short AT_TARGET = 2;
const unsigned short BUBBLING_PHASE = 3;
readonly attribute unsigned short eventPhase;
undefined stopPropagation();
attribute boolean cancelBubble; // stopPropagation()
の旧来の別名
undefined stopImmediatePropagation();
readonly attribute boolean bubbles;
readonly attribute boolean cancelable;
attribute boolean returnValue; // 旧来
undefined preventDefault();
readonly attribute boolean defaultPrevented;
readonly attribute boolean composed;
[LegacyUnforgeable] readonly attribute boolean isTrusted;
readonly attribute DOMHighResTimeStamp timeStamp;
undefined initEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false); // 旧来
};
dictionary EventInit {
boolean bubbles = false;
boolean cancelable = false;
boolean composed = false;
};
Event
オブジェクトは、
単に
イベント
とも称される。
それは、
何かが生じたとき,それを通達できるようにする
— 例えば、
画像のダウンロードが完了したときなど。
An Event object is simply named an event. It allows for signaling that something has occurred, e.g., that an image has completed downloading.
イベントターゲットになり得るもの
は、[
null / EventTarget
オブジェクト
]である。
A potential event target is null or an EventTarget object.
各イベントには、 次に挙げるものが結び付けられる: ↓
- ターゲット :イベントターゲットになり得るもの — 他が言明されない限り, null とする。 An event has an associated target (a potential event target). Unless stated otherwise it is null.
-
関係するターゲット :イベントターゲットになり得るもの — 他が言明されない限り, null とする。 An event has an associated relatedTarget (a potential event target). Unless stated otherwise it is null.
注記: 他の仕様は
relatedTarget
属性を定義するときに 関係するターゲットを利用する。 [UIEVENTS] Other specifications use relatedTarget to define a relatedTarget attribute. [UIEVENTS] -
touch ターゲットリスト :イベントターゲットになり得るものたちが成すリスト — 他が言明されない限り,空とする。 An event has an associated touch target list (a list of zero or more potential event targets). Unless stated otherwise it is the empty list.
注記: touch ターゲットリストは、 もっぱら
TouchEvent
インタフェースとそれに関係するインタフェースを定義するために利用される。 [TOUCH-EVENTS] The touch target list is for the exclusive use of defining the TouchEvent interface and related interfaces. [TOUCH-EVENTS] -
経路を成す各アイテムは、 次に挙げるものからなる構造体である:
-
呼び出しターゲット
:
EventTarget
オブジェクト - 呼び出しターゲットは shadow ツリー内か :真偽値
- shadow 調整済みターゲット :イベントターゲットになり得るもの
- 関係するターゲット :イベントターゲットになり得るもの
- touch ターゲットリスト :イベントターゲットになり得るものたちが成すリスト
- 閉じたツリーの根か :真偽値
- slot は閉じたツリー内か :真偽値
-
呼び出しターゲット
:
- event =
new Event(type [, eventInitDict])
-
type
属性値が type にされた,新たな event を返す。 eventInitDict 引数により,[bubbles
/cancelable
]属性も — 同じ名前のオブジェクトメンバを介して — 設定できる。 Returns a new event whose type attribute value is set to type. The eventInitDict argument allows for setting the bubbles and cancelable attributes via object members of the same name. - event .
type
-
event の型を返す。
例えば
"
click
", "hashchange
", "submit
" など。 Returns the type of event, e.g. "click", "hashchange", or "submit". - event .
target
- event の配送先のオブジェクト( event のターゲット )を返す。 Returns the object to which event is dispatched (its target).
- event .
currentTarget
- 現在呼び出されている callback を有するイベントリスナが登録されているオブジェクトを返す。 Returns the object whose event listener’s callback is currently being invoked.
- event .
composedPath()
-
event の経路内に在る呼び出しターゲット(それ上でリスナが呼び出されるオブジェクト)たちが成すリストを返す
— ただし、[
shadow 根のモード = "
closed
" ]なる shadow ツリー内のノードであって, event のcurrentTarget
からは到達できないものは、 返り値から除かれる。 Returns the invocation target objects of event’s path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root’s mode is "closed" that are not reachable from event’s currentTarget. - event .
eventPhase
-
イベントの相
— 次のいずれかを返す
:
NONE
,CAPTURING_PHASE
,AT_TARGET
,BUBBLING_PHASE
Returns the event’s phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE. - event .
stopPropagation()
- ツリー 内に配送されているとき、 このメソッドを呼び出すことにより,現在のオブジェクト以外のオブジェクトには event が到達しないようになる。 When dispatched in a tree, invoking this method prevents event from reaching any objects other than the current object.
- event .
stopImmediatePropagation()
- このメソッドを呼び出すことにより、 event は 現在のリスナを走り終えた後に[ それまでに登録されたイベントリスナ ]には到達しなくなり、 ツリー 内に配送されたときには, event は他のどのオブジェクトにも到達しなくなる。 Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects.
- event .
bubbles
- event がどう初期化されたかに応じて,true か false を返す。 event がそのターゲットの先祖へツリー順序の逆順にも遡る場合は true を返す/ 他の場合は false を返す。 Returns true or false depending on how event was initialized. True if event goes through its target’s ancestors in reverse tree order; otherwise false.
- event .
cancelable
-
event がどう初期化されたかに応じて,true か false を返す。
その返り値は常に意味を運ぶとは限らないが、
true の場合,[
event が配送されている間の演算
]は[
preventDefault()
メソッドを呼び出すことにより取り消せる ]ことを指示し得る。 Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method. - event .
preventDefault()
-
event の
cancelable
属性値が true にされた下で,[passive
が false に設定された event ]用のリスナの実行中に呼び出された場合、 event が取り消される必要がある旨をその配送 演算に通達する。 If invoked when the cancelable attribute value is true, and while executing a listener for the event with passive set to false, signals to the operation that caused event to be dispatched that it needs to be canceled. - event .
defaultPrevented
-
true は、
preventDefault()
が呼び出され, 成功裡に取り消されたことを指示する。 他の場合は false を返す。 Returns true if preventDefault() was invoked successfully to indicate cancelation; otherwise false. - event .
composed
-
event がどう初期化されたかに依存して[
true / false
]を返す。
[
event のターゲットの根が
ShadowRoot
ノードである ]ときに,[ そのノードを過ぎた先†に在るリスナも呼び出す場合は true / 他の場合は false ]になる。 Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target; otherwise false. - 【† イベント の経路が、 shadow 根のホストを通して別のノードツリーへつながるように,構成される。 】
- event .
isTrusted
- event は UA から配送されたもの[ であるならば true / でないならば false ]を返す。 Returns true if event was dispatched by the user agent, and false otherwise.
- event .
timeStamp
- event の時刻印を[ the occurrence 【時刻起点】から相対的に測定したミリ秒数 ]として返す。 Returns the event’s timestamp as the number of milliseconds measured relative to the occurrence.
type
取得子手続きは、
初期化時の値を返す。
イベントの作成時には、
この属性は空文字列に初期化するものとする。
The type attribute must return the value it was initialized to. When an event is created the attribute must be initialized to the empty string.
currentTarget
取得子手続きは、
初期化時の値を返す。
The currentTarget attribute must return the value it was initialized to.\
イベントの作成時には、 この属性は null に初期化するものとする。 When an event is created the attribute must be initialized to null.
composedPath()
メソッド手続きは:
The composedPath() method steps are:
- composed 経路 :← « » Let composedPath be an empty list.
- 経路 :← これ°の経路 Let path be this’s path.
- IF[ 経路 は空である ] :RETURN composed 経路 If path is empty, then return composedPath.
-
現ターゲット :← これ°の
currentTarget
属性値 Let currentTarget be this’s currentTarget attribute value. - composed 経路 に 現ターゲット を付加する Append currentTarget to composedPath.
- 現ターゲット index :← 0 Let currentTargetIndex be 0.
- 現ターゲットの非可視下位ツリーレベル :← 0 Let currentTargetHiddenSubtreeLevel be 0.
- index :← 経路 のサイズ − 1 Let index be path’s size − 1.
-
WHILE[ index ≥ 0 ]: While index is greater than or equal to 0:
- IF[ 経路[ index ] の閉じたツリーの根か = true ] :現ターゲットの非可視下位ツリーレベル += 1 If path[index]'s root-of-closed-tree is true, then increase currentTargetHiddenSubtreeLevel by 1.
- IF[ 経路[ index ] の呼び出しターゲット = 現ターゲット ] :現ターゲット index ← index ; BREAK If path[index]'s invocation target is currentTarget, then set currentTargetIndex to index and break.
- IF[ 経路[ index ] の slot は閉じたツリー内か = true ] :現ターゲットの非可視下位ツリーレベル −= 1 If path[index]'s slot-in-closed-tree is true, then decrease currentTargetHiddenSubtreeLevel by 1.
- index −= 1 Decrease index by 1.
- 現非可視レベル :← 現ターゲットの非可視下位ツリーレベル ↓
- 最大非可視レベル :← 現ターゲットの非可視下位ツリーレベル Let currentHiddenLevel and maxHiddenLevel be currentTargetHiddenSubtreeLevel.
- index ← 現ターゲット index − 1 Set index to currentTargetIndex − 1.
-
WHILE[ index ≥ 0 ]: While index is greater than or equal to 0:
- IF[ 経路[ index ] の閉じたツリーの根か = true ] :現非可視レベル += 1 If path[index]'s root-of-closed-tree is true, then increase currentHiddenLevel by 1.
- IF[ 現非可視レベル ≤ 最大非可視レベル ] :composed 経路 に 経路[ index ] の呼び出しターゲットを前付加する If currentHiddenLevel is less than or equal to maxHiddenLevel, then prepend path[index]'s invocation target to composedPath.
-
IF[ 経路[ index ] の slot は閉じたツリー内か = true ]: If path[index]'s slot-in-closed-tree is true:
- 現非可視レベル −= 1 Decrease currentHiddenLevel by 1.
- IF[ 最大非可視レベル ≥ 現非可視レベル ] :最大非可視レベル ← 現非可視レベル If currentHiddenLevel is less than maxHiddenLevel, then set maxHiddenLevel to currentHiddenLevel.
- index −= 1 Decrease index by 1.
- 現非可視レベル ← 現ターゲットの非可視下位ツリーレベル ↓
- 最大非可視レベル ← 現ターゲットの非可視下位ツリーレベル Set currentHiddenLevel and maxHiddenLevel to currentTargetHiddenSubtreeLevel.
- index ← 現ターゲット index + 1 Set index to currentTargetIndex + 1.
-
WHILE[ index < 経路 のサイズ ]: While index is less than path’s size:
- IF[ 経路[ index ] の slot は閉じたツリー内か = true ] :現非可視レベル += 1 If path[index]'s slot-in-closed-tree is true, then increase currentHiddenLevel by 1.
- IF[ 現非可視レベル ≤ 最大非可視レベル ] :composed 経路 に 経路[ index ] の呼び出しターゲットを付加する If currentHiddenLevel is less than or equal to maxHiddenLevel, then append path[index]'s invocation target to composedPath.
-
IF[ 経路[ index ] の閉じたツリーの根か = true ]: If path[index]'s root-of-closed-tree is true:
- 現非可視レベル −= 1 Decrease currentHiddenLevel by 1.
- IF[ 最大非可視レベル ≥ 現非可視レベル ] :最大非可視レベル ← 現非可視レベル If currentHiddenLevel is less than maxHiddenLevel, then set maxHiddenLevel to currentHiddenLevel.
- index += 1 Increase index by 1.
- RETURN composed 経路 Return composedPath.
eventPhase
取得子手続きは、
初期化時の値を返す
— それは、
次のいずれかをとるものとする(括弧内は数値):
The eventPhase attribute must return the value it was initialized to, which must be one of the following:
NONE
(0)- まだ配送されていないイベントはこの相に属する。 Events not currently dispatched are in this phase.
CAPTURING_PHASE
(1)- イベントがツリーに関与しているオブジェクトに向けて配送されるとき、 イベントがそのターゲットに到達するまでは,この相に属する。 When an event is dispatched to an object that participates in a tree it will be in this phase before it reaches its target.
AT_TARGET
(2)- イベントが配送されるとき、 イベントのターゲット上では,この相に属する。 When an event is dispatched it will be in this phase on its target.
BUBBLING_PHASE
(3)- イベントがツリーに関与しているオブジェクトに向けて配送されるとき、 イベントがそのターゲットに到達した後は,この相に属する。 When an event is dispatched to an object that participates in a tree it will be in this phase after it reaches its target.
イベントの作成時には、
この属性は NONE
に初期化するものとする。
Initially the attribute must be initialized to NONE.
各イベントには、 次に挙げるものが結び付けられる — いずれも真偽値をとり,初期時は false とする :伝播を停止するか, 伝播を即時に停止するか, 取り消されたか, 受動リスナ内か, composed か, 初期化済みか, 配送中か Each event has the following associated flags that are all initially unset: • stop propagation flag • stop immediate propagation flag • canceled flag • in passive listener flag • composed flag • initialized flag • dispatch flag
stopPropagation()
メソッド手続きは
:これ°の伝播を停止するか ← true
The stopPropagation() method steps are to set this’s stop propagation flag.cancelBubble
取得子手続きは
:RETURN これ°の伝播を停止するか
The cancelBubble getter steps are to return true if this’s stop propagation flag is set; otherwise false.cancelBubble
設定子手続きは
:IF[
所与の値 = true
]
:これ°の伝播を停止するか ← true
The cancelBubble setter steps are to set this’s stop propagation flag if the given value is true; otherwise do nothing.stopImmediatePropagation()
メソッド手続きは
:これ°の伝播を停止するか ← true;
これ°の伝播を即時に停止するか ← true
The stopImmediatePropagation() method steps are to set this’s stop propagation flag and this’s stop immediate propagation flag.bubbles
取得子手続きは、
初期化時の値を返す。
The bubbles and cancelable attributes must return the values they were initialized to.cancelable
取得子手続きは、
初期化時の値を返す。
↑
取り消されたかを設定する
ときは、
所与の
( イベント イベント )
に対し,次を走らすものとする
:IF[
イベント の cancelable
属性値 = true
]∧[
イベント の受動リスナ内か = false
]
:イベント の取り消されたか ← true
To set the canceled flag, given an event event, if event’s cancelable attribute value is true and event’s in passive listener flag is unset, then set event’s canceled flag, and do nothing otherwise.
returnValue
取得子手続きは
:RETURN これ°の取り消されたか
The returnValue getter steps are to return false if this’s canceled flag is set; otherwise true.returnValue
設定子手続きは
:IF[
所与の値 = false
]
:取り消されたかを設定する( これ° )
The returnValue setter steps are to set the canceled flag with this if the given value is false; otherwise do nothing.
preventDefault()
メソッド手続きは
:取り消されたかを設定する( これ° )
The preventDefault() method steps are to set the canceled flag with this.
注記:
preventDefault()
を呼び出しても効果がない局面もある。
UA には、
デバッグを援助するため,精確な原因を開発者コンソールにログすることが奨励される。
There are scenarios where invoking preventDefault() has no effect. User agents are encouraged to log the precise cause in a developer console, to aid debugging.
defaultPrevented
取得子手続きは
:RETURN これ°の取り消されたか
The defaultPrevented getter steps are to return true if this’s canceled flag is set; otherwise false.composed
取得子手続きは
:RETURN これ°の composed か
The composed getter steps are to return true if this’s composed flag is set; otherwise false.
isTrusted
取得子手続きは、
初期化時の値を返す。
The isTrusted attribute must return the value it was initialized to.\
イベントの作成時には、 この属性は false に初期化するものとする。 When an event is created the attribute must be initialized to false.
注記:
isTrusted
は、
イベントは
( dispatchEvent()
を利用してではなく)
UA により配送されたかどうかを簡便に指示する。
唯一の旧来の例外は click()
であり,UA にイベントを[
isTrusted
属性は false に初期化
]した上で配送させる。
isTrusted is a convenience that indicates whether an event is dispatched by the user agent (as opposed to using dispatchEvent()). The sole legacy exception is click(), which causes the user agent to dispatch an event whose isTrusted attribute is initialized to false.
timeStamp
取得子手続きは、
初期化時の値を返す。
The timeStamp attribute must return the value it was initialized to.
イベントを初期化する
ときは、
所与の
( event, type, bubbles, cancelable )
に対し,
event の各種プロパティを次のように設定するものとする
:初期化済みか ← true,
伝播を停止するか ← false,
伝播を即時に停止するか ← false,
取り消されたか ← false,
isTrusted
属性 ← false,
ターゲット ← null ,
type
属性 ← type,
bubbles
属性 ← bubbles,
cancelable
属性 ← cancelable
To initialize an event, with type, bubbles, and cancelable, run these steps:
• Set event’s initialized flag.
• Unset event’s stop propagation flag, stop immediate propagation flag, and canceled flag.
• Set event’s isTrusted attribute to false.
• Set event’s target to null.
• Set event’s type attribute to type.
• Set event’s bubbles attribute to bubbles.
• Set event’s cancelable attribute to cancelable.
initEvent(type, bubbles, cancelable)
メソッド手続きは:
The initEvent(type, bubbles, cancelable) method steps are:
- IF[ これ°の配送中か = true ] :RETURN If this’s dispatch flag is set, then return.
- イベントを初期化する( これ°, type, bubbles, cancelable ) Initialize this with type, bubbles, and cancelable.
注記:
initEvent()
は、
イベントには構築子があるので冗長であり,
composed
も設定できないが、
旧来の内容用にサポートされる必要がある。
initEvent() is redundant with event constructors and incapable of setting composed. It has to be supported for legacy content.
2.3. Window
インタフェースに対する旧来の拡張
partial interface Window {
[Replaceable] readonly attribute (Event or undefined) event
; // 旧来
};
各 Window
オブジェクトには
現在のイベント
が結び付けられる。
それは,[
undefined
/ Event
オブジェクト
]であり、
他が言明されない限り, undefined
とする。
Each Window object has an associated current event (undefined or an Event object). Unless stated otherwise it is undefined.
注記:
web 開発者には、
代わりにイベントリスナに渡される Event
オブジェクトに依拠することが強く奨励される
— その方が、
コードは よりポート可能になるので。
この属性は、
worker や worklet 内では可用でなく,
shadow ツリー内に配送されるイベント用には 不正確になる。
Web developers are strongly encouraged to instead rely on the Event object passed to event listeners, as that will result in more portable code. This attribute is not available in workers or worklets, and is inaccurate for events dispatched in shadow trees.
2.4. CustomEvent
インタフェース
[Exposed=*]
interface CustomEvent : Event {
constructor(DOMString type, optional CustomEventInit eventInitDict = {});
readonly attribute any detail;
undefined initCustomEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false, optional any detail = null); // 旧来
};
dictionary CustomEventInit : EventInit {
any detail = null;
};
カスタムデータを運ばせる用途に,
CustomEvent
インタフェースを利用するイベントを利用できる。
Events using the CustomEvent interface can be used to carry custom data.
- event =
new CustomEvent(type [, eventInitDict])
-
Event
の構築子と相似的に働く — eventInitDict 引数により,detail
属性も設定できることを除いて。 Works analogously to the constructor for Event except that the eventInitDict argument now allows for setting the detail attribute too. - event .
detail
- event の作成時に与えられたカスタムデータを返す。 概して,合成なイベントで利用される。 Returns any custom data event was created with. Typically used for synthetic events.
detail
取得子手続きは、
初期化時の値を返す。
The detail attribute must return the value it was initialized to.
initCustomEvent(type, bubbles, cancelable, detail)
メソッド手続きは:
The initCustomEvent(type, bubbles, cancelable, detail) method steps are:
- IF[ これ°の配送中か = true ] :RETURN If this’s dispatch flag is set, then return.
- イベントを初期化する( これ°, type, bubbles, cancelable ) Initialize this with type, bubbles, and cancelable.
-
これ°の
detail
属性 ← detail Set this’s detail attribute to detail.
2.5. イベントの構築法
適用可能な仕様は、
すべてまたは一部のイベント用に
イベント構築時の手続き
を定義してもよい。
このアルゴリズムは、
イベントを内的に作成する手続き内から,
( 当のイベント, EventInit
辞書 )
を渡して呼び出される。
Specifications may define event constructing steps for all or some events. The algorithm is passed an event event and an EventInit eventInitDict as indicated in the inner event creation steps.
注記:
この構成子は、
Event
の下位クラスが[
その初期化用の辞書メンバと IDL 属性が一対一に対応していない,より複階的な構造
]を有するときに利用できる。
This construct can be used by Event subclasses that have a more complex structure than a simple 1:1 mapping between their initializing dictionary members and IDL attributes.
[
Event
インタフェース, それを継承する各インタフェース
]の構築子は、
イベント構築子
と総称され,この仕様においては
new Event(type, eventInitDict)
,
new CustomEvent(type, eventInitDict)
が該当する。
そのようなインタフェース インタフェース のイベント構築子は、
次の手続きを走らすものとする:
When a constructor of the Event interface, or of an interface that inherits from the Event interface, is invoked, these steps must be run, given the arguments type and eventInitDict:
- イベント :← イベントを内的に作成する( インタフェース, null , 現在時, eventInitDict ) Let event be the result of running the inner event creation steps with this interface, null, now, and eventInitDict.
-
イベント の
type
属性 ← type に初期化する Initialize event’s type attribute to type. - RETURN イベント Return event.
イベントを作成する
ときは、
所与の
:Event
または それを継承するインタフェース イベントインタフェース,
[realm / null ] realm (省略時は null )
に対し,次を走らす:
To create an event using eventInterface, which must be either Event or an interface that inherits from it, and optionally given a realm realm, run these steps:
• If realm is not given, then set it to null.
-
辞書型 :← イベントインタフェース の構築子が引数に受容する辞書型 (
EventInit
またはそれを継承する辞書型)【
↓Event
を継承するインタフェースであって,複数の構築子を宣言するものは、 現時点では,おそらく無い(今後も定義されないと見込まれる)。 】 -
辞書 :← IDL 値に変換する( JavaScript
undefined
値, 辞書型 ) Let dictionary be the result of converting the JavaScript value undefined to the dictionary type accepted by eventInterface’s constructor. (This dictionary type will either be EventInit or a dictionary that inherits from it.)これは、 辞書型 に
required
を伴うメンバが在る場合に働かない。 課題 #600 を見よ。 This does not work if members are required; see whatwg/dom#600. -
イベント :← イベントを内的に作成する( ↓ ) :イベントインタフェース, realm , 当のイベントが通達している何かが生じた時刻†, 辞書 Let event be the result of running the inner event creation steps with eventInterface, realm, the time of the occurrence that the event is signaling, and dictionary.
†注記: 例えば macOS においては、 入力動作が生じた時刻は
NSEvent
オブジェクトのtimestamp
プロパティを介して可用になる。 In macOS the time of the occurrence for input actions is available via the timestamp property of NSEvent objects. -
イベント の
isTrusted
属性 ← true に初期化する Initialize event’s isTrusted attribute to true. - RETURN イベント Return event.
注記: イベントを作成する手続きは、 単純にイベントを発火する代わりに[ イベントを作成する, イベントを配送する ]手続きを別々に呼び出す必要がある,他の仕様からの利用が意図される。 これは、 イベントの属性が既定の値に正しく初期化されることを確保する。 Create an event is meant to be used by other specifications which need to separately create and dispatch events, instead of simply firing them. It ensures the event’s attributes are initialized to the correct defaults.
イベントを内的に作成する ときは、 所与の ( イベントインタフェース, realm , 時刻, 辞書 ) に対し,次を走らす: The inner event creation steps, given an eventInterface, realm, time, and dictionary, are as follows:
-
イベント :← 新たなオブジェクト( イベントインタフェース, realm ) — ただし, realm = null の場合は Web IDL に定義される既定のふるまいに従う Let event be the result of creating a new object using eventInterface. If realm is non-null, then use that realm; otherwise, use the default behavior defined in Web IDL.
これを書いている時点では、 Web IDL は,まだこの既定のふるまいを定義していない。 whatwg/webidl 課題 #135 を見よ。 As of the time of this writing Web IDL does not yet define any default behavior; see whatwg/webidl#135.
- イベント の初期化済みか ← true Set event’s initialized flag.
-
イベント の
timeStamp
属性 ← 相対的な粗い高分解能時刻( 時刻, イベント に関連する大域オブジェクト ) Initialize event’s timeStamp attribute to the relative high resolution coarse time given time and event’s relevant global object. - 辞書 を成す 各( メンバ → 値 ) に対し :IF[ イベント には メンバ を識別子とする属性はある ] :その属性 ← 値 に初期化する For each member → value in dictionary, if event has an attribute whose identifier is member, then initialize that attribute to value.
- 適用可能な仕様にて イベント 用に定義された各( イベント構築時の手続き 手続き ) に対し :手続き( イベント, 辞書 ) Run the event constructing steps with event and dictionary.
- RETURN イベント Return event.
2.6. イベントインタフェースの定義法
一般に、
Event
を継承する新たなインタフェースを定義する際には,常に
WHATWG
または
W3C WebApps WG
コミュニティからのフィードバックを依頼されたし。
In general, when defining a new interface that inherits from Event please always ask feedback from the WHATWG or the W3C WebApps WG community.
CustomEvent
インタフェースはその出発点に利用できるものだが、
init*Event()
の類いのメソッドは,構築子とかぶって冗長になるので導入しないように。
Event
インタフェースを継承するインタフェースがその種のメソッドを備えているのは、
歴史的な理由に限られている。
The CustomEvent interface can be used as starting point. However, do not introduce any init*Event() methods as they are redundant with constructors. Interfaces that inherit from the Event interface that have such a method only have it for historical reasons.
2.7. EventTarget
インタフェース
[Exposed=*]
interface EventTarget {
constructor();
undefined addEventListener(DOMString type, EventListener? callback, optional (AddEventListenerOptions or boolean) options = {});
undefined removeEventListener(DOMString type, EventListener? callback, optional (EventListenerOptions or boolean) options = {});
boolean dispatchEvent(Event event);
};
callback interface EventListener {
undefined handleEvent(Event event);
};
dictionary EventListenerOptions {
boolean capture = false;
};
dictionary AddEventListenerOptions : EventListenerOptions {
boolean passive;
boolean once = false;
AbortSignal signal;
};
EventTarget
オブジェクトは、
何かが生じたとき,イベントを配送できるターゲットを表現する。
An EventTarget object represents a target to which an event can be dispatched when something has occurred.
各 EventTarget
オブジェクトには、
イベントリスナリスト
が結び付けられる
— それは、
イベントリスナたちが成すリストであり,初期時は空とする。
Each EventTarget object has an associated event listener list (a list of zero or more event listeners). It is initially the empty list.
イベントリスナ を利用すれば、 特定のイベントを観測できる — それは、 次に挙げるものからなる: An event listener can be used to observe a specific event and consists of:
- 型 :文字列 type (a string)
-
callback
: null /
EventListener
オブジェクト callback (null or an EventListener object) - 捕捉するか :真偽値 — 初期時は false とする capture (a boolean, initially false)
- 受動的か : null / 真偽値 — 初期時は null とする 【実質的には真偽値( イベントリスナを追加するとき,真偽値に設定される。)】 passive (null or a boolean, initially null)
- 一度限りか :真偽値 — 初期時は false とする once (a boolean, initially false)
-
通達
: null /
AbortSignal
オブジェクト signal (null or an AbortSignal object) - 除去済みか :内部処理用の真偽値 — 初期時は false とする。 removed (a boolean for bookkeeping purposes, initially false)
注記:
callback は EventListener
オブジェクトであるが、
イベントリスナは 上に示したように より広い概念である。
Although callback is an EventListener object, an event listener is a broader concept as can be seen above.
各 EventTarget
オブジェクトには、
その
親ターゲットを取得する
アルゴリズムも結び付けられる。
それは、
所与のイベントに対し,[
EventTarget
オブジェクト, または null
]を返す。
他から指定されない限り, null を返すとする。
Each EventTarget object also has an associated get the parent algorithm, which takes an event event, and returns an EventTarget object. Unless specified otherwise it returns null.
注記: [ ノード / shadow 根 / 文書 ]は、 親ターゲットを取得するアルゴリズムを上書きする。 Nodes, shadow roots, and documents override the get the parent algorithm.
【 このアルゴリズムは、 イベントの配送時にその伝播経路を構築するために利用される。 】【 指定される個々のアルゴリズムには、 渡されたイベントを利用しないものもある (その場合、 イベントは省略して記述され得る)。 】
各 EventTarget
オブジェクトには、
作動化のふるまい
が結び付けられ得る。
このアルゴリズムは、
イベントを配送するアルゴリズム内から,
( イベント )
を渡して呼び出される。
Each EventTarget object can have an associated activation behavior algorithm. The activation behavior algorithm is passed an event, as indicated in the dispatch algorithm.
注記:
これが存在するのは、
UA が
ある種の EventTarget
オブジェクトに対し,ある種の動作を遂行するためである
— 例えば area
要素は、
合成な MouseEvent
イベントに呼応して,その type
属性は "click
" にされる。
それを除去することは、
Web 互換性のため できない。
それはまた、
今や,何らかの作動化を定義するときに尊守される仕方になっている。
[HTML]
This exists because user agents perform certain actions for certain EventTarget objects, e.g., the area element, in response to synthetic MouseEvent events whose type attribute is click. Web compatibility prevented it from being removed and it is now the enshrined way of defining an activation of something. [HTML]
加えて、
作動化のふるまいが有る EventTarget
オブジェクトには、[
旧来の作動化前のふるまい,
旧来の作動化取り消し時のふるまい
]も有ることもある
(片方のみ有ることはない)。
Each EventTarget object that has activation behavior, can additionally have both (not either) a legacy-pre-activation behavior algorithm and a legacy-canceled-activation behavior algorithm.
注記
これらのアルゴリズムは,[
Checkbox / Radio
]状態にある input
要素のみに存在し、
他では利用されない。
[HTML]
These algorithms only exist for checkbox and radio input elements and are not to be used for anything else. [HTML]
- target =
new EventTarget()
-
開発者がイベントを配送してリッスンするために利用できる,新たな
EventTarget
オブジェクトを作成する。 Creates a new EventTarget object, which can be used by developers to dispatch and listen for events. - target .
addEventListener(type, callback [, options])
-
target のイベントリスナリストに[
type
属性値が type であるイベント用のイベントリスナ ]を付加する。 callback 引数が,イベントが配送されたときに呼び出される callback として設定される。 Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched. -
options 引数は、
リスナに特有なオプションを設定する。
互換性のため、
これは真偽値もとり得る
— その場合、
このメソッドは,正確に[
options の
capture
に その値が指定された ]かのようにふるまう。 The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options’s capture. -
options の
capture
が[ true / [ false または無い ]]ならば、 callback は,イベントのeventPhase
属性値が[BUBBLING_PHASE
/CAPTURING_PHASE
]の間は呼び出されないようになる。 いずれにせよ、 イベントのeventPhase
属性値がAT_TARGET
のときは, callback は呼び出される。 When set to true, options’s capture prevents callback from being invoked when the event’s eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event’s eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event’s eventPhase attribute value is AT_TARGET. -
options の
passive
が true に設定された場合、 callback はpreventDefault()
を呼び出してもイベントを取り消さないことを指示する。 これは、 § イベントリスナの観測法に述べる処理能の最適化を可能化するために利用される When set to true, options’s passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners. -
options の
once
が true に設定された場合、 callback が呼び出されるのは一度限りであり,その後にはイベントリスナは除去されることを指示する。 When set to true, options’s once indicates that the callback will only be invoked once after which the event listener will be removed. -
options の
signal
にAbortSignal
が渡された場合、 その通達が中止されたときイベントリスナは除去されることになる。 If an AbortSignal is passed for options’s signal, then the event listener will be removed when signal is aborted. - イベントリスナは、 重複しない — すなわち、[ 型, callback , 捕捉するか ]のうちいずれかが既存のものと異なる — 場合に限り, target のイベントリスナリストに付加される。 The event listener is appended to target’s event listener list and is not appended if it has the same type, callback, and capture.
- target .
removeEventListener(type, callback [, options])
- 引数と同じ[ 型, callback , 捕捉するか ]を伴うイベントリスナを, target のイベントリスナリストから除去する。 Removes the event listener in target’s event listener list with the same type, callback, and options.
- target .
dispatchEvent(event)
-
合成なイベント event を target に向けて配送する。
[
event の
cancelable
属性値が false である / event のpreventDefault()
メソッドは呼び出されなかった ]ならば true を返す。 他の場合は false を返す。 Dispatches a synthetic event event to target and returns true if either event’s cancelable attribute value is false or its preventDefault() method was not invoked; otherwise false.
options を 平坦化 するときは、 次を走らす: To flatten options, run these steps:
options を もっと平坦化 するときは、 次を走らす: To flatten more options, run these steps:
- ( capture, passive, once, signal ) :← ( options を平坦化した結果, ε, false, ε ) Let capture be the result of flattening options.Let once be false.Let passive and signal be null.
-
IF[
options は辞書である
]
:passive ← options[ "
passive
" ]; once ← options[ "once
" ]; signal ← options[ "signal
" ] If options is a dictionary: • Set once to options["once"]. • If options["passive"] exists, then set passive to options["passive"]. • If options["signal"] exists, then set signal to options["signal"]. - IF[ passive = ε ] :passive ← null ↑
- IF[ signal = ε ] :signal ← null ↑
- RETURN ( capture, passive, once, signal ) Return capture, passive, once, and signal.
new EventTarget()
構築子手続きは、
何もしない。
The new EventTarget() constructor steps are to do nothing.
注記:
他所に言明される既定により、
返される EventTarget
の親ターゲットを取得するアルゴリズムは, null を返すことになり、[
作動化のふるまい,
旧来の作動化前のふるまい,
旧来の作動化取り消し時のふるまい
]は無い。
Because of the defaults stated elsewhere, the returned EventTarget's get the parent algorithm will return null, and it will have no activation behavior, legacy-pre-activation behavior, or legacy-canceled-activation behavior.
注記:
将来には、
親ターゲットを取得するカスタムアルゴリズムも許容され得る。
作者は、
それが自身のプログラムに有用になるなら知らせてほしい。
今の所は、
作者が作成したどの EventTarget
も,ツリー構造には関与しない。
In the future we could allow custom get the parent algorithms. Let us know if this would be useful for your programs. For now, all author-created EventTargets do not participate in a tree structure.
既定の受動値
は、
所与の
( イベント型 型, EventTarget
オブジェクト ターゲット )
に対し
:RETURN IS ∧↓:
-
型 ∈ { "
touchstart
", "touchmove
", "wheel
", "mousewheel
" } [TOUCH-EVENTS] [UIEVENTS] -
∨↓:
イベントリスナを追加する
ときは、
所与の
( EventTarget
オブジェクト ターゲット, イベントリスナ リスナ )
に対し,次を走らす:
To add an event listener, given an EventTarget object eventTarget and an event listener listener, run these steps:
-
IF[ ターゲット は
ServiceWorkerGlobalScope
オブジェクトである ]∧[ ターゲット の service worker のスクリプトリソースのこれまでに評価されたか = true ]∧[ リスナ の型は ある service worker イベントのtype
属性値に合致する† ][SERVICE-WORKERS] :コンソールに警告を報告する( “期待される結果を与えないであろう” ) If eventTarget is a ServiceWorkerGlobalScope object, its service worker’s script resource’s has ever been evaluated flag is set, and listener’s type matches the type attribute value of any of the service worker events, then report a warning to the console that this might not give the expected results. [SERVICE-WORKERS]【† そのようなイベントのインスタンスが在ることも要求しているかのように解釈できる条件だが、 単に,service worker イベントの
type
属性値がとり得る値たちが成す集合に入ることを意味するのかも? (しかしながら、 イベントリスナを除去するときのように,明示的な用語 “取り扱うイベント型の集合” を利用していないので、 実際にその解釈が意図されているのかもしれない。) 】 - 通達 :← リスナ の通達 ↓
- IF[ 通達 ≠ null ]∧[ 通達 は中止済みである ] :RETURN If listener’s signal is not null and is aborted, then return.
- IF[ リスナ の callback = null ] :RETURN If listener’s callback is null, then return.
- IF[ リスナ の受動的か = null ] :リスナ の受動的か ← 既定の受動値( リスナ の型, ターゲット ) If listener’s passive is null, then set it to the default passive value given listener’s type and eventTarget.
- IF[ 次を満たすイベントリスナ L は無い ]… :[ L ∈ ターゲット のイベントリスナリスト ]∧[ L の ( 型, callback , 捕捉するか ) = リスナ の ( 型, callback , 捕捉するか ) ] …ならば :ターゲット のイベントリスナリストに リスナ を付加する If eventTarget’s event listener list does not contain an event listener whose type is listener’s type, callback is listener’s callback, and capture is listener’s capture, then append listener to eventTarget’s event listener list.
- IF[ 通達 ≠ null ] :通達にアルゴリズムを追加する( 通達, 次を走らす中止手続き ) :イベントリスナを除去する( ターゲット, リスナ ) If listener’s signal is not null, then add the following abort steps to it: • Remove an event listener with eventTarget and listener.
注記: [ イベントリスナを追加する ]の概念は、[ イベントハンドラ [HTML] が同じ code pathを利用する ]ことを確保するためにある。 The add an event listener concept exists to ensure event handlers use the same code path. [HTML]
addEventListener(type, callback, options)
メソッド手続きは:
The addEventListener(type, callback, options) method steps are:
- ( 捕捉するか, 受動的か, 一度限りか, 通達 ) :← options をもっと平坦化した結果 Let capture, passive, once, and signal be the result of flattening more options.
- イベントリスナを追加する( これ°, 次のように設定されたイベントリスナ ) :型 ← type , callback ← callback , 捕捉するか ← 捕捉するか , 受動的か ← 受動的か , 一度限りか ← 一度限りか, 通達 ← 通達 Add an event listener with this and an event listener whose type is type, callback is callback, capture is capture, passive is passive, once is once, and signal is signal.
イベントリスナを除去する
ときは、
所与の
( EventTarget
オブジェクト ターゲット, イベントリスナ リスナ )
に対し,次を走らす:
To remove an event listener, given an EventTarget object eventTarget and an event listener listener, run these steps:
-
IF[
ターゲット は
ServiceWorkerGlobalScope
オブジェクトである ]∧[ リスナ の型 ∈ ターゲット の service worker が取り扱うイベント型の集合 ][SERVICE-WORKERS] :コンソールに警告を報告する( “期待される結果を与えないであろう” ) If eventTarget is a ServiceWorkerGlobalScope object and its service worker’s set of event types to handle contains listener’s type, then report a warning to the console that this might not give the expected results. [SERVICE-WORKERS] - リスナ の除去済みか ← true Set listener’s removed to true and\
- ターゲット のイベントリスナリストから リスナ を除去する remove listener from eventTarget’s event listener list.
注記: HTML は、 イベントハンドラを定義するために これを必要とする。 [HTML] HTML needs this to define event handlers. [HTML]
イベントリスナをすべて除去する
ときは、
所与の
( EventTarget
オブジェクト ターゲット )
に対し,次を走らす
:ターゲット のイベントリスナリストを成す
各( リスナ )
に対し
:イベントリスナを除去する( ターゲット, リスナ )
To remove all event listeners, given an EventTarget object eventTarget, for each listener of eventTarget’s event listener list, remove an event listener with eventTarget and listener.
注記:
HTML は、
open()
を定義するために これを必要とする。
[HTML]
HTML needs this to define document.open(). [HTML]
removeEventListener(type, callback, options)
メソッド手続きは:
The removeEventListener(type, callback, options) method steps are:
- capture :← options を平坦化した結果 Let capture be the result of flattening options.
- IF[ 次を満たすイベントリスナ リスナ は在る ]… :[ リスナ ∈ これ°のイベントリスナリスト ]∧[ リスナ の ( 型, callback , 捕捉するか ) = ( type, callback, capture ) ] …ならば :イベントリスナを除去する( これ°, リスナ ) If this’s event listener list contains an event listener whose type is type, callback is callback, and capture is capture, then remove an event listener with this and that event listener.
注記: イベントリスナリストが ( type, callback, capture ) が互いに等しい複数のイベントリスナを包含することはない。 それは、 イベントリスナを追加するときに防止される。 The event listener list will not contain multiple event listeners with equal type, callback, and capture, as add an event listener prevents that.
dispatchEvent(event)
メソッド手続きは:
The dispatchEvent(event) method steps are:
-
IF[
event の配送中か = true
]∨[
event の初期化済みか = false
]
:THROW
InvalidStateError
If event’s dispatch flag is set, or if its initialized flag is not set, then throw an "InvalidStateError" DOMException. -
event の
isTrusted
属性 ← false に初期化する Initialize event’s isTrusted attribute to false. - RETURN イベントを配送する( これ°, event ) Return the result of dispatching event to this.
2.8. イベントリスナの観測法
一般に、 開発者は,イベントリスナの有無が観測可能になるものとは予期しない。 イベントリスナの影響は、 その callback により決定される。 すなわち開発者は、 何もしないイベントリスナを追加しても,副作用が生じるとは予期しない。 In general, developers do not expect the presence of an event listener to be observable. The impact of an event listener is determined by its callback. That is, a developer adding a no-op event listener would not expect it to have any side effects.
あいにく,一部のイベント API は、
効率的に実装するためには,イベントリスナを観測することが要求される設計になっている。
すなわち、
何もしないリスナであっても,アプリのふるまいにおける処理能に劇的に影響し得る結果、
リスナの有無が観測可能になっている。
例えば touch /wheel イベントの利用は、
非同期スクロール処理を阻むことがある。
一部の事例では、[
イベントが cancelable
になるのは, passive
でないリスナが 1 個以上あるときに限る
]ように指定することで,この問題を軽減できる。
例えば、
passive
でない TouchEvent
リスナは,スクロール処理を阻まなければならないが、
どのリスナも passive
であれば,[
TouchEvent
を( preventDefault()
の call は無視されるように)取り消せなくすることで,スクロール処理を並列的に開始できる
]ようになる。
イベントを配送しているコードは、
そのように passive
でないリスナが無いことを観測でき,それを利用して配送しているイベントの cancelable
プロパティを false にできる。
Unfortunately, some event APIs have been designed such that implementing them efficiently requires observing event listeners. This can make the presence of listeners observable in that even empty listeners can have a dramatic performance impact on the behavior of the application. For example, touch and wheel events which can be used to block asynchronous scrolling. In some cases this problem can be mitigated by specifying the event to be cancelable only when there is at least one non-passive listener. For example, non-passive TouchEvent listeners must block scrolling, but if all listeners are passive then scrolling can be allowed to start in parallel by making the TouchEvent uncancelable (so that calls to preventDefault() are ignored). So code dispatching an event is able to observe the absence of non-passive listeners, and use that to clear the cancelable property of the event being dispatched.
新たなイベント API は、 このプロパティを必要としないように定義されるのが理想的である (論を交わしたければ、 whatwg/dom を利用されたし)。 Ideally, any new event APIs are defined such that they do not need this property. (Use whatwg/dom for discussion.)
service worker fetch イベントリスナ callback 群を得る旧来の手続き
は、
所与の
( ServiceWorkerGlobalScope
大域オブジェクト )
に対し,次を走らす
— これは、[
EventListener
オブジェクトたちが成すリスト
]を返す:
To legacy-obtain service worker fetch event listener callbacks given a ServiceWorkerGlobalScope global, run these steps. They return a list of EventListener objects.
- callback 群 :← « » Let callbacks be « ».
-
大域オブジェクト のイベントリスナリストを成す
各( リスナ )
に対し
:IF[
リスナ の型 = "
fetch
" ]∧[ リスナ の callback ≠ null ] :callback 群 に リスナ の callback を付加する For each listener of global’s event listener list: • If listener’s type is "fetch", and listener’s callback is not null, then append listener’s callback to callbacks. - RETURN callback 群 Return callbacks.
2.9. イベントの配送法
イベントを配送する ときは、 所与の ( ターゲット, イベント イベント, ターゲットを上書きするか ∈ { ターゲットを上書きする, ε }(省略時は ε ) ) に対し,次を走らす: To dispatch an event to a target, with an optional legacy target override flag and an optional legacyOutputDidListenersThrowFlag, run these steps:
【 この手続きは、 “ターゲット に向けて(イベントを)配送する” のような形の句でも参照される (例えば,地の文の中で)。 】
【 原文では,省略可能な引数として[ Indexed Database API のみから利用される legacyOutputDidListenersThrowFlag ]も — 参照渡しとして — とるが、 この訳では,[ 関連するイベントに(旧来の)リスナは投出したかを結び付けるよう定義する ]ことにより、 この引数の受け渡しに関する記述を簡素化する。 】
- イベント の配送中か ← true Set event’s dispatch flag.
-
上書きするターゲット :← ターゲットを上書きするか に応じて :ターゲットを上書きする ならば ターゲット に結び付けられた文書 [HTML] / ε ならば ターゲット Let targetOverride be target, if legacy target override flag is not given, and target’s associated Document otherwise. [HTML]
注記: ターゲットを上書きするか は,旧来のフラグであり、 HTML からのみ, それも ターゲット が
Window
オブジェクトである場合に限り,非 ε にされる。 legacy target override flag is only used by HTML and only when target is a Window object. - 作動化ターゲット :← null Let activationTarget be null.
- 関係するターゲット :← イベント の関係するターゲットを ターゲット に向けてターゲットし直す Let relatedTarget be the result of retargeting event’s relatedTarget against target.
-
IF[ ターゲット ≠ 関係するターゲット ]∨[ ターゲット = イベント の関係するターゲット ]: If target is not relatedTarget or target is event’s relatedTarget:
- touch ターゲット群 :← « » Let touchTargets be a new list.
- イベント の touch ターゲットリストを成す 各( touch ターゲット ) に対し :touch ターゲット群 に次の結果を付加する :touch ターゲット を ターゲット に向けてターゲットし直す For each touchTarget of event’s touch target list, append the result of retargeting touchTarget against target to touchTargets.
- イベント経路に付加する( ↓ ) :イベント, ターゲット, 上書きするターゲット, 関係するターゲット, touch ターゲット群, false Append to an event path with event, target, targetOverride, relatedTarget, touchTargets, and false.
-
作動化イベントか :← IS[
イベント は
MouseEvent
オブジェクトである ]∧[ イベント のtype
属性 = "click
" ] Let isActivationEvent be true, if event is a MouseEvent object and event’s type attribute is "click"; otherwise false. - IF[ 作動化イベントか = true ]∧[ ターゲット には作動化のふるまいが有る ] :作動化ターゲット ← ターゲット If isActivationEvent is true and target has activation behavior, then set activationTarget to target.
- slot 可能 :← [ 次が満たされるならば ターゲット / 他の場合は null ] :[ ターゲット は slot 可能である ]∧[ ターゲット のあてがい先 slot ≠ null ] Let slottable be target, if target is a slottable and is assigned, and null otherwise.
- slot は閉じたツリー内か :← false Let slot-in-closed-tree be false.
- 親 :← ターゲット の親ターゲットを取得する( イベント ) Let parent be the result of invoking target’s get the parent with event.
-
WHILE[ 親 ≠ null ]: While parent is non-null:
-
IF[ slot 可能 ≠ null ]: If slottable is non-null:
- IF[ 親 は slot 可能である ]∧[ 親 のあてがい先 slot ≠ null ] :slot 可能 ← 親 If parent is a slottable and is assigned, then set slottable to parent.
- 関係するターゲット :← 関係するターゲット を 親 に向けてターゲットし直す Let relatedTarget be the result of retargeting event’s relatedTarget against parent.
- touch ターゲット群 :← « » Let touchTargets be a new list.
- イベント の touch ターゲットリストを成す 各( touch ターゲット ) に対し :touch ターゲット群 に次の結果を付加する :touch ターゲット を 親 に向けてターゲットし直す For each touchTarget of event’s touch target list, append the result of retargeting touchTarget against parent to touchTargets.
-
IF[ 親 は
Window
オブジェクトである ]∨[[ 親 はノードである ]∧[ ターゲット の根 は 親 の shadow も含めた広義先祖である ]]: If parent is a Window object, or parent is a node and target’s root is a shadow-including inclusive ancestor of parent:-
IF[ 作動化イベントか = true ]∧[ イベント の
bubbles
属性 = true ]∧[ 作動化ターゲット = null ]∧[ 親 には作動化のふるまいが有る ] :作動化ターゲット ← 親 If isActivationEvent is true, event’s bubbles attribute is true, activationTarget is null, and parent has activation behavior, then set activationTarget to parent. - イベント経路に付加する( ↓ ) :イベント, 親, null , 関係するターゲット, touch ターゲット群, slot は閉じたツリー内か Append to an event path with event, parent, null, relatedTarget, touchTargets, and slot-in-closed-tree.
-
- ELSE IF[ 親 = 関係するターゲット ] :親 ← null Otherwise, if parent is relatedTarget, then set parent to null.
-
ELSE: Otherwise:
- ターゲット ← 親 Set target to parent.
- IF[ 作動化イベントか = true ]∧[ 作動化ターゲット = null ]∧[ ターゲット には作動化のふるまいが有る ] :作動化ターゲット ← ターゲット If isActivationEvent is true, activationTarget is null, and target has activation behavior, then set activationTarget to target.
- イベント経路に付加する( ↓ ) :イベント, 親, ターゲット, 関係するターゲット, touch ターゲット群, slot は閉じたツリー内か Append to an event path with event, parent, target, relatedTarget, touchTargets, and slot-in-closed-tree.
- IF[ 親 ≠ null ] :親 ← 親 の親ターゲットを取得する( イベント ) If parent is non-null, then set parent to the result of invoking parent’s get the parent with event.
- slot は閉じたツリー内か ← false Set slot-in-closed-tree to false.
-
- ターゲットクリア用の構造体 :← イベント の経路を成すアイテムのうち,次を満たす最後のもの? :shadow 調整済みターゲット ≠ null Let clearTargetsStruct be the last struct in event’s path whose shadow-adjusted target is non-null.
- Assert: ターゲットクリア用の構造体 ≠ null 【この段は、この訳による補完。】
-
ターゲットたちをクリアするか :← IS[ ∧↓ を満たすノード ノード は在る ]:
- ノード の根は shadow 根である
-
∨↓
- ノード = ターゲットクリア用の構造体 の shadow 調整済みターゲット
- ノード = ターゲットクリア用の構造体 の関係するターゲット
- ノード ∈ ターゲットクリア用の構造体 の touch ターゲットリスト
- IF[ 作動化ターゲット ≠ null ]∧[ 作動化ターゲット には旧来の作動化前のふるまいが有る ] :そのふるまいを走らす If activationTarget is non-null and activationTarget has legacy-pre-activation behavior, then run activationTarget’s legacy-pre-activation behavior.
-
イベント の経路を成す 各( 構造体 ) に対し,逆順に: For each struct in event’s path, in reverse order:
-
イベント の
eventPhase
属性 ← [ 構造体 の shadow 調整済みターゲット ≠ null ならばAT_TARGET
/ 他の場合はCAPTURING_PHASE
] If struct’s shadow-adjusted target is non-null, then set event’s eventPhase attribute to AT_TARGET.Otherwise, set event’s eventPhase attribute to CAPTURING_PHASE. -
リスナを呼び出す( 構造体, イベント, "
capturing
" ) Invoke with struct, event, "capturing", and legacyOutputDidListenersThrowFlag if given.
-
イベント の
-
イベント の経路を成す 各( 構造体 ) に対し: For each struct in event’s path:
-
IF[
構造体 の shadow 調整済みターゲット ≠ null
]
:イベント の
eventPhase
属性 ←AT_TARGET
If struct’s shadow-adjusted target is non-null, then set event’s eventPhase attribute to AT_TARGET. -
ELSE: Otherwise:
-
IF[
イベント の
bubbles
属性 = false ] :CONTINUE If event’s bubbles attribute is false, then continue. -
イベント の
eventPhase
属性 ←BUBBLING_PHASE
Set event’s eventPhase attribute to BUBBLING_PHASE.
-
IF[
イベント の
-
リスナを呼び出す( 構造体, イベント, "
bubbling
" ) Invoke with struct, event, "bubbling", and legacyOutputDidListenersThrowFlag if given.
-
IF[
構造体 の shadow 調整済みターゲット ≠ null
]
:イベント の
-
イベント の
eventPhase
属性 ←NONE
Set event’s eventPhase attribute to NONE. -
イベント の
currentTarget
属性 ← null Set event’s currentTarget attribute to null. - イベント の経路 ← « » Set event’s path to the empty list.
- イベント の :配送中か ← false, 伝播を停止するか ← false, 伝播を即時に停止するか ← false Unset event’s dispatch flag, stop propagation flag, and stop immediate propagation flag.
-
IF[ ターゲットたちをクリアするか = true ] :イベント の :ターゲット ← null 関係するターゲット ← null touch ターゲットリスト ← « » If clearTargets is true: • Set event’s target to null. • Set event’s relatedTarget to null. • Set event’s touch target list to the empty list.
-
IF[ 作動化ターゲット ≠ null ]: If activationTarget is non-null:
- IF[ イベント の取り消されたか = false ] :作動化ターゲット の作動化のふるまい( イベント ) If event’s canceled flag is unset, then run activationTarget’s activation behavior with event.
- ELSE IF[ 作動化ターゲット には旧来の作動化取り消し時のふるまいが有る ] :そのふるまいを走らす Otherwise, if activationTarget has legacy-canceled-activation behavior, then run activationTarget’s legacy-canceled-activation behavior.
- RETURN IS[ イベント の取り消されたか = false ] Return false if event’s canceled flag is set; otherwise true.
イベント経路に付加する ときは、 所与の :イベント, 呼び出しターゲット, shadow 調整済みターゲット, 関係するターゲット, touch ターゲット群, slot は閉じたツリー内か に対し,次を走らす: To append to an event path, given an event, invocationTarget, shadowAdjustedTarget, relatedTarget, touchTargets, and a slot-in-closed-tree, run these steps:
- 呼び出しターゲットは shadow ツリー内か :← IS[ 呼び出しターゲット はノードである ]∧[ 呼び出しターゲット の根は shadow 根である ] Let invocationTargetInShadowTree be false.If invocationTarget is a node and its root is a shadow root, then set invocationTargetInShadowTree to true.
-
閉じたツリーの根か :← IS[
呼び出しターゲット は shadow 根である
]∧[
呼び出しターゲット のモード = "
closed
" ] Let root-of-closed-tree be false.If invocationTarget is a shadow root whose mode is "closed", then set root-of-closed-tree to true. - イベント の経路に次を付加する :新たな構造体 — その :呼び出しターゲット ← 呼び出しターゲット, 呼び出しターゲットは shadow ツリー内か ← 呼び出しターゲットは shadow ツリー内か shadow 調整済みターゲット ← shadow 調整済みターゲット, 関係するターゲット ← 関係するターゲット, 閉じたツリーの根か ← 閉じたツリーの根か, touch ターゲットリスト ← touch ターゲット群 slot は閉じたツリー内か ← slot は閉じたツリー内か Append a new struct to event’s path whose invocation target is invocationTarget, invocation-target-in-shadow-tree is invocationTargetInShadowTree, shadow-adjusted target is shadowAdjustedTarget, relatedTarget is relatedTarget, touch target list is touchTargets, root-of-closed-tree is root-of-closed-tree, and slot-in-closed-tree is slot-in-closed-tree.
リスナを呼び出す ときは、 所与の ( 構造体, イベント, 相 ) に対し,次を走らす: To invoke, given a struct, event, phase, and an optional legacyOutputDidListenersThrowFlag, run these steps:
- イベント のターゲット ← [ イベント の経路内の[ 構造体 または 構造体 に先行する構造体 ]のうち,[ shadow 調整済みターゲット ≠ null ]を満たすもののうち,最後の構造体 ]の shadow 調整済みターゲット Set event’s target to the shadow-adjusted target of the last struct in event’s path, that is either struct or preceding struct, whose shadow-adjusted target is non-null.
- イベント の関係するターゲット ← 構造体 の関係するターゲット Set event’s relatedTarget to struct’s relatedTarget.
- イベント の touch ターゲットリスト ← 構造体 の touch ターゲットリスト Set event’s touch target list to struct’s touch target list.
- IF[ イベント の伝播を停止するか = true ] :RETURN If event’s stop propagation flag is set, then return.
-
イベント の
currentTarget
属性 ← 構造体 の呼び出しターゲットに初期化する Initialize event’s currentTarget attribute to struct’s invocation target. -
リスナ群 :← 構造体 の呼び出しターゲットのイベントリスナリストをクローンする Let listeners be a clone of event’s currentTarget attribute value’s event listener list.
注記: これは、 この時点以降に追加されたイベントリスナは,走らせないようにする。 除去については、 除去済みか フィールドに因り,依然として効果を及ぼすことに注意。 This avoids event listeners added after this point from being run. Note that removal still has an effect due to the removed field.
- 呼び出しターゲットは shadow ツリー内か :← 構造体 の呼び出しターゲットは shadow ツリー内か Let invocationTargetInShadowTree be struct’s invocation-target-in-shadow-tree.
- 見出されたか :← リスナを内的に呼び出す( ↓ ) :イベント, リスナ群, 相, 呼び出しターゲットは shadow ツリー内か Let found be the result of running inner invoke with event, listeners, phase, invocationTargetInShadowTree, and legacyOutputDidListenersThrowFlag if given.
-
IF[ 見出されたか = false ]∧[ イベント の
isTrusted
属性 = true ]∧[ イベント のtype
属性値は[ 下の表の 1 列目に挙げるいずれかの文字列 ]に ASCII 大小無視で合致する ]… If found is false and event’s isTrusted attribute is true:Let originalEventType be event’s type attribute value.If event’s type attribute value is a match for any of the strings in the first column in the following table, set event’s type attribute value to the string in the second column on the same row as the matching string, and return otherwise.イベント型 Event type 旧来のイベント型 Legacy event type " animationend
"" webkitAnimationEnd
"" animationiteration
"" webkitAnimationIteration
"" animationstart
"" webkitAnimationStart
"" transitionend
"" webkitTransitionEnd
"…ならば:
-
元のイベント型 :← イベント の
type
属性値 ↑ -
イベント の
type
属性 ← 合致した行の 2 列目に与える文字列 ↑ - リスナを内的に呼び出す( ↓ ) :イベント, リスナ群, 相, 呼び出しターゲットは shadow ツリー内か Inner invoke with event, listeners, phase, invocationTargetInShadowTree, and legacyOutputDidListenersThrowFlag if given.
-
イベント の
type
属性 ← 元のイベント型 Set event’s type attribute value to originalEventType.
-
元のイベント型 :← イベント の
リスナを内的に呼び出す ときは、 所与の :イベント, リスナ群, 相, 呼び出しターゲットは shadow ツリー内か に対し,次を走らす: To inner invoke, given an event, listeners, phase, invocationTargetInShadowTree, and an optional legacyOutputDidListenersThrowFlag, run these steps:
- 見出されたか :← false Let found be false.
-
リスナ群 を成す 各( イベントリスナ リスナ ) に対し: For each listener in listeners, whose removed is false:
- IF[ リスナ の除去済みか = true ] :CONTINUE ↑
-
IF[
リスナ の型 ≠ イベント の
type
属性値 ] :CONTINUE If event’s type attribute value is not listener’s type, then continue. - 見出されたか ← true Set found to true.
-
IF[
相 = "
capturing
" ]∧[ リスナ の捕捉するか = false ] :CONTINUE If phase is "capturing" and listener’s capture is false, then continue. -
IF[
相 = "
bubbling
" ]∧[ リスナ の捕捉するか = true ] :CONTINUE If phase is "bubbling" and listener’s capture is true, then continue. -
IF[
リスナ の一度限りか = true
]
:イベントリスナを除去する( イベント の
currentTarget
属性値, リスナ ) If listener’s once is true, then remove an event listener given event’s currentTarget attribute value and listener. - 大域オブジェクト :← リスナ の callback が属する realm の大域オブジェクト Let global be listener callback’s associated realm’s global object.
-
現在のイベント :←
undefined
Let currentEvent be undefined. -
IF[ 大域オブジェクト は
Window
オブジェクトである ]: If global is a Window object: - IF[ リスナ の受動的か = true ] :イベント の受動リスナ内か ← true If listener’s passive is true, then set event’s in passive listener flag.
-
IF[
大域オブジェクト は
Window
オブジェクトである ] :イベントリスナ用に計時情報を記録する( イベント, リスナ ) If global is a Window object, then record timing info for event listener given event and listener. -
利用元オブジェクトの演算を call する( ↓ ) :リスナ の callback , "
handleEvent
", « イベント », イベント のcurrentTarget
属性値 Call a user object’s operation with listener’s callback, "handleEvent", « event », and event’s currentTarget attribute value.\例外 例外 が投出されたときは、 catch して: If this throws an exception exception:
- 例外を報告する( 例外, リスナ の callback に対応する JavaScript オブジェクトが属する realm の大域オブジェクト ) Report exception for listener’s callback’s corresponding JavaScript object’s associated realm’s global object.
-
IF[ イベント には(旧来の)リスナは投出したかが結び付けられている ] :イベント の(旧来の)リスナは投出したか ← true Set legacyOutputDidListenersThrowFlag if given.
注記: Indexed Database API [INDEXEDDB] のみが、 これを利用する。 The legacyOutputDidListenersThrowFlag is only used by Indexed Database API. [INDEXEDDB]
- イベント の受動リスナ内か ← false Unset event’s in passive listener flag.
-
IF[
大域オブジェクト は
Window
オブジェクトである ] :大域オブジェクト の現在のイベント ← 現在のイベント If global is a Window object, then set global’s current event to currentEvent. - IF[ イベント の伝播を即時に停止するか = true ] :BREAK If event’s stop immediate propagation flag is set, then break.
- RETURN 見出されたか Return found.
2.10. イベントの発火法
イベントを発火する
ときは、
所与の
( ターゲット, 名前 e, イベント構築子(省略時は Event
のそれ)† )
に対し,以下の手続きを走らす
— この手続きには、
次の入力も与えられ得る:
- ターゲットを上書きするか ∈ { ターゲットを上書きする, ε }(省略時は ε )
-
記述 — [ イベントの各 IDL 属性を どう初期化するか ]についての記述(省略時は何もしない)
【 これは、 IDL 属性以外のプロパティ(例: composed か )を初期化する記述を含む場合もある。 】
【† イベント構築子 には、 (省略されない場合は)ほぼすべての事例で,単にインタフェースが渡される — その場合、 当のインタフェースの唯一の構築子として解釈する。 】
【 この手続きは、 “ターゲット に向けて名前 e のイベントを発火する” のような形の句でも参照される (例えば、 地の文の中で)。 】
To fire an event named e at target, optionally using an eventConstructor, with a description of how IDL attributes are to be initialized, and a legacy target override flag, run these steps: • If eventConstructor is not given, then let eventConstructor be Event.- イベント :← イベントを作成する( イベント構築子, ターゲット に関連する realm ) Let event be the result of creating an event given eventConstructor, in the relevant realm of target.
-
イベント の
type
属性 ← e に初期化する Initialize event’s type attribute to e. -
イベント の各種 IDL 属性を 記述 に従って初期化する Initialize any other IDL attributes of event as described in the invocation of this algorithm.
注記: ここでは[
isTrusted
属性 ← false ]にすることも許容される。 This also allows for the isTrusted attribute to be set to false. - RETURN イベントを配送する( ターゲット, イベント, ターゲットを上書きするか ) Return the result of dispatching event at target, with legacy target override flag set if set.
注記: DOM の文脈における “イベントを発火する” とは、 イベントを[ 作成して, 初期化して, 配送する ]ことの略語であり,この処理を容易に書けるようにするためにある。 Fire in the context of DOM is short for creating, initializing, and dispatching an event. Fire an event makes that process easier to write down.
イベントの[
bubbles
や cancelable
]などの属性も初期化する必要がある場合、
次のようにも書ける
:イベントを発火する( ターゲット, submit
)
— 次のように初期化して
:cancelable
属性 ← true
If the event needs its bubbles or cancelable attribute initialized, one could write "fire an event named submit at target with its cancelable attribute initialized to true".
あるいは,カスタムな構築子も必要なときは、
次のように書く, 等々
:イベントを発火する( ターゲット, click
, MouseEvent
)
— 次のように初期化して
:detail
属性 ← 1
Or, when a custom constructor is needed, "fire an event named click at target using MouseEvent with its detail attribute initialized to 1".
ときには、 返り値が重要になることもある: Occasionally the return value is important:
-
何かするか :← イベントを発火する( ターゲット,
like
) Let doAction be the result of firing an event named like at target. - IF[ 何かするか = true ] :… If doAction is true, then …
2.11. 動作 vs. 発生
イベントは、
動作( action )ではなく,
何かが生じたこと( occurrence )をしるす(徴す/ signify する)ものである。
言葉を代えれば、
あるアルゴリズムからの通知を表現し,そのアルゴリズムの未来の進路に
(例えば preventDefault()
を呼び出すことを通して)
波及させるために利用できるものである。
イベントは、
何らかのアルゴリズムを走らすような[
動作, あるいは動作を起動するもの
]として利用されてはならない。
そのような用途にあるものではない。
An event signifies an occurrence, not an action. Phrased differently, it represents a notification from an algorithm and can be used to influence the future course of that algorithm (e.g., through invoking preventDefault()). Events must not be used as actions or initiators that cause some algorithm to start running. That is not what they are for.
注記: ここで特に強調している理由は、 以前の DOM では,イベントに “既定動作” の概念が結び付けられていて,人を誤った考えに導いていたからである。 イベントは、 動作を表現したり生じさせるものではなく,進行中な何かに波及させるために限り利用できるものである。 This is called out here specifically because previous iterations of the DOM had a concept of "default actions" associated with events that gave folks all the wrong ideas. Events do not represent or cause actions, they can only be used to influence an ongoing one.
3. 進行中な活動の中止法
promise には,中止するための組み込みの仕組みがないが、
それを利用している多くの API は,中止の意味論を要求している。
AbortController
には、
その要件をサポートすることが意図される。
それが供する abort()
メソッドは、
AbortController
に対応している AbortSignal
オブジェクトの状態をトグルする。
中止法をサポートしたいと望む API は、
このオブジェクトを受容して, その状態を利用することにより,どう続行するか決定できる。
Though promises do not have a built-in aborting mechanism, many APIs using them require abort semantics. AbortController is meant to support these requirements by providing an abort() method that toggles the state of a corresponding AbortSignal object. The API which wishes to support aborting can accept an AbortSignal object, and use its state to determine how to proceed.
AbortController
に依拠する API は、[
AbortSignal
の中止事由で未決着な promise を却下する
]ことにより,
abort()
に応答することが奨励される。
APIs that rely upon AbortController are encouraged to respond to abort() by rejecting any unsettled promise with the AbortSignal's abort reason.
メソッド
doAmazingness({ ... })
は、
何か “すごいこと” を行うとする。
このメソッドは、
AbortSignal
オブジェクトを受容して,次のように中止法をサポートできる:
A hypothetical doAmazingness({ ... }) method could accept an AbortSignal object to support aborting as follows:
const controller = new AbortController(); const signal = controller.signal; startSpinner(); doAmazingness({ ..., signal }) .then(result => ...) .catch(err => { if (err.name == 'AbortError') return; showUserErrorMessage(); }) .then(() => stopSpinner()); // … controller.abort();
doAmazingness
は、
次のように実装することもできる:
doAmazingness could be implemented as follows:
function doAmazingness({signal}) { return new Promise((resolve, reject) => { signal.throwIfAborted(); /* “すごいこと” を行うのを始める — 済んだなら resolve(result) を call する。 加えて、 signal も注視する。 Begin doing amazingness, and call resolve(result) when done. But also, watch for signals: */ signal.addEventListener('abort', () => { /* “すごいこと” を行うのを停止してから: Stop doing amazingness, and: */ reject(signal.reason); }); }); }
promise を返さない【が非同期なふるまいを伴う】API は、 次のいずれかにし得る: APIs that do not return promises can either\
- 【 promise を返すバージョンと】 等価な方式で反応する。 react in an equivalent manner\
-
AbortSignal
の中止事由をまったく表に出さないようにする —addEventListener()
は、 こうする方が意味を成す API の例である。 or opt to not surface the AbortSignal's abort reason at all.\ addEventListener() is an example of an API where the latter made sense.
より精細な制御を要する API は、
必要に応じて[
AbortController
, AbortSignal
]両オブジェクトを拡張することもできる。
APIs that require more granular control could extend both AbortController and AbortSignal objects according to their needs.
3.1. AbortController
インタフェース
Exposed=*]
interface AbortController {
constructor();
[SameObject] readonly attribute AbortSignal signal;
undefined abort(optional any reason);
};
- controller =
new AbortController()
-
新たな controller を,その
signal
を[ 新たなAbortSignal
オブジェクト ]に設定した上で返す。 Returns a new controller whose signal is set to a newly created AbortSignal object. - controller .
signal
-
このオブジェクトに結び付けられた
AbortSignal
オブジェクトを返す。 Returns the AbortSignal object associated with this object. - controller .
abort(reason)
-
このメソッドを呼び出すと、
このオブジェクトの
AbortSignal
の中止事由 reason を格納した上で、 結び付けられた活動が中止されることになるよう,観測器たちにも通達することになる。 reason が ε の場合(省略したか明示的にundefined
を与えた場合)、AbortError
例外が格納されることになる。 Invoking this method will store reason in this object’s AbortSignal's abort reason, and signal to any observers that the associated activity is to be aborted. If reason is undefined, then an "AbortError" DOMException will be stored.
各 AbortController
オブジェクトには、
通達
( AbortSignal
オブジェクト)が結び付けられる。
An AbortController object has an associated signal (an AbortSignal object).
new AbortController()
構築子手続きは
:これ°の通達 ← 新たなオブジェクト( AbortSignal
)
The new AbortController() constructor steps are:
• Let signal be a new AbortSignal object.
• Set this’s signal to signal.
abort(reason)
メソッド手続きは
:中止を通達する( これ°, reason )
The abort(reason) method steps are to signal abort on this with reason if it is given.
中止を通達する
ときは、
所与の
( AbortController
制御器, 事由 (省略時は ε ) )
に対し
:中止を通達する( 制御器 の通達, 事由 )
To signal abort on an AbortController controller with an optional reason, signal abort on controller’s signal with reason if it is given.
3.2. AbortSignal
インタフェース
[Exposed=*]
interface AbortSignal : EventTarget {
[NewObject] static AbortSignal abort(optional any reason);
[Exposed=(Window,Worker), NewObject] static AbortSignal timeout([EnforceRange] unsigned long long milliseconds);
[NewObject] static AbortSignal _any(sequence<AbortSignal> signals);
readonly attribute boolean aborted;
readonly attribute any reason;
undefined throwIfAborted();
attribute EventHandler onabort;
};
- AbortSignal .
abort(reason)
-
AbortSignal
インスタンスを返す — その中止事由は[ reason が ε の場合(省略したか明示的にundefined
を与えた場合)はAbortError
例外/ 他の場合は reason ]に設定される。 Returns an AbortSignal instance whose abort reason is set to reason if not undefined; otherwise to an "AbortError" DOMException. - AbortSignal .
any(signals)
-
AbortSignal
インスタンスを返す — signals を成す いずれかのAbortSignal
インスタンスが中止されたなら中止されるような。 その中止事由は、 中止されたAbortSignal
の中止事由に設定されることになる。 Returns an AbortSignal instance which will be aborted once any of signals is aborted. Its abort reason will be set to whichever one of signals caused it to be aborted. - AbortSignal .
timeout(milliseconds)
-
AbortSignal
インスタンスを返す — それは、 milliseconds ミリ秒後に中止され, その中止事由はTimeoutError
例外に設定されることになる。 Returns an AbortSignal instance which will be aborted in milliseconds milliseconds. Its abort reason will be set to a "TimeoutError" DOMException. - signal .
aborted
-
signal の
AbortController
が中止するよう通達されて[ いれば true / いなければ false ]を返す。 Returns true if signal’s AbortController has signaled to abort; otherwise false. - signal .
reason
- signal の中止事由を返す。 Returns signal’s abort reason.
- signal .
throwIfAborted()
-
signal の
AbortController
が中止するよう通達された場合、 signal の中止事由を投出する — 他の場合は何もしない。 Throws signal’s abort reason, if signal’s AbortController has signaled to abort; otherwise, does nothing.
各 AbortSignal
オブジェクト 通達 には、
次に挙げるものが結び付けられる:
↓
-
中止事由
:JavaScript 値
— 初期時は
undefined
とする。 【通例的には、中止時に例外オブジェクトに設定される。】 An AbortSignal object has an associated abort reason (a JavaScript value), which is initially undefined. -
中止するアルゴリズム群 :アルゴリズムたちが成す有順序集合 — 初期時は空とする。 これらのアルゴリズムは、 通達 が中止済みになるとき,実行されることになる。 An AbortSignal object has associated abort algorithms, (a set of algorithms which are to be executed when it is aborted), which is initially empty.
【 集合なので,同じアルゴリズムは重ねて現れ得ないことになるが、 “同じ” がどう定義されるかは, “通達にアルゴリズムを追加する” を利用する他の仕様を見ないとはっきりしない (おそらく、 手続き自体は同じでも,呼び出しごとに異なるものとして扱われるように思われるが)。 】
注記: 中止するアルゴリズム群は、 複階的な要件を伴う API が,
abort()
に対し適度な仕方で反応することを可能化する。 例えば,所与の API の中止事由は、 service worker などの別スレッド環境へ伝播する必要があるかもしれない。 The abort algorithms enable APIs with complex requirements to react in a reasonable way to abort(). For example, a given API’s abort reason might need to be propagated to a cross-thread environment, such as a service worker. -
依存か :真偽値 — 初期時は false とする。
【 true ならば、 通達 が “依存して” いる他の
An AbortSignal object has a dependent (a boolean), which is initially false.AbortSignal
オブジェクトがあり得る (それでも、無い場合はあり得る) — すなわち、 後者が中止されるに伴い, 通達 も中止される。 】 -
ソース通達群
:[
中止済みな状態に関して, 通達 が依存している
AbortSignal
オブジェクト ]たちが成す弱い集合† — 初期時は空とする。 An AbortSignal object has associated source signals (a weak set of AbortSignal objects that the object is dependent on for its aborted state), which is initially empty. -
依存通達群
:[
中止済みな状態に関して,
通達 に依存している
AbortSignal
オブジェクト ]たちが成す弱い集合† — 初期時は空とする。 An AbortSignal object has associated dependent signals (a weak set of AbortSignal objects that are dependent on the object for their aborted state), which is initially empty.
【†
“弱い集合( weak set )” とは、
その名前から,JavaScript の WeakSet
(参考)
の意味論に従うことが意図されていると思われる。
弱い集合内のオブジェクトは、
ガーベジ収集されるに伴い,当の集合から自動的に除去される
(ことになろう
— 以下に定義される仕様レベルの各アルゴリズムにおいて、
これらの集合に付加する演算は現れるが,除去する演算は現れないので)。
】
静的な
abort(reason)
メソッド手続きは:
The static abort(reason) method steps are:
-
通達 :← 新たなオブジェクト(
AbortSignal
) Let signal be a new AbortSignal object. -
通達 の中止事由 ← reason に応じて
:ε ならば新たな
AbortError
例外 / 他の場合は reason Set signal’s abort reason to reason if it is given; otherwise to a new "AbortError" DOMException. - RETURN 通達 Return signal.
静的な
timeout(milliseconds)
メソッド手続きは:
The static timeout(milliseconds) method steps are:
-
通達 :← 新たなオブジェクト(
AbortSignal
) Let signal be a new AbortSignal object. - 大域オブジェクト :← 通達 に関連する大域オブジェクト Let global be signal’s relevant global object.
-
手続きをタイムアウト後に走らす( 大域オブジェクト, "
AbortSignal-timeout
", milliseconds, 次の手続き ) Run steps after a timeout given global, "AbortSignal-timeout", milliseconds, and the following step:手続きは :大域タスクをキューする( タイマータスクソース, 大域オブジェクト, 次の手続き )
手続きは :中止を通達する( 通達, 新たな• Queue a global task on the timer task source given global to signal abort given signal and a new "TimeoutError" DOMException.TimeoutError
例外 )このタイムアウトまでの間は、 通達 の
abort
イベント用にイベントリスナが登録されている限り, 大域オブジェクト から 通達 への強い参照があるものとする。 For the duration of this timeout, if signal has any event listeners registered for its abort event, there must be a strong reference from global to signal. - RETURN 通達 Return signal.
静的な
any(signals)
メソッド手続きは
:RETURN 依存中止通達を作成する( signals, AbortSignal
, 現在の realm )
The static any(signals) method steps are to return the result of creating a dependent abort signal from signals using AbortSignal and the current realm.
aborted
取得子手続きは
:RETURN IS[
これ°は中止済みである
]
The aborted getter steps are to return true if this is aborted; otherwise false.
throwIfAborted()
メソッド手続きは
:IF[
これ°は中止済みである
]
:これ°の中止事由を投出する
The throwIfAborted() method steps are to throw this’s abort reason, if this is aborted.
このメソッドが主として有用になるのは、[
AbortSignal
を受容している関数が,
特定の検査地点で例外を投出する
(または、
却下された promise を返す)
]よう求まれるときである
— 当の AbortSignal
を他のメソッドに渡す代わりに。
例えば,次の関数は、
条件を poll する各試みの間に中止することを許容する。
これは、
実際の非同期な演算(すなわち, await func()
)が AbortSignal
を受容しない場合でも,
poll している処理を中止する機会を与える。
This method is primarily useful for when functions accepting AbortSignals want to throw (or return a rejected promise) at specific checkpoints, instead of passing along the AbortSignal to other methods. For example, the following function allows aborting in between each attempt to poll for a condition. This gives opportunities to abort the polling process, even though the actual asynchronous operation (i.e., await func()) does not accept an AbortSignal.
async function waitForCondition(func, targetValue, { signal } = {}) { while (true) { signal?.throwIfAborted(); const result = await func(); if (result === targetValue) { return; } } }
onabort
は、
onabort
イベントハンドラ用のイベントハンドラ IDL 属性である
— そのイベントハンドライベント型は
abort
とする。
The onabort attribute is an event handler IDL attribute for the onabort event handler, whose event handler event type is abort.
注記:
AbortSignal
オブジェクトに対する変化は,対応している AbortController
オブジェクトの望みを表現するが、
AbortSignal
オブジェクトを観測している API は,それを無視することも選べる
— 一例として、
演算がすでに完了していた場合など。
Changes to an AbortSignal object represent the wishes of the corresponding AbortController object, but an API observing the AbortSignal object can choose to ignore them. For instance, if the operation has already completed.
AbortSignal
オブジェクトが
中止済み
であるとは、
次が満たされることをいう
:その中止事由 ≠ undefined
An AbortSignal object is aborted when its abort reason is not undefined.
通達にアルゴリズムを追加する
ときは、
所与の
( AbortSignal
オブジェクト 通達, アルゴリズム アルゴリズム )
に対し:
To add an algorithm algorithm to an AbortSignal object signal:
- IF[ 通達 は中止済みである ] :RETURN If signal is aborted, then return.
- 通達 の中止するアルゴリズム群に アルゴリズム を付加する Append algorithm to signal’s abort algorithms.
通達からアルゴリズムを除去する
ときは、
所与の
( AbortSignal
オブジェクト 通達, アルゴリズム A )
に対し
:通達 の中止するアルゴリズム群から A を除去する
To remove an algorithm algorithm from an AbortSignal signal, remove algorithm from signal’s abort algorithms.
中止を通達する
ときは、
所与の
( AbortSignal
オブジェクト 通達, 事由(省略時は ε ) )
に対し:
To signal abort, given an AbortSignal object signal and an optional reason:
- IF[ 通達 は中止済みである ] :RETURN If signal is aborted, then return.
-
Assert:
事由 ≠
undefined
【この段は、この訳による補完。】 -
通達 の中止事由 ← 事由 に応じて
:ε ならば新たな
AbortError
例外 / 他の場合は 事由 Set signal’s abort reason to reason if it is given; otherwise to a new "AbortError" DOMException. - 中止する依存通達群 :← 新たなリスト Let dependentSignalsToAbort be a new list.
-
通達 の依存通達群を成す 各( 依存通達 ) に対し: For each dependentSignal of signal’s dependent signals:
- 通達用の中止手続きを走らす( 通達 ) Run the abort steps for signal.
- 中止する依存通達群 を成す 各( 依存通達 ) に対し :通達用の中止手続きを走らす( 依存通達 ) For each dependentSignal of dependentSignalsToAbort, run the abort steps for dependentSignal.
通達用の中止手続きを走らす
ときは、
所与の
( AbortSignal
オブジェクト 通達 )
に対し:
To run the abort steps for an AbortSignal signal:
- 通達 の中止するアルゴリズム群を成す 各( アルゴリズム ) に対し :アルゴリズム を走らす For each algorithm of signal’s abort algorithms: run algorithm.
- 通達 の中止するアルゴリズム群を空にする Empty signal’s abort algorithms.
-
イベントを発火する( 通達,
abort
) Fire an event named abort at signal.
依存中止通達を作成する ときは、 所与の ( 通達群, 通達インタフェース, realm ) に対し: To create a dependent abort signal from a list of AbortSignal objects signals, using signalInterface, which must be either AbortSignal or an interface that inherits from it, and a realm:
-
Assert
:通達群 は
AbortSignal
オブジェクトたちが成すリストである。 通達インタフェース はAbortSignal
インタフェースか それを継承するインタフェースである。 ↑ - 結果通達 :← 新たなオブジェクト( 通達インタフェース, realm ) Let resultSignal be a new object implementing signalInterface using realm.
- 通達群 を成す 各( 通達 ) に対し :IF[ 通達 は中止済みである ] :結果通達 の中止事由 ← 通達 の中止事由; RETURN 結果通達 For each signal of signals: if signal is aborted, then set resultSignal’s abort reason to signal’s abort reason and return resultSignal.
- 結果通達 の依存か ← true Set resultSignal’s dependent to true.
-
通達群 を成す 各( 通達 ) に対し: For each signal of signals:
- RETURN 結果通達 Return resultSignal.
3.2.1. ガーベジ収集
AbortSignal
オブジェクトは、
∧↓ を満たす間は,ガーベジ収集しないものとする:
- 中止済みでない
- その依存か = true
- そのソース通達群は空でない
-
∨↓:
-
abort
イベント用に登録されたイベントリスナが在る 【すなわち、そのイベントリスナリスト内に 型 = "abort
" を満たすものが在る】 - その中止するアルゴリズム群は空でない
-
3.3. API における AbortController
, AbortSignal
オブジェクトの利用法
中止できる演算を表現する promise を利用している web プラットフォーム API は、 次を固守するものとする: Any web platform API using promises to represent operations that can be aborted must adhere to the following:
-
signal
辞書メンバを通して,AbortSignal
オブジェクトを受容すること。 Accept AbortSignal objects through a signal dictionary member. -
演算が中止されたときは、[
AbortSignal
オブジェクトの中止事由 ]で promise を却下することにより,それを伝えること。 Convey that the operation got aborted by rejecting the promise with AbortSignal object’s abort reason. -
AbortSignal
は中止済みである場合 :即時に却下すること。 Reject immediately if the AbortSignal is already aborted, otherwise:他の場合 :
AbortSignal
オブジェクトの変化を観測するときは、 中止するアルゴリズム群による仕組みを,他の観測器と衝突し得ない方式で利用すること。 Use the abort algorithms mechanism to observe changes to the AbortSignal object and do so in a manner that does not lead to clashes with other observers.
promise を返す あるメソッド doAmazingness(options)
用のメソッド手続きは、
次のように記すこともできる:
The method steps for a promise-returning method doAmazingness(options) could be as follows:
- 大域オブジェクト :← これ°に関連する大域オブジェクト Let global be this's relevant global object.
- promise :← 新たな promise Let p be a new promise.
-
通達 :← options[ "
signal
" ] ↓ -
IF[ 通達 ≠ ε ]: If options["signal"] exists:
-
IF[ 通達 は中止済みである ]:
- promise を却下する( promise , 通達 の中止事由 )
- RETURN promise
-
通達にアルゴリズムを追加する( 通達, 次の手続き ): Add the following abort steps to signal:
手続きは:
- (下に定義される) “すごいこと” 行う手続きを停止する Stop doing amazing things.
- promise を却下する( promise , 通達 の中止事由 ) Reject p with signal’s abort reason.
-
-
この段は、 並列的に走らす: Run these steps in parallel:
- すごい結果 :← 何かすごいことを行う 【完遂するまで待機する】 Let amazingResult be the result of doing some amazing things.
-
大域タスクをキューする( すごいタスクソース, 大域オブジェクト, 次の手続き ) Queue a global task on the amazing task source given global to\
手続きは :promise を解決する( p, すごい結果 ) resolve p with amazingResult.
- RETURN p Return p.
promise を利用していない API であっても、 可能な限り,上述を固守するべきである。 APIs not using promises should still adhere to the above as much as possible.
4. ノード
4.1. DOM 序論
DOM ( “The DOM( Document Object Model )” )は、 その元の意味においては, 文書(特に,HTML 文書や XML 文書)にアクセスして操作するための API である。 この仕様における用語 “文書” は,[ 短い静的な文書から 多彩なマルチメディアを伴う長い小論や報告書,更には本格的な対話的アプリ ]までに渡る[ 任意のマークアップに基づくリソース ]を指すものとして利用される。 In its original sense, "The DOM" is an API for accessing and manipulating documents (in particular, HTML and XML documents). In this specification, the term "document" is used for any markup-based resource, ranging from short static documents to long essays or reports with rich multimedia, as well as to fully-fledged interactive applications.
そのような各文書は、 ノードツリーとして表現される。 ツリーを成すノードのうち一部は 他のノードを子に持ち,他のものは葉(末端)ノードになる。 Each such document is represented as a node tree. Some of the nodes in a tree can have children, while others are always leaves.
次の HTML 文書を例に説明する: To illustrate, consider this HTML document:
<!DOCTYPE html> <html class=e> <head><title>Aliens?</title></head> <body>Why yes.</body> </html>
これは次のように表現される: It is represented as follows:
HTML 構文解析器の仕組みから,すべての ASCII 空白が Text
ノードにされてはいないが、
一般概念は明らかである。
入力のマークアップから,ノードたちが成すツリーが出来上がる。
Note that, due to the magic that is HTML parsing, not all ASCII whitespace were turned into Text nodes, but the general concept is clear. Markup goes in, a tree of nodes comes out.
注記: さらに探求してみたければ、 最高によくできている Live DOM Viewer を利用するといい。 The most excellent Live DOM Viewer can be used to explore this matter in more detail.
4.2. ノードツリー
ノード
とは、
Node
を実装するオブジェクトである。
ノードは,
ノードツリー
と称されるツリーに関与する。
Nodes are objects that implement Node. Nodes participate in a tree, which is known as the node tree.
注記: 実施においては、 より特定的なオブジェクトを処することになる。 In practice you deal with more specific objects.
Node
を実装するオブジェクトは、
それを継承するインタフェース
— 次に挙げるいずれか —
も実装する
:Document
,
DocumentType
,
DocumentFragment
,
Element
,
CharacterData
,
Attr
Objects that implement Node also implement an inherited interface: Document, DocumentType, DocumentFragment, Element, CharacterData, or Attr.
DocumentFragment
を実装するオブジェクトには、
ShadowRoot
を実装するものもある。
Objects that implement DocumentFragment sometimes implement ShadowRoot.
Element
を実装するオブジェクトは、
概して,それを継承するインタフェース
— HTMLAnchorElement
など —
も実装する。
Objects that implement Element also typically implement an inherited interface, such as HTMLAnchorElement.
CharacterData
を実装するオブジェクトは,それを継承するインタフェース
— 次に挙げるいずれか —
も実装する
:Text
,
ProcessingInstruction
,
Comment
Objects that implement CharacterData also implement an inherited interface: Text, ProcessingInstruction, or Comment.
Text
を実装するオブジェクトには、
CDATASection
を実装するものもある。
Objects that implement Text sometimes implement CDATASection.
したがって、
ノードの首インタフェースは,次に挙げるいずれかになる
:Document
,
DocumentType
,
DocumentFragment
,
ShadowRoot
,
Element
,
Element
を継承するインタフェース,
Attr
,
Text
,
CDATASection
,
ProcessingInstruction
,
Comment
Thus, every node's primary interface is one of: Document, DocumentType, DocumentFragment, ShadowRoot, Element or an inherited interface of Element, Attr, Text, CDATASection, ProcessingInstruction, or Comment.
この仕様は、
Node
を継承するインタフェース N を実装するオブジェクトを指して,
単に N ノードとも称する。
For brevity, this specification refers to an object that implements Node and an inherited interface NodeInterface, as a NodeInterface node.
ノードツリーは、 次に従うよう拘束される — これらの拘束は、 ノードとそれに許容される子の関係性として表出される: A node tree is constrained as follows, expressed as a relationship between a node and its potential children:
Document
-
ツリー順序で,次に挙げるものからなる: In tree order:
-
0 個以上の[
ProcessingInstruction
/Comment
]ノード Zero or more ProcessingInstruction or Comment nodes. -
0 個または 1 個の
DocumentType
ノード Optionally one DocumentType node. -
0 個以上の[
ProcessingInstruction
/Comment
]ノード Zero or more ProcessingInstruction or Comment nodes. -
0 個または 1 個の
Element
ノード Optionally one Element node. -
0 個以上の[
ProcessingInstruction
/Comment
]ノード Zero or more ProcessingInstruction or Comment nodes.
-
0 個以上の[
DocumentFragment
Element
-
0 個以上の[
Element
/CharacterData
]ノードからなる Zero or more Element or CharacterData nodes. DocumentType
CharacterData
Attr
- 子は無い No children.
注記:
歴史的な理由から Attr
ノードはツリーに関与するが、
それは常に,親は null かつ子群は空である
— したがって、
それだけで,自身が関与するツリーを成すすべてになる。
Attr nodes participate in a tree for historical reasons; they never have a (non-null) parent or any children and are therefore alone in a tree.
【
Attr
ノードが “ツリーに関与するもの” を意味する語として他の仕様から利用されることは,ほぼ無い
(それらは、
通例的に “内容属性” と称される /
Attr
自体を参照している仕様も,ごく限られる)。
他の仕様に現れる語 “ノード” は、
実質的には,ほぼすべて “Attr
以外のノード” を含意する。
】
ノード ノード の
長さ
は、
ノード が実装するインタフェースに応じて,次で決定される
:DocumentType
ならば 0 /
Attr
ならば 0 /
CharacterData
ならば ノード のデータの長さ /
他の場合は ノード の子群のサイズ
To determine the length of a node node, run these steps:
• If node is a DocumentType or Attr node, then return 0.
• If node is a CharacterData node, then return node’s data’s length.
• Return the number of node’s children.
ノードが 空 であるとは、 次を満たすことをいう :その長さ = 0 A node is considered empty if its length is 0.
4.2.1.文書ツリー
文書を根とするノードツリーを 文書ツリー という。 A document tree is a node tree whose root is a document.
文書 文書 の 文書要素 とは、 次を満たす要素は[ 在るならば それ / 無いならば null ]である :その親 = 文書 The document element of a document is the element whose parent is that document, if it exists; otherwise null.
注記:
ノードツリーに対する拘束から、
そのような要素は唯一つに決まる。
【例えば HTML 文書ならば html
要素。】
Per the node tree constraints, there can be only one such element.
ノードは 文書ツリー内 にあるとは、 次を満たすことをいう :その根は文書である A node is in a document tree if its root is a document.
文書ツリー内にあるノードは、 文書内 にあるともいう。 A node is in a document if it is in a document tree.\
注記: 用語 “文書内” は、 もはや利用されないものと想定されている。 この用語は、 それを利用している標準が,まだ shadow ツリーを織り込むよう更新されていないことを指示する。 The term in a document is no longer supposed to be used. It indicates that the standard using it has not been updated to account for shadow trees.
4.2.2. shadow ツリー
shadow 根を根とするノードツリーを shadow ツリー という。 A shadow tree is a node tree whose root is a shadow root.
shadow 根は常に,そのホストを通して別のノードツリーに付される。 したがって,shadow ツリーが孤立することは決してない。 shadow 根のホストが関与しているノードツリーは、 light ツリー とも呼ばれる。 A shadow root is always attached to another node tree through its host. A shadow tree is therefore never alone. The node tree of a shadow root’s host is sometimes referred to as the light tree.
注記: shadow ツリーに対応する light ツリーは、 それ自身 shadow ツリーになり得る。 A shadow tree’s corresponding light tree can be a shadow tree itself.
【 shadow ( “日陰” )と違って,light ( “日なた” )の定義は相対的であり、 あるノードツリーだけで “light である” とは言えない。 】
ノードは 接続されて いるとは、 次を満たすことをいう :その shadow も含めた根は文書である A node is connected if its shadow-including root is a document.
【 文書も指示する必要がある所では、 “ノードは(所与の)文書に接続されている” / “(所与の)ノードが接続されている文書” のような形の句でも表記される。 】
4.2.2.1. slot
各 shadow ツリーは、 0 個以上の, slot と呼ばれる要素を包含する。 A shadow tree contains zero or more elements that are slots.
注記:
slot を作成できるのは、
HTML の slot
要素を通す他にない。
A slot can only be created through HTML’s slot element.
各 slot には、 slot 名 が結び付けられる。 それは文字列であり、 他が言明されない限り,空文字列とする。 A slot has an associated name (a string). Unless stated otherwise it is the empty string.
slot の slot 名を更新するときは、 要素 用の属性°変更時の手続きとして次を利用する — それは、 所与の ( 局所名, 旧値, 値, 名前空間 ) に対し: Use these attribute change steps to update a slot’s name:
-
IF[
要素 は slot でない
]∨[
局所名 ≠ "
name
" ]∨[ 名前空間 ≠ null ] :RETURN If element is a slot, localName is name, and namespace is null: - IF[ 値 = null ] :値 ← 空文字列 ↓
- IF[ 旧値 = null ] :旧値 ← 空文字列 ↓
- IF[ 値 = 旧値 ] :RETURN If value is oldValue, then return.If value is null and oldValue is the empty string, then return.If value is the empty string and oldValue is null, then return.
- 要素 の slot 名 ← 値 If value is null or the empty string, then set element’s name to the empty string.Otherwise, set element’s name to value.
- ツリーに slot 可能なものをあてがう( 要素 の根 ) Run assign slottables for a tree with element’s root.
注記: shadow ツリー内の,[ slot 名 = 空文字列 ]なる slot のうち,ツリー順序で最初のものは “既定の slot ” と称されることもある。 The first slot in a shadow tree, in tree order, whose name is the empty string, is sometimes known as the "default slot".
各 slot には、 あてがわれたノード群 ( assigned nodes )が結び付けられる。 それは,slot 可能たちが成すリストであり、 他が言明されない限り,空とする。 A slot has an associated assigned nodes (a list of slottables). Unless stated otherwise it is empty.
4.2.2.2. slot 可能
[
Element
/ Text
]ノードは、
slot 可能
である。
Element and Text nodes are slottables.
【 slot は “はめ込み口”, slot 可能( slottable )は “はめ込めるモノ” (名詞化された形容詞 — 形容詞としては “はめ込み可能な” を意味する)。 】
注記: slot も、 slot 可能になり得る。 A slot can be a slottable.
各 slot 可能には、 名前 が結び付けられる。 それは文字列であり、 他が言明されない限り,空文字列とする。 A slottable has an associated name (a string). Unless stated otherwise it is the empty string.
slot 可能な 要素 の名前を更新するときは、 要素 用の属性°変更時の手続きとして次を利用する — それは、 所与の ( 局所名, 旧値, 値, 名前空間 ) に対し: Use these attribute change steps to update a slottable’s name:
-
IF[
局所名 ≠ "
slot
" ]∨[ 名前空間 ≠ null ] :RETURN If localName is slot and namespace is null: - IF[ 値 = null ] :値 ← 空文字列 ↓
- IF[ 旧値 = null ] :旧値 ← 空文字列 ↓
- IF[ 値 = 旧値 ] :RETURN If value is oldValue, then return.If value is null and oldValue is the empty string, then return.If value is the empty string and oldValue is null, then return.
- 要素 の名前 ← 値 If value is null or the empty string, then set element’s name to the empty string.Otherwise, set element’s name to value.
- IF[ 要素 のあてがい先 slot ≠ null ] :slot に slot 可能なものをあてがう( その slot ) If element is assigned, then run assign slottables for element’s assigned slot.
- slot 可能を slot にあてがう( 要素 ) Run assign a slot for element.
各 slot 可能には あてがい先 slot ( assigned slot )が結び付けられる。 それは,[ null / slot ]であり、 他が言明されない限り, null とする。 【自身がどの slot にあてがわれたかを指示する。】 A slottable has an associated assigned slot (null or a slot). Unless stated otherwise it is null.\
あてがい先 slot が null でない slot 可能は、 あてがい先がある ( is assigned )という。 【この訳では、この用語は利用せず,直に “あてがい先 slot ≠ null ” と記す。】 A slottable is assigned if its assigned slot is non-null.
各 slot 可能には 手動あてがい先 slot ( manual slot assignment, スクリプトが手動であてがった slot )が結び付けられる。 それは,[ null / slot ]であり、 他が言明されない限り, null とする。 A slottable has an associated manual slot assignment (null or a slot). Unless stated otherwise, it is null.
注記: slot 可能の手動あてがい先 slot は、 スクリプトからは直にアクセス可能でないので, slot への弱い参照を利用して実装できる/され得る。 A slottable’s manual slot assignment can be implemented using a weak reference to the slot, because this variable is not directly accessible from script.
4.2.2.3. slot /slot 可能の見出し方
slot 可能用に slot を見出す ときは、 所与の ( slot 可能 slot 可能, open か ∈ { open , ε }(省略時は ε ) ) に対し,次を走らす: To find a slot for a given slottable slottable and an optional open flag (unset unless stated otherwise), run these steps:
- IF[ slot 可能 の親 = null ] :RETURN null If slottable’s parent is null, then return null.
- shadow :← slot 可能 の親の shadow 根 Let shadow be slottable’s parent’s shadow root.
- IF[ shadow = null ] :RETURN null If shadow is null, then return null.
-
IF[
open か = open
]∧[
shadow のモード ≠ "
open
" ] :RETURN null If the open flag is set and shadow’s mode is not "open", then return null. -
IF[ shadow の slot あてがいモード = "
manual
" ] :RETURN 次を満たす slot は[ 在るならば slot / 無いならば null ] :[ shadow の子孫である ]∧[ slot である ]∧[ slot 可能 ∈ slot に手動であてがわれたノード群 ]【 条件を満たす slot は在っても一つしかないことは、
If shadow’s slot assignment is "manual", then return the slot in shadow’s descendants whose manually assigned nodes contains slottable, if any; otherwise null.assign()
メソッド手続きにより保証される。 】 - RETURN 次を満たす[ shadow の子孫 ]のうち,ツリー順序で最初のもの? :slot であって,その slot 名 = slot 可能 の名前 Return the first slot in tree order in shadow’s descendants whose name is slottable’s name, if any; otherwise null.
slot 用に slot 可能なものを見出す ときは、 所与の ( slot slot ) に対し,次を走らす: To find slottables for a given slot slot, run these steps:
- 結果 :← « » Let result be an empty list.
- 根 :← slot の根 Let root be slot’s root.
- IF[ 根 は shadow 根でない ] :RETURN 結果 If root is not a shadow root, then return result.
- ホスト :← 根 のホスト Let host be root’s host.
-
IF[
根 の slot あてがいモード = "
manual
" ] :slot に手動であてがわれたノード群を成す 各( slot 可能 slot 可能 ) に対し :IF[ slot 可能 の親 = ホスト ] :結果 に slot 可能 を付加する If root’s slot assignment is "manual": • Let result be « ».(不要) • For each slottable slottable of slot’s manually assigned nodes, if slottable’s parent is host, append slottable to result. - ELSE :ホスト の子群を成す 各( 子 ) に対し,ツリー順序で :IF[ 子 は slot 可能である ]∧[ slot 可能用に slot を見出す( 子 ) = slot ] :結果 に 子 を付加する Otherwise, for each slottable child slottable of host, in tree order: • Let foundSlot be the result of finding a slot given slottable. • If foundSlot is slot, then append slottable to result.
- RETURN 結果 Return result.
slot 用に平坦化された slot 可能なものを見出す ときは、 所与の ( slot slot ) に対し,次を走らす: To find flattened slottables for a given slot slot, run these steps:
- 結果 :← « » Let result be an empty list.
- IF[ slot の根は shadow 根でない ] :RETURN 結果 If slot’s root is not a shadow root, then return result.
- slot 可能群 :← slot 用に slot 可能なものを見出す( slot ) Let slottables be the result of finding slottables given slot.
- IF[ slot 可能群 は空である ] :slot の子群を成す 各( 子 ) に対し,ツリー順序で :IF[ 子 は slot 可能である ] :slot 可能群 に 子 を付加する If slottables is the empty list, then append each slottable child of slot, in tree order, to slottables.
-
slot 可能群 を成す 各( ノード ) に対し: For each node in slottables:
-
IF[ ノード は slot である ]∧[ ノード の根は shadow 根である ] :[ slot 用に平坦化された slot 可能なものを見出す( ノード ) ]を成す 各( slot 可能 slot 可能 ) に対し,順に :結果 に slot 可能 を付加する If node is a slot whose root is a shadow root: • Let temporaryResult be the result of finding flattened slottables given node. • Append each slottable in temporaryResult, in order, to result.
- ELSE :結果 に ノード を付加する Otherwise, append node to result.
-
- RETURN 結果 Return result.
4.2.2.4. slot 可能/slot のあてがい方
slot に slot 可能なものをあてがう ときは、 所与の ( slot slot ) に対し,次を走らす: To assign slottables for a slot slot, run these steps:
- slot 可能群 :← slot 用に slot 可能なものを見出す( slot ) Let slottables be the result of finding slottables for slot.
- IF[ slot 可能群 と slot にあてがわれたノード群とは、 一致しない ] :slot の変化を通達する( slot ) If slottables and slot’s assigned nodes are not identical, then run signal a slot change for slot.
- slot にあてがわれたノード群 ← slot 可能群 Set slot’s assigned nodes to slottables.
- slot 可能群 を成す 各( slot 可能 ) に対し :slot 可能 のあてがい先 slot ← slot For each slottable in slottables, set slottable’s assigned slot to slot.
ツリーに slot 可能なものをあてがう ときは、 所与の ( ノード 根 ) に対し,次を走らす :根 の広義子孫である 各( slot slot ) に対し,ツリー順序で :slot に slot 可能なものをあてがう( slot ) To assign slottables for a tree, given a node root, run assign slottables for each slot slot in root’s inclusive descendants, in tree order.
slot 可能を slot にあてがう ときは、 所与の ( slot 可能 slot 可能 ) に対し、 次を走らす: To assign a slot, given a slottable slottable, run these steps:
- slot :← slot 可能用に slot を見出す( slot 可能 ) Let slot be the result of finding a slot with slottable.
- IF[ slot ≠ null ] :slot に slot 可能なものをあてがう( slot ) If slot is non-null, then run assign slottables for slot.
4.2.2.5. slot 変化の通達法
各 生成元が類似な window agent [HTML] は、 通達 slot 群 を有する。 それは,slot たちが成す有順序集合であり、 初期時は空とする。 Each similar-origin window agent has signal slots (a set of slots), which is initially empty. [HTML]
slot の変化を通達する ときは、 所与の ( slot slot ) に対し,次を走らす: To signal a slot change, for a slot slot, run these steps:
- [ slot に関連する agent の通達 slot 群 ]に slot を付加する Append slot to slot’s relevant agent’s signal slots.
- 変異観測器 小タスクをキューする Queue a mutation observer microtask.
4.2.3. 変異アルゴリズム
親の中で子の前に挿入できるか検証する ときは、 所与の ( ノード ノード, ノード 親, ノード 子 ) に対し: To ensure pre-insert validity of a node node into a node parent before a node child:
-
IF[
親 は[
Document
/DocumentFragment
/Element
]ノードでない ] :THROWHierarchyRequestError
If parent is not a Document, DocumentFragment, or Element node, then throw a "HierarchyRequestError" DOMException. -
IF[
ノード は 親 のホストも含めた広義先祖である
]
:THROW
HierarchyRequestError
If node is a host-including inclusive ancestor of parent, then throw a "HierarchyRequestError" DOMException. -
IF[
子 ≠ null
]∧[
子 の親 ≠ 親
]
:THROW
NotFoundError
If child is non-null and its parent is not parent, then throw a "NotFoundError" DOMException. -
IF[ ノード は[
DocumentFragment
/DocumentType
/Element
/CharacterData
]ノードでない ] :THROWHierarchyRequestError
【 すなわち “
If node is not a DocumentFragment, DocumentType, Element, or CharacterData node, then throw a "HierarchyRequestError" DOMException.Document
/Attr
ノードである” (何故そのように記されない?) 】 -
IF[ ∨↓ ]…
…ならば :THROW
If either node is a Text node and parent is a document, or node is a doctype and parent is not a document, then throw a "HierarchyRequestError" DOMException.HierarchyRequestError
-
IF[ 親 は文書である ]∧[ ノード が実装するインタフェースに応じて,以下が満たされる ] :THROW
HierarchyRequestError
If parent is a document, and any of the statements below, switched on the interface node implements, are true, then throw a "HierarchyRequestError" DOMException.DocumentFragment
-
∨↓:
Element
-
∨↓:
parent has an element child, child is a doctype, or child is non-null and a doctype is following child. DocumentType
-
∨↓:
parent has a doctype child, child is non-null and an element is preceding child, or child is null and parent has an element child.
親 の中で ノードを子の前に前挿入する ときは、 所与の ( ノード, 子 ) に対し,次を走らす: To pre-insert a node into a parent before a child, run these steps:
- 親の中で子の前に挿入できるか検証する( ノード, 親, 子 ) Ensure pre-insert validity of node into parent before child.
- 基準子 :← 子 Let referenceChild be child.
- IF[ 基準子 = ノード ] :基準子 ← ノード の直後の同胞? If referenceChild is node, then set referenceChild to node’s next sibling.
- 親 の中でノードを子の前に挿入する( ノード, 基準子 ) Insert node into parent before referenceChild.
- RETURN ノード Return node.
適用可能な仕様は、 すべてまたは一部のノード用に 挿入時の手続き を定義してもよい。 このアルゴリズムは、 ノードを子の前に挿入するアルゴリズム内から, ( 挿入されたノード ) を渡して呼び出される。 この手続きは:
- 次を【同期的に】行ってはならない :挿入されたノードが関与するノードツリーを改変する/ 閲覧文脈作成する/ イベントを発火する/ その他,JavaScript を実行する【 JavaScript の同期的な実行を伴い得る何らかの動作】
- が、 次をしてもよい :前項に挙げたものを非同期に行うための大域タスクをキューする
挿入時の手続きは,とりわけ JavaScript を実行し得ないが、 その帰結が実際にスクリプトから観測可能になることもある。 次の例を考える: While the insertion steps cannot execute JavaScript (among other things), they will indeed have script-observable consequences. Consider the below example:
const h1 = document.querySelector('h1');
const fragment = new DocumentFragment();
const script = fragment.appendChild(document.createElement('script'));
const style = fragment.appendChild(document.createElement('style'));
script.innerText= 'console.log(getComputedStyle(h1).color)'; /*
これは 'rgb(255, 0, 0)
' をログする
Logs 'rgb(255, 0, 0)' */
style.innerText = 'h1 {color: rgb(255, 0, 0);}';
document.body.append(fragment);
この例における script は、
'rgb(255, 0, 0)
' をログする
— 次が順に起こるので:
The script in the above example logs 'rgb(255, 0, 0)' because the following happen in order:
-
ノードを子の前に挿入するアルゴリズムを走らす。 これは、 当の[
script
,style
]要素を順に挿入することになる。 その結果、 [HTML] においては: The insert algorithm runs, which will insert the script and style elements in order.-
script
要素用に挿入時の手続きを走らす。 これは、 何もしない。 The HTML Standard’s insertion steps run for the script element; they do nothing. [HTML] -
style
要素用に挿入時の手続きを走らす。 これは、 即時に,そのスタイル規則を文書に適用する。 The HTML Standard’s insertion steps run for the style element; they immediately apply its style rules to the document. [HTML] -
script
要素用に接続後の手続きを走らす。 これは、 当のスクリプトを走らす — スクリプトは、 前段で適用されたスタイル規則を即時に観測する。 The HTML Standard’s post-connection steps run for the script element; they run the script, which immediately observes the style rules that were applied in the above step. [HTML]
-
適用可能な仕様は、 すべてまたは一部のノード用に 接続後の手続き を定義してもよい。 このアルゴリズムは、 ノードを子の前に挿入するアルゴリズム内から, ( 接続されたノード ) を渡して呼び出される。 Specifications may also define post-connection steps for all or some nodes. The algorithm is passed connectedNode, as indicated in the insert algorithm below.
注記: 接続後の手続きの目的は、 ノード用に[ 接続に関係する演算を遂行する機会 ]を供することにある — [ 接続されたノードが関与しているノードツリーを改変する/ 閲覧文脈を作成する/ その他,JavaScript を実行する ]ために。 この手続きは、 ノードたちが一括して不可分に挿入されることを許容する — スクリプトに関する主要な副作用すべてが,ノードツリーの中への一括挿入が完了した後に生じるよう。 これは、[ 処理待ちなノードツリーへの挿入 ]すべてが[ さらなる挿入が生じ得る前に完全に完遂する ]ことを確保する。 The purpose of the post-connection steps is to provide an opportunity for nodes to perform any connection-related operations that modify the node tree that connectedNode participates in, create browsing contexts, or otherwise execute JavaScript. These steps allow a batch of nodes to be inserted atomically with respect to script, with all major side effects occurring after the batch insertions into the node tree is complete. This ensures that all pending node tree insertions completely finish before more insertions can occur.
適用可能な仕様は、 すべてまたは一部のノード用に 子群変更時の手続き を定義してもよい。 このアルゴリズムは、[ ノードを子の前に挿入する/ ノードを除去する/ データを置換する ]アルゴリズム内から,引数なしで呼び出される。 Specifications may define children changed steps for all or some nodes. The algorithm is passed no argument and is called from insert, remove, and replace data.
【 そのような手続き (通例的に, “〜時の手続き” と称される) が(例えば,複数の仕様にて) 複数定義された 場合 (例えば,属性°変更時の手続きは、この仕様, HTML 仕様の各所にて定義される)、 それらを走らす順序も有意になり得るが,言及されていない (順序は有意にならないことが暗黙的に想定されているかもしれないが、 はっきりしない)。 】
親 の中で ノードを子の前に挿入する ときは、 所与の ( 挿入されるノード, 子, 観測器は抑止するか ∈ { 観測器は抑止する, ε }(省略時は ε ) ) に対し,次を走らす: To insert a node into a parent before a child, with an optional suppress observers flag, run these steps:
- ノード群 :← 挿入されるノード に応じて :文書片であるならば 挿入されるノード の子群【をクローンする】 / 他の場合は « 挿入されるノード » Let nodes be node’s children, if node is a DocumentFragment node; otherwise « node ».
- count :← ノード群 のサイズ Let count be nodes’s size.
- IF[ count = 0 ] :RETURN If count is 0, then return.
-
IF[ 挿入されるノード は文書片である ]: If node is a DocumentFragment node:
- ノード群 を成す 各( ノード ) に対し :ノードを除去する( ノード, 観測器は抑止する ) Remove its children with the suppress observers flag set.
-
挿入されるノード 用にツリー変異記録をキューする( « », ノード群, null , null ) Queue a tree mutation record for node with « », nodes, null, and null.
注記: この段では意図的に 観測器は抑止するか を無視する。 This step intentionally does not pay attention to the suppress observers flag.
-
IF[ 子 ≠ null ] :If child is non-null:
-
各( live 範囲° 範囲° ) に対し: ↓
- IF[ 範囲° の始端ノード = 親 ]∧[ 範囲° の始端オフセット > 子 の index ] :範囲° の始端オフセット += count For each live range whose start node is parent and start offset is greater than child’s index, increase its start offset by count.
- IF[ 範囲° の終端ノード = 親 ]∧[ 範囲° の終端オフセット > 子 の index † ] :範囲° の終端オフセット += count For each live range whose end node is parent and end offset is greater than child’s index, increase its end offset by count.
【† 挿入される地点にちょうど一致する[ 範囲°の境界点 ]は、 それが終端であっても,影響されないことになる — すなわち,挿入後は 挿入されたノードの直前を指す。 その結果,このアルゴリズムを利用している子をノードに置換する(後述)においては、 除去されるノードの直後または内部を指していた範囲°の境界点は, 置換後には 新たに挿入されたノードの直前を指すようになる (ノードツリーの[ 先頭/末尾 ]から相対的な範囲°の[ 始端/終端 ]の位置変化のふるまいが,対称でない — 同様のことは,データを置換するアルゴリズムにも該当する)。 】
-
- 直前の同胞 :← [ 子 ≠ null ならば 子 の直前の同胞? / 他の場合は 親 の最後の子? ] Let previousSibling be child’s previous sibling or parent’s last child if child is null.
-
ノード群 を成す 各( ノード ) に対し,ツリー順序で: For each node in nodes, in tree order:
- 親 のノード文書にノードを受入する( ノード ) Adopt node into parent’s node document.
- IF[ 子 = null ] :親 の子群に ノード を付加する If child is null, then append node to parent’s children.
- ELSE :ノード を親 の子群の中で 子 の index の前に挿入する Otherwise, insert node into parent’s children before child’s index.
-
IF[
親 は shadow ホストである
]∧[
親 の shadow 根の slot あてがいモード = "
named
" ]∧[ ノード は slot 可能である ] :slot 可能を slot にあてがう( ノード ) If parent is a shadow host whose shadow root’s slot assignment is "named" and node is a slottable, then assign a slot for node. - IF[ 親 の根は shadow 根である ]∧[ 親 は slot である ]∧[ 親 にあてがわれたノード群は空である ] :slot の変化を通達する( 親 ) If parent’s root is a shadow root, and parent is a slot whose assigned nodes is the empty list, then run signal a slot change for parent.
- ツリーに slot 可能なものをあてがう( ノード の根 ) Run assign slottables for a tree with node’s root.
-
ノード の 各( shadow も含めた広義子孫 広義子孫 ) に対し,shadow も含めたツリー順序で: For each shadow-including inclusive descendant inclusiveDescendant of node, in shadow-including tree order:
- 適用可能な仕様にて ノード 用に定義された各( 挿入時の手続き 手続き ) に対し :手続き( 広義子孫 ) Run the insertion steps with inclusiveDescendant.
- IF[ 広義子孫 は接続されていない ] :CONTINUE If inclusiveDescendant is connected:
-
IF[
広義子孫 はカスタムである
]
:カスタム要素 callback 反応をエンキューする(
広義子孫,
"
connectedCallback
", « » ) If inclusiveDescendant is custom, then enqueue a custom element callback reaction with inclusiveDescendant, callback name "connectedCallback", and « ». -
ELSE :要素を昇格するよう試行する( 広義子孫 ) Otherwise, try to upgrade inclusiveDescendant.
注記: 広義子孫 が成功裡に昇格された場合、 その
connectedCallback
は,要素を昇格するアルゴリズムの間に自動的にエンキューされる。 If this successfully upgrades inclusiveDescendant, its connectedCallback will be enqueued automatically during the upgrade an element algorithm.
- IF[ 観測器は抑止するか = ε ] :親 用にツリー変異記録をキューする( ノード群, « », 直前の同胞, 子 ) If suppress observers flag is unset, then queue a tree mutation record for parent with nodes, « », previousSibling, and child.
- 適用可能な仕様にて 親 用に定義された各( 子群変更時の手続き 手続き ) に対し :手続き() Run the children changed steps for parent.
-
静的なノードリスト :← 新たなリスト Let staticNodeList be a list of nodes, initially « ».
注記: 以下では、 接続後の手続きを call する前に,その対象になるノードすべてを収集する — ノードツリーを辿っている間に接続後の手続きを call する代わりに。 接続後の手続きは,ツリーの構造を改変し得るので、 live な辿りは安全でない — そうすると、 場合によっては,同じノードに対し接続後の手続きが複数回 call される結果に至る。 We collect all nodes before calling the post-connection steps on any one of them, instead of calling the post-connection steps while we’re traversing the node tree. This is because the post-connection steps can modify the tree’s structure, making live traversal unsafe, possibly leading to the post-connection steps being called multiple times on the same node.
-
ノード群 を成す 各( ノード ) に対し,ツリー順序で :ノード の shadow も含めた広義子孫を成す 各( 広義子孫 ) に対し,shadow も含めたツリー順序で :静的なノードリスト に 広義子孫 を付加する
【 ノード群 を成すノードどうしは, 互いに先祖, 子孫の関係にないので、 同じノードが重複して収集されることはない。 】
For each node of nodes, in tree order: • For each shadow-including inclusive descendant inclusiveDescendant of node, in shadow-including tree order, append inclusiveDescendant to staticNodeList. - 静的なノードリスト を成す 各( ノード ) に対し :IF[ ノード は接続されている ] :適用可能な仕様にて ノード 用に定義された各( 接続後の手続き 手続き ) に対し :手続き( ノード ) For each node of staticNodeList, if node is connected, then run the post-connection steps with node.
親 に ノードを付加する ときは、 所与の ( ノード ) に対し,次を走らす :親 の中でノードを子の前に前挿入する( ノード, null ) To append a node to a parent, pre-insert node into parent before null.
親 の中で 子をノードに置換する ときは、 所与の ( 子, ノード ) に対し,次を走らす: To replace a child with node within a parent, run these steps:
-
IF[
親 は[
Document
/DocumentFragment
/Element
]ノードでない ] :THROWHierarchyRequestError
If parent is not a Document, DocumentFragment, or Element node, then throw a "HierarchyRequestError" DOMException. -
IF[
ノード は 親 のホストも含めた広義先祖である
]
:THROW
HierarchyRequestError
If node is a host-including inclusive ancestor of parent, then throw a "HierarchyRequestError" DOMException. -
IF[
子 の親 ≠ 親
]
:THROW
NotFoundError
If child’s parent is not parent, then throw a "NotFoundError" DOMException. -
IF[ ノード は[
DocumentFragment
/DocumentType
/Element
/CharacterData
]ノードでない ] :THROWHierarchyRequestError
【 すなわち “
If node is not a DocumentFragment, DocumentType, Element, or CharacterData node, then throw a "HierarchyRequestError" DOMException.Document
/Attr
ノードである” (何故そのように記されない?) 】 -
IF[ ∨↓ ]…
…ならば :THROW
If either node is a Text node and parent is a document, or node is a doctype and parent is not a document, then throw a "HierarchyRequestError" DOMException.HierarchyRequestError
-
IF[ 親 は文書である ]∧[ ノード が実装するインタフェースに応じて,以下が満たされる ] :THROW
HierarchyRequestError
If parent is a document, and any of the statements below, switched on the interface node implements, are true, then throw a "HierarchyRequestError" DOMException.DocumentFragment
-
∨↓:
Element
-
∨↓:
parent has an element child that is not child or a doctype is following child. DocumentType
-
∨↓:
parent has a doctype child that is not child, or an element is preceding child.
注記: この段は,親の中で子の前に挿入できるか検証する アルゴリズムの似た段と異なる。 The above statements differ from the pre-insert algorithm.
- 基準子 :← 子 の直後の同胞? Let referenceChild be child’s next sibling.
- IF[ 基準子 = ノード ] :基準子 ← ノード の直後の同胞? If referenceChild is node, then set referenceChild to node’s next sibling.
- 直前の同胞 :← 子 の直前の同胞? Let previousSibling be child’s previous sibling.
- 除去済みノード群 :← 空集合 Let removedNodes be the empty set.
-
IF[ 子 の親 ≠ null ]: If child’s parent is non-null:
- 除去済みノード群 ← « 子 » Set removedNodes to « child ».
- ノードを除去する( 子, 観測器は抑止する ) Remove child with the suppress observers flag set.
注記: この段の条件は[ 子 = ノード ]の場合に限り,偽になる。 The above can only be false if child is node.
- ノード群 :← 挿入されるノード に応じて :文書片であるならば 挿入されるノード の子群【をクローンする】 / 他の場合は « 挿入されるノード » Let nodes be node’s children, if node is a DocumentFragment node; otherwise « node ».
- 親 の中でノードを子の前に挿入する( ノード, 基準子, 観測器は抑止する ) Insert node into parent before referenceChild with the suppress observers flag set.
- 親 用にツリー変異記録をキューする( ノード群, 除去済みノード群, 直前の同胞, 基準子 ) Queue a tree mutation record for parent with nodes, removedNodes, previousSibling, and referenceChild.
- RETURN 子 Return child.
親 の 全内容をノードで置換する ときは、 所与の ( ノード ) に対し,次を走らす: To replace all with a node within a parent, run these steps:
- 除去済みノード群 :← 親 の子群 Let removedNodes be parent’s children.
- 追加済みノード群 :← ノード に応じて,次に与える集合 : null ならば « » / 文書片であるならば ノード の子群【をクローンする】 / 他の場合は « ノード » Let addedNodes be the empty set.If node is a DocumentFragment node, then set addedNodes to node’s children.Otherwise, if node is non-null, set addedNodes to « node ».
- 親 の子群を成す 各( 子 ) に対し,ツリー順序で :ノードを除去する( 子, 観測器は抑止する ) Remove all parent’s children, in tree order, with the suppress observers flag set.
- IF[ ノード ≠ null ] :親 の中でノードを子の前に挿入する( ノード, null , 観測器は抑止する ) If node is non-null, then insert node into parent before null with the suppress observers flag set.
- IF[ 追加済みノード群 は空でない ]∨[ 除去済みノード群 は空でない ] :親 用にツリー変異記録をキューする( 追加済みノード群, 除去済みノード群, null , null ) If either addedNodes or removedNodes is not empty, then queue a tree mutation record for parent with addedNodes, removedNodes, null, and null.
注記: このアルゴリズムは ノードツリーに対する拘束を検査しない。 仕様の策定者は賢く利用すること。 This algorithm does not make any checks with regards to the node tree constraints. Specification authors need to use it wisely.
親 から 子を前除去する ときは、 所与の ( 子 ) に対し,次を走らす: To pre-remove a child from a parent, run these steps:
-
IF[
子 の親 ≠ 親
]
:THROW
NotFoundError
If child’s parent is not parent, then throw a "NotFoundError" DOMException. - ノードを除去する( 子 ) Remove child.
- RETURN 子 Return child.
適用可能な仕様は、 すべてまたは一部のノード用に 除去時の手続き を定義してもよい。 このアルゴリズムには、 ノードを除去する アルゴリズムにて指示されるとおり, ( ノード 除去されたノード, [ ノード/ null ] 旧親 ) が渡される。 Specifications may define removing steps for all or some nodes. The algorithm is passed a node removedNode and a node-or-null oldParent, as indicated in the remove algorithm below.
ノードを除去する ときは、 所与の ( ノード ノード, 観測器は抑止するか ∈ { 観測器は抑止する, ε }(省略時は ε ) ) に対し,次を走らす: To remove a node node, with an optional suppress observers flag, run these steps:
- 親 :← ノード の親 Let parent be node’s parent.
- Assert: 親 ≠ null Assert: parent is non-null.
- index :← ノード の index Let index be node’s index.
-
各( live 範囲° 範囲° ) に対し: ↓
- IF[ 範囲° の始端ノード は ノード の広義子孫である ] :範囲° の始端ノード ← 親; 範囲° の始端オフセット ← index For each live range whose start node is an inclusive descendant of node, set its start to (parent, index).
- IF[ 範囲° の終端ノード は ノード の広義子孫である ] :範囲° の終端ノード ← 親; 範囲° の終端オフセット ← index For each live range whose end node is an inclusive descendant of node, set its end to (parent, index).
- IF[ 範囲° の始端ノード = 親 ]∧[ 範囲° の始端オフセット > index ] :範囲° の始端オフセット −= 1 For each live range whose start node is parent and start offset is greater than index, decrease its start offset by 1.
- IF[ 範囲° の終端ノード = 親 ]∧[ 範囲° の終端オフセット > index ] :範囲° の終端オフセット −= 1 For each live range whose end node is parent and end offset is greater than index, decrease its end offset by 1.
-
各(
NodeIterator
オブジェクト 反復器 ) に対し :IF[ 反復器 の根のノード文書 = ノード のノード文書 ] :ノード反復器用の前除去する手続き( 反復器, ノード ) For each NodeIterator object iterator whose root’s node document is node’s node document, run the NodeIterator pre-remove steps given node and iterator. - 直前の同胞 :← ノード の直前の同胞? Let oldPreviousSibling be node’s previous sibling.
- 直後の同胞 :← ノード の直後の同胞? Let oldNextSibling be node’s next sibling.
- ノード を 親 の子群から除去する Remove node from its parent’s children.
- IF[ ノード のあてがい先 slot ≠ null ] :slot に slot 可能なものをあてがう( その slot ) If node is assigned, then run assign slottables for node’s assigned slot.
- IF[ 親 の根は shadow 根である ]∧[ 親 は slot である ]∧[ 親 にあてがわれたノード群は空である ] :slot の変化を通達する( 親 ) If parent’s root is a shadow root, and parent is a slot whose assigned nodes is the empty list, then run signal a slot change for parent.
-
IF[[ ノード の広義子孫のうち,slot であるもの ]は在る ]: If node has an inclusive descendant that is a slot:
- ツリーに slot 可能なものをあてがう( 親 の根 ) Run assign slottables for a tree with parent’s root.
- ツリーに slot 可能なものをあてがう( ノード ) Run assign slottables for a tree with node.
- 適用可能な仕様にて ノード 用に定義された各( 除去時の手続き 手続き ) に対し :手続き( ノード, 親 ) Run the removing steps with node and parent.
- 親は接続されているか :← IS[ 親 は接続されている ] Let isParentConnected be parent’s connected.
-
IF[ ノード はカスタムである ]∧[ 親は接続されているか = true ] :カスタム要素 callback 反応をエンキューする( ノード, "
disconnectedCallback
", « » ) If node is custom and isParentConnected is true, then enqueue a custom element callback reaction with node, callback name "disconnectedCallback", and « ».注記: 今の所,カスタムである要素には 親 を渡さないのは意図的であるが、 将来に必要になった場合は変更され得る。 It is intentional for now that custom elements do not get parent passed. This might change in the future if there is a need.
-
ノード の 各( shadow も含めた子孫 子孫 ) に対し,shadow も含めたツリー順序で: For each shadow-including descendant descendant of node, in shadow-including tree order:
- 適用可能な仕様にて 子孫 用に定義された各( 除去時の手続き 手続き ) に対し :手続き( 子孫, null ) Run the removing steps with descendant and null.
-
IF[
子孫 はカスタムである
]∧[
親は接続されているか = true
]
:カスタム要素 callback 反応をエンキューする(
子孫,
"
disconnectedCallback
", « » ) If descendant is custom and isParentConnected is true, then enqueue a custom element callback reaction with descendant, callback name "disconnectedCallback", and « ».
-
親 の
各( 広義先祖 広義先祖 )
に対し
:広義先祖 の登録済み観測器リストを成す
各( 登録済み )
に対し
:IF[
登録済み のオプション群[ "
subtree
" ] = true ] :ノード の登録済み観測器リストに 次を付加する :新たな一時登録済み観測器 — その :観測器 ← 登録済み の観測器, オプション群 ← 登録済み のオプション群, ソース ← 登録済み For each inclusive ancestor inclusiveAncestor of parent, and then for each registered of inclusiveAncestor’s registered observer list, if registered’s options["subtree"] is true, then append a new transient registered observer whose observer is registered’s observer, options is registered’s options, and source is registered to node’s registered observer list. - IF[ 観測器は抑止するか = ε ] :親 用にツリー変異記録をキューする( « », « ノード », 直前の同胞, 直後の同胞 ) If suppress observers flag is unset, then queue a tree mutation record for parent with « », « node », oldPreviousSibling, and oldNextSibling.
- 適用可能な仕様にて 親 用に定義された各( 子群変更時の手続き 手続き ) に対し :手続き() Run the children changed steps for parent.
4.2.4. NonElementParentNode
mixin
注記:
Web 互換性のため、
getElementById()
メソッドは,要素 上には(したがって ParentNode
上にも)公開できない。
Web compatibility prevents the getElementById() method from being exposed on elements (and therefore on ParentNode).
interface mixin NonElementParentNode {
Element? getElementById(DOMString elementId);
};
Document includes NonElementParentNode;
DocumentFragment includes NonElementParentNode;
- node .
getElementById(elementId)
- node の子孫である要素のうち[ ID = elementId ]を満たす最初のもの?を返す。 Returns the first element within node’s descendants whose ID is elementId.
getElementById(elementId)
メソッド手続きは
:RETURN 次を満たすノードのうち,最初のもの?
:[
これ°の子孫である
]∧[
要素である
]∧[
ID ( ≠ ε ) = elementId
]
The getElementById(elementId) method steps are to return the first element, in tree order, within this’s descendants, whose ID is elementId; otherwise, if there is no such element, null.4.2.5. DocumentOrShadowRoot
mixin
interface mixin DocumentOrShadowRoot {
};
Document includes DocumentOrShadowRoot;
ShadowRoot includes DocumentOrShadowRoot;
注記:
DocumentOrShadowRoot
mixin は、[
文書, shadow 根
]で共有される API を定義したいと求める他の標準により利用されることが期待されている。
The DocumentOrShadowRoot mixin is expected to be used by other standards that want to define APIs shared between documents and shadow roots.
4.2.6. ParentNode
mixin
ノード群をノードに変換する 手続きは、 所与の ( リスト ノード群, 文書 文書 ) に対し: To convert nodes into a node, given nodes and document, run these steps:
- 変換済みノード群 :← « » ↓ Let node be null.↓
-
ノード群 を成す 各( アイテム ) に対し:
-
IF[
アイテム は文字列である
]
:アイテム ← 新たな
Text
ノード( アイテム のデータ, 文書 ) - Assert: アイテム はノードである。
- 変換済みノード群 に アイテム を付加する
-
IF[
アイテム は文字列である
]
:アイテム ← 新たな
- IF[ 変換済みノード群 のサイズ = 1 ] :RETURN 変換済みノード群[ 0 ] If nodes contains one node, then set node to nodes[0].Otherwise,\
- 文書片 :← 新たな文書片 — その :ノード文書 ← 文書 set node to a new DocumentFragment node whose node document is document,\
- 変換済みノード群 を成す 各( ノード ) に対し :文書片 にノードを付加する( ノード ) and then append each node in nodes, if any, to it.
- RETURN 文書片 Return node.
interface mixin ParentNode {
[SameObject] readonly attribute HTMLCollection children;
readonly attribute Element? firstElementChild;
readonly attribute Element? lastElementChild;
readonly attribute unsigned long childElementCount;
[CEReactions, Unscopable] undefined prepend((Node or DOMString)... nodes);
[CEReactions, Unscopable] undefined append((Node or DOMString)... nodes);
[CEReactions, Unscopable] undefined replaceChildren((Node or DOMString)... nodes);
Element? querySelector(DOMString selectors);
[NewObject] NodeList querySelectorAll(DOMString selectors);
};
Document includes ParentNode;
DocumentFragment includes ParentNode;
Element includes ParentNode;
- collection = node .
children
- 子である要素をすべて返す。 Returns the child elements.
- element = node .
firstElementChild
- 子である要素のうち,最初のもの?を返す。 Returns the first child that is an element; otherwise null.
- element = node .
lastElementChild
- 子である要素のうち,最後のもの?を返す。 Returns the last child that is an element; otherwise null.
- node .
prepend(nodes)
-
nodes 内の各 文字列は等価な
Text
ノードに置換した上で、 nodes を node の最初の子?の前に挿入する。 Inserts nodes before the first child of node, while replacing strings in nodes with equivalent Text nodes. -
ノードツリーに対する拘束に反する場合、
HierarchyRequestError
が投出される。 Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. - node .
append(nodes)
-
nodes 内の各 文字列は等価な
Text
ノードに置換した上で、 nodes を node の最後の子?の後に挿入する。 Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes. -
ノードツリーに対する拘束に反する場合、
HierarchyRequestError
が投出される。 Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. - node .
replaceChildren(nodes)
-
nodes 内の各 文字列は等価な
Text
ノードに置換した上で、 node の子群すべてを nodes で置換する。 Replace all children of node with nodes, while replacing strings in nodes with equivalent Text nodes. -
ノードツリーに対する拘束に反する場合、
HierarchyRequestError
が投出される。 Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. - node .
querySelector(selectors)
- node の子孫であって, selectors に合致する要素のうち,最初のもの?を返す。 Returns the first element that is a descendant of node that matches selectors.
- node .
querySelectorAll(selectors)
- node の子孫であって, selectors に合致する,すべての要素を返す。 Returns all element descendants of node that match selectors.
children
取得子手続きは
:RETURN 次のように設定された HTMLCollection
コレクション
:根 ← これ°,
フィルタは これ°の子である要素のみに合致する
The children getter steps are to return an HTMLCollection collection rooted at this matching only element children.firstElementChild
取得子手続きは
:RETURN これ°の子である要素のうち,最初のもの?
The firstElementChild getter steps are to return the first child that is an element; otherwise null.lastElementChild
取得子手続きは
:RETURN これ°の子である要素のうち,最後のもの?
The lastElementChild getter steps are to return the last child that is an element; otherwise null.childElementCount
取得子手続きは
:RETURN これ°の子である要素の個数
The childElementCount getter steps are to return the number of children of this that are elements.
prepend(nodes)
メソッド手続きは:
The prepend(nodes) method steps are:
- ノード :← ノード群をノードに変換する( nodes, これ°のノード文書 ) Let node be the result of converting nodes into a node given nodes and this’s node document.
- これ°の中でノードを子の前に前挿入する( ノード, これ°の最初の子? ) Pre-insert node into this before this’s first child.
append(nodes)
メソッド手続きは:
The append(nodes) method steps are:
- ノード :← ノード群をノードに変換する( nodes, これ°のノード文書 ) Let node be the result of converting nodes into a node given nodes and this’s node document.
- これ°にノードを付加する( ノード ) Append node to this.
replaceChildren(nodes)
メソッド手続きは:
The replaceChildren(nodes) method steps are:
- ノード :← ノード群をノードに変換する( nodes, これ°のノード文書 ) Let node be the result of converting nodes into a node given nodes and this’s node document.
- 親の中で子の前に挿入できるか検証する( ノード, これ°, null ) Ensure pre-insert validity of node into this before null.
- これ°の全内容をノードで置換する( ノード ) Replace all with node within this.
querySelector(selectors)
メソッド手続きは
:RETURN 次の結果を成す要素のうち,最初のもの?
:これ°の視野の下で選択子を照合する( selectors )
The querySelector(selectors) method steps are to return the first result of running scope-match a selectors string selectors against this, if the result is not an empty list; otherwise null.querySelectorAll(selectors)
メソッド手続きは、
次の結果を静的なものとして返す
:これ°の視野の下で選択子を照合する( selectors )
The querySelectorAll(selectors) method steps are to return the static result of running scope-match a selectors string selectors against this.4.2.7. NonDocumentTypeChildNode
mixin
注記:
Web 互換性のため、
previousElementSibling
, nextElementSibling
属性は,doctype 上には(したがって, ChildNode
上にも)公開できない。
Web compatibility prevents the previousElementSibling and nextElementSibling attributes from being exposed on doctypes (and therefore on ChildNode).
interface mixin NonDocumentTypeChildNode {
readonly attribute Element? previousElementSibling;
readonly attribute Element? nextElementSibling;
};
Element includes NonDocumentTypeChildNode;
CharacterData includes NonDocumentTypeChildNode;
- element = node .
previousElementSibling
- 先行する同胞の要素のうち,最後のもの?を返す。 Returns the first preceding sibling that is an element; otherwise null.
- element = node .
nextElementSibling
- 後続する同胞の要素のうち,最初のもの?を返す。 Returns the first following sibling that is an element; otherwise null.
4.2.8. ChildNode
mixin
interface mixin ChildNode {
[CEReactions, Unscopable] undefined before((Node or DOMString)... nodes);
[CEReactions, Unscopable] undefined after((Node or DOMString)... nodes);
[CEReactions, Unscopable] undefined replaceWith((Node or DOMString)... nodes);
[CEReactions, Unscopable] undefined remove();
};
DocumentType includes ChildNode;
Element includes ChildNode;
CharacterData includes ChildNode;
- node .
before
(...nodes) -
nodes 内の各 文字列は等価な
Text
ノードに置換した上で、 nodes を node の直前に挿入する。 Inserts nodes just before node, while replacing strings in nodes with equivalent Text nodes. -
ノードツリーに対する拘束に反する場合、
HierarchyRequestError
が投出される。 Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. - node .
after
(...nodes) -
nodes 内の各 文字列は等価な
Text
ノードに置換した上で、 nodes を node の直後に挿入する。 Inserts nodes just after node, while replacing strings in nodes with equivalent Text nodes. -
ノードツリーに対する拘束に反する場合、
HierarchyRequestError
が投出される。 Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. - node .
replaceWith
(...nodes) -
nodes 内の各 文字列は等価な
Text
ノードに置換した上で、 node を nodes に置換する。 Replaces node with nodes, while replacing strings in nodes with equivalent Text nodes. -
ノードツリーに対する拘束に反する場合、
HierarchyRequestError
が投出される。 Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. - node .
remove()
- node を除去する。 Removes node.
before(nodes)
メソッド手続きは:
The before(nodes) method steps are:
- 親 :← これ°の親 Let parent be this’s parent.
- IF[ 親 = null ] :RETURN If parent is null, then return.
- およそ直前の同胞 :← 次を満たすノードのうち,最後のもの? :[ これ°の同胞である ]∧[ これ°に先行する ]∧[ ノード ∉ nodes に与えられた引数たちが成す集合 ] Let viablePreviousSibling be this’s first preceding sibling not in nodes; otherwise null.
- ノード :← ノード群をノードに変換する( nodes, これ°のノード文書 ) Let node be the result of converting nodes into a node, given nodes and this’s node document.
- およそ直前の同胞 ← およそ直前の同胞 に応じて : null ならば 親 の最初の子? / 他の場合は およそ直前の同胞 の直後の同胞? If viablePreviousSibling is null, then set it to parent’s first child; otherwise to viablePreviousSibling’s next sibling.
- 親 の中でノードを子の前に前挿入する( ノード, およそ直前の同胞 ) Pre-insert node into parent before viablePreviousSibling.
after(nodes)
メソッド手続きは:
The after(nodes) method steps are:
- 親 :← これ°の親 Let parent be this’s parent.
- IF[ 親 = null ] :RETURN If parent is null, then return.
- およそ直後の同胞 :← 次を満たすノードのうち,最初のもの? :[ これ°の同胞である ]∧[ これ°に後続する ]∧[ ノード ∉ nodes に与えられた引数たちが成す集合 ] Let viableNextSibling be this’s first following sibling not in nodes; otherwise null.
- ノード :← ノード群をノードに変換する( nodes, これ°のノード文書 ) Let node be the result of converting nodes into a node, given nodes and this’s node document.
- 親 の中でノードを子の前に前挿入する( ノード, およそ直後の同胞 ) Pre-insert node into parent before viableNextSibling.
replaceWith(nodes)
メソッド手続きは:
The replaceWith(nodes) method steps are:
- 親 :← これ°の親 Let parent be this’s parent.
- IF[ 親 = null ] :RETURN If parent is null, then return.
- およそ直後の同胞 :← 次を満たすノードのうち,最初のもの? :[ これ°の同胞である ]∧[ これ°に後続する ]∧[ ノード ∉ nodes に与えられた引数たちが成す集合 ] Let viableNextSibling be this’s first following sibling not in nodes; otherwise null.
- ノード :← ノード群をノードに変換する( nodes, これ°のノード文書 ) Let node be the result of converting nodes into a node, given nodes and this’s node document.
-
IF[ これ°の親 = 親 ] :親 の中で子をノードに置換する( これ°, ノード ) If this’s parent is parent, replace this with node within parent.
注記: これ°は ノード の中に挿入されていることもある。 This could have been inserted into node.
- ELSE :親 の中でノードを子の前に前挿入する( ノード, およそ直後の同胞 ) Otherwise, pre-insert node into parent before viableNextSibling.
4.2.9. Slottable
mixin
interface mixin Slottable {
readonly attribute HTMLSlotElement? assignedSlot;
};
Element includes Slottable;
Text includes Slottable;
assignedSlot
取得子手続きは
:RETURN slot 可能用に slot を見出す( これ°, open )
The assignedSlot getter steps are to return the result of find a slot given this and with the open flag set.4.2.10. 旧式なコレクション: NodeList
と HTMLCollection
コレクション は、 ノードたちが成すリストを表現するオブジェクトである。 コレクションは live にも 静的 にもなり得る。 他が言明されない限り、 コレクションは live になるものとする。 A collection is an object that represents a list of nodes. A collection can be either live or static. Unless otherwise stated, a collection must be live.
live であるコレクションの[ 属性/メソッド ]は、 データのスナップショットではなく 実際の下層データ†に対し,演算するものとする††。 If a collection is live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.
【† すなわち、 作成時のデータ(スナップショット)ではなく,アクセスされた時点におけるデータ 】【†† したがって,コレクションを辿っている間にツリーを改変するときは、 コレクションの無限増殖に陥いらないよう注意する必要がある。 】【 静的とされている場合は,逆に、 データのスナップショットに対し演算することになる。 】
各 コレクションの作成時には、 次に挙げるものが結び付けられる:
- 根 :コレクションの視野を与える。
- フィルタ :ノードがコレクションに含められるための条件を与える。
コレクションは、 その根を根とする下位ツリーの中で[ 所与のフィルタに合致するノードのみ ]を包含するようなビューを 表現 する。 このビューは全順序である — コレクションに含められるノードたちは、 他の要件が指定されない限り,ツリー順序でソートするものとする。 The collection then represents a view of the subtree rooted at the collection’s root, containing only nodes that match the given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes within the collection must be sorted in tree order.
【
ほとんどのコレクションでは,根自身はフィルタに合致しないが、
NodeIterator
の反復器コレクションなど,そうでないものもある。
】
4.2.10.1. NodeList
インタフェース
NodeList
オブジェクトはノードのコレクションである。
A NodeList object is a collection of nodes.
[Exposed=Window]
interface NodeList {
getter Node? item(unsigned long index);
readonly attribute unsigned long length;
iterable<Node>;
};
- collection .
length
- コレクションに含まれているノードの個数を返す。 Returns the number of nodes in the collection.
- element = collection .
item(index)
- element = collection[index]
- ツリー順序にソートされた下で、 コレクションの中で, index 番のノードを返す。 Returns the node with index index from the collection. The nodes are sorted in tree order.
コレクション O がサポートするプロパティ index は、 0 以上[ O が表現するノードの個数 ]未満とする。 The object’s supported property indices are the numbers in the range zero to one less than the number of nodes represented by the collection. If there are no such elements, then there are no supported property indices.
length
取得子手続きは
:RETURN これ°が表現するノードの個数
The length attribute must return the number of nodes represented by the collection.item(index)
メソッド手続きは
:RETURN [
index ∉ { これ°がサポートするプロパティ index } ならば null /
他の場合は これ°の中の index 番のノード
]
The item(index) method must return the indexth node in the collection. If there is no indexth node in the collection, then the method must return null.4.2.10.2. HTMLCollection
インタフェース
[Exposed=Window,
LegacyUnenumerableNamedProperties]
interface HTMLCollection {
readonly attribute unsigned long length;
getter Element? item(unsigned long index);
getter Element? namedItem(DOMString name);
};
HTMLCollection
オブジェクトは要素のコレクションである。
An HTMLCollection object is a collection of elements.
注記:
HTMLCollection
は、
歴史的な理由から廃するわけにいかない所産である。
開発者は それを利用し続けても構わないが、
新たな API 標準の設計者は それを利用しないこと
(代わりに IDL
型を利用すること)。
HTMLCollection is a historical artifact we cannot rid the web of. While developers are of course welcome to keep using it, new API standard designers ought not to use it (use sequence<T> in IDL instead).sequence
<T>
- collection .
length
- コレクションに含まれている要素の個数を返す。 Returns the number of elements in the collection.
- element = collection .
item(index)
- element = collection[index]
- 要素たちをツリー順序にソートした下での、 コレクションの中で index 番の要素を返す。 Returns the element with index index from the collection. The elements are sorted in tree order.
- element = collection .
namedItem(name)
- element = collection[name]
- コレクションの中で[ ID または名前 ]が name に一致する最初の要素を返す。 Returns the first element with ID or name name from the collection.
コレクション O がサポートするプロパティ index は、 0 以上[ O が表現する要素の個数 ]未満とする。 The object’s supported property indices are the numbers in the range zero to one less than the number of elements represented by the collection. If there are no such elements, then there are no supported property indices.
length
取得子手続きは
:RETURN これ°が表現するノードの個数
The length getter steps are to return the number of nodes represented by the collection.item(index)
メソッド手続きは
:RETURN [
index ∉ { これ°がサポートするプロパティ index } ならば null /
他の場合は これ°の中の index 番のノード
]
The item(index) method steps are to return the indexth element in the collection. If there is no indexth element in the collection, then the method must return null.コレクション O がサポートするプロパティ名たちは、 次の手続きの結果で与えられる: The supported property names are the values from the list returned by these steps:
- 結果 :← « » Let result be an empty list.
-
O が表現する 各( 要素 要素 ) に対し,ツリー順序で: For each element represented by the collection, in tree order:
- ID :← 要素 の ID ↓
- IF[ ID ≠ ε ]∧[ ID ∉ 結果 ] :結果 に ID を付加する If element has an ID which is not in result, append element’s ID to result.
-
IF[
要素 は HTML 名前空間に属する
]∧[
要素 の属性°リスト内に
name
属性°は在る ]∧[ その属性°の値 name ≠ 空文字列 ]∧[ name ∉ 結果 ] :結果 に name を付加する If element is in the HTML namespace and has a name attribute whose value is neither the empty string nor is in result, append element’s name attribute value to result.
- RETURN 結果 Return result.
namedItem(name)
メソッド手続きは:
The namedItem(key) method steps are:
- IF[ name = 空文字列 ] :RETURN null If key is the empty string, return null.
-
RETURN これ°が表現する要素たちのうち, ∨↓ を満たす最初のもの?:
Return the first element in the collection for which at least one of the following is true: • it has an ID which is key; • it is in the HTML namespace and has a name attribute whose value is key;or null if there is no such element.
4.3. 変異観測器
各 生成元が類似な window agent [HTML] には、 次に挙げるものが結び付けられる: ↓
- 変異観測器の小タスクはキューされたか :真偽値 — 初期時は false とする。 Each similar-origin window agent has a mutation observer microtask queued (a boolean), which is initially false. [HTML]
-
処理待ち変異観測器群
:
MutationObserver
オブジェクトたちが成す有順序集合 — 初期時は空とする。 Each similar-origin window agent also has pending mutation observers (a set of zero or more MutationObserver objects), which is initially empty.
変異観測器 小タスクをキューする ときは、 次を走らす: To queue a mutation observer microtask, run these steps:
- IF[ surrounding agent の変異観測器の小タスクはキューされたか = true ] :RETURN If the surrounding agent’s mutation observer microtask queued is true, then return.
- surrounding agent の変異観測器の小タスクはキューされたか ← true Set the surrounding agent’s mutation observer microtask queued to true.
- 小タスクをキューする( 変異観測器に通知する手続き ) Queue a microtask to notify mutation observers.
変異観測器に通知する ときは、 次を走らす: To notify mutation observers, run these steps:
- surrounding agent の変異観測器の小タスクはキューされたか ← false Set the surrounding agent’s mutation observer microtask queued to false.
- 通知集合 :← surrounding agent の処理待ち変異観測器群をクローンする Let notifySet be a clone of the surrounding agent’s pending mutation observers.
- surrounding agent の処理待ち変異観測器群を空にする Empty the surrounding agent’s pending mutation observers.
- 通達 slot 集合 :← surrounding agent の通達 slot 群をクローンする Let signalSet be a clone of the surrounding agent’s signal slots.
- surrounding agent の通達 slot 群を空にする Empty the surrounding agent’s signal slots.
-
通知集合 を成す 各( MO ) に対し: For each mo of notifySet:
- 記録群 :← MO の記録キューをクローンする Let records be a clone of mo’s record queue.
- MO の記録キューを空にする Empty mo’s record queue.
- MO のノードリストを成す 各( ノード ) に対し :ノード の登録済み観測器リストから 次を満たす一時登録済み観測器をすべて除去する :その観測器 = MO For each node of mo’s node list, remove all transient registered observers whose observer is mo from node’s registered observer list.
- IF[ 記録群 は空でない ] :callback 関数を呼び出す( MO の callback , « 記録群, MO », 報告する, MO ) If records is not empty, then invoke mo’s callback with « records, mo » and "report", and with callback this value mo.
-
通達 slot 集合 を成す
各( slot slot )
に対し
:イベントを発火する( slot ,
slotchange
) — 次のように初期化して :bubbles
属性 ← true For each slot of signalSet, fire an event named slotchange, with its bubbles attribute set to true, at slot.
各 ノードには、 登録済み観測器リスト が結び付けられる — それは、 登録済み観測器たちが成すリストであり,初期時は空とする。 【このノードにおける変異を観測している観測器たちを表す。】 Each node has a registered observer list (a list of zero or more registered observers), which is initially empty.
各 登録済み観測器 は、 次に挙げるものからなる:
-
観測器
:
MutationObserver
オブジェクト -
オプション群
:
MutationObserverInit
辞書
一時登録済み観測器 は、 上述に加えて 次に挙げるものも有する,登録済み観測器である:
- ソース :登録済み観測器
注記:
一時登録済み観測器は、
所与のノードに対し,それが除去された後もノードの子孫における変異を追跡するために利用される
— これにより、
ノードの親にて subtree
が true に設定されたときでも,それらの変異は失われずに済む。
Transient registered observers are used to track mutations within a given node’s descendants after node has been removed so they do not get lost when subtree is set to true on node’s parent.
4.3.1. MutationObserver
インタフェース
[Exposed=Window]
interface MutationObserver {
constructor(MutationCallback callback);
undefined observe(Node target, optional MutationObserverInit options = {});
undefined disconnect();
sequence<MutationRecord> takeRecords();
};
callback MutationCallback = undefined (sequence<MutationRecord> mutations, MutationObserver observer);
dictionary MutationObserverInit {
boolean childList = false;
boolean attributes;
boolean characterData;
boolean subtree = false;
boolean attributeOldValue;
boolean characterDataOldValue;
sequence<DOMString> attributeFilter;
};
MutationObserver
オブジェクトを利用すれば、
ノードが成すツリーにおける変異を観測できる。
A MutationObserver object can be used to observe mutations to the tree of nodes.
各 MutationObserver
オブジェクトには、
次に挙げる概念が結び付けられる:
Each MutationObserver object has these associated concepts:
- callback :callback 関数。 オブジェクトの作成時に設定される。 A callback set on creation.
- ノードリスト :[ ノードへの弱い参照 ]たちが成すリスト — 初期時は空とする。 A node list (a list of weak references to nodes), which is initially empty.
-
記録キュー
:
MutationRecord
オブジェクトたちが成すキュー — 初期時は空とする。 A record queue (a queue of zero or more MutationRecord objects), which is initially empty.
- observer =
new MutationObserver(callback)
-
MutationObserver
オブジェクトを構築し,その callback を callback に設定する。 callback は、 その 1 個目, 2 個目の引数に (MutationRecord
オブジェクトたちが成すリスト, 構築された observer ) が渡されて呼び出される。 callback は、observe()
メソッドにより登録済みにされたノードが変異したとき(した後)に,呼び出される。 Constructs a MutationObserver object and sets its callback to callback. The callback is invoked with a list of MutationRecord objects as first argument and the constructed MutationObserver object as second argument. It is invoked after nodes registered with the observe() method, are mutated. - observer .
observe(target, options)
- target ( ノード )を観測して, options ( オブジェクト)に与えた判定基準に基づいて変異を報告するよう、 UA に指図する。 Instructs the user agent to observe a given target (a node) and report any mutations based on the criteria given by options (an object).
-
options 引数に与えたオブジェクトの各メンバを介して,観測させる変異についてのオプションを設定できる。 利用できるオブジェクトメンバは: The options argument allows for setting mutation observation options via object members. These are the object members that can be used:
childList
- target の子群の変異を観測するときは、 true にする。 Set to true if mutations to target’s children are to be observed.
attributes
-
target の属性°の変異を観測するときは、
true にする。
attributeOldValue
またはattributeFilter
を指定している場合は、 省略できる。 Set to true if mutations to target’s attributes are to be observed. Can be omitted if attributeOldValue or attributeFilter is specified. characterData
-
target のデータの変異を観測するときは、
true にする。
characterDataOldValue
を指定している場合は、 省略できる。 Set to true if mutations to target’s data are to be observed. Can be omitted if characterDataOldValue is specified. subtree
- target のみならず, target の子孫の変異も観測するときは、 true にする。 Set to true if mutations to not just target, but also target’s descendants are to be observed.
attributeOldValue
-
attributes
を true にしているか省略していて,かつ 変異前の target の属性° 値を記録しておく必要がある場合は、 true にする。 Set to true if attributes is true or omitted and target’s attribute value before the mutation needs to be recorded. characterDataOldValue
-
characterData
を true にしているか省略していて,かつ 変異前の target のデータを記録しておく必要がある場合は、 true にする。 Set to true if characterData is set to true or omitted and target’s data before the mutation needs to be recorded. attributeFilter
-
attributes
を true にしているか省略していて,かつ すべての属性°の変異を観測する必要はない場合は、 必要な属性°の(名前空間 のない)局所名たちが成すリストを与える。 Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted.
- observer .
disconnect()
-
observer による変異の観測を停止する。
observe()
メソッドが再び利用されるまで, observer の callback は呼び出されないことになる。 Stops observer from observing any mutations. Until the observe() method is used again, observer’s callback will not be invoked. - observer .
takeRecords()
- 記録キューを空にして,空にする前の内容を返す。 Empties the record queue and returns what was in there.
new MutationObserver(callback)
構築子手続きは
:これ°の callback ← callback
The new MutationObserver(callback) constructor steps are to set this’s callback to callback.
observe(target, options)
メソッド手続きは:
The observe(target, options) method steps are:
-
IF[[
options[ "
attributeOldValue
" ] ≠ ε ]∨[ options[ "attributeFilter
" ] ≠ ε ]]∧[ options[ "attributes
" ] = ε ] :options[ "attributes
" ] ← true If either options["attributeOldValue"] or options["attributeFilter"] exists, and options["attributes"] does not exist, then set options["attributes"] to true. -
IF[
options[ "
characterDataOldValue
" ] ≠ ε ]∧[ options[ "characterData
" ] = ε ] :options[ "characterData
" ] ← true If options["characterDataOldValue"] exists and options["characterData"] does not exist, then set options["characterData"] to true. -
IF[ ∨↓ ]… ↓
-
[
options[ "
childList
" ] = false ]∧[ options[ "attributes
" ] = false ]∧[ options[ "characterData
" ] = false ] If none of options["childList"], options["attributes"], and options["characterData"] is true, then throw a TypeError. -
[
options[ "
attributeOldValue
" ] = true ]∧[ options[ "attributes
" ] = false ] If options["attributeOldValue"] is true and options["attributes"] is false, then throw a TypeError. -
[
options[ "
attributeFilter
" ] ≠ ε ]∧[ options[ "attributes
" ] = false ] If options["attributeFilter"] is present and options["attributes"] is false, then throw a TypeError. -
[
options[ "
characterDataOldValue
" ] = true ]∧[ options[ "characterData
" ] = false ] If options["characterDataOldValue"] is true and options["characterData"] is false, then throw a TypeError.
…ならば :THROW
TypeError
↑ -
[
options[ "
- 登録済みリスト :← target の登録済み観測器リスト内の次を満たす登録済み観測器たちが成すリスト :その観測器 = これ° For each registered of target’s registered observer list, if registered’s observer is this:
-
登録済みリスト を成す 各( 登録済み ) に対し: ↑
-
IF[ 登録済みリスト は空である ]: Otherwise:
disconnect()
メソッド手続きは:
The disconnect() method steps are:
4.3.2. 変異記録のキュー法
ターゲット 用に ある 種別 の 変異記録をキューする ときは、 所与の ( 名前, 名前空間, 旧値, 追加済みノード群, 除去済みノード群, 直前の同胞, 直後の同胞 ) に対し,次を走らす: To queue a mutation record of type for target with name, namespace, oldValue, addedNodes, removedNodes, previousSibling, and nextSibling, run these steps:
- 有関係観測器群 :← 新たなマップ Let interestedObservers be an empty map.
- nodes :← ターゲット のすべての広義先祖 Let nodes be the inclusive ancestors of target.
-
nodes を成す 各( ノード ) に対し 【順序は?】 :ノード の登録済み観測器リストを成す 各( 登録済み ) に対し: For each node in nodes, and then for each registered of node’s registered observer list:
- options :← 登録済み のオプション群 Let options be registered’s options.
-
IF[ ∨↓ ]… If none of the following are true
-
[
ノード ≠ ターゲット
]∧[
options[ "
subtree
" ] = false ] node is not target and options["subtree"] is false -
[
種別 = "
attributes
" ]∧[ options[ "attributes
" ] ≠ true ] type is "attributes" and options["attributes"] either does not exist or is false -
[
種別 = "
attributes
" ]∧[ options[ "attributeFilter
" ] ≠ ε ]∧[[ 名前 ∉ options[ "attributeFilter
" ] ]∨[ 名前空間 ≠ null ]] type is "attributes", options["attributeFilter"] exists, and options["attributeFilter"] does not contain name or namespace is non-null -
[
種別 = "
characterData
" ]∧[ options[ "characterData
" ] ≠ true ] type is "characterData" and options["characterData"] either does not exist or is false -
[
種別 = "
childList
" ]∧[ options[ "childList
" ] = false ] type is "childList" and options["childList"] is false
…ならば :CONTINUE then:
-
[
ノード ≠ ターゲット
]∧[
options[ "
- MO :← 登録済み の観測器 Let mo be registered’s observer.
- IF[ 有関係観測器群[ MO ] = ε ] :有関係観測器群[ MO ] ← null If interestedObservers[mo] does not exist, then set interestedObservers[mo] to null.
-
IF[ ∨↓ ]… If either\
-
[
種別 = "
attributes
" ]∧[ options[ "attributeOldValue
" ] = true ] type is "attributes" and options["attributeOldValue"] is true,\ -
[
種別 = "
characterData
" ]∧[ options[ "characterDataOldValue
" ] = true ] or type is "characterData" and options["characterDataOldValue"] is true,\
…ならば :有関係観測器群[ MO ] ← 旧値 then set interestedObservers[mo] to oldValue.
-
[
種別 = "
-
有関係観測器群 を成す 各( 観測器 → マップ先の旧値 ) に対し: For each observer → mappedOldValue of interestedObservers:
-
記録 :← 新たなオブジェクト(
MutationRecord
) — その :type
← 種別,target
← ターゲット,attributeName
← 名前,attributeNamespace
← 名前空間,oldValue
← マップ先の旧値,addedNodes
← 追加済みノード群,removedNodes
← 除去済みノード群,previousSibling
← 直前の同胞,nextSibling
← 直後の同胞, Let record be a new MutationRecord object with its type set to type, target set to target, attributeName set to name, attributeNamespace set to namespace, oldValue set to mappedOldValue, addedNodes set to addedNodes, removedNodes set to removedNodes, previousSibling set to previousSibling, and nextSibling set to nextSibling. - 観測器 の記録キューに 記録 をエンキューする Enqueue record to observer’s record queue.
- surrounding agent の処理待ち変異観測器群に 観測器 を付加する Append observer to the surrounding agent’s pending mutation observers.
-
記録 :← 新たなオブジェクト(
- 変異観測器 小タスクをキューする Queue a mutation observer microtask.
ターゲット 用に ツリー変異記録をキューする ときは、 所与の ( 追加済みノード群, 除去済みノード群, 直前の同胞, 直後の同胞 ) に対し,次を走らす: To queue a tree mutation record for target with addedNodes, removedNodes, previousSibling, and nextSibling, run these steps:
- Assert: [ 追加済みノード群 は空でない ]∨[ 除去済みノード群 は空でない ] Assert: either addedNodes or removedNodes is not empty.
-
ターゲット 用に種別 "
childList
" の変異記録をキューする( ↓ ) : null , null , null , 追加済みノード群, 除去済みノード群, 直前の同胞, 直後の同胞 Queue a mutation record of "childList" for target with null, null, null, addedNodes, removedNodes, previousSibling, and nextSibling.
4.3.3. MutationRecord
インタフェース
[Exposed=Window]
interface MutationRecord {
readonly attribute DOMString type;
[SameObject] readonly attribute Node target;
[SameObject] readonly attribute NodeList addedNodes;
[SameObject] readonly attribute NodeList removedNodes;
readonly attribute Node? previousSibling;
readonly attribute Node? nextSibling;
readonly attribute DOMString? attributeName;
readonly attribute DOMString? attributeNamespace;
readonly attribute DOMString? oldValue;
};
- record .
type
-
変異の種類に応じて,次を返す
:属性°に対する変異であった場合は "
attributes
",CharacterData
ノードに対する変異であった場合は "characterData
", ノードが成すツリーに対する変異であった場合は "childList
" Returns "attributes" if it was an attribute mutation. "characterData" if it was a mutation to a CharacterData node. And "childList" if it was a mutation to the tree of nodes. - record .
target
-
変異に影響されたノードを返す —
type
に応じて :"attributes
" に対しては,属性°が変化した要素 / "characterData
" に対しては,CharacterData
ノード / "childList
" に対しては,子群が変化したノード Returns the node the mutation affected, depending on the type. For "attributes", it is the element whose attribute changed. For "characterData", it is the CharacterData node. For "childList", it is the node whose children changed. - record .
addedNodes
- record .
removedNodes
- 順に,[ 追加された, 除去された ]ノードたちが成すリストを返す。 Return the nodes added and removed respectively.
- record .
previousSibling
- record .
nextSibling
- [ 追加されたまたは除去された ]ノードが[ 在るならば,順に[ その直前の同胞?, その直後の同胞? ]/ 無いならば null ]を返す。。 Return the previous and next sibling respectively of the added or removed nodes; otherwise null.
- record .
attributeName
- 変化した属性°が[ 在るならば その局所名/ 無いならば null ]を返す。 Returns the local name of the changed attribute; otherwise null.
- record .
attributeNamespace
- 変化した属性°が[ 在るならば その名前空間/ 無いならば null ]を返す。 Returns the namespace of the changed attribute; otherwise null.
- record .
oldValue
-
type
に応じて,次に与える値を返す :"attributes
" ならば,変化した属性°の変化前の値/ "characterData
" ならば,変化したノードの変化前のデータ/ "childList
" ならば, null The return value depends on type. For "attributes", it is the value of the changed attribute before the change. For "characterData", it is the data of the changed node before the change. For "childList", it is null.
type
,
target
,
addedNodes
,
removedNodes
,
previousSibling
,
nextSibling
,
attributeName
,
attributeNamespace
,
oldValue
The type, target, addedNodes, removedNodes, previousSibling, nextSibling, attributeName, attributeNamespace, and oldValue attributes must return the values they were initialized to.4.4. Node
インタフェース
[Exposed=Window]
interface Node : EventTarget {
const unsigned short ELEMENT_NODE = 1;
const unsigned short ATTRIBUTE_NODE = 2;
const unsigned short TEXT_NODE = 3;
const unsigned short CDATA_SECTION_NODE = 4;
const unsigned short ENTITY_REFERENCE_NODE = 5; // 旧来
const unsigned short ENTITY_NODE = 6; // 旧来
const unsigned short PROCESSING_INSTRUCTION_NODE = 7;
const unsigned short COMMENT_NODE = 8;
const unsigned short DOCUMENT_NODE = 9;
const unsigned short DOCUMENT_TYPE_NODE = 10;
const unsigned short DOCUMENT_FRAGMENT_NODE = 11;
const unsigned short NOTATION_NODE = 12; // 旧来
readonly attribute unsigned short nodeType;
readonly attribute DOMString nodeName;
readonly attribute USVString baseURI;
readonly attribute boolean isConnected;
readonly attribute Document? ownerDocument;
Node getRootNode(optional GetRootNodeOptions options = {});
readonly attribute Node? parentNode;
readonly attribute Element? parentElement;
boolean hasChildNodes();
[SameObject] readonly attribute NodeList childNodes;
readonly attribute Node? firstChild;
readonly attribute Node? lastChild;
readonly attribute Node? previousSibling;
readonly attribute Node? nextSibling;
[CEReactions] attribute DOMString? nodeValue;
[CEReactions] attribute DOMString? textContent;
[CEReactions] undefined normalize();
[CEReactions, NewObject] Node cloneNode(optional boolean subtree = false);
boolean isEqualNode(Node? otherNode);
boolean isSameNode(Node? otherNode); // ===
演算子の旧来の別名
const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01;
const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02;
const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04;
const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08;
const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;
unsigned short compareDocumentPosition(Node other);
boolean contains(Node? other);
DOMString? lookupPrefix(DOMString? namespace);
DOMString? lookupNamespaceURI(DOMString? prefix);
boolean isDefaultNamespace(DOMString? namespace);
[CEReactions] Node insertBefore(Node node, Node? child);
[CEReactions] Node appendChild(Node node);
[CEReactions] Node replaceChild(Node node, Node child);
[CEReactions] Node removeChild(Node child);
};
dictionary GetRootNodeOptions {
boolean composed = false;
};
注記:
Node
は、
すべてのノードから利用される抽象インタフェースであり,
その直なインスタンスは取得し得ない。
Node is an abstract interface that is used by all nodes. You cannot get a direct instance of it.
各ノードには、 次に挙げるものが結び付けられる:
- ノード文書 :文書。 作成時に設定される。
注記: ノードのノード文書は、 ノードを受入するアルゴリズムにより変更され得る。 A node’s node document can be changed by the adopt algorithm.
【 ノードが文書ツリー内になくても,結び付けられることになる。 】
ノード ノード の親ターゲットを取得するときは :RETURN [ ノード のあてがい先 slot ≠ null ならば それ / 他の場合は ノード の親 ] A node’s get the parent algorithm, given an event, returns the node’s assigned slot, if node is assigned; otherwise node’s parent.
【 文書は、 ノードの親ターゲットを取得するアルゴリズムを上書きする。 】
注記: 各ノードは、 登録済み観測器リストも有する。 Each node also has a registered observer list.
- node .
nodeType
-
node の型に応じて,適切な数を返す(括弧内は数値)
:
Element
ならばELEMENT_NODE
(1) /Attr
ならばATTRIBUTE_NODE
(2) / 狭義Text
ノードならばTEXT_NODE
(3) /CDATASection
ならばCDATA_SECTION_NODE
(4) /ProcessingInstruction
ならばPROCESSING_INSTRUCTION_NODE
(7) /Comment
ならばCOMMENT_NODE
(8) /Document
ならばDOCUMENT_NODE
(9) /DocumentType
ならばDOCUMENT_TYPE_NODE
(10) /DocumentFragment
ならばDOCUMENT_FRAGMENT_NODE
(11) Returns a number appropriate for the type of node, as follows:Element • Node . ELEMENT_NODE (1). Attr • Node . ATTRIBUTE_NODE (2). An exclusive Text node • Node . TEXT_NODE (3). CDATASection • Node . CDATA_SECTION_NODE (4). ProcessingInstruction • Node . PROCESSING_INSTRUCTION_NODE (7). Comment • Node . COMMENT_NODE (8). Document • Node . DOCUMENT_NODE (9). DocumentType • Node . DOCUMENT_TYPE_NODE (10). DocumentFragment • Node . DOCUMENT_FRAGMENT_NODE (11). - node .
nodeName
-
node の型に応じて,適切な文字列を返す
:
Element
ならば node の HTML 大文字化有修飾名 /Attr
ならば node の有修飾名 / 狭義Text
ノードならば "#text
" /CDATASection
ならば "#cdata-section
" /ProcessingInstruction
ならば node のターゲット /Comment
ならば "#comment
" /Document
ならば "#document
" /DocumentType
ならば node の名前 /DocumentFragment
ならば "#document-fragment
" Returns a string appropriate for the type of node, as follows:Element • Its HTML-uppercased qualified name. Attr • Its qualified name. An exclusive Text node • "#text". CDATASection • "#cdata-section". ProcessingInstruction • Its target. Comment • "#comment". Document • "#document". DocumentType • Its name. DocumentFragment • "#document-fragment".
nodeType
取得子手続きは
:RETURN これ°が実装するインタフェースに応じて(括弧内は数値)
:Element
ならば ELEMENT_NODE
(1) /
Attr
ならば ATTRIBUTE_NODE
(2) /
狭義 Text
ノードならば TEXT_NODE
(3) /
CDATASection
ならば CDATA_SECTION_NODE
(4) /
ProcessingInstruction
ならば PROCESSING_INSTRUCTION_NODE
(7) /
Comment
ならば COMMENT_NODE
(8) /
Document
ならば DOCUMENT_NODE
(9) /
DocumentType
ならば DOCUMENT_TYPE_NODE
(10) /
DocumentFragment
ならば DOCUMENT_FRAGMENT_NODE
(11)
The nodeType getter steps are to return the first matching statement, switching on the interface this implements:Element
• ELEMENT_NODE (1)
Attr
• ATTRIBUTE_NODE (2);
An exclusive Text node
• TEXT_NODE (3);
CDATASection
• CDATA_SECTION_NODE (4);
ProcessingInstruction
• PROCESSING_INSTRUCTION_NODE (7);
Comment
• COMMENT_NODE (8);
Document
• DOCUMENT_NODE (9);
DocumentType
• DOCUMENT_TYPE_NODE (10);
DocumentFragment
• DOCUMENT_FRAGMENT_NODE (11).nodeName
取得子手続きは
:RETURN これ°が実装するインタフェースに応じて:
:Element
ならばこれ°の HTML 大文字化有修飾名 /
Attr
ならばこれ°の有修飾名 /
狭義 Text
ノードならば "#text
" /
CDATASection
ならば "#cdata-section
" /
ProcessingInstruction
ならばこれ°のターゲット /
Comment
ならば "#comment
" /
Document
ならば "#document
" /
DocumentType
ならばこれ°の名前 /
DocumentFragment
ならば "#document-fragment
"
The nodeName getter steps are to return the first matching statement, switching on the interface this implements:Element
• Its HTML-uppercased qualified name.
Attr
• Its qualified name.
An exclusive Text node
• "#text".
CDATASection
• "#cdata-section".
ProcessingInstruction
• Its target.
Comment
• "#comment".
Document
• "#document".
DocumentType
• Its name.
DocumentFragment
• "#document-fragment".baseURI
取得子手続きは
:RETURN URL を直列化する( これ°のノード文書の文書基底 URL )
The baseURI getter steps are to return this’s node document’s document base URL, serialized.- node .
isConnected
- node は接続されて[ いるならば true / いないならば false ]を返す。 Returns true if node is connected; otherwise false.
- node .
ownerDocument
- ノード文書を返す。 文書に対しては null を返す。 Returns the node document. Returns null for documents.
- node .
getRootNode()
- node の根を返す。 Returns node’s root.
- node .
getRootNode
({ composed:true }) - node の shadow も含めた根を返す。 Returns node’s shadow-including root.
- node .
parentNode
- 親を返す。 Returns the parent.
- node .
parentElement
- 親要素を返す。 Returns the parent element.
- node .
hasChildNodes()
- node の子群は空でないかどうかを返す。 Returns whether node has children.
- node .
childNodes
- 子群を返す。 Returns the children.
- node .
firstChild
- 最初の子?を返す。 Returns the first child.
- node .
lastChild
- 最後の子?を返す。 Returns the last child.
- node .
previousSibling
- 直前の同胞?を返す。 Returns the previous sibling.
- node .
nextSibling
- 直後の同胞?を返す。 Returns the next sibling.
isConnected
取得子手続きは
:RETURN IS[
これ°は接続されている
]
The isConnected getter steps are to return true, if this is connected; otherwise false.
ownerDocument
取得子手続きは
:RETURN [
これ°は文書である ならば null /
他の場合は これ°のノード文書
]
The ownerDocument getter steps are to return null, if this is a document; otherwise this’s node document.
注記: 文書のノード文書は,文書自身である。 すべてのノードは、 どの時点であれ,ノード文書を有する。 The node document of a document is that document itself. All nodes have a node document at all times.
getRootNode(options)
メソッド手続きは
:RETURN options[ "composed
" ] に応じて
:true ならば これ°の shadow も含めた根 /
他の場合は これ°の根
The getRootNode(options) method steps are to return this’s shadow-including root if options["composed"] is true; otherwise this’s root.parentElement
取得子手続きは
:RETURN これ°の親要素
The parentElement getter steps are to return this’s parent element.hasChildNodes()
メソッド手続きは
:RETURN IS[
これ°の子群は空でない
]
The hasChildNodes() method steps are to return true if this has children; otherwise false.childNodes
取得子手続きは
:RETURN 次のように設定された NodeList
コレクション
:根 ← これ°,
フィルタは これ°の子のみに合致する
The childNodes getter steps are to return a NodeList rooted at this matching only children.previousSibling
取得子手続きは
:RETURN これ°の直前の同胞?
The previousSibling getter steps are to return this’s previous sibling.nextSibling
取得子手続きは
:RETURN これ°の直後の同胞?
The nextSibling getter steps are to return this’s next sibling.nodeValue
取得子手続きは
:RETURN これ°が実装するインタフェースに応じて
:Attr
ならばこれ°の値/
CharacterData
ならばこれ°のデータ/
他の場合は null
The nodeValue getter steps are to return the following, switching on the interface this implements:Attr
• this’s value.
CharacterData
• this’s data.
Otherwise
• Null.
nodeValue
設定子手続きは:
The nodeValue setter steps are to,\
- 値 :← [ 所与の値 ≠ null ならば それ / 他の場合は 空文字列 ] if the given value is null, act as if it was the empty string instead, and then\
-
これ°が実装するインタフェースに応じて: do as described below, switching on the interface this implements:
-
Attr
:既存の属性°値を設定する( これ°, 値 ) Attr • Set an existing attribute value with this and the given value. -
CharacterData
:これ°のデータを置換する( 0, これ°の長さ, 値 ) CharacterData • Replace data with node this, offset 0, count this’s length, and data the given value. - その他 :何もしない Otherwise • Do nothing.
-
DocumentFragment
ならば ノード の子孫テキスト内容/
Element
ならば ノード の子孫テキスト内容/
Attr
ならば ノード の値/
CharacterData
ならば ノード のデータ/
他の場合は null
To get text content with a node node, return the following, switching on the interface node implements:DocumentFragment
Element
• The descendant text content of node.
Attr
• node’s value.
CharacterData
• node’s data.
Otherwise
• Null.textContent
取得子手続きは
:RETURN ノードのテキスト内容を取得する( これ° )
The textContent getter steps are to return the result of running get text content with this.ノード 親 の 全内容を文字列に置換する ときは、 所与の ( 文字列 文字列 ) に対し,次を走らす: To string replace all with a string string within a node parent, run these steps:
- ノード :← null Let node be null.
-
IF[
文字列 ≠ 空文字列
]
:ノード ← 新たな
Text
ノード( 文字列, 親 のノード文書 ) If string is not the empty string, then set node to a new Text node whose data is string and node document is parent’s node document. - 親 の全内容をノードで置換する( ノード ) Replace all with node within parent.
ノードのテキスト内容を設定する ときは、 所与の ( ノード ノード, 文字列 値 ) に対し, ノード が実装するインタフェースに応じて: To set text content with a node node and a string value, do as defined below, switching on the interface node implements:
-
DocumentFragment
/Element
:これ°の全内容を文字列に置換する( 値 ) DocumentFragment Element • String replace all with value within node. -
Attr
:既存の属性°値を設定する( これ°, 値 ) Attr • Set an existing attribute value with node and value. -
CharacterData
:これ°のデータを置換する( 0, これ°の長さ, 値 ) CharacterData • Replace data with node node, offset 0, count node’s length, and data value. -
その他【すなわち,
Document
/DocumentType
】 :何もしない Otherwise • Do nothing.
textContent
設定子手続きは:
The textContent setter steps are to,\
- 値 :← [ 所与の値 ≠ null ならば 値 / 他の場合は 空文字列 ] if the given value is null, act as if it was the empty string instead, and then\
- ノードのテキスト内容を設定する( これ°, 値 ) run set text content with this and the given value.
- node .
normalize()
-
node に含まれている狭義
Text
ノードのうち空であるものは除去し、 連続的な狭義Text
ノード列に対しては,その最初のノードに後続のデータを連結してひとまとめにする。 Removes empty exclusive Text nodes and concatenates the data of remaining contiguous exclusive Text nodes into the first of their nodes. - 【
この記述は、
“除去” と “連結” の順序に関し,微妙に正確でない
— 実際のアルゴリズムでは、
空な
Text
ノードのうち,[ 最初のノード N が空でない連続的な狭義Text
ノード列 ]に含まれるものは、 後続の空なText
ノードより先に N に連結される(その結果として,除去されるが)。 】
normalize()
メソッド手続きは:
The normalize() method steps are to run these steps\
-
これ°の子孫である 各( 狭義
Text
ノード ノード ) に対し: for each descendant exclusive Text node node of this:【 ツリー順序で。 加えて、 このループの中でツリーから除去される
Text
ノードに対する反復は, 飛ばす必要もある。 】- 長さ :← ノード の長さ Let length be node’s length.
- 長さ = 0 :ノードを除去する( ノード ); CONTINUE If length is zero, then remove node and continue with the next exclusive Text node, if any.
-
除去対象 :← ノード を含む連続的な狭義
Text
ノード列 ↓ - 除去対象 から ノード (常に先頭に在る)を除去する ↓
- データ :← テキストデータを連結する( 除去対象 ) Let data be the concatenation of the data of node’s contiguous exclusive Text nodes (excluding itself), in tree order.
- ノード のデータを置換する( 長さ, 0, データ ) Replace data with node node, offset length, count 0, and data data.
-
除去対象 を成す 各( text ) に対し: Let currentNode be node’s next sibling.While currentNode is an exclusive Text node:
-
各( live 範囲° R ) に対し: ↓
- IF[ 範囲° の始端ノード = text ] :範囲° の始端オフセット += 長さ; 範囲° の始端ノード ← ノード For each live range whose start node is currentNode, add length to its start offset and set its start node to node.
- IF[ 範囲° の終端ノード = text ] :範囲° の終端オフセット += 長さ; 範囲° の終端ノード ← ノード For each live range whose end node is currentNode, add length to its end offset and set its end node to node.
- IF[ 範囲° の始端ノード = text の親 ]∧[ 範囲° の始端オフセット = text の index ] :範囲° の始端ノード ← ノード; 範囲° の始端オフセット ← 長さ For each live range whose start node is currentNode’s parent and start offset is currentNode’s index, set its start node to node and its start offset to length.
- IF[ 範囲° の終端ノード = text の親 ]∧[ 範囲° の終端オフセット = text の index ] :範囲° の終端ノード ← ノード; 範囲° の終端オフセット ← 長さ For each live range whose end node is currentNode’s parent and end offset is currentNode’s index, set its end node to node and its end offset to length.
- 長さ += text の長さ Add currentNode’s length to length.Set currentNode to its next sibling.
-
- 除去対象 を成す 各( text ) に対し,順に :ノードを除去する( text ) Remove node’s contiguous exclusive Text nodes (excluding itself), in tree order.
- node .
cloneNode([subtree = false])
- node の複製を返す。 subtree が true の場合、 複製は node の子孫も含む。 Returns a copy of node. If subtree is true, the copy also includes the node’s descendants.
- node .
isEqualNode(otherNode)
- node と otherNode が同じプロパティを有するかどうかを返す。 Returns whether node and otherNode have the same properties.
適用可能な仕様は、 すべてまたは一部のノード用に クローン時の手続き を定義してもよい。 このアルゴリズムは、 ノードをクローンする アルゴリズム内から, ( ノード, 複製, 下位ツリーか ) を渡して呼び出される。 Specifications may define cloning steps for all or some nodes. The algorithm is passed node, copy, and subtree as indicated in the clone a node algorithm.
注記:
HTML は、
いくつかの要素
— script
, input
, template
など —
用にクローン時の手続きを定義する。
SVG の script
要素用にも同じことが行われるべきだが、
行われない。
HTML defines cloning steps for several elements, such as input, script, and template. SVG ought to do the same for its script elements, but does not.
ノードをクローンする ときは、 所与の :ノード ノード, 真偽値 下位ツリーか (省略時は false ), 文書 文書 (省略時は ノード のノード文書 ), [ ノード/ null ] 親 (省略時は null ) に対し: To clone a node given a node node and an optional document document (default node’s node document), boolean subtree (default false), and node-or-null parent (default null):
- Assert: [ ノード は文書でない ]∨[ ノード = 文書 ] Assert: node is not a document or node is document.
- 複製 :← 単独のノードをクローンする( ノード, 文書 ) Let copy be the result of cloning a single node given node and document.
- 適用可能な仕様にて ノード 用に定義された各( クローン時の手続き 手続き ) に対し :手続き( ノード, 複製, 下位ツリーか ) Run any cloning steps defined for node in other applicable specifications and pass node, copy, and subtree as parameters.
- IF[ 親 ≠ null ] :親 にノードを付加する( 複製 ) If parent is non-null, then append copy to parent.
- IF[ 下位ツリーか = true ] :ノード の子群を成す 各( 子 ) に対し,ツリー順序で :ノードをクローンする( 子, 下位ツリーか, 文書, 複製 ) If subtree is true, then for each child of node’s children, in tree order: clone a node given child with document set to document, subtree set to subtree, and parent set to copy.
- shadow 根 :← ノード の shadow 根 ↓
-
IF[ ノード は要素である ]∧[ shadow 根 ≠ null ]∧[ shadow 根 のクローン可能か = true ]: If node is an element, node is a shadow host, and node’s shadow root’s clonable is true:
- Assert: 複製 は shadow ホストでない。 Assert: copy is not a shadow host.
- shadow 根を付する( ↓ ) :複製, shadow 根 のモード, true, shadow 根 の直列化可能か, shadow 根 のフォーカスを委任するか, shadow 根 の slot あてがいモード Attach a shadow root with copy, node’s shadow root’s mode, true, node’s shadow root’s serializable, node’s shadow root’s delegates focus, and node’s shadow root’s slot assignment.
- 複製 の shadow 根の宣言的か ← shadow 根 の宣言的か Set copy’s shadow root’s declarative to node’s shadow root’s declarative.
- shadow 根 の子群を成す 各( 子 ) に対し,ツリー順序で :ノードをクローンする( 子, 下位ツリーか, 文書, 複製 の shadow 根 ) For each child of node’s shadow root’s children, in tree order: clone a node given child with document set to document, subtree set to subtree, and parent set to copy’s shadow root.
- RETURN 複製 Return copy.
単独のノードをクローンする ときは、 所与の ( ノード ノード, 文書 文書 ) に対し: To clone a single node given a node node and document document:
- 複製 :← null Let copy be null.
-
IF[ ノード は要素である ]: If node is an element:
-
複製 ← 要素を作成する( ↓ )
:文書,
ノード の局所名,
ノード の名前空間,
ノード の名前空間接頭辞,
ノード の
is
値 Set copy to the result of creating an element, given document, node’s local name, node’s namespace, node’s namespace prefix, and node’s is value. - ノード の属性°リストを成す 各( 属性° ) に対し :属性°を付加する( 次の結果, 複製 ) :単独のノードをクローンする( 属性°, 文書 ) For each attribute of node’s attribute list: • Let copyAttribute be the result of cloning a single node given attribute and document. • Append copyAttribute to copy.
-
複製 ← 要素を作成する( ↓ )
:文書,
ノード の局所名,
ノード の名前空間,
ノード の名前空間接頭辞,
ノード の
-
ELSE: Otherwise,\
- 複製 ← 新たなオブジェクト( ノード の首インタフェース ) set copy to a node that implements the same interfaces as node, and\
-
ノード が実装するインタフェースに応じて: fulfills these additional requirements, switching on the interface node implements:
-
Document
:複製 の :符号化法 ← ノード の符号化法, 内容型 ← ノード の内容型, URL ← ノード の URL , 生成元 ← ノード の生成元, 種別 ← ノード の種別, モード ← ノード のモード Document • Set copy’s encoding, content type, URL, origin, type, and mode to those of node. -
DocumentType
:複製 の :名前 ← ノード の名前, 公な ID ← ノード の公な ID , システム ID ← ノード のシステム ID DocumentType • Set copy’s name, public ID, and system ID to those of node. -
Attr
:複製 の :名前空間 ← ノード の名前空間, 名前空間接頭辞 ← ノード の名前空間接頭辞, 局所名 ← ノード の局所名, 値 ← ノード の値 Attr • Set copy’s namespace, namespace prefix, local name, and value to those of node. -
Text
/Comment
:複製 のデータ ← ノード のデータ Text Comment • Set copy’s data to that of node. -
ProcessingInstruction
:複製 の :ターゲット ← ノード のターゲット, データ ← ノード のデータ ProcessingInstruction • Set copy’s target and data to those of node. -
その他【すなわち,
DocumentFragment
】 :何もしない Otherwise • Do nothing.
-
- Assert: 複製 はノードである。 Assert: copy is a node.
- 複製 のノード文書 ← 複製 に応じて :文書であるならば 複製 / 他の場合は 文書 If node is a document, then set document to copy.Set copy’s node document to document.
- RETURN 複製 Return copy.
cloneNode(subtree)
メソッド手続きは:
The cloneNode(subtree) method steps are:
-
IF[
これ°は shadow 根である
]
:THROW
NotSupportedError
If this is a shadow root, then throw a "NotSupportedError" DOMException. - RETURN ノードをクローンする( これ°, subtree ) Return the result of cloning a node given this with subtree set to subtree.
2 つのノード A, B が 同等 であるとは、 ∧↓ を満たすことをいう: A node A equals a node B if all of the following conditions are true:
- A, B は同じインタフェースを実装する A and B implement the same interfaces.
-
A が実装するインタフェースに応じて,次に挙げるものもすべて同等である: The following are equal, switching on the interface A implements:
-
DocumentType
:名前, 公な ID , システム ID DocumentType • Its name, public ID, and system ID. -
Element
:名前空間, 名前空間接頭辞, 局所名, 属性°リストのサイズ Element • Its namespace, namespace prefix, local name, and its attribute list’s size. -
Attr
:名前空間, 局所名, 値 Attr • Its namespace, local name, and value. -
ProcessingInstruction
:ターゲット, データ ProcessingInstruction • Its target and data. -
CharacterData
:データ Text Comment • Its data. -
その他【すなわち,
Document
,DocumentFragment
】 :なし 【すなわち,比較するものは無いので無条件(原文には “—” としか記されていないが)。】 Otherwise • —
-
- A は要素であるならば、 次が満たされる :A の属性°リストを成す どの属性°も,[ B の属性°リストを成す ある属性° ]と同等である If A is an element, each attribute in its attribute list has an attribute that equals an attribute in B’s attribute list.
- A の子群のサイズ = B の子群のサイズ A and B have the same number of children.
- 各 index ∈ { 0 〜 A の子群のサイズ − 1 } に対し :( A の子群[ index ], B の子群[ index ] ) は同等である Each child of A equals the child of B at the identical index.
isEqualNode(otherNode)
メソッド手続きは
:RETURN IS[
otherNode ≠ null
]∧[
( これ°, otherNode )
は同等である
]
The isEqualNode(otherNode) method steps are to return true if otherNode is non-null and this equals otherNode; otherwise false.isSameNode(otherNode)
メソッド手続きは
:RETURN IS[
otherNode = これ°
]
The isSameNode(otherNode) method steps are to return true if otherNode is this; otherwise false.- node .
compareDocumentPosition(other)
-
node に相対的な other の位置を指示するビットマスクを返す。 それを成す各ビットは、 対応する条件が満たされる場合には, “1” に設定される: Returns a bitmask indicating the position of other relative to node. These are the bits that can be set:
Node
.DOCUMENT_POSITION_DISCONNECTED
(1)- node と other は同じツリーに属さない。 Set when node and other are not in the same tree.
Node
.DOCUMENT_POSITION_PRECEDING
(2)- other は node に先行する。 Set when other is preceding node.
Node
.DOCUMENT_POSITION_FOLLOWING
(4)- other は node に後続する。 Set when other is following node.
Node
.DOCUMENT_POSITION_CONTAINS
(8)- other は node の先祖である。 Set when other is an ancestor of node.
Node
.DOCUMENT_POSITION_CONTAINED_BY
(16)- other は node の子孫である。 Set when other is a descendant of node.
- node .
contains(other)
- other が node の広義子孫[ であるならば true / でないならば false ]を返す。 Returns true if other is an inclusive descendant of node; otherwise false.
次に挙げるものは
compareDocumentPosition()
がビットマスクとして返す定数である(括弧内は数値):
These are the constants compareDocumentPosition() returns as mask:
-
DOCUMENT_POSITION_DISCONNECTED
(1) -
DOCUMENT_POSITION_PRECEDING
(2) -
DOCUMENT_POSITION_FOLLOWING
(4) -
DOCUMENT_POSITION_CONTAINS
(8) -
DOCUMENT_POSITION_CONTAINED_BY
(16 = 0x10) -
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
(32 = 0x20)
compareDocumentPosition(other)
メソッド手続きは:
The compareDocumentPosition(other) method steps are:
- IF[ これ° = other ] :RETURN 0 If this is other, then return zero.
- ( 他ノード, 自ノード ) :← ( other, これ° ) Let node1 be other and node2 be this.
- ( 他属性°, 自属性° ) :← ( null , null ) Let attr1 and attr2 be null.
- IF[ 他ノード は属性°である ] :他属性° ← 他ノード; 他ノード ← 他属性° が属する要素 If node1 is an attribute, then set attr1 to node1 and node1 to attr1’s element.
-
IF[ 自ノード は属性°である ]: If node2 is an attribute:
- 自属性° ← 自ノード ↓
- 自ノード ← 自属性° が属する要素 Set attr2 to node2 and node2 to attr2’s element.
-
IF[ 他属性° ≠ null ]∧[ 自属性° ≠ null ]∧[ 自ノード = 他ノード ]: If attr1 and node1 are non-null, and node2 is node1:
-
自ノード の属性°リストを成す 各( 属性° ) に対し: For each attr in node2’s attribute list:
-
IF[
( 属性°, 他属性° )
は同等である
]
:RETURN
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
+DOCUMENT_POSITION_PRECEDING
If attr equals attr1, then return the result of adding DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC and DOCUMENT_POSITION_PRECEDING. -
IF[
( 属性°, 自属性° )
は同等である
]
:RETURN
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
+DOCUMENT_POSITION_FOLLOWING
If attr equals attr2, then return the result of adding DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC and DOCUMENT_POSITION_FOLLOWING.
-
IF[
( 属性°, 他属性° )
は同等である
]
:RETURN
-
-
IF[ 他ノード = null ]∨[ 自ノード = null ]∨[ 他ノード の根 ≠ 自ノード の根 ] :RETURN [
DOCUMENT_POSITION_DISCONNECTED
+DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
+ [DOCUMENT_POSITION_PRECEDING
またはDOCUMENT_POSITION_FOLLOWING
(ただし,いずれが選択されるかは一貫するものとする)] ] If node1 or node2 is null, or node1’s root is not node2’s root, then return the result of adding DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, and either DOCUMENT_POSITION_PRECEDING or DOCUMENT_POSITION_FOLLOWING, with the constraint that this is to be consistent, together.注記:
DOCUMENT_POSITION_PRECEDING
,DOCUMENT_POSITION_FOLLOWING
のどちらを返すかは,概してポインタ比較を介して実装される。 JavaScript 実装においてはMath.random()
値を利用できる。 【理想的には、各ノードツリーどうしの順序も循環しないように一貫するべきであろう。】 Whether to return DOCUMENT_POSITION_PRECEDING or DOCUMENT_POSITION_FOLLOWING is typically implemented via pointer comparison. In JavaScript implementations a cached Math.random() value can be used. -
IF[[
他ノード は 自ノード の先祖である
]∧[
他属性° = null
]]∨[[
他ノード = 自ノード
]∧[
自属性° ≠ null
]]
:RETURN
DOCUMENT_POSITION_CONTAINS
+DOCUMENT_POSITION_PRECEDING
If node1 is an ancestor of node2 and attr1 is null, or node1 is node2 and attr2 is non-null, then return the result of adding DOCUMENT_POSITION_CONTAINS to DOCUMENT_POSITION_PRECEDING. -
IF[[
他ノード は 自ノード の子孫である
]∧[
自属性° = null
]]∨[[
他ノード = 自ノード
]∧[
他属性° ≠ null
]]
:RETURN
DOCUMENT_POSITION_CONTAINED_BY
+DOCUMENT_POSITION_FOLLOWING
If node1 is a descendant of node2 and attr2 is null, or node1 is node2 and attr1 is non-null, then return the result of adding DOCUMENT_POSITION_CONTAINED_BY to DOCUMENT_POSITION_FOLLOWING. -
IF[ 他ノード は 自ノード に先行する ] :RETURN
DOCUMENT_POSITION_PRECEDING
If node1 is preceding node2, then return DOCUMENT_POSITION_PRECEDING.注記: 属性°は,自身が属する要素と同じツリーには関与しないが、 このアルゴリズムに因り[ 属性°は,自身が属する要素の子に先行する ]ものとされることになる。 Due to the way attributes are handled in this algorithm this results in a node’s attributes counting as preceding that node’s children, despite attributes not participating in the same tree.
-
RETURN
DOCUMENT_POSITION_FOLLOWING
Return DOCUMENT_POSITION_FOLLOWING.
contains(other)
メソッド手続きは
:RETURN IS[
other はこれ°の広義子孫である
]
The contains(other) method steps are to return true if other is an inclusive descendant of this; otherwise false (including when other is null).要素 用の 名前空間接頭辞を特定する ときは、 所与の ( 名前空間 ) に対し,次を走らす: To locate a namespace prefix for an element using namespace, run these steps:
- IF[ 要素 の名前空間 = 名前空間 ]∧[ 要素 の名前空間接頭辞 ≠ null ] :RETURN 要素 の名前空間接頭辞 If element’s namespace is namespace and its namespace prefix is non-null, then return its namespace prefix.
-
属性° :← 要素 の属性°リストを成す属性°のうち,次を満たす最初のもの?
:[
名前空間接頭辞 = "
xmlns
" ]∧[ 値 = 名前空間 ] If element has an attribute whose namespace prefix is "xmlns" and value is namespace, then return element’s first such attribute’s local name. - IF[ 属性° ≠ null ] :RETURN 属性° の局所名 ↑
- 親 ← 要素 の親要素 ↓
- IF[ 親 ≠ null ] :RETURN 親 用の名前空間接頭辞を特定する( 名前空間 ) If element’s parent element is not null, then return the result of running locate a namespace prefix on that element using namespace.
- RETURN null Return null.
ノード 用の 名前空間を特定する ときは、 所与の ( 接頭辞 ) に対し,次を走らす: To locate a namespace for a node using prefix,\ ↓switch on the interface node implements:
-
IF[ ノード は
Element
を実装する ]: Element-
IF[
接頭辞 = "
xml
" ] :RETURN XML 名前空間 If prefix is "xml", then return the XML namespace. -
IF[
接頭辞 = "
xmlns
" ] :RETURN XMLNS 名前空間 If prefix is "xmlns", then return the XMLNS namespace. - IF[ ノード の名前空間 ≠ null ]∧[ ノード の名前空間接頭辞 = 接頭辞 ] :RETURN その名前空間 If its namespace is non-null and its namespace prefix is prefix, then return namespace.
-
属性° :← ノード の属性°リストを成す属性°のうち,[ 接頭辞 に応じて,次に与える条件 ]を満たす最初のもの?:
-
接頭辞 ≠ null の場合
:[
名前空間 = XMLNS 名前空間
]∧[
名前空間接頭辞 = "
xmlns
" ]∧[ 局所名 = 接頭辞 ] -
接頭辞 = null の場合
:[
名前空間 = XMLNS 名前空間
]∧[
名前空間接頭辞 = null
]∧[
局所名 = "
xmlns
" ]
-
接頭辞 ≠ null の場合
:[
名前空間 = XMLNS 名前空間
]∧[
名前空間接頭辞 = "
- IF[ 属性° ≠ null ] :RETURN [ 属性° の値 ≠ 空文字列 ならばそれ / 他の場合は null ] then return its value if it is not the empty string, and null otherwise.↓If its parent element is null, then return null.↓Return the result of running locate a namespace on its parent element using prefix.
-
IF[
接頭辞 = "
-
要素 :← ノード が実装するインタフェースに応じて
:
Element
ならば ノード の親要素 /Document
ならば ノード の文書要素 /DocumentType
ならば null /DocumentFragment
ならば null /Attr
ならば ノード が属する要素 / 他の場合は【すなわち,CharacterData
ならば】 ノード の親要素 Document • If its document element is null, then return null. • Return the result of running locate a namespace on its document element using prefix. DocumentType DocumentFragment • Return null. Attr • If its element is null, then return null. • Return the result of running locate a namespace on its element using prefix. Otherwise • If its parent element is null, then return null. • Return the result of running locate a namespace on its parent element using prefix. - IF[ 要素 ≠ null ] :RETURN 要素 用の名前空間を特定する( 接頭辞 ) ↑
- RETURN null ↑
lookupPrefix(namespace)
メソッド手続きは:
The lookupPrefix(namespace) method steps are:
- IF[ namespace ∈ { null , 空文字列 } ] :RETURN null If namespace is null or the empty string, then return null.
-
要素 :← これ°が実装するインタフェースに応じて
:
Element
ならばこれ° /Document
ならばこれ°の文書要素 /DocumentType
ならば null /DocumentFragment
ならば null /Attr
ならばこれ°が属する要素 / 他の場合は【すなわち,CharacterData
ならば】これ°の親要素 Switch on the interface this implements:↓ - IF [ 要素 ≠ null ] :RETURN 要素 用の名前空間接頭辞を特定する( namespace ) • Element •• Return the result of locating a namespace prefix for this using namespace.• Document •• If this’s document element is null, then return null. •• Return the result of locating a namespace prefix for this’s document element using namespace.• DocumentType • DocumentFragment •• Return null.• Attr •• If this’s element is null, then return null. •• Return the result of locating a namespace prefix for this’s element using namespace.• Otherwise •• If this’s parent element is null, then return null. •• Return the result of locating a namespace prefix for this’s parent element using namespace.
- RETURN null ↑
lookupNamespaceURI(prefix)
メソッド手続きは:
The lookupNamespaceURI(prefix) method steps are:
- IF[ prefix = 空文字列 ] :prefix ← null If prefix is the empty string, then set it to null.
- RETURN これ°用の名前空間を特定する( prefix ) Return the result of running locate a namespace for this using prefix.
isDefaultNamespace(namespace)
メソッド手続きは:
The isDefaultNamespace(namespace) method steps are:
- IF[ namespace = 空文字列 ] :namespace ← null If namespace is the empty string, then set it to null.
- 既定名前空間 :← これ°用の名前空間を特定する( null ) Let defaultNamespace be the result of running locate a namespace for this using null.
- RETURN IS[ 既定名前空間 = namespace ] Return true if defaultNamespace is the same as namespace; otherwise false.
insertBefore(node, child)
メソッド手続きは
:RETURN これ°の中でノードを子の前に前挿入する( node, child )
The insertBefore(node, child) method steps are to return the result of pre-inserting node into this before child.
appendChild(node)
メソッド手続きは
:RETURN これ°にノードを付加する( node )
The appendChild(node) method steps are to return the result of appending node to this.replaceChild(node, child)
メソッド手続きは
:RETURN これ°の中で子をノードに置換する( child, node )
The replaceChild(node, child) method steps are to return the result of replacing child with node within this.removeChild(child)
メソッド手続きは
:RETURN これ°から子を前除去する( child )
The removeChild(child) method steps are to return the result of pre-removing child from this.【
上で定義された insertBefore
以下のツリーを改変する各種メソッドは、
改変した結果が文書言語の内容モデルに反することになる場合でも,指定されたとおり遂行され、
ノードツリーに対する拘束に反しない限り,ツリーを改変することになる
(例:HTML の script
要素に子要素を挿入したり,void 要素に子ノードを挿入するなど)。
】
ノード 根 用の[
有修飾名 を
有修飾名に持つ要素のリスト
]は、
次のように設定された HTMLCollection
を返す:
The list of elements with qualified name qualifiedName for a node root is the HTMLCollection returned by the following algorithm:
- 根 ← 根 ↓
-
フィルタは[ 根 の子孫である要素 要素 のうち[ ∨↓ ]が満たされるもの ]に合致する: ↓
- 有修飾名 = U+002A (*) (この場合、 要素 は無条件に合致することになる) If qualifiedName is U+002A (*), then return an HTMLCollection rooted at root, whose filter matches only descendant elements.
-
[ 根 のノード文書は HTML 文書である ]∧[ ∨↓ ]: Otherwise, if root’s node document is an HTML document, return an HTMLCollection rooted at root, whose filter matches the following descendant elements:
- 要素 の有修飾名 = 有修飾名 Otherwise, return an HTMLCollection rooted at root, whose filter matches descendant elements whose qualified name is qualifiedName.
以前の call と同じ引数で呼び出されたときは、
根 のノード文書の種別が変化していない限り,そのときに返したものと同じ HTMLCollection
オブジェクトを返してもよい。
When invoked with the same argument, and as long as root’s node document’s type has not changed, the same HTMLCollection object may be returned as returned by an earlier call.
ノード 根 用の[
( 名前空間, 局所名 )
を
( 名前空間, 局所名 ) に持つ要素のリスト
]は、
次のように設定された HTMLCollection
を返す:
The list of elements with namespace namespace and local name localName for a node root is the HTMLCollection returned by the following algorithm:
- 根 ← 根 ↓
-
フィルタは[ 根 の子孫である要素 要素 のうち,次の結果 = true になるもの ]に合致する:
- IF[ 名前空間 = 空文字列 ] :名前空間 ← null
- RETURN IS[ 名前空間 ∈ { U+002A (*), 要素 の名前空間 } ]∧[ 局所名 ∈ { U+002A (*), 要素 の局所名 } ]
( 名前空間 = 局所名 = "
If namespace is the empty string, then set it to null.If both namespace and localName are U+002A (*), then return an HTMLCollection rooted at root, whose filter matches descendant elements.If namespace is U+002A (*), then return an HTMLCollection rooted at root, whose filter matches descendant elements whose local name is localName.If localName is U+002A (*), then return an HTMLCollection rooted at root, whose filter matches descendant elements whose namespace is namespace.Return an HTMLCollection rooted at root, whose filter matches descendant elements whose namespace is namespace and local name is localName.*
" の場合、 要素 は無条件に合致することになる)
以前の call と同じ引数で呼び出されたときは、
そのときに返したものと同じ HTMLCollection
オブジェクトを返してもよい。
When invoked with the same argument, the same HTMLCollection object may be returned as returned by an earlier call.
ノード 根 用の[
classNames を
クラス群に含む要素のリスト
]とは、
次のアルゴリズムが返す HTMLCollection
である:
The list of elements with class names classNames for a node root is the HTMLCollection returned by the following algorithm:
- クラス群 :← 有順序集合として構文解析する( classNames ) Let classes be the result of running the ordered set parser on classNames.
-
IF[
クラス群 は空である
]
:RETURN 空な
HTMLCollection
If classes is the empty set, return an empty HTMLCollection. -
RETURN 次のように設定された
HTMLCollection
コレクション :根 ← 根, フィルタは 根 の子孫である要素のうち次を満たすものに合致する :そのクラス群は クラス群 を成す どのトークンも含む Return an HTMLCollection rooted at root, whose filter matches descendant elements that have all their classes in classes.クラス群と クラス群 の中の各トークンの比較は、[ 根 のノード文書のモードが "
quirks
" ならば ASCII 大小無視 / 他の場合は 一致するかどうか ]で行うものとする。 The comparisons for the classes must be done in an ASCII case-insensitive manner if root’s node document’s mode is "quirks"; otherwise in an identical to manner.
以前の call と同じ引数で呼び出されたときは、
そのときに返したものと同じ HTMLCollection
オブジェクトを返してもよい。
When invoked with the same argument, the same HTMLCollection object may be returned as returned by an earlier call.
4.5. Document
インタフェース
[Exposed=Window]
interface Document : Node {
constructor();
[SameObject] readonly attribute DOMImplementation implementation;
readonly attribute USVString URL;
readonly attribute USVString documentURI;
readonly attribute DOMString compatMode;
readonly attribute DOMString characterSet;
readonly attribute DOMString charset; // characterSet の旧来の別名
readonly attribute DOMString inputEncoding; // characterSet の旧来の別名
readonly attribute DOMString contentType;
readonly attribute DocumentType? doctype;
readonly attribute Element? documentElement;
HTMLCollection getElementsByTagName(DOMString qualifiedName);
HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
HTMLCollection getElementsByClassName(DOMString classNames);
[CEReactions, NewObject] Element createElement(DOMString localName, optional (DOMString or ElementCreationOptions) options = {});
[CEReactions, NewObject] Element createElementNS(DOMString? namespace, DOMString qualifiedName, optional (DOMString or ElementCreationOptions) options = {});
[NewObject] DocumentFragment createDocumentFragment();
[NewObject] Text createTextNode(DOMString data);
[NewObject] CDATASection createCDATASection(DOMString data);
[NewObject] Comment createComment(DOMString data);
[NewObject] ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);
[CEReactions, NewObject] Node importNode(Node node, optional boolean subtree = false);
[CEReactions] Node adoptNode(Node node);
[NewObject] Attr createAttribute(DOMString localName);
[NewObject] Attr createAttributeNS(DOMString? namespace, DOMString qualifiedName);
[NewObject] Event createEvent(DOMString interface); // 旧来
[NewObject] Range createRange();
// NodeFilter.SHOW_ALL = 0xFFFFFFFF
[NewObject] NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
[NewObject] TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
};
[Exposed=Window]
interface XMLDocument : Document {};
dictionary ElementCreationOptions {
DOMString is;
};
Document
ノードは、
単に
文書
( document )とも称される。
Document nodes are simply known as documents.
文書のノード文書は、 それ自身とする。 A document’s node document is itself.
各 文書には、 次に挙げるものが結び付けられる — 他が言明されない限り,括弧内に示す値をとるとする:
- 符号化法 :符号化法 ( utf-8 )
-
内容型
:文字列
( "
application/xml
" ) -
URL
:URL
( "
about:blank
" 【が表現する URL 】) - 生成元 :生成元 ( 不透明な生成元 )
-
種別
:"
xml
" / "html
" ( "xml
" ) -
モード
( "
no-quirks
" ) :"no-quirks
" / "quirks
" / "limited-quirks
" - 宣言的な shadow 根を許容するか :真偽値 ( false )
-
"
xml
" ならば XML 文書 であるとされる。 -
"
html
" ならば HTML 文書 であるとされる。
一部の API のふるまいは、 この 2 種のどちらなのかにより,影響される。
A document is said to be an XML document if its type is "xml"; otherwise an HTML document. Whether a document is an HTML document or an XML document affects the behavior of certain APIs.-
"
no-quirks
" ならば 過去互換なしモード 下にあるとされる。 -
"
quirks
" ならば 過去互換モード 下にあるとされる。 -
"
limited-quirks
" ならば 制限付き過去互換モード 下にあるとされる。
注記:
モードが既定のモードから変更されるのは、
文書が,新たな閲覧文脈(初期の "about:blank
" )から,[
DOCTYPE 文字列の有無, およびその値
]に基づいて HTML 構文解析器を通して作成される場合に限られる。
[HTML]
The mode is only ever changed from the default for documents created by the HTML parser based on the presence, absence, or value of the DOCTYPE string, and by a new browsing context (initial "about:blank"). [HTML]
注記: 過去互換なしモード は,元々は “標準モード” と称され, 制限付き過去互換モード は,かつては “ほぼ標準モード” と称されていた。 それらは,今や標準により定義されたので (また、 それらの元の名前が的外れであることから Ian Hickson が否決したので)、 改称された。 No-quirks mode was originally known as "standards mode" and limited-quirks mode was once known as "almost standards mode". They have been renamed because their details are now defined by standards. (And because Ian Hickson vetoed their original names on the basis that they are nonsensical.)
文書 文書 の親ターゲットを取得するときは、 所与の ( イベント イベント ) に対し:
-
IF[
イベント の
type
属性値 = "load
" ]∨[ 文書 が属する閲覧文脈 = null ] :RETURN null - RETURN 文書 に関連する大域オブジェクト
- document =
new Document()
- 新たな文書を返す。 Returns a new document.
- document .
implementation
-
document の
DOMImplementation
オブジェクトを返す。 Returns document’s DOMImplementation object. - document .
URL
- document .
documentURI
- document の URL を返す。 Returns document’s URL.
- document .
compatMode
-
document のモードに応じて,[
"
quirks
" ならば "BackCompat
" / 他の場合は "CSS1Compat
" ]を返す。 Returns the string "BackCompat" if document’s mode is "quirks"; otherwise "CSS1Compat". - document .
characterSet
- document の符号化法を返す。 Returns document’s encoding.
- document .
contentType
- document の内容型を返す。 Returns document’s content type.
new Document()
構築子手続きは
:これ°の生成元 ← 現在の大域オブジェクトに結び付けられた文書の生成元 [HTML]
The new Document() constructor steps are to set this’s origin to the origin of current global object’s associated Document. [HTML]
注記:
createDocument()
と違って、
この構築子は
XMLDocument
オブジェクトではなく,文書( Document
オブジェクト)を返す。
Unlike createDocument(), this constructor does not return an XMLDocument object, but a document (Document object).
implementation
取得子手続きは
:RETURN これ°に結び付けられた DOMImplementation
オブジェクト
The implementation getter steps are to return the DOMImplementation object that is associated with this.
URL
,
documentURI
取得子手続きは、
いずれも
:RETURN URL を直列化する( これ°の URL )
The URL and documentURI getter steps are to return this’s URL, serialized.
compatMode
取得子手続きは
:RETURN これ°のモードに応じて
:"quirks
" ならば "BackCompat
" /
他の場合は "CSS1Compat
"
The compatMode getter steps are to return "BackCompat" if this’s mode is "quirks"; otherwise "CSS1Compat".characterSet
,
charset
,
inputEncoding
取得子手続きは、
いずれも
:RETURN これ°の符号化法の名前
The characterSet, charset, and inputEncoding getter steps are to return this’s encoding’s name.- document .
doctype
- doctype が[ 在るならばそれ / 無いならば null ]を返す。 Returns the doctype or null if there is none.
- document .
documentElement
- 文書要素を返す。 Returns the document element.
- collection = document .
getElementsByTagName(qualifiedName)
-
引数に応じて,次を満たす子孫要素すべてからなる
HTMLCollection
を返す:-
qualifiedName = "
*
" の場合 :無条件。 -
他の場合、 ∨↓ を満たすもの:
-
qualifiedName = "
- collection = document .
getElementsByTagNameNS(namespace, localName)
-
引数に応じて,次を満たす子孫要素すべてからなる
HTMLCollection
を返す: ↓-
namespace, localName ともに "
*
" の場合: 無条件。 If namespace and localName are "*", returns an HTMLCollection of all descendant elements. -
namespace のみ "
*
" の場合: [ 局所名 = localName ]なるもの。 If only namespace is "*", returns an HTMLCollection of all descendant elements whose local name is localName. -
localName のみ "
*
" の場合: [ 名前空間 = namespace ]なるもの。 If only localName is "*", returns an HTMLCollection of all descendant elements whose namespace is namespace. - 他の場合: [ 名前空間 = namespace ]∧[ 局所名 = localName ]なるもの。 Otherwise, returns an HTMLCollection of all descendant elements whose namespace is namespace and local name is localName.
-
namespace, localName ともに "
- collection = document .
getElementsByClassName(classNames)
- collection = element .
getElementsByClassName(classNames)
-
メソッドが呼び出されたオブジェクト(文書または要素)内の要素のうち,[
classNames で与えられる一連のクラス名をすべて有するもの
]からなる
HTMLCollection
を返す。 classNames 引数は、 一連のクラス名をスペース等で分離したリストとして解釈される。 Returns an HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes.
doctype
取得子手続きは
:RETURN 次を満たすノードのうち,最初のもの?
:[
これ°の子である
]∧[
doctype である
]
The doctype getter steps are to return the child of this that is a doctype; otherwise null.documentElement
取得子手続きは
:RETURN これ°の文書要素
The documentElement getter steps are to return this’s document element.
getElementsByTagName(qualifiedName)
メソッド手続きは
:RETURN これ°用の[
qualifiedName を有修飾名に持つ要素のリスト
]
The getElementsByTagName(qualifiedName) method steps are to return the list of elements with qualified name qualifiedName for this.
注記:
したがって,HTML 文書においては、
document.getElementsByTagName("FOO")
は
HTML 名前空間に属さない FOO
要素と
HTML 名前空間に属する foo
要素に合致し,
HTML 名前空間に属する FOO
要素には合致しないことになる。
Thus, in an HTML document, document.getElementsByTagName("FOO") will match <FOO> elements that are not in the HTML namespace, and <foo> elements that are in the HTML namespace, but not <FOO> elements that are in the HTML namespace.
getElementsByTagNameNS(namespace, localName)
メソッド手続きは
:RETURN これ°用の[
( namespace, localName ) を
( 名前空間, 局所名 ) に持つ要素のリスト
]
The getElementsByTagNameNS(namespace, localName) method steps are to return the list of elements with namespace namespace and local name localName for this.
getElementsByClassName(classNames)
メソッド手続きは
:RETURN これ°用の[
classNames をクラス群に含む要素のリスト
]
The getElementsByClassName(classNames) method steps are to return the list of elements with class names classNames for this.
次の XHTML 片が与えられたとする: Given the following XHTML fragment:
<div id="example"> <p id="p1" class="aaa bbb"/> <p id="p2" class="aaa ccc"/> <p id="p3" class="bbb ccc"/> </div>
document.getElementById("example
").getElementsByClassName("aaa
")
の call は、
その中の 2 個の段落
p1 と p2
からなる HTMLCollection
を返すことになる。
A call to document.getElementById("example").getElementsByClassName("aaa") would return an HTMLCollection with the two paragraphs p1 and p2 in it.
一方で,
getElementsByClassName("ccc bbb
")
の call は
その中の 1 個のノード p3 のみを返すことになる。
document.getElementById("example
").getElementsByClassName("bbb ccc
")
の call も同じものを返すことになる。
A call to getElementsByClassName("ccc bbb") would only return one node, however, namely p3. A call to document.getElementById("example").getElementsByClassName("bbb ccc ") would return the same thing.
getElementsByClassName("aaa,bbb
")
の call は 1 個のノードも返さない。
上のどの要素も aaa,bbb
クラスに属さない。
A call to getElementsByClassName("aaa,bbb") would return no nodes; none of the elements above are in the aaa,bbb class.
- element = document .
createElement(localName [, options])
-
局所名が localName にされた要素を返す
( document が HTML 文書である場合, localName は小文字化される)。
要素の名前空間は,[
次のいずれかに該当する場合は HTML 名前空間 /
他の場合は null
]になる
:document は HTML 文書である /
document の内容型 = "
application/xhtml+xml
" Returns an element with localName as local name (if document is an HTML document, localName gets lowercased). The element’s namespace is the HTML namespace when document is an HTML document or document’s content type is "application/xhtml+xml"; otherwise null. -
localName が
Name
生成規則に合致しない場合,InvalidCharacterError
例外が投出される。 If localName does not match the Name production an "InvalidCharacterError" DOMException will be thrown. -
options の
is
を利用して,カスタム化された組み込みの要素を作成できる。 When supplied, options’s is can be used to create a customized built-in element. - element = document .
createElementNS(namespace, qualifiedName [, options])
- 名前空間 namespace に属するような,新たな要素を返す。 その ( 名前空間接頭辞 接頭辞, 局所名 局所名 ) は、 順に次のようにされる :qualifiedName が U+003A (:) を含むならば それを挟んだ ( 前, 後 ) の部分 / 他の場合は ( null , qualifiedName ) Returns an element with namespace namespace. Its namespace prefix will be everything before U+003A (:) in qualifiedName or null. Its local name will be everything after U+003A (:) in qualifiedName or qualifiedName.
-
qualifiedName が
QName
生成規則に合致しない場合、InvalidCharacterError
例外が投出される。 If qualifiedName does not match the QName production an "InvalidCharacterError" DOMException will be thrown. -
次のいずれかに該当する場合,
NamespaceError
例外が投出される :namespace = 空文字列 ∧ 接頭辞 ≠ null / namespace ≠ XML 名前空間 ∧ 接頭辞 = "xml
" / namespace ≠ XMLNS 名前空間 ∧ qualifiedName = "xmlns
" / namespace ≠ XMLNS 名前空間 ∧ 接頭辞 = "xmlns
" / namespace = XMLNS 名前空間 ∧ qualifiedName ≠ "xmlns
" / namespace = XMLNS 名前空間 ∧ 接頭辞 ≠ "xmlns
" If one of the following conditions is true a "NamespaceError" DOMException will be thrown: • Namespace prefix is not null and namespace is the empty string. • Namespace prefix is "xml" and namespace is not the XML namespace. • qualifiedName or namespace prefix is "xmlns" and namespace is not the XMLNS namespace. • namespace is the XMLNS namespace and neither qualifiedName nor namespace prefix is "xmlns". -
options の
is
を利用して,カスタム化された組み込みの要素を作成できる。 When supplied, options’s is can be used to create a customized built-in element. - documentFragment = document .
createDocumentFragment()
-
DocumentFragment
ノードを返す。 Returns a DocumentFragment node. - text = document .
createTextNode(data)
-
新たな
Text
ノードを返す — そのデータは data にされる。 Returns a Text node whose data is data. - text = document .
createCDATASection(data)
-
新たな
CDATASection
ノードを返す — そのデータは data にされる。 Returns a CDATASection node whose data is data. - comment = document .
createComment(data)
-
新たな
Comment
ノードを返す — そのデータは data にされる。 Returns a Comment node whose data is data. - processingInstruction = document .
createProcessingInstruction(target, data)
-
新たな
ProcessingInstruction
ノードを返す — そのtarget
は target にされ, データは data にされる。 Returns a ProcessingInstruction node whose target is target and data is data.\ -
次のいずれかに該当する場合,
InvalidCharacterError
例外が投出される :target はName
生成規則に合致しない / data は "?>
" を含んでいる If target does not match the Name production an "InvalidCharacterError" DOMException will be thrown. If data contains "?>" an "InvalidCharacterError" DOMException will be thrown.
他が言明されない限り,所与の
( 局所名, 名前空間 )
用の
要素インタフェース
は、
Element
とする。
The element interface for any name and namespace is Element, unless stated otherwise.
注記:
例えば,HTML 標準は、
( html
, HTML 名前空間 )
用のそれを, HTMLHtmlElement
インタフェースと定義している。
[HTML]
The HTML Standard will, e.g., define that for html and the HTML namespace, the HTMLHtmlElement interface is used. [HTML]
createElement(localName, options)
メソッド手続きは:
The createElement(localName, options) method steps are:
-
IF[
localName は
Name
生成規則に合致しない ] :THROWInvalidCharacterError
If localName does not match the Name production, then throw an "InvalidCharacterError" DOMException. - IF[ これ°は HTML 文書 である ] :localName ← ASCII 小文字化する( localName ) If this is an HTML document, then set localName to localName in ASCII lowercase.
- is :← null Let is be null.
-
IF[
options は辞書である
]∧[
options[ "
is
" ] ≠ ε ] :is ← options[ "is
" ] If options is a dictionary and options["is"] exists, then set is to it. -
名前空間 :← [
次が満たされるならば HTML 名前空間 /
他の場合は null
]
:[
これ°は HTML 文書である
]∨[
これ°の内容型 = "
application/xhtml+xml
" ] Let namespace be the HTML namespace, if this is an HTML document or this’s content type is "application/xhtml+xml"; otherwise null. - RETURN 要素を作成する( ↓ ) :これ°, localName, 名前空間, null , is, true Return the result of creating an element given this, localName, namespace, null, is, and true.
内部 createElementNS 手続き は、 所与の ( 文書, namespace, qualifiedName, options ) に対し,次を走らす: The internal createElementNS steps, given document, namespace, qualifiedName, and options, are as follows:
- ( 名前空間, 接頭辞, 局所名 ) :← 検証して抽出する( namespace, qualifiedName ) Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract.
- is :← null Let is be null.
-
IF[
options は辞書である
]∧[
options[ "
is
" ] ≠ ε ] :is ← options[ "is
" ] If options is a dictionary and options["is"] exists, then set is to it. - RETURN 要素を作成する( ↓ ) :文書, 局所名, 名前空間, 接頭辞, is, true Return the result of creating an element given document, localName, namespace, prefix, is, and true.
createElementNS(namespace, qualifiedName, options)
メソッド手続きは
:RETURN 内部 createElementNS 手続き( これ°, namespace, qualifiedName, options )
The createElementNS(namespace, qualifiedName, options) method steps are to return the result of running the internal createElementNS steps, given this, namespace, qualifiedName, and options.
注記:
web 互換性のため、[
createElement()
/ createElementNS()
]の options 引数には文字列も許容される【無視されることになる】。
createElement() and createElementNS()'s options parameter is allowed to be a string for web compatibility.
createDocumentFragment()
メソッド手続きは
:RETURN 新たな文書片
— その
:ノード文書 ← これ°
The createDocumentFragment() method steps are to return a new DocumentFragment node whose node document is this.
createTextNode(data)
メソッド手続きは
:RETURN 新たな Text
ノード( data, これ° )
The createTextNode(data) method steps are to return a new Text node whose data is data and node document is this.
注記:
[
data が Char
生成規則に合致しない文字を含む
]かどうかは、
検査されない。
No check is performed that data consists of characters that match the Char production.
createCDATASection(data)
メソッド手続きは:
The createCDATASection(data) method steps are:
-
IF[
これ°は HTML 文書である
]
:THROW
NotSupportedError
If this is an HTML document, then throw a "NotSupportedError" DOMException. -
IF[
data は文字列 "
]]>
" を包含する ] :THROWInvalidCharacterError
If data contains the string "]]>", then throw an "InvalidCharacterError" DOMException. -
RETURN 新たなオブジェクト(
CDATASection
) — その :データ ← data, ノード文書 ← これ° Return a new CDATASection node with its data set to data and node document set to this.
createComment(data)
メソッド手続きは
:RETURN 新たなオブジェクト( Comment
)
— その
:データ ← data,
ノード文書 ← これ°
The createComment(data) method steps are to return a new Comment node whose data is data and node document is this.
注記:
data が[
Char
生成規則に合致しない文字を含む /
連続する 2 個のハイフン( "--" )を含む /
ハイフンで終わる
]かどうかは、
検査されない。
No check is performed that data consists of characters that match the Char production or that it contains two adjacent hyphens or ends with a hyphen.
createProcessingInstruction(target, data)
メソッド手続きは:
The createProcessingInstruction(target, data) method steps are:
-
IF[
target は
Name
生成規則に合致しない ] :THROWInvalidCharacterError
If target does not match the Name production, then throw an "InvalidCharacterError" DOMException. -
IF[
data は文字列 "
?>
" を含む ] :THROWInvalidCharacterError
If data contains the string "?>", then throw an "InvalidCharacterError" DOMException. -
RETURN 新たなオブジェクト(
ProcessingInstruction
) — その :ターゲット ← target, データ ← data, ノード文書 ← これ° Return a new ProcessingInstruction node, with target set to target, data set to data, and node document set to this.
注記:
[
target が "xml
" または ":
" を含む /
data が Char
生成規則に合致しない文字を含む
]かどうかは、
検査されない。
No check is performed that target contains "xml" or ":", or that data contains characters that match the Char production.
- clone = document .
importNode(node [, subtree = false])
- node の複製を返す。 subtree = true の場合、 複製には node の子孫も含められる。 Returns a copy of node. If subtree is true, the copy also includes the node’s descendants.
-
node が文書または shadow 根である場合,
NotSupportedError
例外が投出される。 If node is a document or a shadow root, throws a "NotSupportedError" DOMException. - node = document .
adoptNode(node)
- node を他の文書から移動させた上で,それを返す。 Moves node from another document and returns it.
-
node が文書である場合,
NotSupportedError
例外が投出される。 If node is a document, throws a "NotSupportedError" DOMException or,\ -
node が shadow 根である場合,
HierarchyRequestError
例外が投出される。 if node is a shadow root, throws a "HierarchyRequestError" DOMException.
importNode(node, subtree)
メソッド手続きは:
The importNode(node, subtree) method steps are:
-
IF[
node は[
文書/shadow 根
]である
]
:THROW
NotSupportedError
If node is a document or shadow root, then throw a "NotSupportedError" DOMException. - RETURN ノードをクローンする( node, subtree, これ° ) Return the result of cloning a node given node with document set to this and subtree set to subtree.
適用可能な仕様は、 すべてまたは一部のノード用に 受入時の手続き を定義してもよい。 このアルゴリズムは、 ノードを受入するアルゴリズム内から, ( ノード, 文書 ) を渡して呼び出される。 Specifications may define adopting steps for all or some nodes. The algorithm is passed node and oldDocument, as indicated in the adopt algorithm.
文書 に ノードを受入する ときは、 所与の ( ノード ) に対し,次を走らす: To adopt a node into a document, run these steps:
- 旧文書 :← ノード のノード文書 Let oldDocument be node’s node document.
- IF[ ノード の親 ≠ null ] :ノードを除去する( ノード ) If node’s parent is non-null, then remove node.
-
IF[ 文書 ≠ 旧文書 ]: If document is not oldDocument:
-
ノード の 各( shadow も含めた広義子孫 広義子孫 ) に対し For each inclusiveDescendant in node’s shadow-including inclusive descendants:
-
ノード の
各( shadow も含めた広義子孫 広義子孫 )
に対し
:IF[
広義子孫 はカスタムである
]
:カスタム要素 callback 反応をエンキューする(
広義子孫,
"
adoptedCallback
", « 旧文書, 文書 » ) For each inclusiveDescendant in node’s shadow-including inclusive descendants that is custom, enqueue a custom element callback reaction with inclusiveDescendant, callback name "adoptedCallback", and « oldDocument, document ». - ノード の 各( shadow も含めた広義子孫 広義子孫 ) に対し,shadow も含めたツリー順序で :適用可能な仕様にて 広義子孫 用に定義された各( 受入時の手続き 手続き ) に対し :手続き( 広義子孫, 旧文書 ) For each inclusiveDescendant in node’s shadow-including inclusive descendants, in shadow-including tree order, run the adopting steps with inclusiveDescendant and oldDocument.
-
adoptNode(node)
メソッド手続きは:
The adoptNode(node) method steps are:
-
IF[
node は文書である
]
:THROW
NotSupportedError
If node is a document, then throw a "NotSupportedError" DOMException. -
IF[
node は shadow 根である
]
:THROW
HierarchyRequestError
If node is a shadow root, then throw a "HierarchyRequestError" DOMException. - IF[ node は文書片である ]∧[ node のホスト ≠ null ] :RETURN If node is a DocumentFragment node whose host is non-null, then return.
- これ°にノードを受入する( node ) Adopt node into this.
- RETURN node Return node.
createAttribute(localName)
メソッド手続きは:
The createAttribute(localName) method steps are:
-
IF[
localName は XML の
Name
生成規則に合致しない ] :THROWInvalidCharacterError
If localName does not match the Name production in XML, then throw an "InvalidCharacterError" DOMException. - IF[ これ°は HTML 文書である ] :localName ← ASCII 小文字化する( localName ) If this is an HTML document, then set localName to localName in ASCII lowercase.
- RETURN 新たな属性° — その :局所名 ← localName, ノード文書 ← これ° Return a new attribute whose local name is localName and node document is this.
createAttributeNS(namespace, qualifiedName)
メソッド手続きは:
The createAttributeNS(namespace, qualifiedName) method steps are:
- ( 名前空間, 接頭辞, 局所名 ) :← 検証して抽出する( namespace, qualifiedName ) Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract.
- RETURN 新たな属性° — その :名前空間 ← 名前空間, 名前空間接頭辞 ← 接頭辞, 局所名 ← 局所名, ノード文書 ← これ° Return a new attribute whose namespace is namespace, namespace prefix is prefix, local name is localName, and node document is this.
createEvent(interface)
メソッド手続きは:
The createEvent(interface) method steps are:
- 構築子 :← null Let constructor be null.
-
IF[ interface は[ 下の表のいずれかの行の 1 列目の文字列 ]に ASCII 大小無視で合致する ] :構築子 ← [ 合致した行の 2 列目のインタフェース ]の構築子 If interface is an ASCII case-insensitive match for any of the strings in the first column in the following table, then set constructor to the interface in the second column on the same row as the matching string:
文字列 String インタフェース Interface 仕様(空欄はこの仕様) Notes " beforeunloadevent
"BeforeUnloadEvent
[HTML] " compositionevent
"CompositionEvent
[UIEVENTS] " customevent
"CustomEvent
" devicemotionevent
"DeviceMotionEvent
[DEVICE-ORIENTATION] " deviceorientationevent
"DeviceOrientationEvent
同上 " dragevent
"DragEvent
[HTML] " event
"Event
" events
"同上 " focusevent
"FocusEvent
[UIEVENTS] " hashchangeevent
"HashChangeEvent
[HTML] " htmlevents
"Event
" keyboardevent
"KeyboardEvent
[UIEVENTS] " messageevent
"MessageEvent
[HTML] " mouseevent
"MouseEvent
[UIEVENTS] " mouseevents
"同上 同上 " storageevent
"StorageEvent
[HTML] " svgevents
"Event
" textevent
"TextEvent
[UIEVENTS] " touchevent
"TouchEvent
[TOUCH-EVENTS] " uievent
"UIEvent
[UIEVENTS] " uievents
"同上 同上 -
IF[
構築子 = null
]
:THROW
NotSupportedError
If constructor is null, then throw a "NotSupportedError" DOMException. -
IF[ 構築子 が指示するインタフェースは,これ°に関連する大域オブジェクトに公開されていない ] :THROW
NotSupportedError
If the interface indicated by constructor is not exposed on the relevant global object of this, then throw a "NotSupportedError" DOMException.注記: 概して UA は、 環境設定によっては,touch イベントのサポートを不能化する — その場合、 この段が
TouchEvent
インタフェース用に誘発されることになる。 Typically user agents disable support for touch events in some configurations, in which case this clause would be triggered for the interface TouchEvent. - イベント :← イベントを作成する( 構築子 ) Let event be the result of creating an event given constructor.
-
イベント の次に挙げる属性を初期化する
:
type
← 空文字列,timeStamp
← 現在の高分解能時刻( これ°に関連する大域オブジェクト ),isTrusted
← false Initialize event’s type attribute to the empty string.Initialize event’s timeStamp attribute to the result of calling current high resolution time with this’s relevant global object.Initialize event’s isTrusted attribute to false. - イベント の初期化済みか ← false Unset event’s initialized flag.
- RETURN イベント Return event.
注記: 代わりに,イベント構築子が利用されるべきである。 Event constructors ought to be used instead.
createRange()
メソッド手続きは
:RETURN 新たな live 範囲°
— その
:始端 ← 境界点( これ°, 0 ),
終端 ← 境界点( これ°, 0 )
The createRange() method steps are to return a new live range with (this, 0) as its start an end.
注記:
代わりに, new Range()
構築子を利用できる。
The Range() constructor can be used instead.
createNodeIterator(root, whatToShow, filter)
メソッド手続きは
:RETURN 新たなオブジェクト( NodeIterator
)
— その
:根 ← root,
起点 ← root,
起点の直前か ← true,
whatToShow ← whatToShow,
フィルタ callback ← filter
The createNodeIterator(root, whatToShow, filter) method steps are:
• Let iterator be a new NodeIterator object.
• Set iterator’s root and iterator’s reference to root.
• Set iterator’s pointer before reference to true.
• Set iterator’s whatToShow to whatToShow.
• Set iterator’s filter to filter.
• Return iterator.createTreeWalker(root, whatToShow, filter)
メソッド手続きは
:RETURN 新たなオブジェクト( TreeWalker
)
— その
:根 ← root,
現ノード ← root,
whatToShow ← whatToShow,
フィルタ callback ← filter
The createTreeWalker(root, whatToShow, filter) method steps are:
• Let walker be a new TreeWalker object.
• Set walker’s root and walker’s current to root.
• Set walker’s whatToShow to whatToShow.
• Set walker’s filter to filter.
• Return walker.4.5.1. DOMImplementation
インタフェース
UA は、
文書 文書 が作成されるときには,
DOMImplementation
オブジェクトを作成して 文書 にそれを結び付けるものとする。
User agents must create a DOMImplementation object whenever a document is created and associate it with that document.
[Exposed=Window]
interface DOMImplementation {
[NewObject] DocumentType createDocumentType(DOMString qualifiedName, DOMString publicId, DOMString systemId);
[NewObject] XMLDocument createDocument(DOMString? namespace, [LegacyNullToEmptyString] DOMString qualifiedName, optional DocumentType? doctype = null);
[NewObject] Document createHTMLDocument(optional DOMString title);
boolean hasFeature(); // 無用の長物 — 常に true を返す
};
- doctype = document .
implementation
.createDocumentType(qualifiedName, publicId, systemId)
-
所与の[
qualifiedName, publicId, systemId
]を伴う doctype を返す。
qualifiedName が[
Name
生成規則に合致しない場合はInvalidCharacterError
例外 /QName
生成規則に合致しない場合はNamespaceError
例外 ]が投出される。 Returns a doctype, with the given qualifiedName, publicId, and systemId. If qualifiedName does not match the Name production, an "InvalidCharacterError" DOMException is thrown, and if it does not match the QName production, a "NamespaceError" DOMException is thrown. - doc = document .
implementation
.createDocument(namespace, qualifiedName [, doctype = null])
-
局所名が qualifiedName で名前空間が namespace
( qualifiedName が空文字列でなければ)
の文書要素を伴い,
doctype が与えられていれば doctype がそれに設定された
XMLDocument
を返す。 Returns an XMLDocument, with a document element whose local name is qualifiedName and whose namespace is namespace (unless qualifiedName is the empty string), and with doctype, if it is given, as its doctype. -
このメソッドは、
createElementNS()
メソッドと同じ例外を, ( namespace, qualifiedName ) で呼び出したときに投出する。 This method throws the same exceptions as the createElementNS() method, when invoked with namespace and qualifiedName. - doc = document .
implementation
.createHTMLDocument([title])
-
基本構造が構築済みなツリーを伴う文書を返す。
title 引数が省略されていなければ
title
要素も含められる。 Returns a document, with a basic tree already constructed including a title element, unless the title argument is omitted.
createDocumentType(qualifiedName, publicId, systemId)
メソッド手続きは:
The createDocumentType(qualifiedName, publicId, systemId) method steps are:
- 有修飾名として検証する( qualifiedName ) Validate qualifiedName.
- RETURN 新たな doctype — その :名前 ← qualifiedName, 公な ID ← publicId, システム ID ← systemId, ノード文書 ← これ°を結び付けている文書 Return a new doctype, with qualifiedName as its name, publicId as its public ID, and systemId as its system ID, and with its node document set to the associated document of this.
注記:
[
publicId を成す符号位置並びが PubidChar
生成規則に合致しない /
systemId が文字 ""
" や "'
" を含む
]かどうかは、
検査されない。
No check is performed that publicId code points match the PubidChar production or that systemId does not contain both a '"' and a "'".
createDocument(namespace, qualifiedName, doctype)
メソッド手続きは:
The createDocument(namespace, qualifiedName, doctype) method steps are:
-
文書 :← 新たなオブジェクト(
XMLDocument
) Let document be a new XMLDocument. - 要素 :← null Let element be null.
- IF[ qualifiedName ≠ 空文字列 ] :要素 ← 内部 createElementNS 手続き( これ°, namespace, qualifiedName, 空な辞書 ) If qualifiedName is not the empty string, then set element to the result of running the internal createElementNS steps, given document, namespace, qualifiedName, and an empty dictionary.
- IF[ doctype ≠ null ] :文書 にノードを付加する( doctype ) If doctype is non-null, append doctype to document.
- IF[ 要素 ≠ null ] :文書 にノードを付加する( 要素 ) If element is non-null, append element to document.
- 文書 の生成元 ← これ°を結び付けている文書の生成元 document’s origin is this’s associated document’s origin.
-
文書 の内容型 ← namespace に応じて
:HTML 名前空間ならば
application/xhtml+xml
/ SVG 名前空間ならばimage/svg+xml
/ 他の場合はapplication/xml
document’s content type is determined by namespace:HTML namespace • application/xhtml+xml SVG namespace • image/svg+xml Any other namespace • application/xml - RETURN 文書 Return document.
createHTMLDocument(title)
メソッド手続きは:
The createHTMLDocument(title) method steps are:
-
文書 :← 新たな文書
— その
:種別 ← "
html
", 内容型 ← "text/html
" Let doc be a new document that is an HTML document.Set doc’s content type to "text/html". -
doctype :← 新たな doctype
— その
:名前 ← "
html
", ノード文書 ← 文書 Append a new doctype, with "html" as its name and with its node document set to doc, to doc. - 文書 にノードを付加する( doctype ) ↑
-
html 要素 :← 要素を作成する( 文書, "
html
", HTML 名前空間 ) Append the result of creating an element given doc, "html", and the HTML namespace, to doc. - 文書 にノードを付加する( html 要素 ) ↑
-
head 要素 :← 要素を作成する( 文書, "
head
", HTML 名前空間 ) Append the result of creating an element given doc, "head", and the HTML namespace, to the html element created earlier. - html 要素 にノードを付加する( head 要素 ) ↑
-
IF[ title ≠ ε ]: If title is given:
-
title 要素 :← 要素を作成する( 文書, "
title
", HTML 名前空間 ) Append the result of creating an element given doc, "title", and the HTML namespace, to the head element created earlier. - head 要素 にノードを付加する( title 要素 ) ↑
-
title 要素 にノードを付加する( 新たな
Text
ノード( title, 文書 ) ) Append a new Text node, with its data set to title (which could be the empty string) and its node document set to doc, to the title element created earlier.
-
title 要素 :← 要素を作成する( 文書, "
-
html 要素 にノードを付加する( 要素を作成する( 文書, "
body
", HTML 名前空間 ) ) Append the result of creating an element given doc, "body", and the HTML namespace, to the html element created earlier. - 文書 の生成元 ← これ°を結び付けている文書の生成元 [HTML] doc’s origin is this’s associated document’s origin.
- RETURN 文書 Return doc.
hasFeature()
メソッド手続きは
:RETURN true
The hasFeature() method steps are to return true.
注記:
hasFeature()
は、
元々は,UA が所与の DOM 特能のサポートを主張しているかどうかを報告するものであったが、
経験から,単に欲される[
オブジェクト/属性/メソッド
]が存在するかどうか検査する用途には ほど遠いことが判明している。
そのようなわけで,それは もはや利用されないが、
古いページが働き続けられるよう存続している
(単に true を返す)。
hasFeature() originally would report whether the user agent claimed to support a given DOM feature, but experience proved it was not nearly as reliable or granular as simply checking whether the desired objects, attributes, or methods existed. As such, it is no longer to be used, but continues to exist (and simply returns true) so that old pages don’t stop working.
4.6. DocumentType
インタフェース
[Exposed=Window]
interface DocumentType : Node {
readonly attribute DOMString name;
readonly attribute DOMString publicId;
readonly attribute DOMString systemId;
};
DocumentType
ノードは、
単に
doctype
とも称される。
DocumentType nodes are simply known as doctypes.
各 doctype には、 次に挙げるものが結び付けられる:
- 名前 :文字列 — 常に,doctype の作成時に与えられる。
- 公な ID :文字列 — doctype の作成時に明示的に与えられない限り,空文字列とする。
- システム ID :文字列 — doctype の作成時に明示的に与えられない限り,空文字列とする。
【 “作成時に…” — 言い換えれば、 作成されて以降は変化しない。 】
Doctypes have an associated name, public ID, and system ID.When a doctype is created, its name is always given. Unless explicitly given when a doctype is created, its public ID and system ID are the empty string.4.7. DocumentFragment
インタフェース
[Exposed=Window]
interface DocumentFragment : Node {
constructor();
};
DocumentFragment
ノードは、
単に
文書片
( document fragment )とも称される。
【これは、この訳にて導入した非公式な用語である。】
各文書片には、 次に挙げるものが結び付けられる:
A DocumentFragment node has an associated host (null or an element in a different node tree). It is null unless otherwise stated.オブジェクト A が オブジェクト B の ホストも含めた広義先祖 であるとは、[ ∨↓ ]が満たされることをいう: An object A is a host-including inclusive ancestor of an object B, if either\
- A は B の広義先祖である A is an inclusive ancestor of B, or\
- B の根のホストを H とするとき,次が満たされる :[ H ≠ null ]∧[ A は H のホストも含めた広義先祖である ] if B’s root has a non-null host and A is a host-including inclusive ancestor of B’s root’s host.
注記:
文書片のホストは,[
shadow 根, HTML の template
要素
]で有用になる概念であり、[
ノードを子の前に前挿入する/子をノードに置換する
]アルゴリズムに影響する。
The DocumentFragment node’s host concept is useful for HTML’s template element and for shadow roots, and impacts the pre-insert and replace algorithms.
- tree =
new DocumentFragment()
- 新たな文書片を返す。 Returns a new DocumentFragment node.
new DocumentFragment()
構築子手続きは
:これ°のノード文書 ← 現在の大域オブジェクトに結び付けられた文書
The new DocumentFragment() constructor steps are to set this’s node document to current global object’s associated Document.
4.8. ShadowRoot
インタフェース
[Exposed=Window]
interface ShadowRoot : DocumentFragment {
readonly attribute ShadowRootMode mode;
readonly attribute boolean delegatesFocus;
readonly attribute SlotAssignmentMode slotAssignment;
readonly attribute boolean clonable;
readonly attribute boolean serializable;
readonly attribute Element host;
attribute EventHandler onslotchange;
};
enum ShadowRootMode { "open
", "closed
" };
enum SlotAssignmentMode { "manual
", "named
" };
ShadowRoot
ノードは、
単に
shadow 根
( shadow root )とも称される。
ShadowRoot nodes are simply known as shadow roots.
各 shadow 根には、 次に挙げるものが結び付けられる: ↓
-
モード
:
ShadowRootMode
値 Shadow roots have an associated mode ("open" or "closed"). - フォーカスを委任するか :真偽値 — 初期時は false とする。 Shadow roots have an associated delegates focus. It is initially set to false.
- 要素の内部特能から可用か :真偽値 — 初期時は false とする。 Shadow roots have an associated available to element internals. It is initially set to false.
- 宣言的か :真偽値 — 初期時は false とする。 Shadow roots have an associated declarative (a boolean). It is initially set to false.
-
slot あてがいモード
:
SlotAssignmentMode
値 ↓ Shadow roots’s associated host is never null.Shadow roots have an associated slot assignment ("manual" or "named"). - クローン可能か :真偽値 — 初期時は false とする。 Shadow roots have an associated clonable (a boolean). It is initially set to false.
- 直列化可能か :真偽値 — 初期時は false とする。 Shadow roots have an associated serializable (a boolean). It is initially set to false.
shadow 根のホストが null になることは決してない。 ↑
shadow 根 根 の親ターゲットを取得するときは、 所与の ( イベント イベント ) に対し: A shadow root’s get the parent algorithm, given an event,\
- IF[ イベント の composed か = false ]∧[ 根 = [[[ イベント の経路 ]内の最初の構造体 ]の呼び出しターゲット ]の根 ] :RETURN null returns null if event’s composed flag is unset and shadow root is the root of event’s path’s first struct’s invocation target;\
- RETURN 根 のホスト otherwise shadow root’s host.
delegatesFocus
取得子手続きは
:RETURN これ°のフォーカスを委任するか
The delegatesFocus getter steps are to return this’s delegates focus.slotAssignment
取得子手続きは
:RETURN これ°の slot あてがいモード
The slotAssignment getter steps are to return this’s slot assignment.serializable
取得子手続きは
:RETURN これ°の直列化可能か
The serializable getter steps are to return this’s serializable.
onslotchange
は、
onslotchange
イベントハンドラ用のイベントハンドラ IDL 属性である
— そのイベントハンドライベント型は slotchange
とする。
The onslotchange attribute is an event handler IDL attribute for the onslotchange event handler, whose event handler event type is slotchange.
ノードツリー ツリー における shadow も含めたツリー順序 は、 shadow も含めた深さ優先かつ前順による辿り による順序であり,次に従う :ツリー に対する深さ優先かつ前順による辿り 【すなわち,通常のツリー順序】 に従いつつ, ツリー において[ shadow ホストである要素 要素 ]に遭遇した各所では,[[ 要素 の shadow 根を根とするノードツリー ]における,shadow も含めた深さ優先かつ前順による辿り ]に従う。 In shadow-including tree order is shadow-including preorder, depth-first traversal of a node tree. Shadow-including preorder, depth-first traversal of a node tree tree is preorder, depth-first traversal of tree, with for each shadow host encountered in tree, shadow-including preorder, depth-first traversal of that element’s shadow root’s node tree just after it is encountered.
オブジェクト O の shadow も含めた根 とは、 O の根を 根 とするとき,[ 根 は shadow 根であるならば 根 のホストの shadow も含めた根 / 他の場合は 根 ]である。 The shadow-including root of an object is its root’s host’s shadow-including root, if the object’s root is a shadow root; otherwise its root.
オブジェクト A がオブジェクト B の shadow も含めた子孫 であるとは、 次が満たされることをいう :[ A は B の子孫である ]∨[ A の根は次を満たす ] :[ shadow 根である ]∧[ そのホストは B の shadow も含めた広義子孫である ] An object A is a shadow-including descendant of an object B, if A is a descendant of B, or A’s root is a shadow root and A’s root’s host is a shadow-including inclusive descendant of B.
オブジェクト A がオブジェクト B の shadow も含めた広義子孫 であるとは、 次が満たされることをいう :[ A = B ]∨[ A は B の shadow も含めた子孫である ] A shadow-including inclusive descendant is an object or one of its shadow-including descendants.
オブジェクト A がオブジェクト B の shadow も含めた先祖 であるとは、 次が満たされることをいう :B は A の shadow も含めた子孫である An object A is a shadow-including ancestor of an object B, if and only if B is a shadow-including descendant of A.
オブジェクト A がオブジェクト B の shadow も含めた広義先祖 であるとは、 次が満たされることをいう :[ A = B ]∨[ A は B の shadow も含めた先祖である ] A shadow-including inclusive ancestor is an object or one of its shadow-including ancestors.
ノード A が ノード B からは 閉じた shadow で非可視 であるとは、 A の根 根 が ∧↓ を満たすことをいう: A node A is closed-shadow-hidden from a node B if all of the following conditions are true:
- 根 は shadow 根である A’s root is a shadow root.
- 根 は B の shadow も含めた広義先祖でない A’s root is not a shadow-including inclusive ancestor of B.
-
[
根 のモード = "
closed
" ]∨[ 根 のホストは B からは閉じた shadow で非可視である ] A’s root is a shadow root whose mode is "closed" or A’s root’s host is closed-shadow-hidden from B.
オブジェクト A を オブジェクト B に向けて ターゲットし直す ときは、 次を走らす: To retarget an object A against an object B,\
-
WHILE 無条件: repeat these steps until they return an object:
- 根 :← A の根 ↓
-
IF[ ∨↓ ]… If one of the following is true
- A はノードでない A is not a node
- 根 は shadow 根でない A’s root is not a shadow root
- [ B はノードである ]∧[ 根 は B の shadow も含めた広義先祖である ] B is a node and A’s root is a shadow-including inclusive ancestor of B
…ならば :RETURN A then return A.
- A ← 根 のホスト Set A to A’s root’s host.
注記: ターゲットし直すアルゴリズムは、 イベントの配送時, および [FULLSCREEN] などの他の仕様により利用される。 The retargeting algorithm is used by event dispatch as well as other specifications, such as Fullscreen. [FULLSCREEN]
4.9. Element
インタフェース
[Exposed=Window]
interface Element : Node {
readonly attribute DOMString? namespaceURI;
readonly attribute DOMString? prefix;
readonly attribute DOMString localName;
readonly attribute DOMString tagName;
[CEReactions] attribute DOMString id;
[CEReactions] attribute DOMString className;
[SameObject, PutForwards=value] readonly attribute DOMTokenList classList;
[CEReactions, Unscopable] attribute DOMString slot;
boolean hasAttributes();
[SameObject] readonly attribute NamedNodeMap attributes;
sequence<DOMString> getAttributeNames();
DOMString? getAttribute(DOMString qualifiedName);
DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
[CEReactions] undefined setAttribute(DOMString qualifiedName, DOMString value);
[CEReactions] undefined setAttributeNS(DOMString? namespace, DOMString qualifiedName, DOMString value);
[CEReactions] undefined removeAttribute(DOMString qualifiedName);
[CEReactions] undefined removeAttributeNS(DOMString? namespace, DOMString localName);
[CEReactions] boolean toggleAttribute(DOMString qualifiedName, optional boolean force);
boolean hasAttribute(DOMString qualifiedName);
boolean hasAttributeNS(DOMString? namespace, DOMString localName);
Attr? getAttributeNode(DOMString qualifiedName);
Attr? getAttributeNodeNS(DOMString? namespace, DOMString localName);
[CEReactions] Attr? setAttributeNode(Attr attr);
[CEReactions] Attr? setAttributeNodeNS(Attr attr);
[CEReactions] Attr removeAttributeNode(Attr attr);
ShadowRoot attachShadow(ShadowRootInit init);
readonly attribute ShadowRoot? shadowRoot;
Element? closest(DOMString selectors);
boolean matches(DOMString selectors);
boolean webkitMatchesSelector(DOMString selectors); // matches の旧来の別名
HTMLCollection getElementsByTagName(DOMString qualifiedName);
HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
HTMLCollection getElementsByClassName(DOMString classNames);
[CEReactions] Element? insertAdjacentElement(DOMString where, Element element); // 旧来
undefined insertAdjacentText(DOMString where, DOMString data); // 旧来
};
dictionary ShadowRootInit {
required ShadowRootMode mode;
boolean delegatesFocus = false;
SlotAssignmentMode slotAssignment = "named
";
boolean clonable = false;
boolean serializable = false;
};
Element
ノードは、
単に
要素
( element )とも称される。
Element nodes are simply known as elements.
各 要素には、
次に挙げるものが結び付けられ,いずれも要素を作成するときに初期化される
:名前空間,
名前空間接頭辞,
局所名,
カスタム要素状態,
カスタム要素定義,
is
値
Elements have an associated namespace, namespace prefix, local name, custom element state, custom element definition, is value. When an element is created, all of these values are initialized.
要素のカスタム要素状態は、
次に挙げるいずれかである
:"undefined
",
"failed
",
"uncustomized
",
"precustomized
",
"custom
"
An element’s custom element state is one of "undefined", "failed", "uncustomized", "precustomized", or "custom".\
所与の要素 要素 に対し:
-
要素 は
定義済み
であるとは、
次が満たされることをいう
:要素 のカスタム要素状態 ∈ { "
uncustomized
", "custom
" } -
要素 は
カスタム
であるとは、
次が満たされることをいう
:要素 のカスタム要素状態 = "
custom
"
注記:
要素が定義済みかどうかは、
:defined
疑似クラスのふるまいを決定するときに利用される。
要素がカスタムかどうかは、
変異アルゴリズムのふるまいを決定するときに利用される。
状態[
"failed
", "precustomized
"
]は、
カスタム要素構築子が[
初回に正しく実行することに失敗した場合
]に[
要素を昇格するとき,再び実行されない
]ことを確保するために利用される。
Whether or not an element is defined is used to determine the behavior of the :defined pseudo-class. Whether or not an element is custom is used to determine the behavior of the mutation algorithms. The "failed" and "precustomized" states are used to ensure that if a custom element constructor fails to execute correctly the first time, it is not executed again by an upgrade.
要素がとり得るこれら 4 種の状態を,次のコードで説明する: The following code illustrates elements in each of these four states:
<!DOCTYPE html> <script> window.customElements.define( "sw-rey", class extends HTMLElement {} ); window.customElements.define( "sw-finn", class extends HTMLElement {}, { extends: "p" } ); window.customElements.define( "sw-kylo", class extends HTMLElement { constructor() { /*super()
は、 この例からは意図的に省略している。 super() intentionally omitted for this example */ } }); </script> <!-- "undefined
" (定義済みでもカスタムでもない) "undefined" (not defined, not custom) --> <sw-han></sw-han> <p is="sw-luke"></p> <p is="asdf"></p> <!-- "failed
" (定義済みでもカスタムでもない) "failed" (not defined, not custom) --> <sw-kylo></sw-kylo> <!-- "uncustomized
" (定義済みだがカスタムではない) "uncustomized" (defined, not custom) --> <p></p> <asdf></asdf> <!-- "custom
" (定義済みかつカスタムである) "custom" (defined, custom) --> <sw-rey></sw-rey> <p is="sw-finn"></p>
各 要素には、 shadow 根 も結び付けられる: Elements also have an associated shadow root\
- それは,[ null / shadow 根 ]であり、 他が言明されない限り, null とする。 (null or a shadow root). It is null unless otherwise stated.\
-
null でない場合、 当の要素は shadow ホスト であるとされる。
【 すなわち,要素は、[ shadow 根を根とする ある shadow ツリー ]をホストしている — 言い換えれば、 ある shadow 根のホストである。 】
An element is a shadow host if its shadow root is non-null.
要素 要素 の 有修飾名 は、 次の手続きの結果を返す:
An element’s qualified name is its local name if its namespace prefix is null; otherwise its namespace prefix, followed by ":", followed by its local name.要素 要素 の HTML 大文字化有修飾名 は、 次の手続きの結果を返す: An element’s HTML-uppercased qualified name is the return value of these steps:
- 有修飾名 :← 要素 の有修飾名 Let qualifiedName be this’s qualified name.
- IF[ 要素 は HTML 名前空間に属する ]∧[ 要素 のノード文書は HTML 文書である ] :RETURN ASCII 大文字化する( 有修飾名 ) If this is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII uppercase.
- RETURN 有修飾名 Return qualifiedName.
注記: UA は、 有修飾名と HTML 大文字化有修飾名を内部 slot に格納して最適化することもできる。 User agents could optimize qualified name and HTML-uppercased qualified name by storing them in internal slots.
要素を作成する ときは、 所与の :文書 文書, 文字列 局所名, [文字列/ null ] 名前空間, [文字列/ null ] 接頭辞 (省略時は null ), [文字列/ null ] is (省略時は null ), 真偽値 同期カスタム要素か(省略時は false ) に対し: To create an element, given a document document, string localName, string-or-null namespace, and optionally a string-or-null prefix (default null), string-or-null is (default null), and boolean synchronousCustomElements (default false):
- 結果 :← null Let result be null.
- 定義 :← カスタム要素定義を検索する( 文書, 名前空間, 局所名, is ) Let definition be the result of looking up a custom element definition given document, namespace, localName, and is.
-
IF[ 定義 ≠ null ]∧[ 定義 の名前 ≠ 定義 の局所名 ](すなわち,定義 はカスタム化された組み込みの要素を表現する): If definition is non-null, and definition’s name is not equal to its local name (i.e., definition represents a customized built-in element):
- インタフェース :← ( 局所名, HTML 名前空間 ) 用の要素インタフェース Let interface be the element interface for localName and the HTML namespace.
-
結果 ← 新たなオブジェクト( インタフェース )
— その
:属性°リスト ← « »,
名前空間 ← HTML 名前空間,
名前空間接頭辞 ← 接頭辞 ,
局所名 ← 局所名,
カスタム要素状態 ← "
undefined
", カスタム要素定義 ← null ,is
値 ← is, ノード文書 ← 文書 Set result to a new element that implements interface,\ with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "undefined", custom element definition set to null, is value set to is, and node document set to document. -
IF[ 同期カスタム要素か = true ] :要素を昇格する( 定義, 結果 ) If synchronousCustomElements is true, then run this step while catching any exceptions: • Upgrade result using definition.
この段から例外 例外 が投出されたときは、 catch して: If this step threw an exception exception:
- ELSE :カスタム要素昇格反応をエンキューする( 結果, 定義 ) Otherwise, enqueue a custom element upgrade reaction given result and definition.
-
ELSE IF[ 定義 ≠ null ]∧[ 同期カスタム要素か = true ]: Otherwise, if definition is non-null: • If synchronousCustomElements is true, then run these steps\
この段から例外が投出されたときは、 catch して,下の (A) に移行するとする while catching any exceptions:
- C :← 定義 の構築子 Let C be definition’s constructor.
- 結果 ← callback 関数で構築する( C, 空な引数リスト ) Set result to the result of constructing C, with no arguments.
- Assert: 結果 の[ カスタム要素状態, カスタム要素定義 ]は初期化済みである Assert: result’s custom element state and custom element definition are initialized.
-
Assert: 結果 の名前空間 = HTML 名前空間 Assert: result’s namespace is the HTML namespace.
注記: IDL により, 結果 は
HTMLElement
オブジェクトになるよう施行され、 そのようなオブジェクトは,すべて HTML 名前空間を利用する。 IDL enforces that result is an HTMLElement object, which all use the HTML namespace. -
IF[ ∨↓ ]…
…ならば :THROW
If result’s attribute list is not empty, then throw a "NotSupportedError" DOMException.If result has children, then throw a "NotSupportedError" DOMException.If result’s parent is not null, then throw a "NotSupportedError" DOMException.If result’s node document is not document, then throw a "NotSupportedError" DOMException.If result’s local name is not equal to localName, then throw a "NotSupportedError" DOMException.NotSupportedError
- 結果 の名前空間接頭辞 ← 接頭辞 Set result’s namespace prefix to prefix.
-
結果 の
is
値 ← null Set result’s is value to null.
(A) — 上の手続きにて,例外 例外 が投出されたときは: If any of these steps threw an exception exception:
- 例外を報告する( 例外, 定義 の構築子に対応する JavaScript オブジェクトが属する realm の大域オブジェクト ) Report exception for definition’s constructor’s corresponding JavaScript object’s associated realm’s global object.
-
結果 ← 新たなオブジェクト(
HTMLUnknownElement
) — その :属性°リスト ← « », 名前空間 ← HTML 名前空間, 名前空間接頭辞 ← 接頭辞, 局所名 ← 局所名, カスタム要素状態 ← "failed
", カスタム要素定義 ← null ,is
値 ← null , ノード文書 ← 文書 Set result to a new element that implements the HTMLUnknownElement interface,\ with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "failed", custom element definition set to null, is value set to null, and node document set to document.
-
ELSE IF[ 定義 ≠ null ]: ↑Otherwise:
-
結果 ← 新たなオブジェクト(
HTMLElement
) — その :属性°リスト ← « », 名前空間 ← HTML 名前空間, 名前空間接頭辞 ← 接頭辞 , 局所名 ← 局所名, カスタム要素状態 ← "undefined
", カスタム要素定義 ← null ,is
値 ← null , ノード文書 ← 文書 Set result to a new element that implements the HTMLElement interface,\ with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "undefined", custom element definition set to null, is value set to null, and node document set to document. - カスタム要素昇格反応をエンキューする( 結果, 定義 ) Enqueue a custom element upgrade reaction given result and definition.
-
結果 ← 新たなオブジェクト(
-
ELSE: Otherwise:
- インタフェース :← ( 局所名, 名前空間 ) 用の要素インタフェース Let interface be the element interface for localName and namespace.
-
結果 ← 新たなオブジェクト( インタフェース )
— その
:属性°リスト ← « »,
名前空間 ← 名前空間,
名前空間接頭辞 ← 接頭辞 ,
局所名 ← 局所名,
カスタム要素状態 ← "
uncustomized
", カスタム要素定義 ← null ,is
値 ← is, ノード文書 ← 文書 Set result to a new element that implements interface,\ with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "uncustomized", custom element definition set to null, is value set to is, and node document set to document. -
IF[ ∧↓ ]…
- 名前空間 = HTML 名前空間
- [ 局所名 は妥当なカスタム要素名である ]∨[ is ≠ null ]
…ならば :結果 のカスタム要素状態 ← "
If namespace is the HTML namespace, and either localName is a valid custom element name or is is non-null, then set result’s custom element state to "undefined".undefined
"
- RETURN 結果 Return result.
各要素は、
属性°リスト
も有する。
それは、
リストであり,
NamedNodeMap
【オブジェクトを返す attributes
属性】
を通して公開される。
要素の作成時に明示的に与えられない限り,その属性°リストは空とする。
Elements also have an attribute list, which is a list exposed through a NamedNodeMap. Unless explicitly given when an element is created, its attribute list is empty.
要素 要素 の属性°リスト内に属性° 属性° が在ることを, 要素 は 属性° を 有する ( has )ともいう。 An element has an attribute A if its attribute list contains A.
【 この場合、[ 属性° が属する要素 = 要素 ]も満たすことになる — 複数の要素が同じ属性°を有することはない (アルゴリズム内で同期的に遂行される ある瞬間を除いて)。 】【 “有する” という句は、 他の仕様(主に HTML )で利用されている。 しかしながら,この訳では、 この用語を(この仕様内では)利用せず,一律に属性°リスト(適用可能な所では属する要素)を通して述べることにする。 】
適用可能な仕様は、 要素用に 属性°変更時の手続き を定義してもよい。 このアルゴリズムは、 当の要素に加えて, ( 局所名, 旧値, 値, 名前空間 ) を渡して呼び出される。 This and other specifications may define attribute change steps for elements. The algorithm is passed element, localName, oldValue, value, and namespace.
属性°値の変化を取り扱う ときは、 所与の ( 属性° 属性°, 要素, 旧値, 新値 ) に対し,次を走らす: To handle attribute changes for an attribute attribute with element, oldValue, and newValue, run these steps:
-
要素 用に種別 "
attributes
" の変異記録をキューする( ↓ ) :属性° の局所名, 属性° の名前空間, 旧値, « », « », null , null Queue a mutation record of "attributes" for element with attribute’s local name, attribute’s namespace, oldValue, « », « », null, and null. -
IF[
要素 はカスタムである
]
:カスタム要素 callback 反応をエンキューする(
要素,
"
attributeChangedCallback
", « 属性° の局所名, 旧値, 新値, 属性° の名前空間 » ) If element is custom, then enqueue a custom element callback reaction with element, callback name "attributeChangedCallback", and « attribute’s local name, oldValue, newValue, attribute’s namespace ». - 適用可能な仕様にて 要素 用に定義された各( 属性°変更時の手続き 手続き ) に対し :手続き( 属性° の局所名, 旧値, 新値, 属性° の名前空間 ) Run the attribute change steps with element, attribute’s local name, oldValue, newValue, and attribute’s namespace.
属性°値を変更する ときは、 所与の ( 属性° 属性°, 値 ) に対し,次を走らす: To change an attribute attribute to value, run these steps:
- 旧値 :← 属性° の値 Let oldValue be attribute’s value.
- 属性° の値 ← 値 Set attribute’s value to value.
- 属性°値の変化を取り扱う( 属性°, 属性° が属する要素, 旧値, 値 ) Handle attribute changes for attribute with attribute’s element, oldValue, and value.
属性°を付加する ときは、 所与の ( 属性° 属性°, 要素 要素 ) に対し,次を走らす: To append an attribute attribute to an element element, run these steps:
- 要素 の属性°リストに 属性° を付加する Append attribute to element’s attribute list.
- 属性° が属する要素 ← 要素 Set attribute’s element to element.
- 属性°値の変化を取り扱う( 属性°, 要素, null , 属性° の値 ) Handle attribute changes for attribute with element, null, and attribute’s value.
属性°を除去する ときは、 所与の ( 属性° 属性° ) に対し,次を走らす: To remove an attribute attribute, run these steps:
属性°を置換する ときは、 所与の ( 属性° 旧属性°, 属性° 新属性° ) に対し,次を走らす: To replace an attribute oldAttr with an attribute newAttr, run these steps:
- 旧属性° が属する要素の属性°リスト内で, 旧属性° を 新属性° に置換する Replace oldAttr by newAttr in oldAttr’s element’s attribute list.
- 新属性° が属する要素 ← 旧属性° が属する要素 Set newAttr’s element to oldAttr’s element.
- 旧属性° が属する要素 ← null Set oldAttr’s element to null.
- 属性°値の変化を取り扱う( 旧属性°, 新属性° が属する要素, 旧属性° の値, 新属性° の値 ) Handle attribute changes for oldAttr with newAttr’s element, oldAttr’s value, and newAttr’s value.
要素 要素 の 属性°を名前により取得する ときは、 所与の ( 文字列 有修飾名 ) に対し: To get an attribute by name given a string qualifiedName and an element element:
- IF[ 要素 は HTML 名前空間に属する ]∧[ 要素 のノード文書は HTML 文書である ] :有修飾名 ← ASCII 小文字化する( 有修飾名 ) If element is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
- RETURN 要素 の属性°リストを成す属性°のうち,次を満たす最初のもの? :有修飾名 = 有修飾名 Return the first attribute in element’s attribute list whose qualified name is qualifiedName; otherwise null.
要素 要素 の 属性°を名前空間と局所名により取得する ときは、 所与の ( [ 文字列 / null ] 名前空間, 文字列 局所名 ) に対し: To get an attribute by namespace and local name given null or a string namespace, a string localName, and an element element:
要素 要素 の 属性°値を取得する ときは、 所与の ( 文字列 局所名, [ 文字列 / null ] 名前空間 (省略時は null ) ) に対し: To get an attribute value given an element element, a string localName, and an optional null or string namespace (default null):
- 属性° :← 要素 の属性°を名前空間と局所名により取得する( 局所名, 名前空間 ) Let attr be the result of getting an attribute given namespace, localName, and element.
- RETURN [ 属性° = null ならば空文字列 / 他の場合は 属性° の値 ] If attr is null, then return the empty string.Return attr’s value.
要素 要素 の 属性°を設定する ときは、 所与の ( 属性° 属性° ) に対し: To set an attribute given an attribute attr and an element element:
-
IF[
属性° が属する要素 ∉ { null , 要素 }
]
:THROW
InUseAttributeError
If attr’s element is neither null nor element, throw an "InUseAttributeError" DOMException. - 旧属性° :← 要素 の属性°を名前空間と局所名により取得する( 属性° の名前空間, 属性° の局所名 ) Let oldAttr be the result of getting an attribute given attr’s namespace, attr’s local name, and element.
- IF[ 旧属性° = 属性° ] :RETURN 属性° If oldAttr is attr, return attr.
- IF[ 旧属性° ≠ null ] :属性°を置換する( 旧属性°, 属性° ) If oldAttr is non-null, then replace oldAttr with attr.
- ELSE :属性°を付加する( 属性°, 要素 ) Otherwise, append attr to element.
- RETURN 旧属性° Return oldAttr.
要素 要素 の 属性°値を設定する ときは、 所与の :文字列 局所名, 文字列 値, [ 文字列 / null ] 接頭辞 (省略時は null ), [ 文字列 / null ] 名前空間 (省略時は null ) ) に対し,次を走らす: To set an attribute value given an element element, a string localName, a string value, an optional null or string prefix (default null), and an optional null or string namespace (default null):
- 属性° :← 要素 の属性°を名前空間と局所名により取得する( 名前空間, 局所名 ) Let attribute be the result of getting an attribute given namespace, localName, and element.
-
IF[ 属性° = null ]: If attribute is null,\
- 属性° :← 新たな属性° — その :名前空間 ← 名前空間, 名前空間接頭辞 ← 接頭辞, 局所名 ← 局所名, 値 ← 値, ノード文書 ← 要素 のノード文書 create an attribute whose namespace is namespace, namespace prefix is prefix, local name is localName, value is value, and node document is element’s node document,\
- 属性°を付加する( 属性°, 要素 ) then append this attribute to element,\
- RETURN and then return.
- 属性°値を変更する( 属性°, 値 ) Change attribute to value.
要素 要素 の 属性°を名前により除去する ときは、 所与の ( 文字列 有修飾名 ) に対し: To remove an attribute by name given a string qualifiedName and an element element:
- 属性° :← 要素 の属性°を名前により取得する( 有修飾名 ) Let attr be the result of getting an attribute given qualifiedName and element.
- IF[ 属性° ≠ null ] :属性°を除去する( 属性° ) If attr is non-null, then remove attr.
- RETURN 属性° Return attr.
要素 要素 の 属性°を名前空間と局所名により除去する ときは、 所与の ( [ 文字列 / null ] 名前空間, 文字列 局所名 ) に対し: To remove an attribute by namespace and local name given null or a string namespace, a string localName, and an element element:
- 属性° :← 要素 の属性°を名前空間と局所名により取得する( 名前空間, 局所名 ) Let attr be the result of getting an attribute given namespace, localName, and element.
- IF[ 属性° ≠ null ] :属性°を除去する( 属性° ) If attr is non-null, then remove attr.
- RETURN 属性° Return attr.
各 要素には、 ID が結び付けられる — それは、[ 一意†な識別子を与える文字列 / ε †† ]であり,初期時は ε とする。 An element can have an associated unique identifier (ID)
【†
この “一意” は、
文書内で一意を意味する。
これは、
適合性の目的において,そう要求されることを意味する
— 不適合な文書においては、
複数個の要素が同じ ID ( ≠ ε )を伴い得る。
】【††
具体的には、
要素が id
属性°を有さないとき ε になる
(原文では, “ID は無い”, “ID を未設定にする” の様な句で表現されているが、
この訳では ε で表現する)。
】
注記:
歴史的に,要素は複数個の識別子を有することもできていた
— 例えば、
HTML id
属性°と DTD を利用して。
この仕様では、
ID を DOM の概念とし,
各要素に対し id
属性°で与えられる 1 個に限るとする。
Historically elements could have multiple identifiers e.g., by using the HTML id attribute and a DTD. This specification makes ID a concept of the DOM and allows for only one per element, given by an id attribute.
要素 要素 の ID を更新するときは、 要素 用の属性°変更時の手続きとして次を利用する — それは、 所与の ( 局所名, 旧値, 値, 名前空間 ) に対し:
-
IF[
局所名 = "
id
" ]∧[ 名前空間 = null ] :要素 の ID ← [ 値 ∈ { null , 空文字列 } ならば ε / 他の場合は 値 ]
注記:
この仕様は、
どの要素に対しても,その[
id
/ class
/ slot
]属性°用の要件を定義しているが、
これらの属性°を利用をするかどうかは,適合性の要件にしていない。
While this specification defines requirements for class, id, and slot attributes on any element, it makes no claims as to whether using them is conforming or not.
ノード N の 親要素 とは、[ N の親は要素であるならば それ / 他の場合は null ]である。 A node’s parent of type Element is known as its parent element. If the node has a parent of a different type, its parent element is null.
- namespace = element .
namespaceURI
- 名前空間を返す。 Returns the namespace.
- prefix = element .
prefix
- 名前空間接頭辞を返す。 Returns the namespace prefix.
- localName = element .
localName
- 局所名を返す。 Returns the local name.
- qualifiedName = element .
tagName
- HTML 大文字化有修飾名を返す。 Returns the HTML-uppercased qualified name.
tagName
取得子手続きは
:RETURN これ°の HTML 大文字化有修飾名
The tagName getter steps are to return this’s HTML-uppercased qualified name.- element .
id
[ = value ] -
element の
id
属性°の値を返す。 設定して変更できる。 Returns the value of element’s id content attribute. Can be set to change it. - element .
className
[ = value ] -
element の
class
属性°の値を返す。 設定して変更できる。 Returns the value of element’s class content attribute. Can be set to change it. - element .
classList
-
element の
class
属性°を,空白で分離されたトークンたちが成す集合として —DOMTokenList
オブジェクトを通して — 操作できるようにする。 Allows for manipulation of element’s class content attribute as a set of whitespace-separated tokens through a DOMTokenList object. - element .
slot
[ = value ] -
element の
slot
属性°を返す。 設定して変更できる。 Returns the value of element’s slot content attribute. Can be set to change it.
所与の文字列 名前 を 反映する ように定義される IDL 属性は、 次の[ 取得子手続き, 設定子手続き ]を有するものとする: IDL attributes that are defined to reflect a string name, must have these getter and setter steps:
- 取得子手続きは :RETURN これ°の属性°値を取得する( 名前 ) getter steps • Return the result of running get an attribute value given this and name.
- 設定子手続きは :これ°の属性°値を設定する( 名前, 所与の値 ) setter steps • Set an attribute value for this using name and the given value.
id
属性は、
"id
" を反映するものとする。
The id attribute must reflect "id".
className
属性は、
"class
" を反映するものとする。
The className attribute must reflect "class".
classList
取得子手続きは
:RETURN DOMTokenList
— その
:要素 ← これ°,
属性°の局所名 ← class
The classList getter steps are to return a DOMTokenList object whose associated element is this and whose associated attribute’s local name is class.\
この取得子が返す DOMTokenList
オブジェクトのトークン集合は、
要素の
クラス群
とも称される。
The token set of this particular DOMTokenList object are also known as the element’s classes.
【 [SameObject] が指定されているので、 各要素とこのオブジェクトの各インスタンスは,一対一に対応する。 】
slot
属性は、
"slot
" を反映するものとする。
The slot attribute must reflect "slot".
注記:
[
id
/ class
/ slot
]属性°は、
要素の名前空間にかかわらず どの要素上にも現れ得るので、
実質的に,(すべての名前空間より)上位の大域属性になる。
id, class, and slot are effectively superglobal attributes as they can appear on any element, regardless of that element’s namespace.
- element .
hasAttributes()
- [ element の属性°リストは空でないならば true / 他の場合は false ]を返す。 Returns true if element has attributes; otherwise false.
- element .
getAttributeNames()
- element のすべての属性°の有修飾名を返す — 重複を包含し得る。 Returns the qualified names of all element’s attributes. Can contain duplicates.
- element .
getAttribute(qualifiedName)
- element の属性°リストを成す属性°のうち,次を満たす最初のもの?を返す :有修飾名 = qualifiedName Returns element’s first attribute whose qualified name is qualifiedName, and null if there is no such attribute otherwise.
- element .
getAttributeNS(namespace, localName)
- element の属性°リストを成す属性°のうち,次を満たす最初のもの?を返す :[ 名前空間 = namespace ]∧[ 局所名 = localName ] Returns element’s attribute whose namespace is namespace and local name is localName, and null if there is no such attribute otherwise.
- element .
setAttribute(qualifiedName, value)
- element の属性°リスト内に次を満たす属性°は在るならば[ それらのうち最初のもの ]の値を value に設定する :有修飾名 = qualifiedName Sets the value of element’s first attribute whose qualified name is qualifiedName to value.
- element .
setAttributeNS(namespace, localName, value)
- element の属性°リスト内に次を満たす属性°は在るならば[ それらのうち最初のもの ]の値を value に設定する :[ 名前空間 = namespace ]∧[ 局所名 = localName ] Sets the value of element’s attribute whose namespace is namespace and local name is localName to value.
- element .
removeAttribute(qualifiedName)
- element の属性°リスト内に次を満たす属性°は在るならば[ それらのうち最初のもの ]を element から除去する :有修飾名 = qualifiedName Removes element’s first attribute whose qualified name is qualifiedName.
- element .
removeAttributeNS(namespace, localName)
- element の属性°リスト内に次を満たす属性°は在るならば[ それらのうち最初のもの ]を element から除去する :[ 名前空間 = namespace ]∧[ 局所名 = localName ] Removes element’s attribute whose namespace is namespace and local name is localName.
- element .
toggleAttribute(qualifiedName [, force])
-
force に応じて:
- 省略されているならば、 qualifiedName の有無を “トグルする” — すなわち,それがすでに在るならば除去し,無いならば追加する。
- true ならば、 qualifiedName を追加する。
- false ならば、 qualifiedName を除去する。
その結果、 qualifiedName が[ 残っていれば true / 無くなっていれば false ]を返す。
If force is not given, "toggles" qualifiedName, removing it if it is present and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName.Returns true if qualifiedName is now present; otherwise false. - element .
hasAttribute(qualifiedName)
- element の属性°リスト内に次を満たす属性°は[ 在るならば true / 無いならば false ]を返す :有修飾名 = qualifiedName Returns true if element has an attribute whose qualified name is qualifiedName; otherwise false.
- element .
hasAttributeNS(namespace, localName)
- element の属性°リスト内に次を満たす属性°は[ 在るならば true / 無いならば false ]を返す :[ 名前空間 = namespace ]∧[ 局所名 = localName ] Returns true if element has an attribute whose namespace is namespace and local name is localName.
hasAttributes()
メソッド手続きは
:RETURN IS[
これ°の属性°リストは空でない
]
The hasAttributes() method steps are to return false if this’s attribute list is empty; otherwise true.attributes
取得子手続きは
:RETURN これ°に結び付けられた NamedNodeMap
The attributes getter steps are to return the associated NamedNodeMap.
getAttributeNames()
メソッド手続きは:
注記: 名前が 結果 内で一意になることは保証されない。
The getAttributeNames() method steps are to return the qualified names of the attributes in this’s attribute list, in order; otherwise a new list.These are not guaranteed to be unique.
getAttribute(qualifiedName)
メソッド手続きは:
The getAttribute(qualifiedName) method steps are:
- 属性° :← これ°の属性°を名前により取得する( qualifiedName ) Let attr be the result of getting an attribute given qualifiedName and this.
- RETURN [ 属性° = null ならば null / 他の場合は 属性° の値 ] If attr is null, return null.Return attr’s value.
getAttributeNS(namespace, localName)
メソッド手続きは:
The getAttributeNS(namespace, localName) method steps are:
- 属性° :← これ°の属性°を名前空間と局所名により取得する( namespace, localName ) Let attr be the result of getting an attribute given namespace, localName, and this.
- IF[ 属性° = null ] :RETURN null If attr is null, return null.
- RETURN 属性° の値 Return attr’s value.
setAttribute(qualifiedName, value)
メソッド手続きは:
The setAttribute(qualifiedName, value) method steps are:
-
IF[
qualifiedName は XML の
Name
生成規則に合致しない ] :THROWInvalidCharacterError
If qualifiedName does not match the Name production in XML, then throw an "InvalidCharacterError" DOMException. - IF[ これ°は HTML 名前空間に属する ]∧[ これ°のノード文書は HTML 文書である ] :qualifiedName ← ASCII 小文字化する( qualifiedName ) If this is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
- 属性° :← これ°の属性°リストを成す属性°のうち,次を満たす最初のもの? :有修飾名 = qualifiedName Let attribute be the first attribute in this’s attribute list whose qualified name is qualifiedName, and null otherwise.
-
IF[ 属性° = null ]: If attribute is null,\
- 属性°値を変更する( 属性°, value ) Change attribute to value.
setAttributeNS(namespace, qualifiedName, value)
メソッド手続きは:
The setAttributeNS(namespace, qualifiedName, value) method steps are:
removeAttribute(qualifiedName)
メソッド手続きは
:これ°の属性°を名前により除去する( qualifiedName )
The removeAttribute(qualifiedName) method steps are to remove an attribute given qualifiedName and this, and then return undefined.removeAttributeNS(namespace, localName)
メソッド手続きは
:これ°の属性°を名前空間と局所名により除去する( namespace, localName )
The removeAttributeNS(namespace, localName) method steps are to remove an attribute given namespace, localName, and this, and then return undefined.
hasAttribute(qualifiedName)
メソッド手続きは:
The hasAttribute(qualifiedName) method steps are:
- IF[ これ°は HTML 名前空間に属する ]∧[ これ°のノード文書は HTML 文書である ] :qualifiedName ← ASCII 小文字化する( qualifiedName ) If this is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
- RETURN IS[ これ°の属性°リスト内に次を満たす属性°は在る ] :有修飾名 = qualifiedName Return true if this has an attribute whose qualified name is qualifiedName; otherwise false.
toggleAttribute(qualifiedName, force)
メソッド手続きは:
The toggleAttribute(qualifiedName, force) method steps are:
-
IF[
qualifiedName は XML の
Name
生成規則に合致しない ] :THROWInvalidCharacterError
If qualifiedName does not match the Name production in XML, then throw an "InvalidCharacterError" DOMException. - IF[ これ°は HTML 名前空間に属する ]∧[ これ°のノード文書は HTML 文書である ] :qualifiedName ← ASCII 小文字化する( qualifiedName ) If this is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
- 属性° :← これ°の属性°リストを成す属性°のうち,次を満たす最初のもの? :有修飾名 = qualifiedName Let attribute be the first attribute in this’s attribute list whose qualified name is qualifiedName, and null otherwise.
- 結果 :← IS[ force = true ]∨[[ force = ε ]∧[ 属性° = null ]] ↓
-
IF[ 結果 = true ]∧[ 属性° = null ]: If attribute is null:
- 属性° :← 新たな属性° — その :局所名 ← qualifiedName, 値 ← 空文字列, ノード文書 ← これ°のノード文書 ↑If force is not given or is true,\ create an attribute whose local name is qualifiedName, value is the empty string, and node document is this’s node document,\
- 属性°を付加する( 属性°, これ° ) then append this attribute to this,\ ↓and then return true.↓Return false.
- ELSE IF[ 結果 = false ]∧[ 属性° ≠ null ] :これ°の属性°を名前により除去する( qualifiedName ); Otherwise, if force is not given or is false, remove an attribute given qualifiedName and this,\ ↓and then return false.
- RETURN 結果 Return true.
hasAttributeNS(namespace, localName)
メソッド手続きは:
The hasAttributeNS(namespace, localName) method steps are:
getAttributeNode(qualifiedName)
メソッド手続きは
:RETURN これ°の属性°を名前により取得する( qualifiedName )
The getAttributeNode(qualifiedName) method steps are to return the result of getting an attribute given qualifiedName and this.getAttributeNodeNS(namespace, localName)
メソッド手続きは
:RETURN これ°の属性°を名前空間と局所名により取得する( namespace, localName )
The getAttributeNodeNS(namespace, localName) method steps are to return the result of getting an attribute given namespace, localName, and this.setAttributeNode(attr)
,
setAttributeNodeNS(attr)
メソッド手続きは、
いずれも
:RETURN これ°の属性°を設定する( attr )
The setAttributeNode(attr) and setAttributeNodeNS(attr) methods steps are to return the result of setting an attribute given attr and this.
removeAttributeNode(attr)
メソッド手続きは:
The removeAttributeNode(attr) method steps are:
-
IF[
attr ∉ これ°の属性°リスト
]
:THROW
NotFoundError
If this’s attribute list does not contain attr, then throw a "NotFoundError" DOMException. - 属性°を除去する( attr ) Remove attr.
- RETURN attr Return attr.
- shadow = element .
attachShadow(init)
- element 用に shadow 根を作成した上で,それを返す。 Creates a shadow root for element and returns it.
- shadow = element .
shadowRoot
-
element の shadow 根 shadow は非 null ,かつ shadow の[
モード = "
open
" ]ならば shadow を返す。 他の場合は null を返す。 Returns element’s shadow root, if any, and if shadow root’s mode is "open", and null otherwise.
次に挙げるものが, 妥当な shadow ホスト名 であるとされる: A valid shadow host name is:
- 妥当なカスタム要素名 a valid custom element name
-
"
article
", "aside
", "blockquote
", "body
", "div
", "footer
", "h1
", "h2
", "h3
", "h4
", "h5
", "h6
", "header
", "main
", "nav
", "p
", "section
", "span
" "article", "aside", "blockquote", "body", "div", "footer", "h1", "h2", "h3", "h4", "h5", "h6", "header", "main", "nav", "p", "section", or "span"
attachShadow(init)
メソッド手続きは:
The attachShadow(init) method steps are:
-
shadow 根を付する( ↓ )
:これ°,
init[ "
mode
" ], init[ "clonable
" ], init[ "serializable
" ], init[ "delegatesFocus
" ], init[ "slotAssignment
" ] Run attach a shadow root with this, init["mode"], init["clonable"], init["serializable"], init["delegatesFocus"], and init["slotAssignment"]. - RETURN これ°の shadow 根 Return this’s shadow root.
shadow 根を付する
ときは、
所与の
:要素 要素,
文字列 モード,
真偽値 クローン可能か,
真偽値 直列化可能か,
真偽値 フォーカスを委任するか,
SlotAssignmentMode
値 slot あてがいモード
に対し:
To attach a shadow root, given an element element, a string mode, a boolean clonable, a boolean serializable, a boolean delegatesFocus, and a string slotAssignment:
-
IF[
要素 の名前空間 ≠ HTML 名前空間
]
:THROW
NotSupportedError
If element’s namespace is not the HTML namespace, then throw a "NotSupportedError" DOMException. -
IF[
要素 の局所名は妥当な shadow ホスト名でない
]
:THROW
NotSupportedError
If element’s local name is not a valid shadow host name, then throw a "NotSupportedError" DOMException. -
IF[ 要素 の局所名は妥当なカスタム要素名である ]∨[ 要素 の
is
値 ≠ null ]: If element’s local name is a valid custom element name, or element’s is value is non-null:-
定義 :← カスタム要素定義を検索する( ↓ )
:要素 のノード文書,
要素 の名前空間,
要素 の局所名,
要素 の
is
値 Let definition be the result of looking up a custom element definition given element’s node document, its namespace, its local name, and its is value. -
IF[
定義 ≠ null
]∧[
定義 の shadow を不能化するか = true
]
:THROW
NotSupportedError
If definition is not null and definition’s disable shadow is true, then throw a "NotSupportedError" DOMException.
-
定義 :← カスタム要素定義を検索する( ↓ )
:要素 のノード文書,
要素 の名前空間,
要素 の局所名,
要素 の
- 現在の shadow 根 :← 要素 の shadow 根 ↓
-
IF[ 現在の shadow 根 ≠ null ]: If element is a shadow host: • Let currentShadowRoot be element’s shadow root.
-
IF[ ∨↓ ]… If any of the following are true:
- 現在の shadow 根 の宣言的か = false currentShadowRoot’s declarative is false; or
- 現在の shadow 根 のモード ≠ モード currentShadowRoot’s mode is not mode,
…ならば :THROW
NotSupportedError
then throw a "NotSupportedError" DOMException. -
ELSE: Otherwise:
-
-
要素の内部特能から可用か :← IS[
要素 のカスタム要素状態 ∈ { "
precustomized
", "custom
" } ] ↓ - 要素 の shadow 根 ← 新たな shadow 根 — その :ノード文書 ← 要素 のノード文書, ホスト ← 要素, モード ← モード, フォーカスを委任するか ← フォーカスを委任するか, 要素の内部特能から可用か ← 要素の内部特能から可用か, slot あてがいモード ← slot あてがいモード, 宣言的か ← false, クローン可能か ← クローン可能か, 直列化可能か ← 直列化可能か Let shadow be a new shadow root whose node document is element’s node document, host is element, and mode is mode.Set shadow’s delegates focus to delegatesFocus.If element’s custom element state is "precustomized" or "custom", then set shadow’s available to element internals to true.Set shadow’s slot assignment to slotAssignment.Set shadow’s declarative to false.Set shadow’s clonable to clonable.Set shadow’s serializable to serializable.Set element’s shadow root to shadow.
shadowRoot
取得子手続きは:
The shadowRoot getter steps are:
- element .
closest(selectors)
- element の広義先祖であって, selectors に合致するような要素が[ 在るならば,それらのうち element に最も近いもの / 無いならば null ]を返す。 Returns the first (starting at element) inclusive ancestor that matches selectors, and null otherwise.
- element .
matches(selectors)
- element の根に対し selectors を照合した結果,[ element が得られるならば true / 他の場合は false ]を返す。 Returns true if matching selectors against element’s root yields element; otherwise false.
closest(selectors)
メソッド手続きは:
The closest(selectors) method steps are:
- 選択子 :← 選択子として構文解析する( selectors ) [SELECTORS4] Let s be the result of parse a selector from selectors. [SELECTORS4]
-
IF[
選択子 = 失敗
]
:THROW
SyntaxError
If s is failure, then throw a "SyntaxError" DOMException. - 要素 :← これ° ↓
-
WHILE[ 要素 は要素である ]:
- IF[ 要素に対し選択子を照合する( 要素, 選択子, 視野根たちが成す集合 { これ° } ) = 成功 [SELECTORS4] ] :RETURN 要素
- 要素 ← 要素 の親
- RETURN null Return null.
matches(selectors)
,
webkitMatchesSelector(selectors)
メソッド手続きは、
いずれも:
The matches(selectors) and webkitMatchesSelector(selectors) method steps are:
- 選択子 :← 選択子として構文解析する( selectors ) [SELECTORS4] Let s be the result of parse a selector from selectors. [SELECTORS4]
-
IF[
選択子 = 失敗
]
:THROW
SyntaxError
If s is failure, then throw a "SyntaxError" DOMException. - RETURN IS[ 次の結果 = 成功 ] :要素に対し選択子を照合する( これ°, 選択子, 視野根たちが成す集合 { これ° } ) [SELECTORS4] If the result of match a selector against an element, using s, this, and scoping root this, returns success, then return true; otherwise, return false. [SELECTORS4]
getElementsByTagName(qualifiedName)
メソッド手続きは
:RETURN これ°用の[
qualifiedName を有修飾名に持つ要素のリスト
]
The getElementsByTagName(qualifiedName) method steps are to return the list of elements with qualified name qualifiedName for this.getElementsByTagNameNS(namespace, localName)
メソッド手続きは
:RETURN これ°用の[
( namespace, localName ) を
( 名前空間, 局所名 ) に持つ要素のリスト
]
The getElementsByTagNameNS(namespace, localName) method steps are to return the list of elements with namespace namespace and local name localName for this.getElementsByClassName(classNames)
メソッド手続きは
:RETURN これ°用の[
classNames をクラス群に含む要素のリスト
]
The getElementsByClassName(classNames) method steps are to return the list of elements with class names classNames for this.要素 要素 の 隣にノードを挿入する ときは、 所与の ( 文字列 where, ノード ノード ) に対し: To insert adjacent, given an element element, string where, and a node node,\
- where ← ASCII 小文字化する( where ) ↓
-
where に応じて: run the steps associated with the first ASCII case-insensitive match for where:
-
"
beforebegin
" :"beforebegin"- IF[ 要素 の親 = null ] :RETURN null If element’s parent is null, return null.
- RETURN 要素 の親の中でノードを子の前に前挿入する( ノード, 要素 ) Return the result of pre-inserting node into element’s parent before element.
-
"
afterbegin
" :RETURN 要素 の中でノードを子の前に前挿入する( ノード, 要素 の最初の子? ) "afterbegin" • Return the result of pre-inserting node into element before element’s first child. -
"
beforeend
" :RETURN 要素 の中でノードを子の前に前挿入する( ノード, null ) "beforeend" • Return the result of pre-inserting node into element before null. -
"
afterend
": "afterend"- IF[ 要素 の親 = null ] :RETURN null If element’s parent is null, return null.
- RETURN 要素 の親の中でノードを子の前に前挿入する( ノード, 要素 の直後の同胞? ) Return the result of pre-inserting node into element’s parent before element’s next sibling.
-
その他
:THROW
SyntaxError
Otherwise • Throw a "SyntaxError" DOMException.
-
insertAdjacentElement(where, element)
メソッド手続きは
:RETURN element の隣にノードを挿入する( where, これ° )
The insertAdjacentElement(where, element) method steps are to\
return the result of running insert adjacent, give this, where, and element.
insertAdjacentText(where, data)
メソッド手続きは:
The insertAdjacentText(where, data) method steps are:
-
text :← 新たな
Text
ノード( data, これ°のノード文書 ) Let text be a new Text node whose data is data and node document is this’s node document. - これ°の隣にノードを挿入する( where, text ) Run insert adjacent, given this, where, and text.
注記: このメソッドは何も返さない — それを設計する機会を得る前からすでに存在していたので。 This method returns nothing because it existed before we had a chance to design it.
【
参考:
insertAdjacentHTML()
という類似な便利メソッドもある。
】
4.9.1. NamedNodeMap
インタフェース
[Exposed=Window,
LegacyUnenumerableNamedProperties]
interface NamedNodeMap {
readonly attribute unsigned long length;
getter Attr? item(unsigned long index);
getter Attr? getNamedItem(DOMString qualifiedName);
Attr? getNamedItemNS(DOMString? namespace, DOMString localName);
[CEReactions] Attr? setNamedItem(Attr attr);
[CEReactions] Attr? setNamedItemNS(Attr attr);
[CEReactions] Attr removeNamedItem(DOMString qualifiedName);
[CEReactions] Attr removeNamedItemNS(DOMString? namespace, DOMString localName);
};
各 NamedNodeMap
オブジェクトには、
次に挙げるものが結び付けられる:
- 要素 :要素。
NamedNodeMap
オブジェクト O の
属性°リスト
は、
O の要素の属性°リストを指す。
A NamedNodeMap object’s attribute list is its element’s attribute list.
NamedNodeMap
オブジェクト O がサポートするプロパティ index は、
0 以上[
O の属性°リストのサイズ
]未満とする。
A NamedNodeMap object’s supported property indices are the numbers in the range zero to its attribute list’s size minus one, unless the attribute list is empty, in which case there are no supported property indices.
length
取得子手続きは
:RETURN これ°の属性°リストのサイズ
The length getter steps are to return the attribute list’s size.item(index)
メソッド手続きは
:RETURN [
index ∉ { これ°がサポートするプロパティ index } ならば null /
他の場合は これ°の属性°リスト[ index ]
]
The item(index) method steps are:
• If index is equal to or greater than this’s attribute list’s size, then return null.
• Otherwise, return this’s attribute list[index].
NamedNodeMap
オブジェクト O がサポートするプロパティ名たちは、
次の手続きの結果で与えられる:
A NamedNodeMap object’s supported property names are the return value of running these steps:
- 名前群 :← O の属性°リスト 内の各[ 属性°の有修飾名 ]たちが成す,同順のリスト Let names be the qualified names of the attributes in this NamedNodeMap object’s attribute list, with duplicates omitted, in order.
- 要素 :← O の要素 ↓
- IF[ 要素 は HTML 名前空間に属する ]∧[ 要素 のノード文書は HTML 文書である ] :名前群 を成す 各( 名前 ) に対し :IF[ ASCII 小文字化する( 名前 ) ≠ 名前 ] :名前 を 名前群 から除去する If this NamedNodeMap object’s element is in the HTML namespace and its node document is an HTML document, then for each name in names: • Let lowercaseName be name, in ASCII lowercase. • If lowercaseName is not equal to name, remove name from names.
- RETURN 名前群 Return names.
getNamedItem(qualifiedName)
メソッド手続きは
:RETURN これ°の要素の属性°を名前により取得する( qualifiedName )
The getNamedItem(qualifiedName) method steps are to return the result of getting an attribute given qualifiedName and element.getNamedItemNS(namespace, localName)
メソッド手続きは
:RETURN これ°の要素の属性°を名前空間と局所名により取得する( namespace, localName )
The getNamedItemNS(namespace, localName) method steps are to return the result of getting an attribute given namespace, localName, and element.setNamedItem(attr)
,
setNamedItemNS(attr)
メソッド手続きは:
:RETURN これ°の要素の属性°を設定する( attr )
The setNamedItem(attr) and setNamedItemNS(attr) method steps are to return the result of setting an attribute given attr and element.
removeNamedItem(qualifiedName)
メソッド手続きは:
The removeNamedItem(qualifiedName) method steps are:
- 属性° :← これ°の要素の属性°を名前により除去する( qualifiedName ) Let attr be the result of removing an attribute given qualifiedName and element.
-
IF[
属性° = null
]
:THROW
NotFoundError
If attr is null, then throw a "NotFoundError" DOMException. - RETURN 属性° Return attr.
removeNamedItemNS(namespace, localName)
メソッド手続きは:
The removeNamedItemNS(namespace, localName) method steps are:
- 属性° :← これ°の要素の属性°を名前空間と局所名により除去する( namespace, localName ) Let attr be the result of removing an attribute given namespace, localName, and element.
-
IF[
属性° = null
]
:THROW
NotFoundError
If attr is null, then throw a "NotFoundError" DOMException. - RETURN 属性° Return attr.
4.9.2. Attr
インタフェース
[Exposed=Window]
interface Attr : Node {
readonly attribute DOMString? namespaceURI;
readonly attribute DOMString? prefix;
readonly attribute DOMString localName;
readonly attribute DOMString name;
[CEReactions] attribute DOMString value;
readonly attribute Element? ownerElement;
readonly attribute boolean specified; // 無用の長物 — 常に true を返す
};
Attr
ノードは、
単に
属性°
( attribute )とも称される
— IDL 属性と区別するため、
内容属性とも称される。
【この訳では, “°” を付けて “属性°” と記すことにする。】
Attr nodes are simply known as attributes. They are sometimes referred to as content attributes to avoid confusion with IDL attributes.
各属性°は、 次に挙げるものを有する:
- 名前空間 : null /空でない文字列
- 名前空間接頭辞 : null /空でない文字列
- 局所名 :空でない文字列
- 値 :文字列
-
属する要素 : null /要素
【 null でないならば、 当の属性°は要素の属性°リスト内に在ることになる。 】
注記: 今 設計するなら、[ 名前, 値 ]だけを有するようにする所 ☹ If designed today they would just have a name and value. ☹
属性° 属性° の
有修飾名
は、
属性° の名前空間接頭辞 接頭辞 に応じて[
null ならば 属性° の局所名 /
他の場合は 次の並びになる
]
:接頭辞,
":
",
属性° の局所名
An attribute’s qualified name is its local name if its namespace prefix is null, and its namespace prefix, followed by ":", followed by its local name, otherwise.
注記: UA は、 これを内部 slot に持たせて最適化することもできる。 User agents could have this as an internal slot as an optimization.
属性°の局所名は、 当の属性°の作成時に与えられる。 他のものは、 当の属性°の作成時に明示的に与えられない限り,次のように設定される :名前空間 ← null , 名前空間接頭辞 ← null , 属する要素 ← null , 値 ← 空文字列 When an attribute is created, its local name is given. Unless explicitly given when an attribute is created, its namespace, namespace prefix, and element are set to null, and its value is set to the empty string.
A 属性° という表記は、 所与の文字列 A に対し,次を満たす属性°であることをいう :( 局所名, 名前空間, 名前空間接頭辞 ) = ( A, null , null ) An A attribute is an attribute whose local name is A and whose namespace and namespace prefix are null.
既存の属性°値を設定する ときは、 所与の ( 属性° 属性°, 文字列 値 ) に対し,次を走らす: To set an existing attribute value, given an attribute attribute and string value, run these steps:
value
設定子手続きは
:既存の属性°値を設定する( これ°, 所与の値 )
The value setter steps are to set an existing attribute value with this and the given value.specified
取得子手続きは
:RETURN true
The specified getter steps are to return true.4.10. CharacterData
インタフェース
[Exposed=Window]
interface CharacterData : Node {
attribute [LegacyNullToEmptyString] DOMString data;
readonly attribute unsigned long length;
DOMString substringData(unsigned long offset, unsigned long count);
undefined appendData(DOMString data);
undefined insertData(unsigned long offset, DOMString data);
undefined deleteData(unsigned long offset, unsigned long count);
undefined replaceData(unsigned long offset, unsigned long count, DOMString data);
};
注記:
CharacterData
は、[
Text
, ProcessingInstruction
, Comment
]ノードから利用される抽象インタフェースであり,その直なインスタンスは取得し得ない。
CharacterData is an abstract interface. You cannot get a direct instance of it. It is used by Text, ProcessingInstruction, and Comment nodes.
このインタフェースを実装するノードは、
文字データノード
とも称される
(すなわち, Text
( CDATASection
も含む), ProcessingInstruction
, Comment
)。
【 文字データノードは、 これらのインタフェースを簡潔に総称するために この訳に導入した,非公式な用語である。 これらは、 (機能上は異なるものだが)多くの処理で同等に扱われるので。 】
各文字データノードには、 次に挙げるものが結び付けられる:
- データ :文字列 — 【当のノードの作成時に設定され,それ以降も】変異可能。
文字データノード ノード の データを置換する ときは、 所与の ( offset, count, data ) に対し,次を走らす: To replace data of node node with offset offset, count count, and data data, run these steps:
- 長さ :← ノード の長さ Let length be node’s length.
-
IF[
offset > 長さ
]
:THROW
IndexSizeError
If offset is greater than length, then throw an "IndexSizeError" DOMException. - IF[ offset + count > 長さ ] :count ← 長さ − offset If offset plus count is greater than length, then set count to length minus offset.
-
ノード 用に種別 "
characterData
" の変異記録をキューする( ↓ ) : null , null , ノード のデータ, « », « », null , null Queue a mutation record of "characterData" for node with null, null, node’s data, « », « », null, and null. - ノード のデータ ← 次を順に連結する :ノード のデータの中の 0 から offset までを成す符号単位部分文字列, data, ノード のデータの中の ( offset + count ) から終端までを成す符号単位部分文字列 Insert data into node’s data after offset code units.Let delete offset be offset + data’s length.Starting from delete offset code units, remove count code units from node’s data.
- 差分 :← data の長さ − count ↓
-
各( live 範囲° 範囲° ) に対し:
For each live range whose start node is node and start offset is greater than offset but less than or equal to offset plus count, set its start offset to offset.For each live range whose end node is node and end offset is greater than offset but less than or equal to offset plus count, set its end offset to offset.For each live range whose start node is node and start offset is greater than offset plus count, increase its start offset by data’s length and decrease it by count.For each live range whose end node is node and end offset is greater than offset plus count, increase its end offset by data’s length and decrease it by count. - IF[ ノード の親 ≠ null ] :適用可能な仕様にて ノード の親用に定義された各( 子群変更時の手続き 手続き ) に対し :手続き() If node’s parent is non-null, then run the children changed steps for node’s parent.
文字データノード ノード の データの部分文字列 は、 所与の ( offset, count ) に対し,次を走らせた結果を返す: To substring data with node node, offset offset, and count count, run these steps:
- 長さ :← ノード の長さ Let length be node’s length.
-
IF[
offset > 長さ
]
:THROW
IndexSizeError
If offset is greater than length, then throw an "IndexSizeError" DOMException. - IF[ offset + count > 長さ ] :count :← 長さ − offset If offset plus count is greater than length, return a string whose value is the code units from the offsetth code unit to the end of node’s data, and then return.
- RETURN 符号単位部分文字列( ノード のデータ, offset, count ) Return a string whose value is the code units from the offsetth code unit to the offset+countth code unit in node’s data.
data
設定子手続きは:
:これ°のデータを置換する( 0, これ°の長さ, 所与の値 )
Its setter must replace data with node this, offset 0, count this’s length, and data new value.substringData(offset, count)
メソッド手続きは
:RETURN これ°のデータの部分文字列( offset, count )
The substringData(offset, count) method steps are to return the result of running substring data with node this, offset offset, and count count.appendData(data)
メソッド手続きは
:これ°のデータを置換する( これ°の長さ, 0, data )
The appendData(data) method steps are to replace data with node this, offset this’s length, count 0, and data data.insertData(offset, data)
メソッド手続きは
:これ°のデータを置換する( offset, 0, data )
The insertData(offset, data) method steps are to replace data with node this, offset offset, count 0, and data data.deleteData(offset, count)
メソッド手続きは
:これ°のデータを置換する( offset, count, 空文字列 )
The deleteData(offset, count) method steps are to replace data with node this, offset offset, count count, and data the empty string.replaceData(offset, count, data)
メソッド手続きは
:これ°のデータを置換する( offset, count, data )
The replaceData(offset, count, data) method steps are to replace data with node this, offset offset, count count, and data data.4.11. Text
インタフェース
[Exposed=Window]
interface Text : CharacterData {
constructor(optional DOMString data = "");
[NewObject] Text splitText(unsigned long offset);
readonly attribute DOMString wholeText;
};
- text =
new Text([data = ""])
-
データが data にされた,新たな
Text
ノードを返す。 Returns a new Text node whose data is data. - text .
splitText(offset)
-
所与の offset の地点でデータを分割し,残りの部分を
Text
ノードとして返す。 Splits data at the given offset and returns the remainder as Text node. - text .
wholeText
-
隣接するすべての同胞
Text
ノードのデータを連結した結果を返す。 Returns the combined data of all direct Text node siblings.
新たな Text
ノード
は、
所与の
( 文字列, 文書 )
に対し
:RETURN 新たなオブジェクト( Text
)
— その
:データ ← 文字列,
ノード文書 ← 文書
【 この手続きは、 他所を簡潔に述べるための,この訳による追加。 】
狭義 Text
ノード
とは、
CDATASection
ノードでない Text
ノードである。
An exclusive Text node is a Text node that is not a CDATASection node.
Text
ノード列
は
:RETURN 条件[
Text
ノードである
]を満たす, ノード を含む連続的な同胞列
The contiguous Text nodes of a node node are node, node’s previous sibling Text node, if any, and its contiguous Text nodes, and node’s next sibling Text node, if any, and its contiguous Text nodes, avoiding any duplicates.Text
ノード列
:RETURN 条件[
狭義 Text
ノードである
]を満たす, ノード を含む連続的な同胞列
The contiguous exclusive Text nodes of a node node are node, node’s previous sibling exclusive Text node, if any, and its contiguous exclusive Text nodes, and node’s next sibling exclusive Text node, if any, and its contiguous exclusive Text nodes, avoiding any duplicates.条件 条件 を満たす, ノード を含む 連続的な同胞列 は、 次の結果を返す:
- Assert: ノード は 条件 を満たす
- WHILE[ ノード の直前の同胞?は 条件 を満たす ] :ノード ← ノード の直前の同胞?
- リスト :← « »
-
WHILE[ ノード は 条件 を満たす ]:
- RETURN リスト
【 この手続きは、 原文による “連続的な…” の(再帰的な)定義を等価な(かつ平坦化された平易な)定義に変形したものである。 】
↑ノード ノード の 子テキスト内容 は、 次の結果を返す:
The child text content of a node node is the concatenation of the data of all the Text node children of node, in tree order.ノード ノード の 子孫テキスト内容 は、 次の結果を返す:
The descendant text content of a node node is the concatenation of the data of all the Text node descendants of node, in tree order.
new Text(data)
構築子手続きは
:これ°のデータ ← data,
これ°のノード文書 ← 現在の大域オブジェクトに結び付けられた文書
The new Text(data) constructor steps are to set this’s data to data and this’s node document to current global object’s associated Document.
Text
ノードを分割する
ときは、
所与の
( Text
ノード ノード, オフセット offset )
に対し,次を走らす:
To split a Text node node with offset offset, run these steps:
- 長さ :← ノード の長さ Let length be node’s length.
-
IF[
offset > 長さ
]
:THROW
IndexSizeError
If offset is greater than length, then throw an "IndexSizeError" DOMException. - count :← 長さ − offset Let count be length minus offset.
- 新データ :← これ°のデータの部分文字列( offset, count ) Let new data be the result of substringing data with node node, offset offset, and count count.
-
新ノード :← 新たな
Text
ノード( 新データ, ノード のノード文書 ) Let new node be a new Text node, with the same node document as node. Set new node’s data to new data. - 親 :← ノード の親 Let parent be node’s parent.
-
IF[ 親 ≠ null ]: If parent is not null:
- 親 の中でノードを子の前に挿入する( 新ノード, ノード の直後の同胞? ) Insert new node into parent before node’s next sibling.
-
各( live 範囲° 範囲° ) に対し: ↓
- IF[ 範囲° の始端ノード = ノード ]∧[ 範囲° の始端オフセット > offset ] :範囲° の始端ノード ← 新ノード; 範囲° の始端オフセット −= offset For each live range whose start node is node and start offset is greater than offset, set its start node to new node and decrease its start offset by offset.
- IF[ 範囲° の終端ノード = ノード ]∧[ 範囲° の終端オフセット > offset ] :範囲° の終端ノード ← 新ノード; 範囲° の終端オフセット −= offset For each live range whose end node is node and end offset is greater than offset, set its end node to new node and decrease its end offset by offset.
- IF[ 範囲° の始端ノード = 親 ]∧[ 範囲° の始端オフセット = ノード の index + 1 ] :範囲° の始端オフセット += 1 For each live range whose start node is parent and start offset is equal to the index of node plus 1, increase its start offset by 1.
- IF[ 範囲° の終端ノード = 親 ]∧[ 範囲° の終端オフセット = ノード の index + 1 ] :範囲° の終端オフセット += 1 For each live range whose end node is parent and end offset is equal to the index of node plus 1, increase its end offset by 1.
- ノード のデータを置換する( offset, count, 空文字列 ) Replace data with node node, offset offset, count count, and data the empty string.
- RETURN 新ノード Return new node.
splitText(offset)
メソッド手続きは
:RETURN Text
ノードを分割する( これ°, offset )
The splitText(offset) method steps are to split this with offset offset.wholeText
取得子手続きは
:RETURN テキストデータを連結する( これ°を含む連続的な Text
ノード列 )
The wholeText getter steps are to return the concatenation of the data of the contiguous Text nodes of this, in tree order.4.12. CDATASection
インタフェース
[Exposed=Window]
interface CDATASection : Text {
};
4.13. ProcessingInstruction
インタフェース
[Exposed=Window]
interface ProcessingInstruction : CharacterData {
readonly attribute DOMString target;
};
各 ProcessingInstruction
ノードには、
次に挙げるものが結び付けられる:
- ターゲット :文字列 【— 作成時に与えられる。】
4.14. Comment
インタフェース
[Exposed=Window]
interface Comment : CharacterData {
constructor(optional DOMString data = "");
};
- comment =
new Comment([data = ""])
-
データが data にされた,新たな
Comment
ノードを返す。 Returns a new Comment node whose data is data.
new Comment(data)
構築子手続きは
:これ°のデータ ← data,
これ°のノード文書 ← 現在の大域オブジェクトに結び付けられた文書
The new Comment(data) constructor steps are to set this’s data to data and this’s node document to current global object’s associated Document.
5. 範囲°
5.1. “DOM Ranges” 序論
[
StaticRange
/ Range
]オブジェクト ( 範囲° )はノードツリーの中の連続する内容を表現する。
各範囲°には、[
始端, 終端
]がある
— これらは、
範囲°の境界点と総称される。
各境界点は、
( ノード, オフセット )
が成すタプルである。
言い換えれば、
範囲°はノードツリーの中の 2 つの境界点に挟まれる
内容
を表現する。
StaticRange and Range objects (ranges) represent a sequence of content within a node tree. Each range has a start and an end which are boundary points. A boundary point is a tuple consisting of a node and an offset. So in other words, a range represents a piece of content within a node tree between two boundary points.
範囲°は、 編集時に内容を[ 選択する/複製する ]ときに,よく利用される。 例えば,次のノードツリーが与えられたとき: Ranges are frequently used in editing for selecting and copying content.
- 要素:
p
次の様にして,並び "syndata is awes
" を表現する範囲°が得られる
(変数[
p / em
]には[
p
/ em
]要素があてがわれたとする):
In the node tree above, a range can be used to represent the sequence “syndata is awes”. Assuming p is assigned to the p element, and em to the em element, this would be done as follows:
var range = new Range(), firstText = p.childNodes[1], secondText = em.firstChild range.setStart(firstText, 9) /* 先頭の空白も数に入れる do not forget the leading space */ range.setEnd(secondText, 4) /* range を文字列化した結果は、 今や先に示した文字列になる range now stringifies to the aforementioned quote */
注記:
範囲°は、
上のノードツリーの src
や alt
などの属性°は表現できない。
範囲°はノード用に限り有用になる。
Attributes such as src and alt in the node tree above cannot be represented by a range. Ranges are only useful for nodes.
StaticRange
オブジェクトと違って、
Range
オブジェクトは,ノードツリーに対する変異に影響される。
なので、
live 範囲°とも称される。
その種の変異によりそれらが無効化されることはなく,可能なら内容の同じ部分を表現するようになる。
live 範囲°は、
ノードツリーに対する変異
— 自身が表現する内容の一部が変異したときなど —
に伴い,必要に応じて自身も改変され得る。
Range objects, unlike StaticRange objects, are affected by mutations to the node tree. Therefore they are also known as live ranges. Such mutations will not invalidate them and will try to ensure that it still represents the same piece of content. Necessarily, a live range might itself be modified as part of the mutation to the node tree when, e.g., part of the content it represents is mutated.
詳細は、
次に挙げる各種アルゴリズム/メソッドを見よ
:ノードを子の前に挿入する,
ノードを除去する
normalize()
,
データを置換する,
Text
ノードを分割する
See the insert and remove algorithms, the normalize() method, and the replace data and split algorithms for details.
【 例えば,範囲°の境界点が あるノードの “内側” を指していて, そのノードがツリーから除去された場合、 その境界点は “ノードが抜けた穴” を指すようにされる (始端と終端が別々なツリーの中を指さないよう)。 始端と終端の両者が同じノードの内側を指していたとしても、 除去されたノードの内側を指すことはなく,それらは同じ “穴” を指すよう畳まれることになる。 】
ノードツリーの変異に呼応して,live 範囲°を更新することは、
高価になり得る。
ノードツリーが変化するたびに、
影響されるすべての Range
オブジェクトは更新される必要がある。
アプリが live 範囲°に関心がなくなろうが、
変異が生じたときには,それらを最新に保つコストを支払うことになる。
Updating live ranges in response to node tree mutations can be expensive. For every node tree change, all affected Range objects need to be updated. Even if the application is uninterested in some live ranges, it still has to pay the cost of keeping them up-to-date when a mutation occurs.
StaticRange
オブジェクトは、
ノードツリーが変異しても更新されない,軽量な範囲°であり、
したがって,
live 範囲°と同じ保守コストの対象にならない。
A StaticRange object is a lightweight range that does not update when the node tree mutates. It is therefore not subject to the same maintenance cost as live ranges.
5.2. 境界点
境界点 とは、 ( あるノード ノード , 負でない整数 オフセット ) が成すタプルである。 A boundary point is a tuple consisting of a node (a node) and an offset (a non-negative integer).
所与の ( ノード node, 負でない整数 offset ) に対し, 境界点( node, offset ) と記された所では、 ( ノード, オフセット ) として ( node, offset ) を伴う境界点を表すとする。 【この表記は、この訳による追加。】
注記: 正しい境界点のオフセットは、 0 以上, 境界点のノードの長さ以下になる。 A correct boundary point’s offset will be between 0 and the boundary point’s node’s length, inclusive.
【 HTML や XML のソーステキストの中では,境界点は、 すべてのテキストデータ(文字データノード)を “仮想の” 開始タグ, 終了タグ で括り, すべての空要素(HTML の void 要素も含む)は[ 開始タグ, 終了タグ ]の組に置換した上で、 すべての[ タグ, および 文字データを成す符号単位たち ]それぞれを点に見立てて,ソースに現れる順に一列に並べたときの,隣接する任意の 2 つの点の隙間を指すものと見なせる。
例えば "<b>text</b>" のようなマークアップの中の,[ 開始タグ "<b>" ]と[ "text" の先頭 ]との隙間を指す境界点には、 "text" ノード の[ 内縁( “仮想の” タグの内縁)を指すもの, および 外縁を指すもの ]があり、 また,境界点は[ "<br>" のような空タグ / データが空な文字データノード ]の内部も指し得る†。
† 唯一の例外は,doctype であり、 境界点は doctype の内部は指し得ないようにされている — したがってこのモデルでは,一個の “点” になる。
文書のノードツリーの一例とそのすべての境界点を表す模式図を次に示す。 縦棒 "|" が境界点が指し得る位置を表し,ドット "." が文字データを成す各文字を表す (先掲の模式図と同様に、 左端が文書の先頭, 右端が文書の末尾,横線はツリーの中の各ノードが文書内を占める範囲を表し,赤色区間は文字データノードを表す):
境界点を表す縦棒の直上の横線がその境界点のノードを表す。 境界点のオフセットは、 図の中では,その境界点を表す縦棒の直上の横線直下に在って, その縦棒より左側に在る縦棒の本数になる (境界点のノードが図の緑色区間ならば、 その直下の各数字がその境界点のオフセット)。
図の先頭の *
は doctype を表す
(内部に境界点は無い)。
その次の孤立した A はデータが空な文字データノードの内部を指す(唯一の)境界点を表し,その次の B は内容が空な要素の内部を指す境界点を表し,後続の 2 個の赤色区間は 2 個の文字データノードが境界点( C )を挟んで間を置かずに連続していることを表している。
】
境界点 A の[ 境界点 B に 相対的な位置 ]が, B [ より前 / に等しい / より後 ]のいずれかになるかは、 次に従って決定される: The position of a boundary point (nodeA, offsetA) relative to a boundary point (nodeB, offsetB) is before, equal, or after, as returned by these steps:
【 このアルゴリズムは、 2 つの境界点に対し,上に示した様な模式図における位置関係(左側が “より前” )を算出する。 】
- ( nodeA, offsetA, nodeB, offsetB ) :← ( A のノード, A のオフセット, B のノード, B のオフセット ) ↑
- Assert: nodeA の根 = nodeB の根 Assert: nodeA and nodeB have the same root.
- IF[ nodeA = nodeB ] :RETURN [ offsetA < offsetB ならば より前 / offsetA = offsetB ならば に等しい / offsetA > offsetB ならば より後 ] If nodeA is nodeB, then return equal if offsetA is offsetB, before if offsetA is less than offsetB, and after if offsetA is greater than offsetB.
- IF[ nodeA は nodeB に後続する ] :RETURN B は A [ より前 ならば より後 / より後 ならば より前 ] If nodeA is following nodeB, then if the position of (nodeB, offsetB) relative to (nodeA, offsetA) is before, return after, and if it is after, return before.
-
IF[ nodeA は nodeB の先祖である ]: If nodeA is an ancestor of nodeB:
- RETURN より前 Return before.
5.3. AbstractRange
インタフェース
[Exposed=Window]
interface AbstractRange {
readonly attribute Node startContainer;
readonly attribute unsigned long startOffset;
readonly attribute Node endContainer;
readonly attribute unsigned long endOffset;
readonly attribute boolean collapsed;
};
AbstractRange
インタフェースを実装するオブジェクトは、
単に
範囲°
とも称される。
Objects implementing the AbstractRange interface are known as ranges.
【 一般語の “範囲” と区別し易くするため、 この訳では, “°” を付けて “範囲°” と記すことにする ( “DOM range”, “範囲オブジェクト” などの呼称もあるが)。 】
各 範囲°には、 2 つの境界点 始端, 終端 が結び付けられる。 A range has two associated boundary points — a start and end.
便宜のため、 範囲°の: For convenience,\
- ( 始端ノード, 始端オフセット ) は、 順に,始端の ( ノード, オフセット ) を指すとする。 a range’s start node is its start’s node, its start offset is its start’s offset,\
- ( 終端ノード, 終端オフセット ) は、 順に,終端の ( ノード, オフセット ) を指すとする。 its end node is its end’s node, and its end offset is its end’s offset.
所与の範囲°は、 次を満たすとき 畳まれて いるとされる :[ 始端ノード = 終端ノード ]∧[ 始端オフセット = 終端オフセット ] A range is collapsed if its start node is its end node and its start offset is its end offset.
- node = range .
startContainer
- range の始端ノードを返す。 Returns range’s start node.
- offset = range .
startOffset
- range の始端オフセットを返す。 Returns range’s start offset.
- node = range .
endContainer
- range の終端ノードを返す。 Returns range’s end node.
- offset = range .
endOffset
- range の終端オフセットを返す。 Returns range’s end offset.
- collapsed = range .
collapsed
- range は畳まれて[ いるならば true / いないならば false ]を返す。 Returns true if range is collapsed; otherwise false.
startContainer
取得子手続きは
:RETURN これ°の始端ノード
The startContainer getter steps are to return this’s start node.startOffset
取得子手続きは
:RETURN これ°の始端オフセット
The startOffset getter steps are to return this’s start offset.collapsed
取得子手続きは
:RETURN IS[
これ°は畳まれている
]
The collapsed getter steps are to return true if this is collapsed; otherwise false.5.4. StaticRange
インタフェース
dictionary StaticRangeInit {
required Node startContainer;
required unsigned long startOffset;
required Node endContainer;
required unsigned long endOffset;
};
[Exposed=Window]
interface StaticRange : AbstractRange {
constructor(StaticRangeInit init);
};
- staticRange =
new StaticRange(init)
- ノードツリーが変異しても更新しない,新たな範囲°を返す。 Returns a new range object that does not update when the node tree mutates.
new StaticRange(init)
構築子手続きは:
-
始端ノード :← init[ "
startContainer
" ] -
終端ノード :← init[ "
endContainer
" ] -
IF[
始端ノード, 終端ノード いずれかは[
DocumentType
/Attr
]ノードである ] :THROWInvalidNodeTypeError
-
これ°の始端 ← 境界点( 始端ノード, init[ "
startOffset
" ] ), -
これ°の終端 ← 境界点( 終端ノード, init[ "
endOffset
" ] )
範囲°は、 ∧↓ を満たすならば 妥当 であるとされる: A StaticRange is valid if all of the following are true:
- 始端, 終端は同じノードツリー内にある Its start and end are in the same node tree.
- 0 ≤ 始端オフセット ≤ 始端ノードの長さ Its start offset is between 0 and its start node’s length, inclusive.
- 0 ≤ 終端オフセット ≤ 終端ノードの長さ Its end offset is between 0 and its end node’s length, inclusive.
- 始端は終端より前か終端に等しい Its start is before or equal to its end.
【 この用語は、 他の仕様から利用するためにある — この仕様が主に取り扱う live 範囲°に対する演算は、 常に,結果が妥当になるように施行されるので。 】
5.5. Range
インタフェース
[Exposed=Window]
interface Range : AbstractRange {
constructor();
readonly attribute Node commonAncestorContainer;
undefined setStart(Node node, unsigned long offset);
undefined setEnd(Node node, unsigned long offset);
undefined setStartBefore(Node node);
undefined setStartAfter(Node node);
undefined setEndBefore(Node node);
undefined setEndAfter(Node node);
undefined collapse(optional boolean toStart = false);
undefined selectNode(Node node);
undefined selectNodeContents(Node node);
const unsigned short START_TO_START = 0;
const unsigned short START_TO_END = 1;
const unsigned short END_TO_END = 2;
const unsigned short END_TO_START = 3;
short compareBoundaryPoints(unsigned short how, Range sourceRange);
[CEReactions] undefined deleteContents();
[CEReactions, NewObject] DocumentFragment extractContents();
[CEReactions, NewObject] DocumentFragment cloneContents();
[CEReactions] undefined insertNode(Node node);
[CEReactions] undefined surroundContents(Node newParent);
[NewObject] Range cloneRange();
undefined detach();
boolean isPointInRange(Node node, unsigned long offset);
short comparePoint(Node node, unsigned long offset);
boolean intersectsNode(Node node);
stringifier;
};
Range
インタフェースを実装するオブジェクトは単に
live 範囲°
とも称される。
Objects implementing the Range interface are known as live ranges.
注記:
ツリーを改変するアルゴリズム
(特に,
ノードを子の前に挿入する,
ノードを除去する,
データを置換する,
Text
ノードを分割する)
は、
そのツリーに結び付けられた一連の live 範囲°も改変する。
Algorithms that modify a tree (in particular the insert, remove, replace data, and split algorithms) modify live ranges associated with that tree.
live 範囲°の 根 とは、 その始端ノードの根である。 The root of a live range is the root of its start node.
【 終端ノードの根と同じになる (常にそうなるように拘束される)。 各 live 範囲°は、 その作成時からずっと,同じあるノードツリーに結び付けられ続ける — 言い換えれば、 根は変化しない。 (仕様には明示的にそう述べられてはいないが、 各種アルゴリズムのふるまいから,そう結論できる。 一般な範囲°は、 そのように拘束されない。 】
ノード node が live 範囲° 範囲° に 包含され ているとは、 ∧↓ が満たされることをいう: A node node is contained in a live range range if\
- node の根 = 範囲° の根 node’s root is range’s root, and \
- 境界点( node, 0 ) は 範囲° の始端より後 (node, 0) is after range’s start, and\
- 境界点( node, node の長さ ) は 範囲° の終端より前 (node, node’s length) is before range’s end.
ノード node が live 範囲° 範囲° に 部分的に包含され ているとは、 ∨↓ が満たされることをいう: A node is partially contained in a live range if\
- [ node は 範囲° の始端ノードの広義先祖である ]∧[ node は 範囲° の終端ノードの広義先祖でない ] it’s an inclusive ancestor of the live range’s start node but not its end node, or\
- [ node は 範囲° の始端ノードの広義先祖でない ]∧[ node は 範囲° の終端ノードの広義先祖である ] vice versa.
【 次の図は先掲の模式図と同様にツリーを表したものであり,図の記号 s が始端, e が終端を表すとする。 このとき、 図の緑色区間のノードが包含され, 青色区間のノード(始端/終端の一方のみを内部に含むノード)が部分的に包含される。 最上層の横線のノードは 内部に s, e とも含むので、 定義により,部分的に包含されることはない。 】
注記: これらの定義をより理解し易くする事実をいくつか挙げる: Some facts to better understand these definitions:
- live 範囲°の内容は、 包含されているすべてのノードに加えて,[[ 始端ノード / 終端ノード ]の広義子孫である文字データノードのうち,範囲°に入るもの ]からなるものとみなせる。 The content that one would think of as being within the live range consists of all contained nodes, plus possibly some of the contents of the start node and end node if those are CharacterData nodes.
- live 範囲°に包含されているノードたちが成す集合は、 包含されているノードの親が常に包含されるとは限らないので,一般に連続的でない。 The nodes that are contained in a live range will generally not be contiguous, because the parent of a contained node will not always be contained.
- しかしながら,包含されているノードの子孫は包含されており、 2 つの同胞が包含されているならば,それらの間に在るどの同胞も包含される。 However, the descendants of a contained node are contained, and if two siblings are contained, so are any siblings that lie between them.
- live 範囲°の始端ノード と終端ノード は決して その範囲°に包含されない。 The start node and end node of a live range are never contained within it.
- 包含されているノードのうち、 最初のもの(もし在れば)は,常に始端ノードに後続し、 最後のものは,常に終端ノードの最後の子孫と同じか, それに先行する。 The first contained node (if there are any) will always be after the start node, and the last contained node will always be equal to or before the end node’s last descendant.
- 部分的に包含されるノードが存在するのは、 始端ノード と終端ノード が異なるとき, そのときに限る。 There exists a partially contained node if and only if the start node and end node are different.
- 始端ノードと終端ノードの共通な広義先祖は、 包含されることも, 部分的に包含されることもない。 The commonAncestorContainer attribute value is neither contained nor partially contained.
-
- A が, A, B に共通な広義先祖になる。
- A の子のうち, 1 つだけ( C とする)が部分的に包含される。
- A の別の子 C1 が包含されるのは、 C1 が C に先行するとき, そのときに限る。
【 この場合の例。 前と同様,記号 s は始端, e は終端を表す。 この例では図の最上層のノードが共通な広義先祖になる。 共通な広義先祖の子のうち、 青色区間のノードが上述の C (共通な広義先祖の子であってかつ部分的に包含される)に該当し,緑色区間のノードが包含される子になる。 】
B が A の先祖である場合、 前述の逆になる。 【上の図で、 s と e を入れ替えて,右端からツリーの順序が開始されていると考えるとよい。】
If the start node is an ancestor of the end node, the common inclusive ancestor will be the start node. Exactly one of its children will be partially contained, and a child will be contained if and only if it precedes the partially contained child. If the end node is an ancestor of the start node, the opposite holds. - 始端ノード A, 終端ノード B とも他方の広義先祖でない場合: A, B の共通な広義先祖 先祖 は、 A とも B とも異なる。 先祖 の子のうち,ちょうど 2 個が部分的に包含され、 先祖 の子が包含されるのは,これら 2 個の合間に在るとき, そのときに限る。 If the start node is not an inclusive ancestor of the end node, nor vice versa, the common inclusive ancestor will be distinct from both of them. Exactly two of its children will be partially contained, and a child will be contained if and only if it lies between those two.
- range =
new Range()
- 新たな live 範囲°を返す。 Returns a new live range.
new Range()
構築子手続きは:
- container = range .
commonAncestorContainer
- range の[ 始端ノード, 終端ノード ]両者の広義先祖であるような,最も末端のノードを返す。 【原文の “ancestor” (先祖)は厳密な記述ではない。】 Returns the node, furthest away from the document, that is an ancestor of both range’s start node and end node.
commonAncestorContainer
取得子手続きは
:RETURN これ°の
( 始端ノード, 終端ノード )
の共通な広義先祖
The commonAncestorContainer getter steps are:
• Let container be start node.
• While container is not an inclusive ancestor of end node, let container be container’s parent.
• Return container.【 次のブロックは、 原文には存在しない,この訳による補完。 ブロックにて挙げる各種メソッドは、 範囲°の片方または両方の境界点を新たな地点に変更する。 片方の境界点(以下, P )のみを変更するメソッドについては、 妥当性を保つため,もう片方の境界点(以下, Q )も必要に応じて正される: すなわち, Q が[ P と異なるツリーの中に在る, または[ P より前(始端が変更された場合) / P より後(終端が変更された場合) ]に位置する ]ようになった場合、 P と同じ地点にされる( 範囲°は畳まれる)。 】
- range .
setStart(node, offset)
- range .
setEnd(node, offset)
- それぞれ,始端/終端を 境界点( node, offset ) と同じ位置にする。
-
node が doctype である場合,
InvalidNodeTypeError
例外が投出される。 他の場合, offset が node の長さを超えている場合,IndexSizeError
例外が投出される。 - range .
setStartBefore(node)
- range .
setStartAfter(node)
- それぞれ,始端を node の外縁な[ 始端(下図の S )/終端(下図の E ) ]に位置させる。
-
node の親が null の場合,
InvalidNodeTypeError
例外が投出される。 - range .
setEndBefore(node)
- range .
setEndAfter(node)
- それぞれ,終端を node の外縁な[ 始端(下図の S )/終端(下図の E ) ]に位置させる。
-
node の親が null の場合,
InvalidNodeTypeError
例外が投出される。 -
(説明用の図式 — node 引数が,図の青色区間が表すノードに対応しているとする。)
- range .
collapse(toStart)
- 範囲°を畳む — すなわち、 toStart が true の場合は 終端を始端と同じ地点に位置させ,他の場合は 始端を終端と同じ地点に位置させる。
- range .
selectNode(node)
- node を選択する — すなわち、 始端と終端を node の外縁な両端(上図の S, E )に位置させる。
-
node の親が null の場合,
InvalidNodeTypeError
例外が投出される。 - range .
selectNodeContents(node)
- node の内容を選択する — すなわち、 始端と終端を node の内縁な両端(上図の s, e )に位置させる。
-
node が doctype である場合,
InvalidNodeTypeError
例外が投出される。 - range .
compareBoundaryPoints(how, sourceRange)
- range の始端または終端( how により指示される)の位置が, sourceRange の始端または終端( how により指示される)[ より前, に等しい, より後 ]のいずれになるかに応じて、[ −1, 0, 1 ]を返す。
範囲° 範囲° の 境界点を設定する ときは、 所与の ( 端 ∈ { 始端, 終端 }, ノード node, 負でない整数 offset ) に対し: To set the start or end of a range to a boundary point (node, offset), run these steps:
-
IF[
node は doctype である
]
:THROW
InvalidNodeTypeError
If node is a doctype, then throw an "InvalidNodeTypeError" DOMException. -
IF[
offset > node の長さ
]
:THROW
IndexSizeError
If offset is greater than node’s length, then throw an "IndexSizeError" DOMException. - 境界点 :← 境界点( node, offset ) Let bp be the boundary point (node, offset).
-
IF[ 端 = 始端 ]: If these steps were invoked as "set the start"
-
ELSE( 端 = 終端 ) If these steps were invoked as "set the end"
setStart(node, offset)
メソッド手続きは
:これ°の境界点を設定する( 始端, node, offset )
The setStart(node, offset) method steps are to set the start of this to boundary point (node, offset).setEnd(node, offset)
メソッド手続きは
:これ°の境界点を設定する( 終端, node, offset )
The setEnd(node, offset) method steps are to set the end of this to boundary point (node, offset).
setStartBefore(node)
メソッド手続きは:
The setStartBefore(node) method steps are:
- 親 :← node の親 Let parent be node’s parent.
-
IF[
親 = null
]
:THROW
InvalidNodeTypeError
If parent is null, then throw an "InvalidNodeTypeError" DOMException. - これ°の境界点を設定する( 始端, 親, node の index ) Set the start of this to boundary point (parent, node’s index).
setStartAfter(node)
メソッド手続きは:
The setStartAfter(node) method steps are:
- 親 :← node の親 Let parent be node’s parent.
-
IF[
親 = null
]
:THROW
InvalidNodeTypeError
If parent is null, then throw an "InvalidNodeTypeError" DOMException. - これ°の境界点を設定する( 始端, 親, node の index + 1 ) Set the start of this to boundary point (parent, node’s index plus 1).
setEndBefore(node)
メソッド手続きは:
The setEndBefore(node) method steps are:
- 親 :← node の親 Let parent be node’s parent.
-
IF[
親 = null
]
:THROW
InvalidNodeTypeError
If parent is null, then throw an "InvalidNodeTypeError" DOMException. - これ°の境界点を設定する( 終端, 親, node の index ) Set the end of this to boundary point (parent, node’s index).
setEndAfter(node)
メソッド手続きは:
The setEndAfter(node) method steps are:
- 親 :← node の親 Let parent be node’s parent.
-
IF[
親 = null
]
:THROW
InvalidNodeTypeError
If parent is null, then throw an "InvalidNodeTypeError" DOMException. - これ°の境界点を設定する( 終端, 親, node の index + 1 ) Set the end of this to boundary point (parent, node’s index plus 1).
collapse(toStart)
メソッド手続きは:
The collapse(toStart) method steps are to,\
範囲°の内容として選択する ときは、 所与の ( 範囲° 範囲°, ノード node ) に対し: To select a node node within a range range, run these steps:
- 親 :← node の親 Let parent be node’s parent.
-
IF[
親 = null
]
:THROW
InvalidNodeTypeError
If parent is null, then throw an "InvalidNodeTypeError" DOMException. - index :← node の index Let index be node’s index.
- 範囲° の始端 ← 境界点( 親, index ) Set range’s start to boundary point (parent, index).
- 範囲° の終端 ← 境界点( 親, index + 1 ) Set range’s end to boundary point (parent, index plus 1).
selectNode(node)
メソッド手続きは
:範囲°の内容として選択する( これ°, node )
The selectNode(node) method steps are to select node within this.
selectNodeContents(node)
メソッド手続きは:
The selectNodeContents(node) method steps are:
-
IF[
node は doctype である
]
:THROW
InvalidNodeTypeError
If node is a doctype, throw an "InvalidNodeTypeError" DOMException. - 長さ :← node の長さ Let length be the length of node.
- これ°の始端 ← 境界点( node, 0 ) Set start to the boundary point (node, 0).
- これ°の終端 ← 境界点( node, 長さ ) Set end to the boundary point (node, length).
compareBoundaryPoints(how, sourceRange)
メソッド手続きは:
The compareBoundaryPoints(how, sourceRange) method steps are:
-
IF[
how ∉ {
START_TO_START
,START_TO_END
,END_TO_END
,END_TO_START
} ] :THROWNotSupportedError
If how is not one of • START_TO_START • START_TO_END • END_TO_END • END_TO_STARTthen throw a "NotSupportedError" DOMException. -
IF[
これ°の根 ≠ sourceRange の根
]
:THROW
WrongDocumentError
If this’s root is not the same as sourceRange’s root, then throw a "WrongDocumentError" DOMException. -
( 基準点, この点 ) :← how に応じて,次で与えられる 2 個の境界点: If how is:
START_TO_START
:- ( sourceRange の始端, これ°の始端 ) Let this point be this’s start. Let other point be sourceRange’s start.
START_TO_END
:- ( sourceRange の始端, これ°の終端 ) Let this point be this’s end. Let other point be sourceRange’s start.
END_TO_END
:- ( sourceRange の終端, これ°の終端 ) Let this point be this’s end. Let other point be sourceRange’s end.
END_TO_START
:- ( sourceRange の終端, これ°の始端 ) Let this point be this’s start. Let other point be sourceRange’s end.
- RETURN [ この点 は 基準点 [ より前 ならば − 1 / に等しい ならば 0 / より後 ならば 1 ] If the position of this point relative to other point isbefore • Return −1.equal • Return 0.after • Return 1.
【 次のブロックは、 原文には存在しない,この訳による補完。 ブロックにて挙げる各種メソッドは、 主に,範囲°の内容を操作する。 】
- range .
deleteContents()
- この範囲°の内容を削除した上で、 範囲°の境界点を畳む。
-
deleteContents()
の実行例。 図の記号[ s, e ]が順に範囲°の[ 始端, 終端 ]を表すとするとき、 図左の状態から図右の状態になる。 包含されているノード(図の 緑色区間 ), および 始端/終端ノードの文字データのうち 範囲°に入る部分の文字(図の+
)が除去される。 部分的に包含されているノード(図の 青色区間 )は除去されない。 この例では、 始端 s が指す文字データノードは,データは空になるがノード自体は残される。 図右の S, E が元の始端, 終端に対応する位置であるが、 実行後の始端と終端は,図右の X (共通な広義先祖の直下)を指すようになることに注意(範囲°は畳まれる)。 始端ノードが終端ノードの広義先祖であった場合、 始端の位置は変化しない。 始端ノードが終端ノード の広義子孫であった場合、 全体の終端(右端)から相対的な終端の位置は変化しない。 - range .
extractContents()
-
この範囲°の内容をクローンした結果を返すと同時に,当の内容を削除する( “カット” )。
機能上は
cloneContents()
とdeleteContents()
の組み合わせと等価になる。 - range .
cloneContents()
- この範囲°の内容をクローンした結果を返す。 返される内容は、 新たな文書片で包装される。
-
cloneContents()
の実行例。 図左の記号[ s, e ]が順に範囲の[ 始端, 終端 ]を表すとするとき、 その間に挟まれた部分のクローンが図右に示すように得られる ( S, E が元の始端と終端に対応する位置)。 図の青色区間の 2 個のノードが,範囲に部分的に包含されている子。 入れ物にあたる それらの共通な広義先祖は、 クローンにおいては文書片(緑色区間)に置換される。 始端 s が属する文字データノードはデータが空になるが、 ノード自体は[ その親から共通な広義先祖の子まで ]の先祖も含めてクローンされる。 - range .
insertNode(node)
- この範囲°の内容の先頭に node を挿入する(範囲°の中へ挿入する)。
- range .
surroundContents(newParent)
- この範囲°の内容を newParent ノードで包装する。 それに伴い、 範囲°の始端, 終端は, newParent の(外縁な)両端を指すようになる。 包装するに先立って、 newParent の元々の子はすべて除去され, newParent 自身も元々の親から除去される。
-
surroundContents
(newParent) の実行例。 記号 s は始端, e は終端を表すとき、 それらに挟まれた区間が newParent で包装される(図の青色区間)。 部分的に包含されるものはText
以外は許容されないので、 始端と終端はText
の層を無視すれば同じ親の直下に在る必要がある (さもなければ例外が投出される)。 図の e の様に境界点がText
ノード内に位置していた場合、 そのノードはそこで分割される。
deleteContents()
メソッド手続きは:
The deleteContents() method steps are:
- IF[ これ°は畳まれている ] :RETURN If this is collapsed, then return.
- ( 元の始端ノード, 元の始端オフセット, 元の終端ノード, 元の終端オフセット ) :← 順に,これ°の ( 始端ノード, 始端オフセット, 終端ノード, 終端オフセット ) Let original start node, original start offset, original end node, and original end offset be this’s start node, start offset, end node, and end offset, respectively.
-
IF[ 元の始端ノード = 元の終端ノード ]∧[ 元の始端ノード は文字データノードである ]: If original start node is original end node and it is a CharacterData node, then\
- 元の始端ノード のデータを置換する( 元の始端オフセット, 元の終端オフセット − 元の始端オフセット, 空文字列 ) replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string,\
- RETURN and then return.
- 除去対象 :← 次を満たすノードたちが成す,ツリー順序によるリスト :[ これ°に包含されている ]∧[ その親はこれ°に包含されていない ] Let nodes to remove be a list of all the nodes that are contained in this, in tree order, omitting any node whose parent is also contained in this.
- IF[ 元の始端ノード は 元の終端ノード の広義先祖である ] :新ノード :← 元の始端ノード; 新オフセット :← 元の始端オフセット If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.
-
ELSE:
【 見通しを良くするため、 ここの訳は,原文を等価な記述に変形している。 前段の条件の否定が成立することから † に該当するノードは必ず存在し, 新ノード に部分的に包含されている子のうち 最初のものになる。 】
Otherwise: • Let reference node equal original start node. • While reference node’s parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent. • Set new node to the parent of reference node, and new offset to one plus the index of reference node. • If reference node’s parent were null, it would be the root of this, so would be an inclusive ancestor of original end node, and we could not reach this point. - IF[ 元の始端ノード は文字データノードである ] :元の始端ノード のデータを置換する( 元の始端オフセット, 元の始端ノード の長さ − 元の始端オフセット, 空文字列 ) If original start node is a CharacterData node, then replace data with node original start node, offset original start offset, count original start node’s length − original start offset, data the empty string.
- 除去対象 を成す 各( node ) に対し,ツリー順序で :ノードを除去する( node ) For each node in nodes to remove, in tree order, remove node.
- IF[ 元の終端ノード は文字データノードである ] :元の終端ノード のデータを置換する( 0, 元の終端オフセット, 空文字列 ) If original end node is a CharacterData node, then replace data with node original end node, offset 0, count original end offset and data the empty string.
- これ°の :始端 ← 境界点( 新ノード, 新オフセット ); 終端 ← 境界点( 新ノード, 新オフセット ) Set start and end to (new node, new offset).
範囲°の内容を抽出する ときは、 所与の ( live 範囲° 範囲° ) に対し: To extract a live range range, run these steps:
- 文書片 :← 新たな文書片 — その :ノード文書 ← 範囲° の始端ノードのノード文書 Let fragment be a new DocumentFragment node whose node document is range’s start node’s node document.
- IF[ 範囲° は畳まれている ] :RETURN 文書片 If range is collapsed, then return fragment.
- ( 元の始端ノード, 元の始端オフセット, 元の終端ノード, 元の終端オフセット ) :← 順に, 範囲° の ( 始端ノード, 始端オフセット, 終端ノード, 終端オフセット ) Let original start node, original start offset, original end node, and original end offset be range’s start node, start offset, end node, and end offset, respectively.
-
IF[ 元の始端ノード = 元の終端ノード ]∧[ 元の始端ノード は文字データノードである ]: If original start node is original end node and it is a CharacterData node:
- clone :← ノードをクローンする( 元の始端ノード ) Let clone be a clone of original start node.
- clone のデータ ← 元の始端ノード のデータの部分文字列( 元の始端オフセット, ( 元の終端オフセット − 元の始端オフセット ) ) Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
- 元の始端ノード のデータを置換する( 元の始端オフセット, 元の終端オフセット − 元の始端オフセット, 空文字列 ) Replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string.
- RETURN 文書片 Return fragment.
- 共通な広義先祖 :← ( 元の始端ノード, 元の終端ノード ) の共通な広義先祖 Let common ancestor be original start node.While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.
- 部分的に包含された最初の子 :← null Let first partially contained child be null.
- IF[ 元の始端ノード は 元の終端ノード の広義先祖でない ] :部分的に包含された最初の子 ← 範囲° に部分的に包含されている[ 共通な広義先祖 の子 ]のうち,最初のもの If original start node is not an inclusive ancestor of original end node, set first partially contained child to the first child of common ancestor that is partially contained in range.
- 部分的に包含された最後の子 :← null Let last partially contained child be null.
-
IF[ 元の終端ノード は 元の始端ノード の広義先祖でない ] :部分的に包含された最後の子 ← 範囲° に部分的に包含されている[ 共通な広義先祖 の子 ]のうち,最後のもの If original end node is not an inclusive ancestor of original start node, set last partially contained child to the last child of common ancestor that is partially contained in range.
注記: これらの変数代入は実際に常に意味を成す。 例えば, 元の始端ノード が 元の終端ノード の広義先祖でない場合、[ 元の始端ノード = 共通な広義先祖 ]にはなり得ないので[ 元の始端ノード の広義先祖であって 共通な広義先祖 の子孫でもあるもの ]が 1 つ以上あり,それらは 範囲° に部分的に包含され、 それらのうち 共通な広義先祖 の子であるものが該当するものになる。 逆の場合も同様になる。 また、 2 つの子がいずれも定義されたなら,それらは決して等しくならないことにも注意。 These variable assignments do actually always make sense. For instance, if original start node is not an inclusive ancestor of original end node, original start node is itself partially contained in range, and so are all its ancestors up until a child of common ancestor. common ancestor cannot be original start node, because it has to be an inclusive ancestor of original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.
- 包含された子群 :← 次を満たすノードたちが成す,ツリー順序によるリスト :[ 共通な広義先祖 の子である ]∧ 範囲° に包含されている ] Let contained children be a list of all children of common ancestor that are contained in range, in tree order.
-
IF[ 包含された子群 内に doctype が在る ] :THROW
HierarchyRequestError
If any member of contained children is a doctype, then throw a "HierarchyRequestError" DOMException.注記: doctype が部分的に包含されることは決してないので、 部分的に包含されるノードを気にする必要はない。 それは 範囲° の境界点 【始端ノード/終端ノード】 にはなり得ず, 何かの先祖にもなり得ない。 We do not have to worry about the first or last partially contained node, because a doctype can never be partially contained. It cannot be a boundary point of a range, and it cannot be the ancestor of anything.
- IF[ 元の始端ノード は 元の終端ノード の広義先祖である ] :新ノード :← 元の始端ノード; 新オフセット :← 元の始端オフセット If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.
-
ELSE :新ノード :← 共通な広義先祖; 新オフセット :← 部分的に包含された最初の子 の index + 1
【 ここの訳は、 原文の記述と同じ結果を得るものに簡略化している。 】
Otherwise: • Let reference node equal original start node. • While reference node’s parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent. • Set new node to the parent of reference node, and new offset to one plus reference node’s index. • If reference node’s parent is null, it would be the root of range, so would be an inclusive ancestor of original end node, and we could not reach this point. -
IF[ 部分的に包含された最初の子 は文字データノードである ]: If first partially contained child is a CharacterData node:
この事例では, 部分的に包含された最初の子 は 元の始端ノード である。 In this case, first partially contained child is original start node.
- clone :← ノードをクローンする( 元の始端ノード ) Let clone be a clone of original start node.
- clone のデータ ← 元の始端ノード のデータの部分文字列( 元の始端オフセット, ( 元の始端ノード の長さ − 元の始端オフセット ) ) Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node’s length − original start offset.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
- 元の始端ノード のデータを置換する( 元の始端オフセット, 元の始端ノード の長さ − 元の始端オフセット, 空文字列 ) Replace data with node original start node, offset original start offset, count original start node’s length − original start offset, and data the empty string.
-
ELSE IF[ 部分的に包含された最初の子 ≠ null ]: Otherwise, if first partially contained child is not null:
- clone :← ノードをクローンする( 部分的に包含された最初の子 ) Let clone be a clone of first partially contained child.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
- 下位範囲° :← 新たな live 範囲° — その :始端 ← 境界点( 元の始端ノード, 元の始端オフセット ), 終端 ← 境界点( 部分的に包含された最初の子, 部分的に包含された最初の子 の長さ ) Let subrange be a new live range whose start is (original start node, original start offset) and whose end is (first partially contained child, first partially contained child’s length).
- 下位素片 :← 範囲°の内容を抽出する( 下位範囲° ) Let subfragment be the result of extracting subrange.
- clone にノードを付加する( 下位素片 ) Append subfragment to clone.
- 包含された子群 を成す 各( 包含された子 ) に対し :文書片 にノードを付加する( 包含された子 ) For each contained child in contained children, append contained child to fragment.
-
IF[ 部分的に包含された最後の子 は文字データノードである ]: If last partially contained child is a CharacterData node:
注記: この事例では, 部分的に包含された最後の子 は 元の始端ノード である。 In this case, last partially contained child is original end node.
- clone :← ノードをクローンする( 元の終端ノード ) Let clone be a clone of original end node.
- clone のデータ ← 元の終端ノード のデータの部分文字列( 0, 元の終端オフセット ) Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
- 元の終端ノード のデータを置換する( 0, 元の終端オフセット, 空文字列 ) Replace data with node original end node, offset 0, count original end offset, and data the empty string.
-
ELSE IF[ 部分的に包含された最後の子 ≠ null ]: Otherwise, if last partially contained child is not null:
- clone :← ノードをクローンする( 部分的に包含された最後の子 ) Let clone be a clone of last partially contained child.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
- 下位範囲° :← 新たな live 範囲° — その :始端 ← 境界点( 部分的に包含された最後の子, 0 ), 終端 ← 境界点( 元の終端ノード, 元の終端オフセット ) Let subrange be a new live range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
- 下位素片 :← 範囲°の内容を抽出する( 下位範囲° ) Let subfragment be the result of extracting subrange.
- clone にノードを付加する( 下位素片 ) Append subfragment to clone.
- 範囲° の :始端 ← 境界点( 新ノード, 新オフセット ); 終端 ← 境界点( 新ノード, 新オフセット ) Set range’s start and end to (new node, new offset).
- RETURN 文書片 Return fragment.
extractContents()
メソッド手続きは
:RETURN 範囲°の内容を抽出する( これ° )
The extractContents() method steps are to return the result of extracting this.範囲°の内容をクローンする ときは、 所与の ( live 範囲° 範囲° ) に対し: To clone the contents of a live range range, run these steps:
- 文書片 :← 新たな文書片 — その :ノード文書 ← 範囲° の始端ノードのノード文書 Let fragment be a new DocumentFragment node whose node document is range’s start node’s node document.
- IF[ 範囲° は畳まれている ] :RETURN 文書片 If range is collapsed, then return fragment.
- ( 元の始端ノード, 元の始端オフセット, 元の終端ノード, 元の終端オフセット ) :← 順に, 範囲° の ( 始端ノード, 始端オフセット, 終端ノード, 終端オフセット ) Let original start node, original start offset, original end node, and original end offset be range’s start node, start offset, end node, and end offset, respectively.
-
IF[ 元の始端ノード = 元の終端ノード ]∧[ 元の始端ノード は文字データノードである ]: If original start node is original end node and it is a CharacterData node:
- clone :← ノードをクローンする( 元の始端ノード ) Let clone be a clone of original start node.
- clone のデータ ← 元の始端ノード のデータの部分文字列( 元の始端オフセット, ( 元の終端オフセット − 元の始端オフセット ) ) Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
- RETURN 文書片 Return fragment.
- 共通な広義先祖 :← ( 元の始端ノード, 元の終端ノード ) の共通な広義先祖 Let common ancestor be original start node.While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.
- 部分的に包含された最初の子 :← null Let first partially contained child be null.
- IF[ 元の始端ノード は 元の終端ノード の広義先祖でない ] :部分的に包含された最初の子 ← 範囲° に部分的に包含されている[ 共通な広義先祖 の子 ]のうち,最初のもの If original start node is not an inclusive ancestor of original end node, set first partially contained child to the first child of common ancestor that is partially contained in range.
- 部分的に包含された最後の子 :← null Let last partially contained child be null.
-
IF[ 元の終端ノード は 元の始端ノード の広義先祖でない ] :部分的に包含された最後の子 ← 範囲° に部分的に包含されている[ 共通な広義先祖 の子 ]のうち,最後のもの If original end node is not an inclusive ancestor of original start node, set last partially contained child to the last child of common ancestor that is partially contained in range.
注記: これらの変数代入は実際に常に意味を成す。 例えば, 元の始端ノード が 元の終端ノード の広義先祖でない場合、[ 元の始端ノード = 共通な広義先祖 ]にはなり得ないので[ 元の始端ノード の広義先祖であって 共通な広義先祖 の子孫でもあるもの ]が 1 つ以上あり,それらは 範囲° に部分的に包含され、 それらのうち 共通な広義先祖 の子であるものが該当するものになる。 逆の場合も同様になる。 また、 2 つの子がいずれも定義されたなら,それらは決して等しくならないことにも注意。 These variable assignments do actually always make sense. For instance, if original start node is not an inclusive ancestor of original end node, original start node is itself partially contained in range, and so are all its ancestors up until a child of common ancestor. common ancestor cannot be original start node, because it has to be an inclusive ancestor of original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.
- 包含された子群 :← 次を満たすノードたちが成す,ツリー順序によるリスト :[ 共通な広義先祖 の子である ]∧ 範囲° に包含されている ] Let contained children be a list of all children of common ancestor that are contained in range, in tree order.
-
IF[ 包含された子群 内に doctype が在る ] :THROW
HierarchyRequestError
If any member of contained children is a doctype, then throw a "HierarchyRequestError" DOMException.注記: doctype が部分的に包含されることは決してないので、 部分的に包含されるノードを気にする必要はない。 それは 範囲° の境界点 【始端ノード/終端ノード】 にはなり得ず, 何かの先祖にもなり得ない。 We do not have to worry about the first or last partially contained node, because a doctype can never be partially contained. It cannot be a boundary point of a range, and it cannot be the ancestor of anything.
-
IF[ 部分的に包含された最初の子 は文字データノードである ]: If first partially contained child is a CharacterData node:
この事例では, 部分的に包含された最初の子 は 元の始端ノード である。 In this case, first partially contained child is original start node.
- clone :← ノードをクローンする( 元の始端ノード ) Let clone be a clone of original start node.
- clone のデータ ← 元の始端ノード のデータの部分文字列( 元の始端オフセット, ( 元の始端ノード の長さ − 元の始端オフセット ) ) Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node’s length − original start offset.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
-
ELSE IF[ 部分的に包含された最初の子 ≠ null ]: Otherwise, if first partially contained child is not null:
- clone :← ノードをクローンする( 部分的に包含された最初の子 ) Let clone be a clone of first partially contained child.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
- 下位範囲° :← 新たな live 範囲° — その :始端 ← 境界点( 元の始端ノード, 元の始端オフセット ), 終端 ← 境界点( 部分的に包含された最初の子, 部分的に包含された最初の子 の長さ ) Let subrange be a new live range whose start is (original start node, original start offset) and whose end is (first partially contained child, first partially contained child’s length).
- 下位素片 :← 範囲°の内容をクローンする( 下位範囲° ) Let subfragment be the result of cloning the contents of subrange.
- clone にノードを付加する( 下位素片 ) Append subfragment to clone.
-
包含された子群 を成す 各( 包含された子 ) に対し: For each contained child in contained children:
- clone :← ノードをクローンする( 包含された子, true ) Let clone be a clone of contained child with the clone children flag set.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
-
IF[ 部分的に包含された最後の子 は文字データノードである ]: If last partially contained child is a CharacterData node:
注記: この事例では, 部分的に包含された最後の子 は 元の始端ノード である。 In this case, last partially contained child is original end node.
- clone :← ノードをクローンする( 元の終端ノード ) Let clone be a clone of original end node.
- clone のデータ ← 元の終端ノード のデータの部分文字列( 0, 元の終端オフセット ) Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
-
ELSE IF[ 部分的に包含された最後の子 ≠ null ]: Otherwise, if last partially contained child is not null:
- clone :← ノードをクローンする( 部分的に包含された最後の子 ) Let clone be a clone of last partially contained child.
- 文書片 にノードを付加する( clone ) Append clone to fragment.
- 下位範囲° :← 新たな live 範囲° — その :始端 ← 境界点( 部分的に包含された最後の子, 0 ), 終端 ← 境界点( 元の終端ノード, 元の終端オフセット ) Let subrange be a new live range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
- 下位素片 :← 範囲°の内容をクローンする( 下位範囲° ) Let subfragment be the result of cloning the contents of subrange.
- clone にノードを付加する( 下位素片 ) Append subfragment to clone.
- RETURN 文書片 Return fragment.
cloneContents()
メソッド手続きは
:RETURN 範囲°の内容をクローンする( これ° )
The cloneContents() method steps are to return the result of cloning the contents of this.範囲°の中へ挿入する ときは、 所与の ( live 範囲° 範囲°, ノード node ) に対し,次を走らす: To insert a node node into a live range range, run these steps:
【 始端の直後に node を挿入する。 それに伴い、 終端は,末尾側からの相対位置が変化しないように適宜ずらされる (すなわち、[ 始端/終端 ]は,挿入後においても[ 先頭/末尾 ]からの相対位置は不変)。 始端が文字データノードの内部を指している場合、 そのノードは始端の所で 2 つに分割される。 】
- ( 始端ノード, 始端オフセット ) :← 範囲° の ( 始端ノード, 始端オフセット ) ↓
-
IF[ 始端ノード は ∨↓ を満たす ]…
-
ProcessingInstruction
ノードである -
Comment
ノードである -
[
Text
ノードである ]∧[ 親 = null ] - 始端ノード = node
…ならば :THROW
If range’s start node is a ProcessingInstruction or Comment node, is a Text node whose parent is null, or is node, then throw a "HierarchyRequestError" DOMException.HierarchyRequestError
-
- 基準ノード :← null Let referenceNode be null.
-
IF[
始端ノード は
Text
ノードである ] :基準ノード ← 始端ノード If range’s start node is a Text node, set referenceNode to that Text node. - ELSE IF[ 始端ノード の子に[ index = 始端オフセット ]なるものが在る ] :基準ノード ← それ Otherwise, set referenceNode to the child of start node whose index is start offset, and null if there is no such child.
- 親 :← [ 基準ノード ≠ null ならば その親 / 他の場合は 始端ノード ] Let parent be range’s start node if referenceNode is null, and referenceNode’s parent otherwise.
- 親の中で子の前に挿入できるか検証する( node, 親, 基準ノード ) Ensure pre-insert validity of node into parent before referenceNode.
-
IF[ 始端ノード は
Text
ノードである ] :基準ノード ←Text
ノードを分割する( 始端ノード, 始端オフセット )【 始端オフセット が 0 でも分割されることになる。 】
If range’s start node is a Text node, set referenceNode to the result of splitting it with offset range’s start offset. - IF[ node = 基準ノード ] :基準ノード ← node の直後の同胞? If node is referenceNode, set referenceNode to its next sibling.
- IF[ node の親 ≠ null ] :ノードを除去する( node ) If node’s parent is non-null, then remove node.
- 新オフセット :← [ 基準ノード ≠ null ならば その index / 他の場合は 親 の長さ ] Let newOffset be parent’s length if referenceNode is null; otherwise referenceNode’s index.
- 新オフセット += [ node は文書片であるならば その長さ / 他の場合は 1 ] Increase newOffset by node’s length if node is a DocumentFragment node; otherwise 1.
- 親 の中でノードを子の前に前挿入する( node, 基準ノード ) Pre-insert node into parent before referenceNode.
-
IF[ 範囲° は畳まれている ] :範囲° の終端 ← 境界点( 親, 新オフセット )
【 畳まれていない場合の終端の位置は,ノードを子の前に前挿入する(手続きの中でノードを子の前に挿入する)段階で適宜ずらされる。 】
If range is collapsed, then set range’s end to (parent, newOffset).
insertNode(node)
メソッド手続きは
:範囲°の中へ挿入する( これ°, node )
The insertNode(node) method steps are to insert node into this.
surroundContents(newParent)
メソッド手続きは:
The surroundContents(newParent) method steps are:
-
IF[
ある非
Text
ノードがこれ°に部分的に包含されている ] :THROWInvalidStateError
If a non-Text node is partially contained in this, then throw an "InvalidStateError" DOMException. -
IF[ newParent は
Document
,DocumentType
,DocumentFragment
ノード のいずれかである ] :THROWInvalidNodeTypeError
If newParent is a Document, DocumentType, or DocumentFragment node, then throw an "InvalidNodeTypeError" DOMException.注記: 歴史的な理由から、 文字データノードに対しては、 この段では検査されず,後の段にて副作用とともに例外が投出される結果になる。 For historical reasons CharacterData nodes are not checked here and end up throwing later on as a side effect.
- 文書片 :← 範囲°の内容を抽出する( これ° ) Let fragment be the result of extracting this.
- IF[ newParent の子群は空でない ] :newParent の全内容をノードで置換する( null ) If newParent has children, then replace all with null within newParent.
- 範囲°の中へ挿入する( これ°, newParent ) Insert newParent into this.
- newParent にノードを付加する( 文書片 ) Append fragment to newParent.
- 範囲°の内容として選択する( これ°, newParent ) Select newParent within this.
cloneRange()
メソッド手続きは
:RETURN 新たな live 範囲°
— その
:始端 ← これ°の始端の複製,
終端 ← これ°の終端の複製
The cloneRange() method steps are to return a new live range with the same start and end as this.
detach()
メソッド手続きは、
何もしない。
The detach() method steps are to do nothing.\
注記:
この機能性( Range
オブジェクトを不能化する)は、
除去された。
互換性のため存続はするが。
Its functionality (disabling a Range object) was removed, but the method itself is preserved for compatibility.
- position = range .
isPointInRange(node, offset)
- 境界点( node, offset ) が range 内に入る†かどうかを返す。
- position = range .
comparePoint(node, offset)
- 境界点( node, offset ) が range より前に位置する場合は − 1 を, range 内に入る†場合は 0 を, range より後に位置する場合は 1 を 返す。 Returns −1 if the point is before the range, 0 if the point is in the range, and 1 if the point is after the range.
- 【† 境界点が range のいずれかの境界点に一致する場合も,“入る” と見なされる。 】
- intersects = range .
intersectsNode(node)
- range が node と交わるかどうかを返す。 Returns whether range intersects node.
-
【 node が range に隣接している場合 ( range の終端(始端)が node の 外縁な 始端(終端)を指す境界点に一致する場合)は、 “交わらない”。 例えば下図で s, e が range の境界点を表すとするとき,図の青色区間が表す node は交わらない。 】
【 一般に、 node は 範囲° に (1) 包含されているとき, または (2) 範囲° の始端ノード/終端ノードいずれかの広義先祖であるとき、 “交わる”。 】
stringifier
- 範囲°を文字列化した結果は、 範囲°により “選択” されているすべてのテキストになる。
【
上のブロックに挙げた isPointInRange()
, stringifier
は、
原文には存在しない,この訳による補完。
】
isPointInRange(node, offset)
メソッド手続きは:
The isPointInRange(node, offset) method steps are:
- IF[ node の根 ≠ これ°の根 ] :RETURN false If node’s root is different from this’s root, return false.
-
IF[
node は doctype である
]
:THROW
InvalidNodeTypeError
If node is a doctype, then throw an "InvalidNodeTypeError" DOMException. -
IF[
offset > node の長さ
]
:THROW
IndexSizeError
If offset is greater than node’s length, then throw an "IndexSizeError" DOMException. - IF[ 境界点( node, offset ) は[[ これ°の始端より前 ]∨[ これ°の終端より後 ]]] :RETURN false If (node, offset) is before start or after end, return false.
- RETURN true Return true.
comparePoint(node, offset)
メソッド手続きは:
The comparePoint(node, offset) method steps are:
-
IF[
node の根 ≠ これ°の根
]
:THROW
WrongDocumentError
If node’s root is different from this’s root, then throw a "WrongDocumentError" DOMException. -
IF[
node は doctype である
]
:THROW
InvalidNodeTypeError
If node is a doctype, then throw an "InvalidNodeTypeError" DOMException. -
IF[
offset > node の長さ
]
:THROW
IndexSizeError
If offset is greater than node’s length, then throw an "IndexSizeError" DOMException. - IF[ 境界点( node, offset ) は これ°の始端より前 ] :RETURN − 1 If (node, offset) is before start, return −1.
- IF[ 境界点( node, offset ) は これ°の終端より後 ] :RETURN 1 If (node, offset) is after end, return 1.
- RETURN 0 Return 0.
intersectsNode(node)
メソッド手続きは:
The intersectsNode(node) method steps are:
- IF[ node の根 ≠ これ°の根 ] :RETURN false If node’s root is different from this’s root, return false.
- 親 :← node の親 Let parent be node’s parent.
- IF[ 親 = null ] :RETURN true If parent is null, return true.
- offset :← node の index Let offset be node’s index.
- IF[ 境界点( 親, offset ) は これ°の終端より前 ]∧[ 境界点( 親, offset + 1 ) は これ°の始端より後 ] :RETURN true If (parent, offset) is before end and (parent, offset plus 1) is after start, return true.
- RETURN false Return false.
stringifier
における文字列化のふるまいは:
The stringification behavior must run these steps:
- 結果 :← 空文字列 Let s be the empty string.
- ( 始端ノード, 始端オフセット, 終端ノード, 終端オフセット ) :← これ°の ( 始端ノード, 始端オフセット, 終端ノード, 終端オフセット ) ↓
-
- IF[ 始端ノード = 終端ノード ] :RETURN 始端ノード のデータの中の 始端オフセット から 終端オフセット までを成す符号単位部分文字列
- 結果 に次を付加する :始端ノード のデータの中の 始端オフセット から終端までを成す符号単位部分文字列
-
これ°に包含されている
各(
Text
ノード ノード ) に対し,ツリー順序で :結果 に ノード のデータを付加する Append the concatenation of the data of all Text nodes that are contained in this, in tree order, to s. -
IF[
終端ノード は
Text
ノードである ] :結果 に次を付加する :終端ノード のデータの中の 0 から 終端オフセット までを成す符号単位部分文字列 If this’s end node is a Text node, then append the substring of that node’s data from its start until this’s end offset to s. - RETURN 結果 Return s.
注記:
Range
インタフェースに対する拡張として、
他の仕様にて次に挙げるメソッドが定義されている
:createContextualFragment()
[DOM-Parsing][HTML],
getClientRects()
,
getBoundingClientRect()
[CSSOM-VIEW]
The createContextualFragment(), getClientRects(), and getBoundingClientRect() methods are defined in other specifications. [DOM-Parsing] [CSSOM-VIEW]
6. 辿り
[
NodeIterator
/ TreeWalker
]オブジェクトを利用すれば、
ノードツリーをフィルタにかけながら辿れる。
NodeIterator and TreeWalker objects can be used to filter and traverse node trees.
各[
NodeIterator
/ TreeWalker
]オブジェクトには、
次に挙げるものが結び付けられる:
- 作動中か :真偽値 — 初期時は false とする。 再入的な呼び出しを避けるためにある。
- 根 :ノード — 辿られる下位ツリーの根を与える。
-
whatToShow
:ビットマスクを成す整数
— どの型(
nodeType
)のノードを辿るかを指示する。 1 にされたビットに対応する型のノードのみがフィルタを “通過する” 。 - フィルタ callback :callback / null — callback は、 対象を更に “濾過する” 条件を与える。
【 作動中か以外の各項の記述は、 値型を除いて,この訳による補完。 】
Each NodeIterator and TreeWalker object has an associated active flag to avoid recursive invocations. It is initially unset.Each NodeIterator and TreeWalker object also has an associated root (a node), a whatToShow (a bitmask), and a filter (a callback).
辿り器の中でノードをフィルタにかける
ときは、
所与の
([
NodeIterator
/ TreeWalker
]オブジェクト 辿り器, ノード ノード )
に対し,次を走らす:
To filter a node node within a NodeIterator or TreeWalker object traverser, run these steps:
-
IF[
辿り器 の作動中か = true
]
:THROW
InvalidStateError
If traverser’s active flag is set, then throw an "InvalidStateError" DOMException. -
n :← ノード の
nodeType
属性値 − 1 Let n be node’s nodeType attribute value − 1. -
IF[
辿り器 の whatToShow の n 番のビット( 0 番が最下位ビットとする) = 0
]
:RETURN
FILTER_SKIP
If the nth bit (where 0 is the least significant bit) of traverser’s whatToShow is not set, then return FILTER_SKIP. -
IF[
辿り器 のフィルタ callback = null
]
:RETURN
FILTER_ACCEPT
If traverser’s filter is null, then return FILTER_ACCEPT. - 辿り器 の作動中か ← true Set traverser’s active flag.
-
結果 :← 次を与える下で,利用元オブジェクトの演算を call する :辿り器 のフィルタ callback , "
acceptNode
", « ノード »call した結果,例外が投出されたときは、 catch して :辿り器 の作動中か ← false; THROW その例外
Let result be the return value of call a user object’s operation with traverser’s filter, "acceptNode", and « node ». If this throws an exception, then unset traverser’s active flag and rethrow the exception. - 辿り器 の作動中か ← false Unset traverser’s active flag.
- RETURN 結果 Return result.
6.1. NodeIterator
インタフェース
[Exposed=Window]
interface NodeIterator {
[SameObject] readonly attribute Node root;
readonly attribute Node referenceNode;
readonly attribute boolean pointerBeforeReferenceNode;
readonly attribute unsigned long whatToShow;
readonly attribute NodeFilter? filter;
Node? nextNode();
Node? previousNode();
undefined detach();
};
注記:
NodeIterator
オブジェクトは、
Document
オブジェクト上の createNodeIterator()
メソッドを利用して作成できる。
NodeIterator objects can be created using the createNodeIterator() method on Document objects.
各 NodeIterator
オブジェクトには、
次に挙げるものが結び付けられる:
【 ( 起点, 起点の直前か ) が成す組は、[ 反復器で辿るとき,どのノードから探索し始めるか ]を指すポインタを表現する。 起点(初期時は先頭のノードである根にされる)は、 “現在の” ノードを表す。 ポインタは、 起点の直前か (初期時は true )に応じて, 現在のノードの “直前” ( true )か “直後” ( false )を指す (したがって、 初期時のポインタは根の直前を指す)。 】
Each NodeIterator object has an associated iterator collection, which is a collection rooted at the NodeIterator object’s root, whose filter matches any node.Each NodeIterator object also has an associated reference (a node) and pointer before reference (a boolean).
注記:
前に言及したように、
NodeIterator
オブジェクトには[
作動中か,
根,
whatToShow ,
フィルタ callback
]も結び付けられる。
As mentioned earlier, NodeIterator objects have an associated active flag, root, whatToShow, and filter as well.
ノード反復器用の前除去する手続き
は、
所与の
( NodeIterator
反復器, ノード 除去されるノード )
に対し:
The NodeIterator pre-remove steps given a nodeIterator and toBeRemovedNode, are as follows:
- IF[ 除去されるノード は 反復器 の起点の広義先祖でない ]∨[ 除去されるノード = 反復器 の根 ] :RETURN If toBeRemovedNode is not an inclusive ancestor of nodeIterator’s reference, or toBeRemovedNode is nodeIterator’s root, then return.
-
IF[ 反復器 の起点の直前か = true ]: If nodeIterator’s pointer before reference is true:
- Let next be toBeRemovedNode’s first following node that is an inclusive descendant of nodeIterator’s root and is not an inclusive descendant of toBeRemovedNode, and null if there is no such node.
- IF[ 直後の ≠ null ] :反復器 の起点 ← 直後の; RETURN If next is non-null, then set nodeIterator’s reference to next and return.
- 反復器 の起点の直前か ← false Otherwise, set nodeIterator’s pointer before reference to false.Steps are not terminated here.
- 直前の同胞 :← 除去されるノード の直前の同胞? ↓
- 反復器 の起点 ← 直前の同胞 に応じて : null ならば 除去されるノード の親 / 他の場合は 直前の同胞 の広義子孫のうち 最後のもの? Set nodeIterator’s reference to toBeRemovedNode’s parent, if toBeRemovedNode’s previous sibling is null, and to the inclusive descendant of toBeRemovedNode’s previous sibling that appears last in tree order otherwise.
pointerBeforeReferenceNode
取得子手続きは
:RETURN これ°の起点の直前か
The pointerBeforeReferenceNode getter steps are to return this’s pointer before reference.whatToShow
取得子手続きは
:RETURN これ°の whatToShow
The whatToShow getter steps are to return this’s whatToShow.
反復器で辿る
ときは、
所与の
( NodeIterator
オブジェクト 反復器, 方向 ∈ { 順, 逆 } )
に対し,次を走らす:
To traverse, given a NodeIterator object iterator and a direction direction, run these steps:
- ノード :← 反復器 の起点 Let node be iterator’s reference.
- 直前か :← 反復器 の起点の直前か Let beforeNode be iterator’s pointer before reference.
- コレクション :← 反復器 の反復器コレクション ↓
-
WHILE 無条件: While true:
-
IF[ 方向 = 順 ]: Branch on direction:next
-
IF[ 直前か = false ]: If beforeNode is false, then\
- ELSE :直前か ← false If beforeNode is true, then set it to false.
-
-
ELSE( 方向 = 逆 ): previous
-
IF[ 直前か = true ]: If beforeNode is true, then\
- ELSE :直前か ← true If beforeNode is false, then set it to true.
-
-
IF[
辿り器の中でノードをフィルタにかける( 反復器, ノード ) =
FILTER_ACCEPT
] :BREAK Let result be the result of filtering node within iterator.If result is FILTER_ACCEPT, then break.
-
- 反復器 の起点 ← ノード Set iterator’s reference to node.
- 反復器 の起点の直前か ← 直前か Set iterator’s pointer before reference to beforeNode.
- RETURN ノード Return node.
【 辿り方向が前回と逆向きに切り替わった場合、 探索処理は,前回の辿りによる “現在の” ノード( 起点 )から開始されることに注意(その直後の/直前のノードからではなく)。 探索した結果,フィルタに合致するノードが見出されなかった場合、 起点は変更されない。 見出された場合、 起点 は,新たに見出されたノードにされ, 起点の直前か ( “現在の” 辿り方向)は,渡された 方向 を反映するようになる ( false が 順 方向に対応する)。 】
nextNode()
メソッド手続きは
:RETURN 反復器で辿る( これ°, 順 )
The nextNode() method steps are to return the result of traversing with this and next.previousNode()
メソッド手続きは
:RETURN 反復器で辿る( これ°, 逆 )
The previousNode() method steps are to return the result of traversing with this and previous.
detach()
メソッド手続きは、
何もしない。
The detach() method steps are to do nothing.\
注記:
この機能性( NodeIterator
オブジェクトを不能化する)は、
除去された。
互換性のため存続はするが。
Its functionality (disabling a NodeIterator object) was removed, but the method itself is preserved for compatibility.
6.2. TreeWalker
インタフェース
[Exposed=Window]
interface TreeWalker {
[SameObject] readonly attribute Node root;
readonly attribute unsigned long whatToShow;
readonly attribute NodeFilter? filter;
attribute Node currentNode;
Node? parentNode();
Node? firstChild();
Node? lastChild();
Node? previousSibling();
Node? nextSibling();
Node? previousNode();
Node? nextNode();
};
注記:
TreeWalker
オブジェクトは、
Document
オブジェクト上の createTreeWalker()
メソッドを利用して作成できる。
TreeWalker objects can be created using the createTreeWalker() method on Document objects.
各 TreeWalker
オブジェクトには、
現ノード
( ノード )が結び付けられる。
Each TreeWalker object has an associated current (a node).
注記:
前に言及したとおり、
TreeWalker
オブジェクトには[
根,
whatToShow ,
フィルタ callback
]も結び付けられる。
As mentioned earlier TreeWalker objects have an associated root, whatToShow, and filter as well.
whatToShow
取得子手続きは
:RETURN これ°の whatToShow
The whatToShow getter steps are to return this’s whatToShow.currentNode
設定子手続きは
:これ°の現ノード ← 所与の値
The currentNode setter steps are to set this’s current to the given value.
parentNode()
メソッド手続きは:
The parentNode() method steps are:
- ノード :← これ°の現ノード Let node be this’s current.
-
WHILE[ ノード の親 ≠ null ]∧[ ノード ≠ これ°の根 ]:
- ノード ← ノード の親
- 結果 :← 辿り器の中でノードをフィルタにかける( これ°, ノード )
-
IF[
結果 ≠
FILTER_ACCEPT
] :CONTINUE - これ°の現ノード ← ノード
- RETURN ノード
- RETURN null Return null.
子群を辿る ときは、 所与の ( walker, 向き ∈ { 最初から, 最後から } ) に対し,次を走らす: To traverse children, given a walker and type, run these steps:
- ノード :← walker の現ノード Let node be walker’s current.
- ノード ← 向き に応じて :最初から ならば ノード の最初の子? / 最後から ならば ノード の最後の子? Set node to node’s first child if type is first, and node’s last child if type is last.
-
WHILE[ ノード ≠ null ]: While node is non-null:
- 結果 :← 辿り器の中でノードをフィルタにかける( walker, ノード ) Let result be the result of filtering node within walker.
-
IF[
結果 =
FILTER_ACCEPT
] :walker の現ノード ← ノード; RETURN ノード If result is FILTER_ACCEPT, then set walker’s current to node and return node. -
IF[ 結果 =
FILTER_SKIP
]: If result is FILTER_SKIP: -
WHILE[ ノード ≠ null ]: While node is non-null:
- 同胞 :← 向き に応じて :最初から ならば ノード の直後の同胞? / 最後から ならば ノード の直前の同胞? Let sibling be node’s next sibling if type is first, and node’s previous sibling if type is last.
- IF[ 同胞 ≠ null ] :ノード ← 同胞; BREAK If sibling is non-null, then set node to sibling and break.
- 親 :← ノード の親 Let parent be node’s parent.
- IF[ 親 ∈ { null , walker の根, walker の現ノード } ] :RETURN null If parent is null, walker’s root, or walker’s current, then return null.
- ノード ← 親 Set node to parent.
- RETURN null Return null.
firstChild()
メソッド手続きは
:RETURN 子群を辿る( これ°, 最初から )
The firstChild() method steps are to traverse children with this and first.lastChild()
メソッド手続きは
:RETURN 子群を辿る( これ°, 最後から )
The lastChild() method steps are to traverse children with this and last.同胞たちを辿る ときは、 所与の ( walker, 向き ∈ { 順, 逆 } ) に対し,次を走らす: To traverse siblings, given a walker and type, run these steps:
- ノード :← walker の現ノード Let node be walker’s current.
- IF[ ノード = walker の根 ] :RETURN null If node is root, then return null.
-
WHILE 無条件: While true:
- 同胞 :← 向き に応じて :順 ならば ノード の直後の同胞? / 逆 ならば ノード の直前の同胞? Let sibling be node’s next sibling if type is next, and node’s previous sibling if type is previous.
-
WHILE[ 同胞 ≠ null ]: While sibling is non-null:
- ノード ← 同胞 Set node to sibling.
- 結果 :← 辿り器の中でノードをフィルタにかける( walker, ノード ) Let result be the result of filtering node within walker.
-
IF[
結果 =
FILTER_ACCEPT
] :walker の現ノード ← ノード; RETURN ノード If result is FILTER_ACCEPT, then set walker’s current to node and return node. - 同胞 ← 向き に応じて :順 ならば ノード の最初の子? / 逆 ならば ノード の最後の子? Set sibling to node’s first child if type is next, and node’s last child if type is previous.
-
IF[
結果 =
FILTER_REJECT
]∨[ 同胞 = null ] :同胞 ← 向き に応じて :順 ならば ノード の直後の同胞? / 逆 ならば ノード の直前の同胞? If result is FILTER_REJECT or sibling is null, then set sibling to node’s next sibling if type is next, and node’s previous sibling if type is previous.
- ノード ← ノード の親 Set node to node’s parent.
- IF[ ノード ∈ { null , walker の根 } ] :RETURN null If node is null or walker’s root, then return null.
-
IF[
辿り器の中でノードをフィルタにかける( これ°, ノード ) =
FILTER_ACCEPT
] :RETURN null If the return value of filtering node within walker is FILTER_ACCEPT, then return null.
nextSibling()
メソッド手続きは
:RETURN 同胞たちを辿る( これ°, 順 )
The nextSibling() method steps are to traverse siblings with this and next.previousSibling()
メソッド手続きは
:RETURN 同胞たちを辿る( これ°, 逆 )
The previousSibling() method steps are to traverse siblings with this and previous.
previousNode()
メソッド手続きは:
The previousNode() method steps are:
- ノード :← これ°の現ノード Let node be this’s current.
-
WHILE[ ノード ≠ これ°の根 ]: While node is not this’s root:
- 同胞 :← ノード の直前の同胞? Let sibling be node’s previous sibling.
-
WHILE[ 同胞 ≠ null ]: While sibling is non-null:
- ノード ← 同胞 Set node to sibling.
- 結果 :← 辿り器の中でノードをフィルタにかける( これ°, ノード ) Let result be the result of filtering node within this.
-
WHILE[ 結果 ≠
FILTER_REJECT
]∧[ ノード の子群は空でない ]: While result is not FILTER_REJECT and node has a child:- ノード ← ノード の最後の子? Set node to node’s last child.
- 結果 ← 辿り器の中でノードをフィルタにかける( これ°, ノード ) Set result to the result of filtering node within this.
-
IF[
結果 =
FILTER_ACCEPT
] :これ°の現ノード ← ノード; RETURN ノード If result is FILTER_ACCEPT, then set this’s current to node and return node. - 同胞 ← ノード の直前の同胞? Set sibling to node’s previous sibling.
- IF[ ノード = これ°の根 ]∨[ ノード の親 = null ] :RETURN null If node is this’s root or node’s parent is null, then return null.
- ノード ← ノード の親 Set node to node’s parent.
- 結果 :← 辿り器の中でノードをフィルタにかける( これ°, ノード ) ↓
-
IF[
結果 =
FILTER_ACCEPT
] :これ°の現ノード ← ノード; RETURN ノード If the return value of filtering node within this is FILTER_ACCEPT, then set this’s current to node and return node.
- RETURN null Return null.
nextNode()
メソッド手続きは:
The nextNode() method steps are:
- ノード :← これ°の現ノード Let node be this’s current.
-
結果 :←
FILTER_ACCEPT
Let result be FILTER_ACCEPT. -
WHILE 無条件: While true:
-
WHILE[ 結果 ≠
FILTER_REJECT
]∧[ ノード の子群は空でない ]: While result is not FILTER_REJECT and node has a child:- ノード ← ノード の最初の子? Set node to its first child.
- 結果 ← 辿り器の中でノードをフィルタにかける( これ°, ノード ) Set result to the result of filtering node within this.
-
IF[
結果 =
FILTER_ACCEPT
] :これ°の現ノード ← ノード; RETURN ノード If result is FILTER_ACCEPT, then set this’s current to node and return node.
- 同胞 :← null Let sibling be null.
- temporary :← ノード Let temporary be node.
-
WHILE[ temporary ≠ null ]: While temporary is non-null:
- IF[ temporary = これ°の根 ] :RETURN null If temporary is this’s root, then return null.
- 同胞 ← temporary の直後の同胞? Set sibling to temporary’s next sibling.
- IF[ 同胞 ≠ null ] :ノード ← 同胞; BREAK If sibling is non-null, then set node to sibling and break.
- temporary ← temporary の親 Set temporary to temporary’s parent.
- 結果 ← 辿り器の中でノードをフィルタにかける( これ°, ノード ) Set result to the result of filtering node within this.
-
IF[
結果 =
FILTER_ACCEPT
] :これ°の現ノード ← ノード; RETURN ノード If result is FILTER_ACCEPT, then set this’s current to node and return node.
-
6.3. NodeFilter
インタフェース
[Exposed=Window]
callback interface NodeFilter {
/*
acceptNode() 用の定数
Constants for acceptNode */
const unsigned short FILTER_ACCEPT = 1;
const unsigned short FILTER_REJECT = 2;
const unsigned short FILTER_SKIP = 3;
/*
whatToShow 用の定数
Constants for whatToShow bitmask */
const unsigned long SHOW_ALL = 0xFFFFFFFF;
const unsigned long SHOW_ELEMENT = 0x1;
const unsigned long SHOW_ATTRIBUTE = 0x2;
const unsigned long SHOW_TEXT = 0x4;
const unsigned long SHOW_CDATA_SECTION = 0x8;
const unsigned long SHOW_ENTITY_REFERENCE = 0x10; // 旧来
const unsigned long SHOW_ENTITY = 0x20; // 旧来
const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x40;
const unsigned long SHOW_COMMENT = 0x80;
const unsigned long SHOW_DOCUMENT = 0x100;
const unsigned long SHOW_DOCUMENT_TYPE = 0x200;
const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x400;
const unsigned long SHOW_NOTATION = 0x800; // 旧来
unsigned short acceptNode(Node node);
};
注記:
NodeFilter
オブジェクトは、[
NodeIterator
/ TreeWalker
]用のフィルタ callback として利用できる。
また、
それら用の whatToShow としてビットマスク定数を供する。
NodeFilter
オブジェクトは、
概して,JavaScript 関数として実装される。
NodeFilter objects can be used as filter for NodeIterator and TreeWalker objects and also provide constants for their whatToShow bitmask. A NodeFilter object is typically implemented as a JavaScript function.
フィルタ callback の返り値には、
次に挙げる定数を利用できる(括弧内は数値)
:FILTER_ACCEPT
(1),
FILTER_REJECT
(2),
FILTER_SKIP
(3)
These constants can be used as filter return value:
• FILTER_ACCEPT (1);
• FILTER_REJECT (2);
• FILTER_SKIP (3).
【 これらの定数の意味は: 】
-
FILTER_ACCEPT
:ノードはフィルタを “通過する”。 -
FILTER_REJECT
:NodeIterator
に利用されている下では、FILTER_SKIP
と同じ結果になる。TreeWalker
に利用されている下では、 ノードはその子孫も含めて “濾過される”。 -
FILTER_SKIP
:ノード自身は “濾過される” が、 その子孫は,依然としてフィルタの対象になり得る。
whatToShow 用には、 次に挙げる定数を利用できる(括弧内は数値): These constants can be used for whatToShow:
SHOW_ALL
(4294967295 = 0xFFFFFFFF)SHOW_ELEMENT
(1)SHOW_ATTRIBUTE
(2)SHOW_TEXT
(4)SHOW_CDATA_SECTION
(8)SHOW_PROCESSING_INSTRUCTION
(64 = 0x40)SHOW_COMMENT
(128 = 0x80)SHOW_DOCUMENT
(256 = 0x100)SHOW_DOCUMENT_TYPE
(512 = 0x200)SHOW_DOCUMENT_FRAGMENT
(1024 = 0x400)
7. トークン集合
Yes, the name DOMTokenList
is an unfortunate legacy mishap.
7.1. DOMTokenList
インタフェース
[Exposed=Window]
interface DOMTokenList {
readonly attribute unsigned long length;
getter DOMString? item(unsigned long index);
boolean contains(DOMString token);
[CEReactions] undefined add(DOMString... tokens);
[CEReactions] undefined remove(DOMString... tokens);
[CEReactions] boolean toggle(DOMString token, optional boolean force);
[CEReactions] boolean replace(DOMString token, DOMString newToken);
boolean supports(DOMString token);
[CEReactions] stringifier attribute DOMString value;
iterable<DOMString>;
};
各 DOMTokenList
には、
次に挙げるものが結び付けられる:
適用可能な仕様は、
属性°の局所名に対し,それが
サポートするトークン集合
を DOMTokenList
用に定義してもよい
— これは、
トークンたちが成す集合であり,他が指定されない限り ε (未定義)とする。
Specifications may define supported tokens for a DOMTokenList's associated attribute’s local name.
所与の DOMTokenList
オブジェクト O 対し,
( 要素, 名前 )
は
( O の要素, O の属性°の局所名 )
とするとき:
↓
-
O 上で トークンを検証する ときは、 所与の ( トークン ) に対し,次を走らす: A DOMTokenList object’s validation steps for a given token are:
- トークン集合 :← 名前 がサポートするトークン集合 ↓
-
IF[
トークン集合 = ε
]
:THROW
TypeError
If the associated attribute’s local name does not define supported tokens, throw a TypeError. - RETURN IS[ ASCII 小文字化する( トークン ) ∈ トークン集合 ] Let lowercase token be a copy of token, in ASCII lowercase.If lowercase token is present in supported tokens, return true.Return false.
-
O の 更新手続き は、 次を走らす: A DOMTokenList object’s update steps are:
- IF[ 要素 の属性°リストは空である ]∧[ O のトークン集合は空である ] :RETURN If the associated element does not have an associated attribute and token set is empty, then return.
- 要素 の属性°値を設定する( 名前, 有順序集合を直列化する( O のトークン集合 ) ) Set an attribute value for the associated element using associated attribute’s local name and the result of running the ordered set serializer for token set.
- O の 直列化手続き は、 次の結果を返す :要素 の属性°値を取得する( 名前 ) A DOMTokenList object’s serialize steps are to return the result of running get an attribute value given the associated element and the associated attribute’s local name.
-
要素 用の属性°変更時の手続きは、 所与の ( 局所名, 旧値, 値, 名前空間 ) に対し: A DOMTokenList object has these attribute change steps for its associated element:
-
IF[ 局所名 = 名前 ]∧[ 名前空間 = null ]:
- IF[ 値 = null ] :O のトークン集合を空にする
- ELSE :O のトークン集合 ← 有順序集合として構文解析する( 値 )
-
-
O の作成時には、 次を走らす: When a DOMTokenList object is created, then:
- 値 :← 要素 の属性°値を取得する( 名前 ) Let element be associated element.Let localName be associated attribute’s local name.Let value be the result of getting an attribute value given element and localName.
- 適用可能な仕様にて 要素 用に定義された各( 属性°変更時の手続き 手続き ) に対し :手続き( 名前, 値, 値, null ) Run the attribute change steps for element, localName, value, value, and null.
- tokenlist .
length
- トークンの個数を返す。 Returns the number of tokens.
- tokenlist .
item(index)
- tokenlist[index]
- index 番のトークンを返す。 Returns the token with index index.
- tokenlist .
contains(token)
- token が[ 在るならば true / 無いならば false ]を返す。 Returns true if token is present; otherwise false.
- tokenlist .
add(tokens…)
- 渡された引数のうち,まだ無いものを追加する。 Adds all arguments passed, except those already present.
- 下記に該当する場合、 例外が投出される。 Throws a "SyntaxError" DOMException if one of the arguments is the empty string.Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace.
- tokenlist .
remove(tokens…)
- 渡された引数のそれぞれを(もし在れば)除去する。 Removes arguments passed, if they are present.
- 下記に該当する場合、 例外が投出される。 Throws a "SyntaxError" DOMException if one of the arguments is the empty string.Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace.
- tokenlist .
toggle(token [, force])
-
force に応じて:
- 省略されているならば、 token の有無を “トグルする”。 すなわち、 token がすでに在るならば除去し,無いならば追加する。
-
true ならば、
token を追加する
(
add()
と同じ)。 -
false ならば、
token を除去する
(
remove()
と同じ)。
その結果、 token が[ 残っていれば true / 無くなっていれば false ]を返す。
If force is not given, "toggles" token, removing it if it’s present and adding it if it’s not present. If force is true, adds token (same as add()). If force is false, removes token (same as remove()).Returns true if token is now present; otherwise false. - 下記に該当する場合、 例外が投出される。 Throws a "SyntaxError" DOMException if token is empty.Throws an "InvalidCharacterError" DOMException if token contains any spaces.
- tokenlist .
replace(token, newToken)
- token を newToken に置換する。 Replaces token with newToken.
- token が newToken に[ 置換されたなら true / 置換されなかったなら false ]を返す。 Returns true if token was replaced with newToken; otherwise false.
- 下記に該当する場合、 例外が投出される。 Throws a "SyntaxError" DOMException if one of the arguments is the empty string.Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace.
- (例外)
-
上の各種メソッドに渡された文字列引数のいずれかが,次に該当する場合、 対応する例外が投出される:
-
空文字列の場合:
SyntaxError
-
ASCII 空白を含む場合:
InvalidCharacterError
-
空文字列の場合:
- tokenlist .
supports(token)
- 属性°の局所名がサポートするトークン集合に token が含まれて[ いれば true / いなければ false ]を返す。 Returns true if token is in the associated attribute’s supported tokens. Returns false otherwise.
-
サポートするトークン集合が定義されていない場合、
TypeError
が投出される。 Throws a TypeError if the associated attribute has no supported tokens defined. - tokenlist .
value
- 結び付けられたトークン集合を文字列として返す。 Returns the associated set as string.
- 設定して結び付けられた属性を変更できる。 Can be set, to change the associated attribute.
length
取得子手続きは
:RETURN これ°のトークン集合のサイズ
The length attribute' getter must return this’s token set’s size.
DOMTokenList
オブジェクト O がサポートするプロパティ index は、
0 以上[
O のトークン集合のサイズ
]未満とする。
The object’s supported property indices are the numbers in the range zero to object’s token set’s size minus one, unless token set is empty, in which case there are no supported property indices.
item(index)
メソッド手続きは:
The item(index) method steps are:
- IF[ index ∉ { これ°がサポートするプロパティ index } ] :RETURN null If index is equal to or greater than this’s token set’s size, then return null.
- RETURN これ°のトークン集合[ index ] Return this’s token set[index].
トークンを検査する ときは、 所与の ( token ) に対し,次を走らす:
-
IF[
token = 空文字列
]
:THROW
SyntaxError
-
IF[
token は ASCII 空白を含んでいる
]
:THROW
InvalidCharacterError
contains(token)
メソッド手続きは
:RETURN IS[
token ∈ これ°のトークン集合
]
The contains(token) method steps are to return true if this’s token set[token] exists; otherwise false.
add(tokens…)
メソッド手続きは:
The add(tokens…) method steps are:
- tokens を成す 各( token ) に対し,与えられた順に :トークンを検査する( token ) For each token in tokens: • If token is the empty string, then throw a "SyntaxError" DOMException. • If token contains any ASCII whitespace, then throw an "InvalidCharacterError" DOMException.
- tokens を成す 各( token ) に対し :これ°のトークン集合に token を付加する For each token in tokens, append token to this’s token set.
- これ°の更新手続きを走らす Run the update steps.
remove(tokens…)
メソッド手続きは:
The remove(tokens…) method steps are:
- tokens を成す 各( token ) に対し,与えられた順に :トークンを検査する( token ) For each token in tokens: • If token is the empty string, then throw a "SyntaxError" DOMException. • If token contains any ASCII whitespace, then throw an "InvalidCharacterError" DOMException.
- tokens を成す 各( token ) に対し :これ°のトークン集合から token を除去する For each token in tokens, remove token from this’s token set.
- これ°の更新手続きを走らす Run the update steps.
toggle(token, force)
メソッド手続きは:
The toggle(token, force) method steps are:
- トークンを検査する( token ) If token is the empty string, then throw a "SyntaxError" DOMException.If token contains any ASCII whitespace, then throw an "InvalidCharacterError" DOMException.
-
IF[ token ∈ これ°のトークン集合 ]: If this’s token set[token] exists:
-
IF[ force = ε ]∨[ force = true ]:
Otherwise, if force not given or is true, append token to this’s token set, run the update steps, and return true. - RETURN false Return false.
注記:
web 互換性のため、
toggle()
に対しては,更新手続きを常に走らすとは限らない。
The update steps are not always run for toggle() for web compatibility.
replace(token, newToken)
メソッド手続きは:
The replace(token, newToken) method steps are:
-
IF[
token = 空文字列
]∨[
newToken = 空文字列
]
:THROW
SyntaxError
If either token or newToken is the empty string, then throw a "SyntaxError" DOMException. -
IF[
token は ASCII 空白を含んでいる
]∨[
newToken は ASCII 空白を含んでいる
]
:THROW
InvalidCharacterError
If either token or newToken contains any ASCII whitespace, then throw an "InvalidCharacterError" DOMException. - IF[ token ∉ これ°のトークン集合 ] :RETURN false If this’s token set does not contain token, then return false.
- これ°のトークン集合内で token を newToken に置換する Replace token in this’s token set with newToken.
- これ°の更新手続きを走らす Run the update steps.
- RETURN true Return true.
注記:
web 互換性のため、
replace()
に対しては,更新手続きを常に走らすとは限らない。
The update steps are not always run for replace() for web compatibility.
【 最初と二番目の段は、 token, newToken の順にトークンを検査するのとは,ふるまいが異なる。 】
supports(token)
メソッド手続きは
:RETURN これ°上でトークンを検証する( token )
The supports(token) method steps are:
• Let result be the return value of validation steps called with token.
• Return result.value
取得子手続きは
:RETURN これ°の直列化手続きを走らせた結果
The value attribute must return the result of running this’s serialize steps.8. XPath
DOM Level 3 XPath は、 XPath 1.0 式を評価するための API を定義した。 これらの API は、 広く実装されてはいるが,保守されていない。 各種インタフェース定義は、 Web IDL が変更されるに伴い更新できるよう,ここに保守される。 これらの API の完全な定義は、 引き続き必要とされる — そのような作業は、 課題 #67にて追跡され,そこに貢献できる/され得る。 [DOM-Level-3-XPath] [XPath] [WEBIDL] DOM Level 3 XPath defined an API for evaluating XPath 1.0 expressions. These APIs are widely implemented, but have not been maintained. The interface definitions are maintained here so that they can be updated when Web IDL changes. Complete definitions of these APIs remain necessary and such work is tracked and can be contributed to in whatwg/dom#67. [DOM-Level-3-XPath] [XPath] [WEBIDL]
8.1. XPathResult
インタフェース
[Exposed=Window]
interface XPathResult {
const unsigned short ANY_TYPE = 0;
const unsigned short NUMBER_TYPE = 1;
const unsigned short STRING_TYPE = 2;
const unsigned short BOOLEAN_TYPE = 3;
const unsigned short UNORDERED_NODE_ITERATOR_TYPE = 4;
const unsigned short ORDERED_NODE_ITERATOR_TYPE = 5;
const unsigned short UNORDERED_NODE_SNAPSHOT_TYPE = 6;
const unsigned short ORDERED_NODE_SNAPSHOT_TYPE = 7;
const unsigned short ANY_UNORDERED_NODE_TYPE = 8;
const unsigned short FIRST_ORDERED_NODE_TYPE = 9;
readonly attribute unsigned short resultType;
readonly attribute unrestricted double numberValue;
readonly attribute DOMString stringValue;
readonly attribute boolean booleanValue;
readonly attribute Node? singleNodeValue;
readonly attribute boolean invalidIteratorState;
readonly attribute unsigned long snapshotLength;
Node? iterateNext();
Node? snapshotItem(unsigned long index);
};
8.2. XPathExpression
インタフェース
[Exposed=Window]
interface XPathExpression {
// XPathResult.ANY_TYPE = 0
XPathResult evaluate(Node contextNode, optional unsigned short type = 0, optional XPathResult? result = null);
};
8.3. XPathEvaluatorBase
mixin
callback interface XPathNSResolver {
DOMString? lookupNamespaceURI(DOMString? prefix);
};
interface mixin XPathEvaluatorBase {
[NewObject] XPathExpression createExpression(DOMString expression, optional XPathNSResolver? resolver = null);
Node createNSResolver(Node nodeResolver); // 旧来
// XPathResult.ANY_TYPE = 0
XPathResult evaluate(DOMString expression, Node contextNode, optional XPathNSResolver? resolver = null, optional unsigned short type = 0, optional XPathResult? result = null);
};
Document includes XPathEvaluatorBase;
createNSResolver(nodeResolver)
メソッド手続きは
:RETURN nodeResolver
The createNSResolver(nodeResolver) method steps are to return nodeResolver.
注記: このメソッドは、 歴史的な理由に限り,存在する。 This method exists only for historical reasons.
8.4. XPathEvaluator
インタフェース
[Exposed=Window]
interface XPathEvaluator {
constructor();
};
XPathEvaluator includes XPathEvaluatorBase;
注記:
歴史的な理由から、
XPathEvaluator
を構築することも,
Document
上で同じメソッドにアクセスすることもできる。
For historical reasons you can both construct XPathEvaluator and access the same methods on Document.
9. XSLT
XSLT ( XSL Transformations )は、 XML 文書を他の XML 文書へ形式変換するための言語である。 この節にて定義される API は,広く実装されており、 Web IDL が変更されたとき更新できるよう,ここに保守される。 これらの API の完全な定義は、 引き続き必要とされる — そのような作業は 課題 #181 にて追跡され,そこに貢献できる/され得る。 [XSLT] XSL Transformations (XSLT) is a language for transforming XML documents into other XML documents. The APIs defined in this section have been widely implemented, and are maintained here so that they can be updated when Web IDL changes. Complete definitions of these APIs remain necessary and such work is tracked and can be contributed to in whatwg/dom#181. [XSLT]
9.1. XSLTProcessor
インタフェース
[Exposed=Window]
interface XSLTProcessor {
constructor();
undefined importStylesheet(Node style);
[CEReactions] DocumentFragment transformToFragment(Node source, Document output);
[CEReactions] Document transformToDocument(Node source);
undefined setParameter([LegacyNullToEmptyString] DOMString namespaceURI, DOMString localName, any value);
any getParameter([LegacyNullToEmptyString] DOMString namespaceURI, DOMString localName);
undefined removeParameter([LegacyNullToEmptyString] DOMString namespaceURI, DOMString localName);
undefined clearParameters();
undefined reset();
};
10. セキュリティ/プライバシーの考慮点
この標準には、 既知な[ セキュリティ/プライバシー ]の考慮点は無い。 There are no known security or privacy considerations for this standard.
11. 歴史的なもの
この標準が包含していた,いくつかの[ インタフェース/インタフェースメンバ ]は、 除去された。 This standard used to contain several interfaces and interface members that have been removed.
次に挙げるインタフェースは、 除去された: These interfaces have been removed:
DOMConfiguration
DOMError
DOMErrorHandler
DOMImplementationList
DOMImplementationSource
DOMLocator
DOMObject
DOMUserData
Entity
EntityReference
MutationEvent
MutationNameEvent
NameList
Notation
RangeException
TypeInfo
UserDataHandler
次に挙げるインタフェースメンバは、 除去された: And these interface members have been removed:
Attr
schemaTypeInfo
isId
Document
createEntityReference()
xmlEncoding
xmlStandalone
xmlVersion
strictErrorChecking
domConfig
normalizeDocument()
renameNode()
DocumentType
entities
notations
internalSubset
DOMImplementation
getFeature()
Element
schemaTypeInfo
setIdAttribute()
setIdAttributeNS()
setIdAttributeNode()
Node
isSupported
getFeature()
getUserData()
setUserData()
NodeIterator
expandEntityReferences
Text
isElementContentWhitespace
replaceWholeText()
TreeWalker
expandEntityReferences
謝辞
年月に渡り、 DOM を相互運用可能にするために,たくさんの方々が助力され、 この標準の目標へ近付けてきた。 同様に,この標準の今日の姿は、 多くの方々からの助力により作り上げられている。 There have been a lot of people that have helped make DOM more interoperable over the years and thereby furthered the goals of this standard. Likewise many people have helped making this standard what it is today.
With that, many thanks to Adam Klein, Adrian Bateman, Ahmid snuggs, Alex Komoroske, Alex Russell, Alexey Shvayka, Andreas Kling, Andreu Botella, Anthony Ramine, Arkadiusz Michalski, Arnaud Le Hors, Arun Ranganathan, Benjamin Gruenbaum, Björn Höhrmann, Boris Zbarsky, Brandon Payton, Brandon Slade, Brandon Wallace, Brian Kardell, C. Scott Ananian, Cameron McCormack, Chris Dumez, Chris Paris, Chris Rebert, Cyrille Tuzi, Dan Burzo, Daniel Clark, Daniel Glazman, Darien Maillet Valentine, Darin Fisher, David Baron, David Bruant, David Flanagan, David Håsäther, David Hyatt, Deepak Sherveghar, Dethe Elza, Dimitri Glazkov, Domenic Denicola, Dominic Cooney, Dominique Hazaël-Massieux, Don Jordan, Doug Schepers, Edgar Chen, Elisée Maurer, Elliott Sprehn, Emilio Cobos Álvarez, Eric Bidelman, Erik Arvidsson, François Daoust, François Remy, Gary Kacmarcik, Gavin Nicol, Giorgio Liscio, Glen Huang, Glenn Adams, Glenn Maynard, Hajime Morrita, Harald Alvestrand, Hayato Ito, Henri Sivonen, Hongchan Choi, Hunan Rostomyan, Ian Hickson, Igor Bukanov, Jacob Rossi, Jake Archibald, Jake Verbaten, James Graham, James Greene, James M Snell, James Robinson, Jeffrey Yasskin, Jens Lindström, Jeremy Davis, Jesse McCarthy, Jinho Bang, João Eiras, Joe Kesselman, John Atkins, John Dai, Jonas Sicking, Jonathan Kingston, Jonathan Robie, Joris van der Wel, Joshua Bell, J. S. Choi, Jungkee Song, Justin Summerlin, Kagami Sascha Rosylight, 呂康豪 (Kang-Hao Lu), 田村健人 (Kent TAMURA), Kevin J. Sung, Kevin Sweeney, Kirill Topolyan, Koji Ishii, Lachlan Hunt, Lauren Wood, Luca Casonato, Luke Zielinski, Magne Andersson, Majid Valipour, Malte Ubl, Manish Goregaokar, Manish Tripathi, Marcos Caceres, Mark Miller, Martijn van der Ven, Mason Freed, Mats Palmgren, Mounir Lamouri, Michael Stramel, Michael™ Smith, Mike Champion, Mike Taylor, Mike West, Nicolás Peña Moreno, Nidhi Jaju, Ojan Vafai, Oliver Nightingale, Olli Pettay, Ondřej Žára, Peter Sharpe, Philip Jägenstedt, Philippe Le Hégaret, Piers Wombwell, Pierre-Marie Dartus, prosody—Gab Vereable Context(, Rafael Weinstein, Rakina Zata Amni, Richard Bradshaw, Rick Byers, Rick Waldron, Robbert Broersma, Robin Berjon, Roland Steiner, Rune F. Halvorsen, Russell Bicknell, Ruud Steltenpool, Ryosuke Niwa, Sam Dutton, Sam Sneddon, Samuel Giles, Sanket Joshi, Scott Haseley, Sebastian Mayr, Seo Sanghyeon, Sergey G. Grekhov, Shiki Okasaka, Shinya Kawanaka, Simon Pieters, Stef Busking, Steve Byrne, Stig Halvorsen, Tab Atkins, Takashi Sakamoto, Takayoshi Kochi, Theresa O’Connor, Theodore Dubois, timeless, Timo Tijhof, Tobie Langel, Tom Pixley, Travis Leithead, Trevor Rowbotham, triple-underscore, Tristan Fraipont, Veli Şenol, Vidur Apparao, Warren He, Xidorn Quan, Yash Handa, Yehuda Katz, Yoav Weiss, Yoichi Osato, Yoshinori Sano, Yu Han, Yusuke Abe, and Zack Weinberg for being awesome!
This standard is written by Anne van Kesteren (Apple, annevk@annevk.nl) with substantial contributions from Aryeh Gregor (ayg@aryeh.name) and Ms2ger (ms2ger@gmail.com).
知的財産権
Part of the revision history of the integration points related to custom elements can be found in the w3c/webcomponents repository, which is available under the W3C Software and Document License.
Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.
This is the Living Standard. Those interested in the patent-review version should view the Living Standard Review Draft.