1. 基盤
この仕様はInfra Standardに依存しています。[INFRA]
この仕様書で使用されている用語のいくつかは、Encoding、Selectors、Trusted Types、Web IDL、XML、およびNamespaces in XMLで定義されています。 [ENCODING] [SELECTORS4] [TRUSTED-TYPES] [WEBIDL] [XML] [XML-NAMES]
拡張が必要な場合、DOM標準を適宜更新するか、他の仕様で提供される拡張フックに接続する新しい標準を作成できます。 適用可能な仕様。
1.1. ツリー
ツリーは、有限階層構造のツリーです。 ツリー順は、 ツリーの前順・深さ優先の走査です。
ツリーに属する ツリーに属するオブジェクトは、親(nullまたはオブジェクト)を持ち、子(オブジェクトの順序付き集合)を持ちます。オブジェクトAの親がオブジェクトBであれば、AはBの子です。
根は、その親がnullなら自身であり、 そうでなければその親の根です。 ツリーの根は、そのツリーに属するオブジェクトのうち、親がnullのものです。
オブジェクトAは、オブジェクトBの 子孫 であると言い、AがBの子であるか、AがオブジェクトCの子であり、かつCがBの子孫である場合です。
包括的子孫は、オブジェクト自身またはその子孫です。
オブジェクトAは、オブジェクトBの 祖先 であると言い、BがAの子孫である場合のみ成立します。
包括的祖先は、オブジェクト自身またはその祖先です。
オブジェクトAは、オブジェクトBの 兄弟 であると言い、BとAが同じ非nullの親を持つ場合のみ成立します。
包括的兄弟は、オブジェクト自身またはその兄弟です。
オブジェクトAは、オブジェクトBの 前方 であると言い、AとBが同じツリーに属し、 AがBよりツリー順で前にある場合です。
オブジェクトAは、オブジェクトBの 後方 であると言い、AとBが同じツリーに属し、 AがBよりツリー順で後ろにある場合です。
最初の子は、オブジェクトの最初の子であり、 子がいなければnullです。
最後の子は、オブジェクトの最後の子であり、 子がいなければnullです。
前の兄弟は、オブジェクトの最初の前方兄弟であり、前方兄弟がいなければnullです。
次の兄弟は、オブジェクトの最初の後方兄弟であり、後方 兄弟がいなければnullです。
インデックスは、オブジェクトの前方 兄弟の数であり、いなければ0です。
1.2. 順序付き集合
順序付き集合パーサーは、文字列inputを受け取り、次の手順を実行します:
-
inputTokensをASCII空白で分割した結果とする。
-
tokensを新しい順序付き集合とする。
-
各inputTokensのtokenについて: tokenをtokensに追加する。
- tokensを返す。
順序付き集合シリアライザは、 setを受け取り、U+0020 SPACEで連結した結果を返します。
1.3. セレクター
セレクター文字列のスコープマッチを、文字列 selectors と ノード node に対して行うには:
-
selector を、セレクターを構文解析する selectors の結果とする。 [SELECTORS4]
-
もし selector が失敗であれば、スローする "
SyntaxError"DOMExceptionを。 -
selector と node のルートを使い、セレクターをツリーに対してマッチさせるを、スコーピングルート node で実行した結果を返す。[SELECTORS4]。
セレクター内での名前空間のサポートは予定されておらず、追加されません。
1.4. 名前の検証
文字列 name が 有効な要素ローカル名であるのは、次の手順が true を返す場合である:
-
もし name の長さが0であれば、false を返す。
-
もし name の0番目のコードポイントがASCIIアルファベットであれば:
-
もし name がASCII空白、U+0000 NULL、U+002F (/)、U+003E (>) を含む場合、false を返す。
-
true を返す。
-
-
もし name の0番目のコードポイントが U+003A (:)、U+005F (_) でなく、かつ U+0080 から U+10FFFF の範囲に含まれない場合、false を返す。
-
もし name のそれ以降のコードポイント(もしあれば)がASCIIアルファベット、ASCII数字、 U+002D (-)、U+002E (.)、U+003A (:)、U+005F (_) または U+0080 から U+10FFFF の範囲に含まれない場合、false を返す。
-
true を返す。
この概念は、DOM APIで生成される要素のローカル名の検証に使われます。HTMLパーサーで生成可能な名前を許容するのが意図であり(最初の符号位置がASCII英字の場合)、加えて歴史的な理由でASCII範囲では制限されているが、ASCII以外は何でも許容されます。
以下のJavaScript互換の正規表現は、 有効な要素ローカル名の実装例です:
/^(?:[A-Za-z][^\0\t\n\f\r\u0020/>]*|[:_\u0080-\u{10FFFF}][A-Za-z0-9-.:_\u0080-\u{10FFFF}]*)$/u
文字列は、 有効なDOCTYPE名であり、 ASCII空白、U+0000 NULL、U+003E (>) を含まない場合です。
空文字列も有効なDOCTYPE名です。
バリデートと抽出 namespaceとqualifiedNameを、contextを元に行うには:
-
namespaceが空文字列なら、nullに設定する。
-
prefixをnullにする。
-
localNameをqualifiedNameにする。
-
qualifiedNameがU+003A (:) を含む場合:
-
splitResultをqualifiedNameをU+003A (:)で厳密分割した結果とする。
-
prefixにsplitResult[0]を設定する。
-
localNameにsplitResult[1]を設定する。
-
prefixが有効な名前空間プレフィックスでなければ、 throwし、 "
InvalidCharacterError"DOMExceptionを投げる。
-
-
Assert: prefixはnullまたは有効な名前空間プレフィックスであること。
-
contextが"
attribute"で、localNameが有効な属性ローカル名でないなら、 throwし、"InvalidCharacterError"DOMExceptionを投げる。 -
contextが"
element"で、localNameが有効な要素ローカル名でないなら、 throwし、"InvalidCharacterError"DOMExceptionを投げる。 -
prefixがnullでなく、namespaceがnullなら、 throwし、 "
NamespaceError"DOMExceptionを投げる。 -
prefixが"
xml"で、namespaceがXML名前空間でないなら、 throwし、 "NamespaceError"DOMExceptionを投げる。 -
いずれかqualifiedNameまたはprefixが"
xmlns"で、 namespaceがXMLNS名前空間でないなら、 throwし、 "NamespaceError"DOMExceptionを投げる。 -
namespaceがXMLNS名前空間で、 qualifiedNameまたはprefixが"
xmlns"でないなら、 throwし、 "NamespaceError"DOMExceptionを投げる。 -
(namespace, prefix, localName) を返す。
この仕様の各APIは、名前空間プレフィックス、属性ローカル名、要素ローカル名、DOCTYPE名をより厳密に検証していました。これは様々なXML関連仕様に合わせたものでした(ただし全ての仕様のルールが適用されたわけではありません)。
しかし、HTMLパーサーで生成可能な名前がDOM APIでは生成できないことがあり、Web開発者にとって煩わしいことが判明したため、検証は上記のように緩和されました。
2. イベント
2.1. 「DOMイベント」の紹介
ウェブプラットフォーム全体で、イベントは、ネットワーク活動やユーザー操作などの発生を通知するためにオブジェクトに発行されます。これらのオブジェクトは
EventTarget
インターフェースを実装しているため、addEventListener()
を呼び出すことでイベントリスナーを追加し、イベントを監視できます。
obj. addEventListener( "load" , imgFetched) function imgFetched( ev) { // great success …}
イベントリスナーは、
removeEventListener()
メソッドを使って同じ引数を渡すことで削除できます。
また、AbortSignal
を
addEventListener()
に渡し、そのシグナルを管理するコントローラーでabort()
を呼ぶことでイベントリスナーを削除することもできます。
イベントもオブジェクトであり、
Eventインターフェース(または派生インターフェース)を実装します。上の例では
evがイベントです。
evは
イベントリスナーのコールバック
(通常はJavaScriptの関数)に引数として渡されます。
イベントリスナーは、
イベントの
type
属性値(上の例では"load")をキーにします。
イベントの
target
属性値は
イベントが発行されたオブジェクト(上記ではobj)を返します。
通常イベントはユーザーエージェントによってユーザー操作やタスク完了の結果として発行されますが、アプリケーションから合成イベント(シンセティックイベント)として イベントを自分で発行することもできます:
// 適切なイベントリスナーを追加 obj. addEventListener( "cat" , function ( e) { process( e. detail) }) // イベントを作成して発行 var event= new CustomEvent( "cat" , { "detail" : { "hazcheeseburger" : true }}) obj. dispatchEvent( event)
シグナリング以外にも、イベントは、
操作の次の処理をアプリケーション側で制御できるように使われることがあります。例えば、フォーム送信の一部として、
type属性値が
"submit" であるイベントが
発行されます。
このイベントの
preventDefault()
メソッドが呼び出されると、フォーム送信は中止されます。この機能をイベント(アプリケーションで発行される、合成イベント)を通じて利用したい場合は、
dispatchEvent()
メソッドの返り値を利用できます。
if ( obj. dispatchEvent( event)) { // イベントはキャンセルされなかったので、何か魔法を実行 …}
イベントがツリーに属するオブジェクト(例:要素)に発行された場合、
そのオブジェクトの祖先の
イベントリスナーにも到達することがあります。実際には、全ての包括的祖先の
イベントリスナーのうち、captureがtrueのものが
ツリー順で呼ばれます。そして、イベントのbubbles
がtrueなら、今度は包括的祖先のイベントリスナーのうちcaptureがfalseのものが逆順で呼ばれます。
イベントがツリーでどのように動作するか、例を見てみましょう:
<!doctype html> < html > < head > < title > Boring example</ title > </ head > < body > < p > Hello< span id = x > world</ span > !</ p > < script > function test( e) { debug( e. target, e. currentTarget, e. eventPhase) } document. addEventListener( "hey" , test, { capture: true }) document. body. addEventListener( "hey" , test) var ev= new Event( "hey" , { bubbles: true }) document. getElementById( "x" ). dispatchEvent( ev) </ script > </ body > </ html >
debug関数は2回呼ばれます。どちらの時もイベントの
target
属性値はspan 要素です。最初は
currentTarget
属性値がdocument、2回目はbody 要素となります。
eventPhase
属性値は
CAPTURING_PHASE
からBUBBLING_PHASEに切り替わります。
span 要素にイベントリスナーが登録されていた場合、eventPhase
属性値は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 ; // legacyreadonly 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 ; // legacy alias of .stopPropagation()undefined stopImmediatePropagation ();readonly attribute boolean bubbles ;readonly attribute boolean cancelable ;attribute boolean returnValue ; // legacyundefined 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 ); // legacy };dictionary {EventInit boolean =bubbles false ;boolean =cancelable false ;boolean =composed false ; };
Event オブジェクトは、単に イベント
と呼ばれます。これは、何かが発生したこと(例:画像のダウンロードが完了したこと)を通知できます。
潜在的なイベントターゲットは、null または EventTarget
オブジェクトです。
イベントには、target(潜在的なイベントターゲット)が関連付けられています。特に記載がない限り、これは null です。
イベントには、relatedTarget(潜在的なイベントターゲット)が関連付けられています。特に記載がない限り、これは null です。
他の仕様では relatedTarget を使って relatedTarget 属性を定義します。[UIEVENTS]
イベントには、touch target list(リスト。0個以上の潜在的なイベントターゲット)が関連付けられています。特に記載がない限り、空リストです。
touch target listは、TouchEventインターフェースおよび関連インターフェースの定義専用です。[TOUCH-EVENTS]
イベントには、pathが関連付けられています。pathは、リストで、各構造体には、
invocation target(EventTarget
オブジェクト)、
invocation-target-in-shadow-tree(真偽値)、
shadow-adjusted target(潜在的なイベントターゲット)、
relatedTarget(潜在的なイベントターゲット)、
touch target list(リスト。潜在的なイベントターゲット)、
root-of-closed-tree(真偽値)、
slot-in-closed-tree(真偽値)が含まれます。
pathは最初は空リストです。
event = new Event(type [, eventInitDict])- 新しい event を返します。
type属性値が type になります。eventInitDict 引数により、bubblesおよびcancelable属性を同名のオブジェクトメンバーで設定できます。 event .type- event のタイプ(例: "
click"、"hashchange"、"submit")を返します。 event .target- event が 発行されたオブジェクト(target)を返します。
event .currentTarget- 現在コールバックが実行されているイベントリスナーのオブジェクトを返します。
event .composedPath()- event の invocation target
オブジェクト(リスナーが呼ばれるオブジェクト)のリストを返します。ただし、event の
currentTargetから到達できないclosedモードの shadow root を持つ shadow tree 内のノードは除外されます。 event .eventPhase- event のフェーズを返します。値は
NONE、CAPTURING_PHASE、AT_TARGET、BUBBLING_PHASEのいずれかです。 event . stopPropagation()- ツリー内で 発行された場合、このメソッドを呼ぶと event が現在のオブジェクト以外に到達しなくなります。
event . stopImmediatePropagation()- このメソッドを呼ぶと、現在のリスナー以降の登録済みイベントリスナーには到達せず、ツリー内で 発行された場合、他のオブジェクトにも到達しなくなります。
event .bubbles- event の初期化方法によって true または false を返します。true の場合、event は target の祖先を逆ツリー順で辿ります。false の場合は辿りません。
event .cancelable- event の初期化方法によって true または false を返します。true の場合、event の 発行元の処理を
preventDefault()メソッドでキャンセルできます。 event . preventDefault()cancelable属性値が true で、かつ event のリスナーのpassiveが false の場合、このメソッドを呼ぶと発行元の処理をキャンセルするよう指示します。event .defaultPreventedpreventDefault()が正常に呼ばれキャンセル指示された場合は true、それ以外は false を返します。event .composed- event の初期化方法によって true または false を返します。true の場合、event は root である
ShadowRootノードを越えてリスナーを呼びます。false の場合は越えません。 event .isTrusted- event がユーザーエージェントによって 発行された場合は true、それ以外は false を返します。
event .timeStamp- event の発生時刻(ミリ秒単位)を返します。
type属性は初期化された値を返さなければなりません。イベントが作成されたとき、この属性は空文字列で初期化されなければなりません。
targetゲッターの手順は、thisのtargetを返すことです。
srcElementゲッターの手順は、thisのtargetを返すことです。
currentTarget属性は初期化された値を返さなければなりません。イベントが作成されたとき、この属性はnullで初期化されなければなりません。
composedPath()メソッドの手順は以下の通りです:
-
composedPathを空のリストとする。
-
pathが空なら、composedPathを返す。
-
currentTargetをthisの
currentTarget属性値とする。 -
Assert:currentTargetは
EventTargetオブジェクトであること。 -
Append:currentTargetをcomposedPathに追加する。
-
currentTargetIndexを0とする。
-
currentTargetHiddenSubtreeLevelを0とする。
-
indexをpathのサイズ−1とする。
-
indexが0以上の間、繰り返す:
-
path[index]のroot-of-closed-treeがtrueなら、 currentTargetHiddenSubtreeLevelを1増やす。
-
path[index]のinvocation targetがcurrentTargetなら、 currentTargetIndexをindexに設定し、 breakする。
-
path[index]のslot-in-closed-treeがtrueなら、 currentTargetHiddenSubtreeLevelを1減らす。
-
indexを1減らす。
-
-
currentHiddenLevelとmaxHiddenLevelをcurrentTargetHiddenSubtreeLevelとする。
-
indexをcurrentTargetIndex−1に設定する。
-
indexが0以上の間、繰り返す:
-
path[index]のroot-of-closed-treeがtrueなら、 currentHiddenLevelを1増やす。
-
currentHiddenLevelがmaxHiddenLevel以下なら、 prepend:path[index]のinvocation targetをcomposedPathの先頭に追加する。
-
path[index]のslot-in-closed-treeがtrueなら:
-
currentHiddenLevelを1減らす。
-
currentHiddenLevelがmaxHiddenLevel未満なら、 maxHiddenLevelをcurrentHiddenLevelに設定する。
-
-
indexを1減らす。
-
-
currentHiddenLevelとmaxHiddenLevelをcurrentTargetHiddenSubtreeLevelに設定する。
-
indexをcurrentTargetIndex+1に設定する。
-
indexがpathのサイズ未満の間、繰り返す:
-
path[index]のslot-in-closed-treeがtrueなら、 currentHiddenLevelを1増やす。
-
currentHiddenLevelがmaxHiddenLevel以下なら、 append:path[index]のinvocation targetをcomposedPathに追加する。
-
path[index]のroot-of-closed-treeがtrueなら:
-
currentHiddenLevelを1減らす。
-
currentHiddenLevelがmaxHiddenLevel未満なら、 maxHiddenLevelをcurrentHiddenLevelに設定する。
-
-
indexを1増やす。
-
-
composedPathを返す。
eventPhase属性は初期化された値を返さなければなりません。値は以下のいずれかです:
NONE(数値値 0)- 現在イベントが発行されていない場合はこのフェーズです。
CAPTURING_PHASE(数値値 1)- イベントが発行され、ツリーに属するオブジェクトの場合、targetに到達する前はこのフェーズになります。
AT_TARGET(数値値 2)- イベントが発行されたとき、target上ではこのフェーズになります。
BUBBLING_PHASE(数値値 3)- イベントが発行され、ツリーに属するオブジェクトの場合、targetに到達した後はこのフェーズになります。
初期状態では、この属性はNONEで初期化されなければなりません。
各イベントには、以下の関連フラグがあり、全て初期状態では未設定です:
- stop propagation flag
- stop immediate propagation flag
- canceled flag
- in passive listener flag
- composed flag
- initialized flag
- dispatch flag
stopPropagation()メソッドの手順は、thisのstop propagation flagを設定することです。
cancelBubbleゲッターの手順は、thisのstop propagation
flagが設定されていればtrue、そうでなければfalseを返すことです。
cancelBubbleセッターの手順は、指定された値がtrueならthisのstop propagation
flagを設定し、そうでなければ何もしないことです。
stopImmediatePropagation()メソッドの手順は、thisのstop propagation
flagとthisのstop immediate propagation flagを設定することです。
bubblesと
cancelable属性は、それぞれ初期化された値を返さなければなりません。
canceled
flagを設定するには、event
eventが、cancelable属性値がtrueであり、かつeventのin passive
listener flagが未設定なら、eventのcanceled flagを設定し、そうでなければ何もしないことです。
returnValueゲッターの手順は、thisのcanceled flagが設定されていればfalse、そうでなければtrueを返すことです。
returnValueセッターの手順は、指定された値がfalseならcanceled
flagを設定する(thisに対して)、そうでなければ何もしないことです。
preventDefault()メソッドの手順は、canceled flagを設定する(thisに対して)。
preventDefault()を呼んでも効果がない場合があります。ユーザーエージェントは、開発者コンソールで正確な理由を記録し、デバッグを支援することが推奨されます。
defaultPreventedゲッターの手順は、thisのcanceled flagが設定されていればtrue、そうでなければfalseを返すことです。
composedゲッターの手順は、thisのcomposed flagが設定されていればtrue、そうでなければfalseを返すことです。
isTrusted属性は初期化された値を返さなければなりません。イベントが作成されたとき、この属性はfalseで初期化されなければなりません。
isTrustedは、イベントがユーザーエージェントによって発行されたか(dispatchEvent()によるものではないか)を示す便宜的なものです。唯一のレガシー例外はclick()で、これによりユーザーエージェントがisTrusted属性がfalseで初期化されたイベントを発行します。
timeStamp属性は初期化された値を返さなければなりません。
initializeするには、event・type・bubbles・cancelableを使って以下の手順を実行します:
-
eventのinitialized flagを設定する。
-
eventのstop propagation flag、stop immediate propagation flag、canceled flagを未設定にする。
-
eventの
isTrusted属性をfalseに設定する。 -
eventのtargetをnullに設定する。
-
eventの
type属性をtypeに設定する。 -
eventの
bubbles属性をbubblesに設定する。 -
eventの
cancelable属性をcancelableに設定する。
initEvent(type, bubbles, cancelable)
メソッドの手順は以下の通りです:
-
thisのdispatch flagが設定されていれば、returnする。
-
initialize:thisにtype・bubbles・cancelableで初期化する。
initEvent()はイベントのコンストラクタと重複しており、composedを設定できません。レガシーコンテンツのためにサポートが必要です。
2.3.
Window
インターフェースへのレガシー拡張
partial interface Window { [Replaceable ]readonly attribute (Event or undefined )event ; // legacy };
各Window
オブジェクトは、current event(現在のイベント)(undefinedまたはEventオブジェクト)を持ちます。特に記載がない限りundefinedです。
eventゲッターの手順は、thisの
current
eventを返すことです。
Web開発者は、イベントリスナーに渡されるEventオブジェクトを使うことが強く推奨されます。その方が移植性の高いコードになります。この属性はworkersやworkletsでは利用できず、shadow
tree内で発行されるイベントには正確ではありません。
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 ); // legacy };dictionary :CustomEventInit EventInit {any =detail null ; };
イベントは
CustomEventインターフェースを使うことで、カスタムデータを持たせることができます。
event = new CustomEvent(type [, eventInitDict])Eventのコンストラクタと同様ですが、eventInitDict引数でdetail属性も設定できます。event .detail- event作成時に指定した任意のカスタムデータを返します。主に合成イベントで使用されます。
detail属性は初期化された値を返さなければなりません。
initCustomEvent(type, bubbles, cancelable, detail)
メソッドの手順は以下の通りです:
-
thisのdispatch flagが設定されていれば、returnする。
-
initialize:thisをtype、bubbles、cancelableで初期化する。
2.5. イベントの構築
仕様は、すべてまたは一部のイベントのためのイベント構築手順を定義できます。アルゴリズムには、イベントeventとEventIniteventInitDictが、内部イベント生成手順で示された通り渡されます。
この構造は、初期化辞書のメンバーとIDL属性が単純な1:1対応ではない、より複雑な構造を持つEventのサブクラスで利用できます。
Eventインターフェース、またはEventインターフェースを継承したインターフェースのconstructorが呼び出された時、typeとeventInitDictを引数として、次の手順を実行します:
-
eventを、thisインターフェース・null・現在時刻・eventInitDictで内部イベント生成手順を実行した結果とする。
-
eventの
type属性をtypeで初期化する。 -
eventを返す。
イベントを生成するには、eventInterface(必ずEventまたはそれを継承したインターフェース)、任意でrealmrealmを受け取り、以下の手順を実行します:
-
realmが与えられていなければnullに設定する。
-
dictionaryを、JavaScriptの値undefinedをeventInterfaceのコンストラクタが受け付ける辞書型に変換した結果とする。(この辞書型は
EventInitか、それを継承した辞書型です。)メンバーが必須の場合は機能しません。whatwg/dom#600参照。
-
eventを、eventInterface・realm・イベントが通知する発生時刻・dictionaryで内部イベント生成手順を実行した結果とする。
-
eventの
isTrusted属性をtrueで初期化する。 -
eventを返す。
イベントの生成は、他の仕様が単に発火するのではなく、イベントを個別に生成して発行する必要がある場面で利用します。これによりイベント属性が正しい初期値になることを保証します。
内部イベント生成手順は、eventInterface・realm・time・dictionaryを受け、以下の通りです:
-
eventをeventInterfaceを使って新しいオブジェクトとして生成する。realmがnullでなければそれを使い、そうでなければWeb IDLのデフォルト動作を使う。
Web IDLは現時点でデフォルト動作を定義していません。whatwg/webidl#135参照。
-
eventのinitialized flagを設定する。
-
eventの
timeStamp属性を、相対高精度粗時間(time・eventの関連グローバルオブジェクトを使う)で初期化する。 -
各dictionaryのmember→valueで: eventがmemberという識別子を持つ属性を持つなら、その属性をvalueで初期化する。
-
イベント構築手順をeventとdictionaryで実行する。
-
eventを返す。
2.6. イベントインターフェースの定義
一般的に、Eventを継承した新しいインターフェースを定義する際は、必ずWHATWGまたはW3C WebApps
WGコミュニティに意見を求めてください。
CustomEvent
インターフェースを出発点として使用できます。
ただし、init*Event()メソッドはコンストラクタと冗長であるため導入しないでください。Event
インターフェースを継承するインターフェースでそのようなメソッドが存在するのは、歴史的な理由によるものだけです。
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
オブジェクトは、イベントが発行されるターゲットを表します。
各EventTarget
オブジェクトには、関連付けられたイベントリスナーリスト(ゼロ個以上のイベントリスナーのリスト)があります。初期状態では空のリストです。
イベントリスナー は、特定のイベントを監視するために使用され、次の要素から構成されます:
- type(文字列)
- callback(null または
EventListenerオブジェクト) - capture(ブール値、初期状態はfalse)
- passive(null またはブール値、初期状態はnull)
- once(ブール値、初期状態はfalse)
- signal(null または
AbortSignalオブジェクト) - removed(管理目的のブール値、初期状態はfalse)
callbackはEventListener
オブジェクトですが、イベントリスナーは、上記のようにより広い概念です。
各EventTarget
オブジェクトには、関連付けられたget the
parentアルゴリズムがあり、イベントeventを受け取り、EventTarget
オブジェクトを返します。特に記載がない限り、nullを返します。
ノード、 シャドウルート、および ドキュメントは、get the parentアルゴリズムをオーバーライドしています。
各EventTarget
オブジェクトは、関連付けられたactivation behaviorアルゴリズムを持つことができます。この
activation behaviorアルゴリズムは、イベントを引数として受け取り、dispatchアルゴリズムで示されています。
これは、特定のEventTarget
オブジェクトに対してユーザーエージェントが特定のアクションを実行するために存在します。例えば、
area
要素では、合成されたMouseEvent
イベント(type
属性がclickであるもの)に応答します。ウェブ互換性のためこれを削除することはできず、現在では何かをアクティブ化する方法として定義されています。[HTML]
関連付けられたactivation behaviorを持つ各EventTarget
オブジェクトは、さらに(どちらか一方ではなく)legacy-pre-activation behaviorアルゴリズムと、
legacy-canceled-activation behavior
アルゴリズムを持つことができます。
これらのアルゴリズムは、チェックボックスおよびラジオの
input
要素に対してのみ存在し、それ以外の用途では使用しないでください。[HTML]
target = new EventTarget();-
新しい
EventTargetオブジェクトを作成します。これは、開発者がイベントを発行したり、イベントを監視するために使用できます。 target . addEventListener(type, callback [, options])-
イベントの
type属性値がtypeである場合に対応するイベントリスナーを追加します。callback引数は、イベントが発行されたときに呼び出されるコールバックを設定します。options引数はリスナー固有のオプションを設定します。互換性のため、これはブール値である場合もあり、その場合、このメソッドは値がoptionsの
captureとして指定されたかのように動作します。optionsの
captureがtrueに設定されている場合、イベントのeventPhase属性値がBUBBLING_PHASEのときにコールバックが呼び出されるのを防ぎます。false(または指定されていない場合)では、イベントのeventPhase属性値がCAPTURING_PHASEのときに呼び出されません。いずれの場合も、イベントのeventPhase属性値がAT_TARGETの場合はコールバックが呼び出されます。optionsの
passiveがtrueに設定されている場合、コールバックがpreventDefault()を呼び出してイベントをキャンセルしないことを示します。これは、§ 2.8 Observing event listenersで説明されるパフォーマンス最適化を有効にするために使用されます。optionsの
onceがtrueに設定されている場合、コールバックは一度だけ呼び出され、その後イベントリスナーが削除されます。もしoptionsの
signalとしてAbortSignalが渡された場合、シグナルが中止されたときにイベントリスナーが削除されます。イベントリスナーはtargetのイベントリスナーリストに追加されますが、同じtype、callback、およびcaptureを持つリスナーがすでに存在する場合は追加されません。
target . removeEventListener(type, callback [, options])-
targetのイベントリスナーリストにある、同じtype、callback、および optionsを持つイベントリスナーを削除します。
target . dispatchEvent(event)-
targetに対して合成されたeventを発行し、eventの
cancelable属性値がfalseであるか、preventDefault()メソッドが呼び出されていない場合はtrueを返します。それ以外の場合はfalseを返します。
flattenでoptionsを処理するには、次の手順を実行します:
-
optionsがブール値の場合、optionsを返す。
-
options["
capture"]を返す。
flatten moreでoptionsを処理するには、次の手順を実行します:
new EventTarget()
コンストラクタ手順は何も行いません。
他の箇所で規定されたデフォルトのため、返されるEventTargetの
get the
parentアルゴリズムはnullを返し、
activation behavior、
legacy-pre-activation behavior、
またはlegacy-canceled-activation
behaviorを持ちません。
将来的にはカスタムget the parentアルゴリズムを許可する可能性があります。これがプログラムで有用である場合はお知らせください。
現時点では、作成されたすべてのEventTargetは
ツリー構造に参加しません。
デフォルトのパッシブ値は、イベントタイプtypeとEventTarget
eventTargetを受け取り、以下のように決定されます:
イベントリスナーを追加するには、EventTarget
オブジェクトeventTargetとイベントリスナーlistenerを受け取り、以下の手順を実行します:
-
eventTargetが
ServiceWorkerGlobalScopeオブジェクトであり、そのサービスワーカーのスクリプトリソースの評価済みフラグが設定されており、listenerのtypeが、いずれかのサービスワーカーイベントのtype属性値に一致する場合、この結果が予期したものと異なる可能性があるとコンソールに警告を報告します。[SERVICE-WORKERS] -
listenerのcallbackがnullである場合、終了する。
-
listenerのpassiveがnullである場合、listenerのtypeとeventTargetを用いてデフォルトのパッシブ値に設定する。
-
eventTargetのイベントリスナーリストに、含まれていない場合、そのtypeがlistenerのtypeであり、callbackがlistenerのcallbackであり、captureがlistenerのcaptureであるイベントリスナーがある場合、追加する。
-
listenerのsignalがnullでない場合、次の中止手順を追加する:
- イベントリスナーを削除する、対象はeventTargetとlistener。
イベントリスナーを追加するの概念は、イベントハンドラーが同じコードパスを使用することを保証するために存在します。[HTML]
addEventListener(type, callback, options)
メソッドの手順は以下の通りです:
-
capture、passive、once、およびsignalを、flattening more optionsの結果に設定する。
-
イベントリスナーを追加する、対象はthisとイベントリスナーであり、そのtypeがtype、callbackがcallback、captureがcapture、passiveがpassive、onceがonce、およびsignalがsignalである。
イベントリスナーを削除するには、EventTarget
オブジェクトeventTargetとイベントリスナーlistenerを受け取り、以下の手順を実行します:
-
eventTargetが
ServiceWorkerGlobalScopeオブジェクトであり、そのサービスワーカーの処理するイベントタイプのセットがlistenerのtypeを含む場合、コンソールに警告を報告する。[SERVICE-WORKERS] -
listenerのremovedをtrueに設定し、eventTargetのイベントリスナーリストから削除する。
HTMLではこれを使用してイベントハンドラーを定義します。[HTML]
すべてのイベントリスナーを削除するには、EventTarget
オブジェクトeventTargetを受け取り: 各eventTargetのイベントリスナーリストのlistenerに対して: イベントリスナーを削除するを実行する。
HTMLではこれを使用してdocument.open()を定義します。[HTML]
removeEventListener(type, callback, options)
メソッドの手順は以下の通りです:
-
captureを、flattening optionsの結果に設定する。
-
thisのイベントリスナーリストに、含まれる、typeがtypeであり、callbackがcallbackであり、captureがcaptureであるイベントリスナーがある場合、イベントリスナーを削除する、対象はthisとそのイベントリスナー。
イベントリスナーリストには、同じtype、callback、およびcaptureを持つ複数のイベントリスナーが含まれないため、イベントリスナーを追加するがこれを防ぎます。
dispatchEvent(event)
メソッドの手順は以下の通りです:
-
eventのdispatch flagが設定されている場合、またはそのinitialized flagが設定されていない場合、例外を投げる "
InvalidStateError"DOMException。 -
eventの
isTrusted属性をfalseに初期化する。 -
dispatchingをeventとthisを用いて実行した結果を返す。
2.8. イベントリスナーの観察
一般的に、開発者はイベントリスナーの存在が観察可能であることを期待していません。 イベントリスナーの影響は、そのコールバックによって決定されます。つまり、 開発者が何もしないイベントリスナーを追加しても、副作用がないことを期待します。
しかしながら、一部のイベントAPIは効率的に実装するために
イベントリスナーを観察する必要があるように設計されています。これにより、リスナーの存在が観察可能になり、
空のリスナーであってもアプリケーションの動作やパフォーマンスに大きな影響を与える可能性があります。
例えば、非同期スクロールをブロックするために使用されるタッチイベントやホイールイベントのような場合です。
この問題は、少なくとも1つの非passiveリスナーが存在する場合にのみ
イベントをcancelableとして指定することで、軽減されることがあります。
例えば、非passive
TouchEvent
リスナーはスクロールをブロックする必要がありますが、すべてのリスナーがpassive
である場合、並行してスクロールを開始できるよう、TouchEvent
をキャンセル不可(preventDefault()
の呼び出しを無視する)にすることができます。そのため、イベントを発行するコードは非passiveリスナーの有無を観察し、
発行されるイベントのcancelableプロパティをクリアすることができます。
理想的には、新しいイベントAPIはこの特性を必要としないように定義されるべきです。(議論についてはwhatwg/domを使用してください。)
レガシーなサービスワーカーのfetchイベントリスナーコールバックを取得するには、
ServiceWorkerGlobalScope
globalを受け取り、以下の手順を実行します。これにより、リストとして
EventListener
オブジェクトが返されます。
2.9. イベントのディスパッチ
dispatch を使って event を target に、オプションの legacy target override flag およびオプションの legacyOutputDidListenersThrowFlag とともにディスパッチするには、以下の手順を実行する:
-
event の dispatch flag を設定する。
-
targetOverride を target に設定する。ただし legacy target override flag が指定されていない場合は target の 関連付けられた
Documentに設定する。 [HTML]legacy target override flag は HTML でのみ使用され、target が
Windowオブジェクトの場合のみ使用される。 -
activationTarget を null に設定する。
-
relatedTarget を retargeting により event の relatedTarget を target に対して再ターゲットした結果に設定する。
-
clearTargets を false に設定する。
-
target が relatedTarget でない、または target が event の relatedTarget である場合:
-
touchTargets を新しい リスト に設定する。
-
各 touchTarget を event の touch target list から取り出し: retargeting により touchTarget を target に対して再ターゲットした結果を touchTargets に 追加する。
-
イベントパスに追加 を event, target, targetOverride, relatedTarget, touchTargets, false で実行する。
-
isActivationEvent を true に設定する。ただし event が
MouseEventオブジェクトであり、event のtype属性が "click" の場合のみ。そうでなければ false。 -
isActivationEvent が true かつ target が activation behavior を持つ場合、activationTarget を target に設定する。
-
slottable を target に設定する。ただし target が slottable かつ assigned の場合のみ。そうでなければ null。
-
slot-in-closed-tree を false に設定する。
-
parent を target の get the parent を event で呼び出した結果に設定する。
-
parent が null でない間:
-
slottable が null でない場合:
-
アサート:parent は slot である。
-
slottable を null に設定する。
-
parent の root が shadow root かつ mode が "
closed" の場合、slot-in-closed-tree を true に設定する。
-
-
parent が slottable かつ assigned の場合、slottable を parent に設定する。
-
relatedTarget を retargeting により event の relatedTarget を parent に対して再ターゲットした結果に設定する。
-
touchTargets を新しい リスト に設定する。
-
各 touchTarget を event の touch target list から取り出し: 追加する。retargeting により touchTarget を parent に対して再ターゲットした結果を touchTargets に追加する。
-
parent が
Windowオブジェクト、または parent が node かつ target の root が shadow-including inclusive ancestor である場合:-
isActivationEvent が true、event の
bubbles属性が true、activationTarget が null、かつ parent が activation behavior を持つ場合、activationTarget を parent に設定する。 -
イベントパスに追加 を event, parent, null, relatedTarget, touchTargets, slot-in-closed-tree で実行する。
-
-
それ以外の場合、parent が relatedTarget であれば、parent を null に設定する。
-
それ以外の場合:
-
target を parent に設定する。
-
isActivationEvent が true、activationTarget が null、かつ target が activation behavior を持つ場合、activationTarget を target に設定する。
-
イベントパスに追加 を event, parent, target, relatedTarget, touchTargets, slot-in-closed-tree で実行する。
-
-
parent が null でない場合、parent を parent の get the parent を event で呼び出した結果に設定する。
-
slot-in-closed-tree を false に設定する。
-
-
clearTargetsStruct を event の path のうち、shadow-adjusted target が null でない最後の構造体に設定する。
-
clearTargetsStruct の shadow-adjusted target、clearTargetsStruct の relatedTarget、または clearTargetsStruct の touch target list 内の
EventTargetオブジェクトが node であり、その root が shadow root である場合、clearTargets を true に設定する。 -
activationTarget が null でなく、activationTarget が legacy-pre-activation behavior を持つ場合、activationTarget の legacy-pre-activation behavior を実行する。
-
各 struct を event の path の逆順で取り出す:
-
struct の shadow-adjusted target が null でない場合、event の
eventPhase属性をAT_TARGETに設定する。 -
それ以外の場合、event の
eventPhase属性をCAPTURING_PHASEに設定する。 -
Invoke を struct, event, "
capturing", legacyOutputDidListenersThrowFlag(指定されていれば)で実行する。
-
-
各 struct を event の path から取り出す:
-
struct の shadow-adjusted target が null でない場合、event の
eventPhase属性をAT_TARGETに設定する。 -
それ以外の場合:
-
event の
eventPhase属性をBUBBLING_PHASEに設定する。
-
Invoke を struct, event, "
bubbling", legacyOutputDidListenersThrowFlag(指定されていれば)で実行する。
-
-
-
event の
eventPhase属性をNONEに設定する。 -
event の
currentTarget属性を null に設定する。 -
event の path を空のリストに設定する。
-
event の dispatch flag、stop propagation flag、stop immediate propagation flag を解除する。
-
clearTargets が true の場合:
-
event の target を null に設定する。
-
event の relatedTarget を null に設定する。
-
event の touch target list を空のリストに設定する。
-
-
activationTarget が null でない場合:
-
event の canceled flag が解除されていれば、activationTarget の activation behavior を event で実行する。
-
それ以外の場合、activationTarget が legacy-canceled-activation behavior を持つ場合、activationTarget の legacy-canceled-activation behavior を実行する。
-
-
event の canceled flag が設定されていれば false を返す。そうでなければ true を返す。
イベントパスに追加するには、event、invocationTarget、shadowAdjustedTarget、relatedTarget、touchTargets、および slot-in-closed-tree が与えられたとき、以下の手順を実行する:
-
invocationTargetInShadowTree を false に設定する。
-
もし invocationTarget が ノードであり、その ルートが シャドウルート であるなら、invocationTargetInShadowTree を true に設定する。
-
root-of-closed-tree を false に設定する。
-
もし invocationTarget が シャドウルートであり、その mode が "
closed" であるなら、root-of-closed-tree を true に設定する。 -
Append を使って新しい struct を event の path に追加する。invocation target は invocationTarget、 invocation-target-in-shadow-tree は invocationTargetInShadowTree、 shadow-adjusted target は shadowAdjustedTarget、 relatedTarget は relatedTarget、 touch target list は touchTargets、 root-of-closed-tree は root-of-closed-tree、 slot-in-closed-tree は slot-in-closed-tree。
invokeするには、struct、event、phase、およびオプションの legacyOutputDidListenersThrowFlag が与えられたとき、以下の手順を実行する:
-
event の target を event の shadow-adjusted target(structまたはそれ以前のstructのうち、shadow-adjusted target が null でない最後のもの)に設定する。
-
event の relatedTarget を struct の relatedTarget に設定する。
-
event の touch target list を struct の touch target list に設定する。
-
event の stop propagation flag が設定されていれば、return する。
-
event の
currentTarget属性を struct の invocation target に初期化する。 -
listeners を clone した event の
currentTarget属性値の event listener list に設定する。これは、この時点以降に追加された event listener が実行されないようにするためである。削除は removed フィールドにより影響を受けることに注意。
-
invocationTargetInShadowTree を struct の invocation-target-in-shadow-tree に設定する。
-
found を inner invoke を event、listeners、phase、invocationTargetInShadowTree、および legacyOutputDidListenersThrowFlag(指定されていれば)で実行した結果に設定する。
-
found が false かつ event の
isTrusted属性が true の場合:-
originalEventType を event の
type属性値に設定する。 -
event の
type属性値が下記の表の第1列のいずれかの文字列と一致する場合、event のtype属性値を同じ行の第2列の文字列に設定し、そうでなければ return する。イベントタイプ レガシーイベントタイプ " animationend"" webkitAnimationEnd"" animationiteration"" webkitAnimationIteration"" animationstart"" webkitAnimationStart"" transitionend"" webkitTransitionEnd" -
inner invoke を event、listeners、phase、invocationTargetInShadowTree、および legacyOutputDidListenersThrowFlag(指定されていれば)で実行する。
-
event の
type属性値を originalEventType に設定する。
-
inner invokeするには、event、listeners、phase、invocationTargetInShadowTree、およびオプションの legacyOutputDidListenersThrowFlag が与えられたとき、以下の手順を実行する:
-
found を false に設定する。
-
各 listener を listeners から取り出し、removed が false の場合:
-
found を true に設定する。
-
phase が "
capturing" かつ listener の capture が false の場合、continue する。 -
phase が "
bubbling" かつ listener の capture が true の場合、continue する。 -
listener の once が true の場合、remove an event listener を event の
currentTarget属性値と listener で実行する。 -
global を listener の callback の associated realm の global object に設定する。
-
currentEvent を undefined に設定する。
-
global が
Windowオブジェクトの場合:-
currentEvent を global の current event に設定する。
-
invocationTargetInShadowTree が false の場合、global の current event を event に設定する。
-
-
listener の passive が true の場合、event の in passive listener flag を設定する。
-
global が
Windowオブジェクトの場合、record timing info for event listener を event と listener で実行する。 -
Call a user object’s operation を listener の callback、"
handleEvent"、« event »、event のcurrentTarget属性値で実行する。これが例外 exception を投げた場合:-
Report exception を listener の callback の対応する JavaScript オブジェクトの associated realm の global object で報告する。
-
legacyOutputDidListenersThrowFlag が指定されていれば設定する。
legacyOutputDidListenersThrowFlag は Indexed Database API でのみ使用される。[INDEXEDDB]
-
-
event の in passive listener flag を解除する。
-
global が
Windowオブジェクトの場合、global の current event を currentEvent に設定する。 -
event の stop immediate propagation flag が設定されていれば、break する。
-
found を返す。
2.10. イベントの発火
fire an event を使って、e という名前のイベントを target で発火し、オプションで eventConstructor を使用し、IDL属性の初期化方法の説明と legacy target override flag を指定して、以下の手順を実行する:
-
eventConstructor が指定されていなければ、eventConstructor を
Eventに設定する。 -
event を creating an event を eventConstructor と target の relevant realm で実行した結果に設定する。
-
event の
type属性を e に初期化する。 -
その他の event の IDL 属性を、このアルゴリズムの呼び出し時の説明に従って初期化する。
これにより
isTrusted属性を false に設定することもできる。 -
dispatching を使って event を target で発火し、legacy target override flag が設定されていればそれを使い、その結果を返す。
DOM における fire は、creating、初期化、および dispatching をまとめて event に対して行うことを意味する。 fire an event はこの処理を簡潔に記述できるようにしている。
event の bubbles
や cancelable
属性を初期化する必要がある場合は、"fire an event named submit at target
with its cancelable
attribute initialized to true" のように記述できる。
また、カスタムコンストラクタが必要な場合は、"fire an event named click at target
using MouseEvent
with its detail
attribute initialized to 1" のように記述できる。
時には戻り値が重要になることもある:
-
doAction を firing an event named
likeat target の結果に設定する。 -
doAction が true なら …
2.11. アクションと発生の違い
event
は「発生」を意味し、「アクション」ではない。言い換えると、アルゴリズムからの通知を表し、そのアルゴリズムの今後の進行に影響を与えるために使うことができる(例:preventDefault()
の呼び出しなど)。
Events
はアクションや何かのアルゴリズムを開始するためのものではない。それが目的ではない。
ここで特に説明する理由は、以前の DOM 仕様では events に「デフォルトアクション」という概念があり、誤解を招いていたためである。 Events はアクションを表したり引き起こしたりするものではなく、進行中のアクションにのみ影響を与えることができる。
3. 進行中のアクティビティの中断
Promise には組み込みの中断メカニズムはありませんが、多くの API では中断のセマンティクスが必要です。AbortController
は、対応する AbortSignal
オブジェクトの状態を切り替える abort()
メソッドを提供することで、これらの要件をサポートすることを目的としています。
中断をサポートしたい API は AbortSignal
オブジェクトを受け取り、その状態に応じて処理を決定できます。
AbortController
を利用する API は、abort()
に応答して、未解決の Promise を AbortSignal
の abort
reason で reject することが推奨されます。
仮想の doAmazingness({ ... }) メソッドは、以下のように AbortSignal
オブジェクトを受け取って中断をサポートできます:
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 は次のように実装できます:
function doAmazingness({ signal}) {
return new Promise(( resolve, reject) => {
signal. throwIfAborted();
// 素晴らしい処理を開始し、完了時に resolve(result) を呼び出す。
// また、シグナルも監視する:
signal. addEventListener( 'abort' , () => {
// 素晴らしい処理を停止し、
reject( signal. reason);
});
});
}
Promise を返さない API は、同等の方法で反応するか、AbortSignal
の abort
reason を全く表に出さないこともできます。addEventListener()
は後者が適切だった API の例です。
より細かな制御が必要な API は、AbortController
や AbortSignal
オブジェクトを必要に応じて拡張できます。
3.1.
インターフェース AbortController
[Exposed=*]interface {AbortController constructor (); [SameObject ]readonly attribute AbortSignal signal ;undefined abort (optional any ); };reason
controller = new AbortController()- 新しい controller を返し、その
signalは新しく作成されたAbortSignalオブジェクトに設定される。 controller . signal- このオブジェクトに関連付けられた
AbortSignalオブジェクトを返す。 controller . abort(reason)- このメソッドを呼び出すと、reason がこのオブジェクトの
AbortSignalの abort reason に保存され、関連するアクティビティが中断されることを監視者に通知する。reason が undefined の場合は "AbortError"DOMExceptionが保存される。
AbortController
オブジェクトには、関連付けられた signal(AbortSignal
オブジェクト)がある。
new AbortController() コンストラクタの手順:
-
signal を新しい
AbortSignalオブジェクトに設定する。
signal getter の手順は、this の signal を返すこと。
abort(reason)
メソッドの手順は、reason が指定されていれば signal abort を this で reason
とともに実行すること。
signal abort を AbortController
controller で、オプションの reason とともに実行するには、controller の signal
で reason とともに signal abort を実行すること。
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 でない場合は reason に、そうでない場合は "AbortError"DOMExceptionに設定される。AbortSignal . any(signals)AbortSignalインスタンスを返し、signals のいずれかが中断されると自身も中断される。その 中断理由は、中断を引き起こした signals のいずれかの理由に設定される。AbortSignal . timeout(milliseconds)AbortSignalインスタンスを返し、milliseconds ミリ秒後に中断される。その 中断理由は、"TimeoutError"DOMExceptionに設定される。signal . aborted- signal の
AbortControllerが中断を通知した場合は true を、そうでない場合は false を返す。 signal . reason- signal の 中断理由を返す。
signal . throwIfAborted()- signal の
AbortControllerが中断を通知した場合、signal の 中断理由をスローする。そうでない場合は何もしない。
AbortSignal
オブジェクトには、関連付けられた 中断理由(JavaScript の値)があり、初期値は undefined である。
AbortSignal
オブジェクトには、関連付けられた 中断アルゴリズム(中断されたときに実行されるアルゴリズムの セット)があり、初期状態は空である。
中断アルゴリズムは、複雑な要件を持つ API が abort()
に合理的な方法で反応できるようにする。たとえば、特定の API の 中断理由は、サービスワーカーなどのスレッド間の環境に伝播する必要がある場合がある。
AbortSignal
オブジェクトには dependent(ブール値)があり、初期値は false である。
AbortSignal
オブジェクトには、関連付けられた source signals(オブジェクトがその 中断された状態に依存する AbortSignal
オブジェクトの弱い セット)があり、初期状態は空である。
AbortSignal
オブジェクトには、関連付けられた dependent signals(オブジェクトにその 中断された状態を依存する AbortSignal
オブジェクトの弱い セット)があり、初期状態は空である。
静的な abort(reason) メソッドのステップは次のとおりである:
-
signal を新しい
AbortSignalオブジェクトにする。 -
signal の 中断理由を、reason が指定されている場合は reason に、そうでない場合は新しい "
AbortError"DOMExceptionに設定する。 - signal を返す。
静的な timeout(milliseconds) メソッドのステップは次のとおりである:
-
signal を新しい
AbortSignalオブジェクトにする。 -
global を signal の 関連するグローバルオブジェクトにする。
-
タイムアウト後にステップを実行するを、global、"
AbortSignal-timeout"、milliseconds、および次のステップで実行する:-
グローバルタスクをキューに入れるを、タイマータスクソース上で global を指定して、signal と新しい "
TimeoutError"DOMExceptionを指定して 中断を通知する。
このタイムアウトの間、signal の
abortイベントにイベントリスナーが登録されている場合、global から signal への強い参照がなければならない。 -
-
signal を返す。
静的な any(signals) メソッドのステップは、signals から
AbortSignal
と 現在のレルムを使用して 依存する中断シグナルを作成する結果を返すことである。
aborted ゲッターのステップは、this が 中断されている場合は true を、そうでない場合は false
を返すことである。
reason ゲッターのステップは、this の 中断理由を返すことである。
throwIfAborted() メソッドのステップは、this が 中断されている場合、this の 中断理由をスローすることである。
このメソッドは主に、AbortSignal
を受け入れる関数が、AbortSignal
を他のメソッドに渡す代わりに、特定のチェックポイントでスロー(または拒否された Promise
を返す)したい場合に便利である。たとえば、次の関数は、条件をポーリングする各試行の間に中断を許可する。これにより、実際の非同期操作(つまり、)が AbortSignal
を受け入れなくても、ポーリングプロセスを中断する機会が与えられる。
async function waitForCondition( func, targetValue, { signal} = {}) { while ( true ) { signal? . throwIfAborted(); const result= await func(); if ( result=== targetValue) { return ; } } }
onabort 属性は、onabort イベントハンドラーの イベントハンドラー IDL 属性であり、その イベントハンドラーイベントタイプは abort である。
AbortSignal
オブジェクトへの変更は、対応する AbortController
オブジェクトの意図を表すが、AbortSignal
オブジェクトを監視する API は、それらを無視することを選択できる。たとえば、操作がすでに完了している場合などである。
AbortSignal
オブジェクトは、その 中断理由が undefined でない場合に 中断される。
アルゴリズム algorithm を AbortSignal
オブジェクト signal に 追加するには:
アルゴリズム algorithm を AbortSignal
signal から 削除するには、algorithm を signal の 中断アルゴリズムから 削除する。
AbortSignal
オブジェクト signal とオプションの reason を指定して 中断を通知するには:
-
signal が 中断されている場合、return する。
-
signal の 中断理由を、reason が指定されている場合は reason に、そうでない場合は新しい "
AbortError"DOMExceptionに設定する。 -
dependentSignalsToAbort を新しい リストにする。
-
signal の 中断ステップを実行する。
-
dependentSignalsToAbort の各 dependentSignal について、繰り返し、dependentSignal の 中断ステップを実行する。
AbortSignal
signal の 中断ステップを実行するには:
AbortSignal
オブジェクトのリスト signals から、signalInterface(AbortSignal
またはそれを継承するインターフェースでなければならない)と realm を使用して、依存する中断シグナルを作成するには:
-
resultSignal を、realm を使用して signalInterface を実装する 新しいオブジェクトにする。
-
signals の各 signal について 繰り返す:signal が 中断されている場合、resultSignal の 中断理由を signal の 中断理由に設定し、resultSignal を返す。
-
resultSignal の dependent を true に設定する。
-
signals の各 signal について 繰り返す:
-
signal の dependent が false の場合:
-
signal を resultSignal の source signals に 追加する。
-
resultSignal を signal の dependent signals に 追加する。
-
-
そうでない場合、signal の source signals の各 sourceSignal について 繰り返す:
-
sourceSignal を resultSignal の source signals に 追加する。
-
resultSignal を sourceSignal の dependent signals に 追加する。
-
-
resultSignal を返す。
3.2.1. ガベージコレクション
中断されていない dependent な
AbortSignal
オブジェクトは、その source signals が空でなく、abort
イベントに登録されたイベントリスナーがあるか、その 中断アルゴリズムが空でない間は、ガベージコレクションされてはならない。
3.3.
API での AbortController
と AbortSignal
オブジェクトの使用
中断可能な操作を表すために Promise を使用するウェブプラットフォーム API は、次に従わなければならない:
signal辞書メンバーを通じてAbortSignalオブジェクトを受け入れる。AbortSignalオブジェクトの 中断理由で Promise を拒否することにより、操作が中断されたことを伝える。AbortSignalがすでに 中断されている場合は即座に拒否し、そうでない場合:- 中断アルゴリズムメカニズムを使用して
AbortSignalオブジェクトの変更を監視し、他の監視者と衝突しない方法で行う。
Promise を返すメソッド doAmazingness(options) のメソッドステップは次のようになる:
-
global を this の 関連するグローバルオブジェクトにする。
-
p を 新しい Promise にする。
-
options["
signal"] が 存在する場合: -
次のステップを 並行して実行する:
-
amazingResult を素晴らしいことをした結果にする。
-
global を指定してアメージングタスクソース上で グローバルタスクをキューに入れ、amazingResult で p を 解決する。
-
-
p を返す。
Promise を使用しない API も、可能な限り上記に従うべきである。
4. ノード
4.1. "The DOM" の概要
本来の意味において、"The DOM" は文書(特に HTML と XML 文書)にアクセスし操作するための API である。この仕様では、「文書」という用語は、短い静的文書から、リッチメディアを含む長いエッセイや報告書、さらには本格的なインタラクティブアプリケーションまで、あらゆるマークアップベースのリソースに使用される。
このような各文書は ノードツリーとして表される。ツリー内の ノードの一部は 子を持つことができるが、他は常にリーフである。
例として、この HTML 文書を考えてみる:
<!DOCTYPE html> < html class = e > < head >< title > Aliens?</ title ></ head > < body > Why yes.</ body > </ html >
これは次のように表される:
HTML パースの魔法により、すべての ASCII 空白文字が
Text ノードに変換されるわけではないが、一般的な概念は明確である。マークアップが入力され、ノードの ツリーが出力される。
優れた Live DOM Viewer を使用して、この件についてより詳細に調べることができる。
4.2. ノードツリー
ノードは Node を実装するオブジェクトである。
ノードは ツリーに参加し、そのツリーは
ノードツリーとして知られている。
実際には、より具体的なオブジェクトを扱う。
Node を実装するオブジェクトは、継承されたインターフェースも実装する:Document、
DocumentType、
DocumentFragment、
Element、
CharacterData、
または Attr。
DocumentFragment
を実装するオブジェクトは、時には ShadowRoot
も実装する。
Element
を実装するオブジェクトは、通常、HTMLAnchorElement
などの継承されたインターフェースも実装する。
CharacterData
を実装するオブジェクトは、継承されたインターフェースも実装する:Text、
ProcessingInstruction、
または Comment。
Text
を実装するオブジェクトは、時には CDATASection
も実装する。
したがって、すべてのノードのプライマリインターフェースは次のいずれかである:Document、
DocumentType、
DocumentFragment、
ShadowRoot、
Element または
Element
の継承されたインターフェース、
Attr、Text、CDATASection、
ProcessingInstruction、
または Comment。
簡潔にするため、この仕様では Node
と継承されたインターフェース NodeInterface を実装するオブジェクトを、
NodeInterface ノードと呼ぶ。
ノードツリーは次のように制約される。これは ノードとその潜在的な子の関係として表現される:
Document-
ツリー順で:
-
0個以上の
ProcessingInstructionまたはCommentノード。 -
オプションで1つの
DocumentTypeノード。 -
0個以上の
ProcessingInstructionまたはCommentノード。 -
0個以上の
ProcessingInstructionまたはCommentノード。
-
DocumentFragmentElement-
0個以上の
ElementまたはCharacterDataノード。 DocumentTypeCharacterDataAttr-
子なし。
Attr ノードは歴史的な理由によりツリーに参加します。ただし、決して(非nullの)親や子を持つことはなく、
そのため常にツリーの中で単独です。
ノード nodeの長さを判定するには、次の手順を実行します:
-
もしnodeが
DocumentTypeまたはAttrノードであれば、0を返す。 -
もしnodeが
CharacterDataノードであれば、nodeの data の 長さを返す。 -
nodeの子の数を返す。
4.2.1. 文書ツリー
文書の文書要素は、 その親がその文書である要素(存在する場合)、そうでない場合は null である。
ノードツリーの制約により、そのような要素は1つしか存在できない。
ノードのルートがドキュメントである場合、そのノードはドキュメントツリー内とみなす。
ノードがドキュメントツリー内である場合、そのノードはドキュメント内とみなす。 ドキュメント内という用語は今後使用しないこととされている。これは、その用語を使っている標準がシャドウツリーに対応できていないことを示している。
4.2.2. シャドウツリー
シャドウツリーは ルートがシャドウルートであるノードツリーである。
シャドウルートは、その ホストを通じて、常に別のノードツリーに接続されている。したがってシャドウツリーは決して単独ではない。 シャドウルートのホストのノードツリーは、時にライトツリーと呼ばれる。
シャドウツリーに対応するライトツリーは、それ自体がシャドウツリーである場合もある。
ノードは、その シャドウを含むルートが文書の場合、接続されている。
4.2.2.1. スロット
スロットは、HTML の
slot
要素を通じてのみ作成できる。
スロットには関連付けられた名前(文字列)がある。特に明記されていない限り、それは空文字列である。
スロットの名前を更新するには、次の属性変更ステップを使用する:
-
element がスロットで、localName が
nameで、 namespace が null の場合:-
value が oldValue の場合、return する。
-
value が null で oldValue が空文字列の場合、return する。
-
value が空文字列で oldValue が null の場合、return する。
-
value が null または空文字列の場合、element の 名前を空文字列に設定する。
-
そうでない場合、element の名前を value に設定する。
-
element のルートを指定してツリーのスロット可能要素を割り当てるを実行する。
-
シャドウツリー内の、ツリー順で最初のスロットで、その 名前が空文字列であるものは、時に「デフォルトスロット」として知られる。
スロットには関連付けられた割り当てられたノード(スロット可能要素のリスト)がある。特に明記されていない限り、それは空である。
4.2.2.2. スロット可能要素
Element と Text ノードは
スロット可能要素である。
スロット可能要素には関連付けられた名前(文字列)がある。特に明記されていない限り、それは空文字列である。
スロット可能要素の名前を更新するには、次の属性変更ステップを使用する:
-
localName が
slotで namespace が null の場合:-
value が oldValue の場合、return する。
-
value が null で oldValue が空文字列の場合、return する。
-
value が空文字列で oldValue が null の場合、return する。
-
value が null または空文字列の場合、element の 名前を空文字列に設定する。
-
そうでない場合、element の名前を value に設定する。
-
element が割り当てられている場合、element の割り当てられたスロットに対してスロット可能要素を割り当てるを実行する。
-
element に対してスロットを割り当てるを実行する。
-
スロット可能要素には関連付けられた 割り当てられたスロット(null またはスロット)がある。 特に明記されていない限り、それは null である。スロット可能要素は、その割り当てられたスロットが非 null の場合、 割り当てられている。
スロット可能要素には関連付けられた手動スロット割り当て(null またはスロット)がある。特に明記されていない限り、それは null である。
スロット可能要素の手動スロット割り当ては、この変数がスクリプトから直接アクセスできないため、スロットへの弱参照を使用して実装できる。
4.2.2.3. スロットとスロット可能要素の検索
指定されたスロット可能要素 slottable とオプションのブール値 open(デフォルトは false)に対してスロットを見つけるには:
-
slottable の親が null の場合、null を返す。
-
shadow が null の場合、null を返す。
-
open が true で shadow のモードが "
open" でない場合、null を返す。 -
shadow のスロット割り当てが "
manual" の場合、shadow の子孫の中で、その 手動で割り当てられたノードが slottable を含むスロットがあればそれを返し、そうでない場合は null を返す。 -
shadow の子孫内でツリー順で最初のスロットで、その名前が slottable の 名前と一致するものがあればそれを返し、そうでない場合は null を返す。
指定されたスロット slot に対してスロット可能要素を見つけるには:
指定されたスロット slot に対して平坦化されたスロット可能要素を見つけるには:
-
result を « » にする。
-
slottables を slot を指定してスロット可能要素を見つけた結果にする。
-
slottables が空のリストの場合、slot の各スロット可能要素子をツリー順で slottables に追加する。
-
slottables の各 node について:
-
-
temporaryResult を node を指定して平坦化されたスロット可能要素を見つけた結果にする。
-
temporaryResult の各スロット可能要素を順番に result に追加する。
-
-
そうでない場合、node を result に追加する。
-
-
result を返す。
4.2.2.4. スロット可能要素とスロットの割り当て
スロット slot に対してスロット可能要素を割り当てるには:
-
slottables を slot に対してスロット可能要素を見つけた結果にする。
-
slottables と slot の割り当てられたノードが同一でない場合、slot に対してスロット変更をシグナルするを実行する。
-
slot の割り当てられたノードを slottables に設定する。
-
slottables の各 slottable について: slottable の 割り当てられたスロットを slot に設定する。
指定されたノード root に対してツリーのスロット可能要素を割り当てるには、 root の包括的子孫の各スロットに対して、ツリー順でスロット可能要素を割り当てるを実行する。
指定されたスロット可能要素 slottable に対してスロットを割り当てるには:
-
slot を slottable を指定してスロットを見つけた結果にする。
-
slot が非 null の場合、slot に対してスロット可能要素を割り当てるを実行する。
4.2.2.5. スロット変更のシグナル
各同一オリジンウィンドウエージェントにはシグナルスロット(スロットのセット)があり、これは最初は空である。[HTML]
スロット slot に対してスロット変更をシグナルするには:
4.2.3. 変更アルゴリズム
ノード pre-insert の妥当性を確保するために、 node node を node parent の null または node child の前に挿入する際に行う手順:
-
もし parent が
Document、DocumentFragment、 またはElementnode でない場合、throw して "HierarchyRequestError" のDOMExceptionとする。 -
もし node が parent の host-including inclusive ancestor である場合、throw して "
HierarchyRequestError" のDOMExceptionとする。 -
もし child が null でなく、その parent が parent でない場合、throw して "
NotFoundError" のDOMExceptionとする。 -
もし node が
DocumentFragment、DocumentType、Element、 またはCharacterDatanode でない場合、throw して "HierarchyRequestError" のDOMExceptionとする。 -
もし node が
Textの node であり parent が document である、または node が doctype で parent が document でない場合、throw して "HierarchyRequestError" のDOMExceptionとする。 -
もし parent が document であり、以下のいずれか(interface node が implements しているものに応じて切り替える)が成り立つ場合、throw して "
HierarchyRequestError" のDOMExceptionとする。DocumentFragment-
もし node が要素 element の child を 1 つより多く持つ、または
Textの node の child を持つ場合。そうでない場合、もし node が要素 element の child を 1 つ持ち、かつ parent が要素 element の child を持つ、child が doctype である、または child が null でなくかつ doctype が following child である場合。
Element-
parent が要素 element の child を持つ、child が doctype である、または child が null でなくかつdoctype が following child である場合。
DocumentType-
parent が doctype の child を持つ、child が null でなくて要素 element が preceding child である、または child が null で parent が要素 element の child を持つ場合。
ノード pre-insert を行うには、node node を node parent の null または node child の前に挿入する手順:
-
Ensure pre-insert validity を実行して、 node を parent の child の前に挿入しても良いか確認する。
-
referenceChild を child とする。
-
もし referenceChild が node と同じであれば、referenceChild を node の next sibling に設定する。
-
Insert を実行して node を parent の referenceChild の前に挿入する。
-
node を返す。
仕様 は、すべてまたは一部の node に対して insertion steps を定義することがある。 このアルゴリズムは下で示す insert アルゴリズムの通り、insertedNode を渡される。 これらのステップは insertedNode が参加する node tree を変更したり、ブラウジングコンテキストを作成したり、 イベントを発火したり、あるいは JavaScript を実行してはならない。ただし、これらを非同期的に行うために タスクをキュー することはできる。
insertion steps は JavaScript を実行できない(その他の制約もある)が、 実際にはスクリプトから観測可能な影響を与えることがある。以下の例を考える:
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)' ; // Logs 'rgb(255, 0, 0)'
style. innerText = 'h1 {color: rgb(255, 0, 0);}' ;
document. body. append( fragment);
上の例のスクリプトが
をログ出力するのは、次の出来事が順に発生するためである:
-
insert アルゴリズムが実行され、
script要素とstyle要素が順に挿入される。-
HTML 標準の insertion steps が
script要素に対して実行されるが、何もしない。[HTML] -
HTML 標準の insertion steps が
style要素に対して実行され、そのスタイル規則が直ちに文書に適用される。[HTML] -
HTML 標準の post-connection steps が
script要素に対して実行され、スクリプトが実行される。そのスクリプトは上のステップで適用されたスタイル規則を直ちに観測する。[HTML]
-
仕様 は、すべてまたは一部の nodes に対して post-connection steps を定義することがある。アルゴリズムには下で示される通り connectedNode が渡される。
post-connection steps の目的は、nodes に対して接続に関連する操作を行い、connectedNode が参加する node tree を変更したり、ブラウジングコンテキストを作成したり、あるいは JavaScript を実行したりする機会を提供することである。これらのステップは一括挿入に関する主要な副作用がすべて完了した後に、非同期的にタスクをキューしてそれらを行うことを許す。
仕様 は、すべてまたは一部の nodes に対して children changed steps を定義することがある。アルゴリズムは引数を取らず、insert、remove、および replace data から呼び出される。
ノード insert を行うには、node node を node parent の null または node child の前に挿入する。オプションのブール値 suppressObservers(デフォルト false)を受け取る:
-
もし node が
DocumentFragmentnode であれば、nodes を node の children とする。そうでなければ « node » とする。 -
count を nodes の size とする。
-
もし count が 0 であれば、戻る。
-
もし node が
DocumentFragmentnode であれば:-
Remove を呼んで、その children を suppressObservers を true にして削除する。
-
Queue a tree mutation record を node について、「« », nodes, null, null」を用いてキューする。
このステップは意図的に suppressObservers を考慮しない。
-
-
もし child が非 null であれば:
-
各 live range について、その start node が parent であり start offset が child の index より大きい場合:その start offset を count 増やす。
-
各 live range について、その end node が parent であり end offset が child の index より大きい場合:その end offset を count 増やす。
-
-
previousSibling を child の previous sibling、または child が null の場合は parent の last child とする。
-
nodes の各 node について、tree order に従って次を行う:
-
Adopt を呼んで、node を parent の node document に適合させる。
-
もし child が null であれば、append を用いて node を parent の children に追加する。
-
そうでなければ、insert を用いて node を parent の children に child の index の前に挿入する。
-
もし parent が shadow host で、その shadow root の slot assignment が "
named" であり、かつ node が slottable であれば、assign a slot を実行して node にスロットを割り当てる。 -
もし parent の root が shadow root であり、 parent がスロット slot で、その assigned nodes が空リストであれば、 signal a slot change を parent に対して実行する。
-
assign slottables for a tree を node の root に対して実行する。
-
node の各 shadow-including inclusive descendant inclusiveDescendant について、 shadow-including tree order に従って次を行う:
-
insertion steps を inclusiveDescendant に対して実行する。
-
もし inclusiveDescendant が element で、かつ inclusiveDescendant の custom element registry が非 null であれば:
-
もし inclusiveDescendant の custom element registry の is scoped が true であれば、append を用いて inclusiveDescendant の node document を inclusiveDescendant の custom element registry の scoped document set に追加する。
-
もし inclusiveDescendant が custom であれば、enqueue a custom element callback reaction を呼び、 inclusiveDescendant、コールバック名 "
connectedCallback"、および « » を渡す。 -
それ以外の場合、try to upgrade を inclusiveDescendant に対して試みる。
もしこれによって inclusiveDescendant が成功裏にアップグレードされれば、その
connectedCallbackは自動的にキューに登録される。
-
-
それ以外で、もし inclusiveDescendant が shadow root で、 その custom element registry が非 null であり、 かつその custom element registry の is scoped が true であれば、append を用いて inclusiveDescendant の node document を その custom element registry の scoped document set に追加する。
-
-
-
もし suppressObservers が false であれば、queue a tree mutation record を parent について、nodes、« »、previousSibling、および child を用いてキューする。
-
children changed steps を parent に対して実行する。
-
staticNodeList を最初は « » の list として用意する。
post-connection steps をいずれかのノードに対して呼ぶ前に、全てのノードを 事前に 集める。この理由は、post-connection steps がツリー構造を変更し得るため、ライブな走査が安全でなくなり、同じノードに対して複数回 post-connection steps が呼ばれる可能性があるからである。
-
nodes の各 node について、tree order に従って次を行う:
-
各 shadow-including inclusive descendant inclusiveDescendant を、shadow-including tree order の順で staticNodeList に append する。
-
-
For each node of staticNodeList: もし node が connected であれば、post-connection steps を node に対して実行する。
ノード append を行うには、node node を node parent に対して、 pre-insert を使って null の前に挿入する。
仕様は、すべてまたは一部のノードに対して 移動手順を定義してもよい。 このアルゴリズムには、ノード movedNode と、 ノードまたはnullの oldParent が、 下記moveアルゴリズムで示される通り渡される。 挿入手順と同様、 これら手順は ノードツリー(movedNode が 属しているもの)を変更してはならず、 閲覧コンテキストの生成や、 イベントの発火、 その他JavaScriptの実行を行ってはならない。ただし、これらの動作を非同期で行うためにタスクをキューイングすることは許されている。
ノード move を行うには、node node を node newParent の null または node child の前に移動する手順:
-
もし newParent の shadow-including root が node の shadow-including root と異なる場合、throw して "
HierarchyRequestError" のDOMExceptionとする。これにより、移動は newParent の connected が node の connected と同じである場合にのみ実行される、という副作用がある。
-
もし node が host-including inclusive ancestor で newParent の祖先であれば、 throw して "
HierarchyRequestError" のDOMExceptionとする。 -
もし child が null でなく、その parent が newParent でない場合、throw して "
NotFoundError" のDOMExceptionとする。 -
もし node が
ElementまたはCharacterDataの node でない場合、throw して "HierarchyRequestError" のDOMExceptionとする。 -
もし node が
Textの node であり newParent が document であれば、 throw して "HierarchyRequestError" のDOMExceptionとする。 -
もし newParent が document で、かつ node が
Elementの node であり、かつ newParent が要素 element の child を持つ、child が doctype である、または child が null でなくかつ doctype が following child である場合、throw して "HierarchyRequestError" のDOMExceptionとする。 -
oldParent を node の parent とする。
-
Assert: oldParent は非 null であることを確認する。
-
live range pre-remove steps を node に対して実行する。
-
各
NodeIteratorオブジェクト iterator について、その root の node document が node の node document と同じであれば、NodeIteratorpre-remove steps を node と iterator を渡して実行する。 -
oldPreviousSibling を node の previous sibling とする。
-
oldNextSibling を node の next sibling とする。
-
もし node が assigned であれば、assign slottables を node の assigned slot に対して実行する。
-
もし oldParent の root が shadow root で、かつ oldParent がスロット slot で、その assigned nodes が空であれば、signal a slot change を oldParent に対して実行する。
-
もし node がスロット slot を含む inclusive descendant を持つ場合:
-
assign slottables for a tree を oldParent の root に対して実行する。
-
assign slottables for a tree を node に対して実行する。
-
-
もし child が非 null であれば:
-
各 live range について、その start node が newParent であり start offset が child の index より大きい場合:その start offset を 1 増やす。
-
各 live range について、その end node が newParent であり end offset が child の index より大きい場合:その end offset を 1 増やす。
-
-
newPreviousSibling を、もし child が非 null であれば child の previous sibling、そうでなければ newParent の last child とする。
-
もし child が null であれば、append を用いて node を newParent の children に追加する。
-
そうでなければ、insert を用いて node を newParent の children に child の index の前に挿入する。
-
もし newParent が shadow host で、その shadow root の slot assignment が "
named" で node が slottable であれば、assign a slot を実行して node にスロットを割り当てる。 -
もし newParent の root が shadow root で、 newParent が slot で、その assigned nodes が空であれば、signal a slot change を newParent に対して実行する。
-
assign slottables for a tree を node の root に対して実行する。
-
node の各 shadow-including inclusive descendant inclusiveDescendant について、 shadow-including tree order に従って次を行う:
-
もし inclusiveDescendant が node であれば、moving steps を inclusiveDescendant と oldParent に対して実行する。そうでなければ、moving steps を inclusiveDescendant と null に対して実行する。
move アルゴリズムは insert と remove とは別のプリミティブであるため、inclusiveDescendant に対して従来の insertion steps や removing steps を呼び出さない。
-
もし inclusiveDescendant が custom であり、かつ newParent が connected であれば、enqueue a custom element callback reaction を呼んで、 inclusiveDescendant、コールバック名 "
connectedMoveCallback"、および « » を渡す。
-
-
Queue a tree mutation record を oldParent について、「« », « node », oldPreviousSibling, oldNextSibling」を用いてキューする。
-
Queue a tree mutation record を newParent について、「« node », « », newPreviousSibling, child」を用いてキューする。
ノード replace を行うには、node child を node node で置き換える手順(node parent 内):
-
もし parent が
Document、DocumentFragment、 またはElementnode でない場合、throw して "HierarchyRequestError" のDOMExceptionとする。 -
もし node が host-including inclusive ancestor で parent の祖先であれば、 throw して "
HierarchyRequestError" のDOMExceptionとする。 -
もし child の parent が parent でない場合、throw して "
NotFoundError" のDOMExceptionとする。 -
もし node が
DocumentFragment、DocumentType、Element、 またはCharacterDatanode でない場合、throw して "HierarchyRequestError" のDOMExceptionとする。 -
もし node が
Textの node であり parent が document である、または node が doctype で parent が document でない場合、throw して "HierarchyRequestError" のDOMExceptionとする。 -
もし parent が document であり、以下のいずれか(interface node が implements しているものに応じて切り替える)が成り立つ場合、throw して "
HierarchyRequestError" のDOMExceptionとする。DocumentFragment-
もし node が要素 element の child を 1 つより多く持つ、または
Textの node の child を持つ場合。そうでない場合、もし node が要素 element の child を 1 つ持ち、かつ parent が要素 element の child を持っており、それが child でないか、または doctype が following child である場合。
Element-
parent が要素 element の child を持っており、それが child でないか、または doctype が following child である場合。
DocumentType-
parent が doctype の child を持っており、それが child でない、または要素 element が preceding child である場合。
上の条件は pre-insert アルゴリズムの条件とは異なる点がある。
-
referenceChild を child の next sibling とする。
-
もし referenceChild が node と同じであれば、referenceChild を node の next sibling に設定する。
-
previousSibling を child の previous sibling とする。
-
removedNodes を空集合として用意する。
-
もし child の parent が非 null であれば:
-
removedNodes を « child » に設定する。
-
Remove を呼んで child を suppressObservers を true にして削除する。
上の条件が偽になり得るのは child が node と同じ場合のみである。
-
-
nodes を、もし node が
DocumentFragmentnode であればその children、そうでなければ « node » とする。 -
Insert を呼んで node を parent の referenceChild の前に挿入する(suppressObservers を true に設定して実行)。
-
Queue a tree mutation record を parent について、 nodes、removedNodes、previousSibling、および referenceChild を用いてキューする。
-
child を返す。
Node のための replace all を行うには、ノードまたは null の node node を node parent 内で置き換える手順:
-
removedNodes を parent の children とする。
-
addedNodes を空集合とする。
-
もし node が
DocumentFragmentnode であれば、addedNodes を node の children に設定する。 -
そうでなければ、もし node が非 null であれば addedNodes を « node » に設定する。
-
Remove を呼んで parent の全ての children を、suppressObservers を true にしてツリー順に削除する。
-
もし node が非 null であれば、insert を呼んで node を parent の null の前に挿入する(suppressObservers を true に設定して実行)。
-
もし addedNodes または removedNodes が 空でない 場合、queue a tree mutation record を parent について、addedNodes、removedNodes、null、null を用いてキューする。
このアルゴリズムは node tree の制約に関するチェックを行わない。仕様作成者はこれを注意して使用する必要がある。
ノード pre-remove を行うには、node child を node parent から削除する手順:
-
もし child の parent が parent でない場合、throw して "
NotFoundError" のDOMExceptionとする。 -
Remove を呼んで child を削除する。
-
child を返す。
仕様 は、すべてまたは一部の nodes に対して removing steps を定義することがある。アルゴリズムは、下で示す remove アルゴリズムに従って node removedNode と ノードまたは null の oldParent を渡される。
ノード remove を行うには、node node を削除する。オプションのブール値 suppressObservers(デフォルト false)を受け取る:
-
parent を node の parent とする。
-
Assert: parent は非 null である。
-
live range pre-remove steps を node に対して実行する。
-
各
NodeIteratorオブジェクト iterator について、その root の node document が node の node document と同じであれば、NodeIteratorpre-remove steps を node と iterator を渡して実行する。 -
oldPreviousSibling を node の previous sibling とする。
-
oldNextSibling を node の next sibling とする。
-
もし node が assigned であれば、assign slottables を node の assigned slot に対して実行する。
-
もし parent の root が shadow root で、かつ parent がスロット slot で、その assigned nodes が空であれば、 signal a slot change を parent に対して実行する。
-
もし node に inclusive descendant が存在し、それが slot である場合:
-
assign slottables for a tree を parent の root に対して実行する。
-
assign slottables for a tree を node に対して実行する。
-
-
removing steps を node と parent を渡して実行する。
-
isParentConnected を parent の connected とする。
-
もし node が custom であり、かつ isParentConnected が true であれば、 enqueue a custom element callback reaction を呼んで、 node、コールバック名 "
disconnectedCallback"、および « » を渡す。現時点では custom な elements に対して parent を渡さないようにしている。将来的に必要があれば変更される可能性がある。
-
node の各 shadow-including descendant descendant について、 shadow-including tree order に従って次を行う:
-
removing steps を descendant と null を渡して実行する。
-
もし descendant が custom であり、かつ isParentConnected が true であれば、enqueue a custom element callback reaction を呼んで、 descendant、コールバック名 "
disconnectedCallback"、および « » を渡す。
-
-
各 inclusive ancestor inclusiveAncestor について、 そして各 for each registered が inclusiveAncestor の registered observer list に含まれている場合、もし registered の options["
subtree"] が true であれば、 append を用いて新しい transient registered observer を作り、その observer を registered の observer にし、options を registered の options にし、 source を registered が属する node の registered observer list にする。 -
もし suppressObservers が false であれば、queue a tree mutation record を parent について、「« », « node », oldPreviousSibling, oldNextSibling」を用いてキューする。
-
children changed steps を parent に対して実行する。
4.2.4.
ミックスイン NonElementParentNode
Web互換性のため、getElementById()
メソッドは要素(およびParentNode)では公開されません。
interface mixin {NonElementParentNode Element ?getElementById (DOMString ); };elementId Document includes NonElementParentNode ;DocumentFragment includes NonElementParentNode ;
getElementById(elementId)
メソッドの手順は、
ツリー順で
thisの
子孫の中から
IDがelementIdである
最初の要素を返します。
該当する要素がなければ、nullを返します。
4.2.5.
ミックスイン DocumentOrShadowRoot
interface mixin {DocumentOrShadowRoot readonly attribute CustomElementRegistry ?customElementRegistry ; };Document includes DocumentOrShadowRoot ;ShadowRoot includes DocumentOrShadowRoot ;
registry = documentOrShadowRoot .customElementRegistry-
documentOrShadowRootの
CustomElementRegistryオブジェクトを返します(存在すれば)。なければnullを返します。
customElementRegistry
ゲッターの手順は以下の通りです。
-
thisが ドキュメントなら、 thisのカスタム要素レジストリを返す。
-
Assert: thisは
ShadowRootノードである。 -
thisのカスタム要素レジストリを返す。
DocumentOrShadowRoot
ミックスインは、ドキュメントと
シャドウルートの両方で
共有されるAPIを定義したい他の標準でも利用されることが期待されています。
4.2.6. ミックスイン ParentNode
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 CEReactions ]undefined moveBefore (Node ,node Node ?);child Element ?querySelector (DOMString ); [selectors NewObject ]NodeList querySelectorAll (DOMString ); };selectors Document includes ParentNode ;DocumentFragment includes ParentNode ;Element includes ParentNode ;
collection = node .children- 子の要素を返します。
element = node .firstElementChild- 最初の子である要素を返します。そうでなければ null です。
element = node .lastElementChild- 最後の子である要素を返します。そうでなければ null です。
node . prepend(nodes)-
nodes を node の最初の子の前に挿入します。その際、nodes 内の文字列は同等の
Textノードに置き換えられます。制約が違反した場合、"
HierarchyRequestError"DOMExceptionを投げます。対象はノードツリーです。 node . append(nodes)-
nodes を node の最後の子の後ろに挿入します。その際、nodes 内の文字列は同等の
Textノード に置き換えられます。制約が違反した場合、"
HierarchyRequestError"DOMExceptionを投げます。対象はノードツリーです。 node . replaceChildren(nodes)-
node のすべての子を nodes に置き換えます。その際、nodes 内の文字列は同等の
Textノード に置き換えられます。制約が違反した場合、"
HierarchyRequestError"DOMExceptionを投げます。対象はノードツリーです。 node . moveBefore(movedNode, child)-
movedNode を child の後ろに、child が null の場合は node の最後の子 の後ろに、削除せずに移動します。このメソッドは movedNode に紐付く状態を保持します。
制約が違反した場合、または移動ノードの状態が保持できない場合は、"
HierarchyRequestError"DOMExceptionを投げます。対象はノードツリーです。 node . querySelector(selectors)node . querySelectorAll(selectors)
children のgetter手順は、HTMLCollection型のコレクションを返します。対象は
this の 要素 子です。
prepend(nodes) メソッドの手順は次の通りです:
-
node を ノード集合をノードへ変換する の結果として、nodes と this の ノード文書を与えて得る。
-
pre-insertで node を this に、最初の子 の前に挿入します。
append(nodes) メソッドの手順は次の通りです:
-
node を ノード集合をノードへ変換する の結果として、nodes と this の ノード文書を与えて得る。
replaceChildren(nodes)
メソッドの手順は次の通りです:
-
node を ノード集合をノードへ変換する の結果として、nodes と this の ノード文書を与えて得る。
-
pre-insertの妥当性を node と this, null で検証する。
-
replace allにより、node で this の中身を置き換える。
moveBefore(node, child)
メソッドの手順は次の通りです:
querySelector(selectors) メソッドの手順は、selectors文字列をスコープマッチし、その結果の最初の要素(リストが空でなければ)を
selectors と this で返し、空なら null を返します。
querySelectorAll(selectors)
メソッドの手順は、静的な結果として、selectors文字列をスコープマッチし、selectors と this
での結果を返します。
4.2.7. ミックスイン NonDocumentTypeChildNode
Web互換性のため、previousElementSibling
および
nextElementSibling
属性はdoctype(およびChildNode)で公開されません。
interface mixin {NonDocumentTypeChildNode readonly attribute Element ?previousElementSibling ;readonly attribute Element ?nextElementSibling ; };Element includes NonDocumentTypeChildNode ;CharacterData includes NonDocumentTypeChildNode ;
element = node .previousElementSibling- 最初の前の兄弟で要素であるものを返します。なければnull。
element = node .nextElementSibling- 最初の後の兄弟で要素であるものを返します。なければnull。
4.2.8. ミックスイン ChildNode
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 を node の直前に挿入します。その際、nodes 内の文字列は同等の
Textノード に置換されます。制約が違反した場合、"
HierarchyRequestError"DOMExceptionを投げます。対象はノードツリーです。 node .after(...nodes)-
nodes を node の直後に挿入します。その際、nodes 内の文字列は同等の
Textノード に置換されます。制約が違反した場合、"
HierarchyRequestError"DOMExceptionを投げます。対象はノードツリーです。 node .replaceWith(...nodes)-
node を nodes で置き換えます。その際、nodes 内の文字列は同等の
Textノード に置換されます。制約が違反した場合、"
HierarchyRequestError"DOMExceptionを投げます。対象はノードツリーです。 node .remove()- node を削除します。
before(nodes) メソッドの手順は次の通りです:
-
もし parent が null なら、何もせず終了する。
-
viablePreviousSibling を this の 先行する兄弟のうち nodes に含まれない最初のものとする。なければ null。
-
node を ノード集合をノードへ変換する の結果として、nodes と this の ノード文書を与えて得る。
-
もし viablePreviousSibling が null なら、それを parent の 最初の子とし、そうでなければ viablePreviousSibling の次の兄弟とする。
-
pre-insertで node を parent に viablePreviousSibling の前へ挿入する。
after(nodes) メソッドの手順は次の通りです:
-
もし parent が null なら、何もせず終了する。
-
viableNextSibling を this の 後続する兄弟のうち nodes に含まれない最初のものとする。なければ null。
-
node を ノード集合をノードへ変換する の結果として、nodes と this の ノード文書を与えて得る。
-
pre-insertで node を parent に viableNextSibling の前へ挿入する。
replaceWith(nodes) メソッドの手順は次の通りです:
-
もし parent が null なら、何もせず終了する。
-
viableNextSibling を this の 後続する兄弟のうち nodes に含まれない最初のものとする。なければ null。
-
node を ノード集合をノードへ変換する の結果として、nodes と this の ノード文書を与えて得る。
-
もし this の 親が parent なら、replaceで this を parent の中で node で置き換える。
this は node の中に挿入されている可能性があります。
-
それ以外の場合は、pre-insertで node を parent に viableNextSibling の前へ挿入します。
4.2.9. ミックスイン Slottable
interface mixin {Slottable readonly attribute HTMLSlotElement ?assignedSlot ; };Element includes Slottable ;Text includes Slottable ;
assignedSlot
のgetter手順は、find a slot を this と true
で呼び出した結果を返します。
4.2.10.
旧式コレクション: NodeList と
HTMLCollection
コレクションは、ノードのリストを表すオブジェクトです。コレクションは、ライブまたは静的のいずれかです。特に明記されていない限り、コレクションはライブでなければなりません。
コレクションがライブの場合、そのオブジェクトの属性およびメソッドは、実際の基礎となるデータに対して動作し、データのスナップショットではありません。
コレクションが生成されると、フィルターとルートがそれに関連付けられます。
その後、コレクションは、コレクションで表されるサブツリーのビューを、コレクションのルートに基づいて、指定されたフィルターに一致するノードだけを含めて表します。ビューは線形です。特に別途要件がない場合、コレクション内のノードはツリー順でソートされなければなりません。
4.2.10.1.
インターフェース NodeList
NodeList
オブジェクトはコレクションであり、ノードを保持します。
[Exposed =Window ]interface {NodeList getter Node ?item (unsigned long );index readonly attribute unsigned long length ;iterable <Node >; };
- collection .
length - コレクション内のノードの数を返します。
- element = collection .
item(index)- element = collection[index]
- コレクションから、インデックス index のノードを返します。ノードはツリー順で並べられます。
このオブジェクトのサポートされるプロパティインデックスは、ノード数の範囲内(ゼロからコレクションで表されるノード数から1を引いた値までの数字)です。該当する要素がない場合、サポートされるプロパティインデックスはありません。
length 属性は、コレクションで表されるノード数を返さなければなりません。
item(index) メソッドは、コレクション内の index 番目のノードを返す必要があります。コレクション内に
index 番目のノードが存在しない場合、このメソッドは 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
オブジェクトはコレクションであり、要素を保持します。
HTMLCollection
は歴史的な遺物でありWebから取り除くことができません。
開発者は引き続き使用できますが、新しいAPI標準の設計者は使用すべきではありません(IDLではsequence<T>を使ってください)。
- collection .
length - コレクション内の要素の数を返す。
- element = collection .
item(index)- element = collection[index]
- コレクションから、インデックスindexで指定された要素を返す。 要素はツリー順でソートされている。
- element = collection .
namedItem(name)- element = collection[name]
- コレクションの中から、nameというIDまたは名前を持つ最初の要素を返す。
オブジェクトのサポートされるプロパティインデックスは、要素の数が0〜(要素数-1)の範囲の数値です。 要素がなければサポートされるプロパティインデックスはありません。
lengthゲッターの手順は、
コレクションで表現されるノード数を返します。
item(index)メソッドの手順は、
コレクション内のindex番目の要素を返します。要素がなければnullを返します。
サポートされるプロパティ名は以下の手順で得られるリストの値です:
-
resultを空リストとする。
-
コレクションで表現される各elementについて、ツリー順で:
-
resultを返す。
namedItem(key)メソッドの手順は:
-
keyが空文字列ならnullを返す。
-
該当する要素がなければnullを返します。
4.3. ミューテーションオブザーバー
各同一オリジンウィンドウエージェントは、 mutation observer microtask queued (真偽値)を持ち、初期値はfalseです。[HTML]
各同一オリジンウィンドウエージェントはさらに
pending mutation
observers(0個以上の集合で、MutationObserverオブジェクト)を持ち、初期値は空です。
ミューテーションオブザーバー・マイクロタスクをキューに入れるには、次のようにする:
-
surrounding agent の mutation observer microtask queued が true なら、何もしないで終了する。
-
surrounding agent の mutation observer microtask queued を true に設定する。
-
microtask を キューイング し、ミューテーションオブザーバーに通知する。
ミューテーションオブザーバーに通知するには、次のようにする:
-
surrounding agent の mutation observer microtask queued を false に設定する。
-
notifySet を クローンした、surrounding agent の pending mutation observers にする。
-
signalSet を クローンした、surrounding agent の signal slots にする。
-
空にする:surrounding agent の signal slots を空にする。
-
各 mo in notifySet について:
-
records を クローンした mo の record queue にする。
-
空にする:mo の record queue を空にする。
-
各 node in mo の node list について:node の registered observer list から transient registered observers のうち、 observer が mo であるものをすべて削除する。
-
records が 空でない場合は、コールバック関数を呼び出す:mo の callback に « records, mo », "
report" を渡し、 callback this value を mo に設定して呼び出す。
-
-
各 slot in signalSet について:イベントを発火させる 名前は
slotchange、bubbles属性を true に設定し、slot で発火させる。
各ノードは、登録済みオブザーバーリスト(リスト、ゼロ個以上の登録済みオブザーバーからなる)を持ち、初期状態は空です。
registered
observerは、
observer(MutationObserverオブジェクト)と
options(MutationObserverInit辞書)で構成されます。
transient registered observerは、 registered observerであり、 さらにsource(registered observer)を持ちます。
一時的登録済みオブザーバーは、特定のノードが削除された後でも、その子孫内の変化を追跡するために使われます。これは、subtreeがノードの親でtrueに設定されている場合に、変更が失われないようにするためです。
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
オブジェクトは、ツリー内のノードの変化を監視するために利用できます。
各MutationObserver
オブジェクトには、以下の概念が関連付けられています:
- 生成時に設定される コールバック
- ノードリスト(リスト、弱参照によるノードからなる)、初期状態は空です。
- レコードキュー(キュー、ゼロ個以上の
MutationRecordオブジェクト)、初期状態は空です。
observer = newMutationObserver(callback)MutationObserverオブジェクトを生成し、そのコールバックに callback を設定します。callback は第一引数にMutationRecordオブジェクトのリスト、第二引数に生成済みMutationObserverオブジェクトが渡され、それぞれ登録済みobserve()メソッドで監視されていたノードが変化すると呼び出されます。observer .observe(target, options)-
ユーザーエージェントに、指定した target(ノード)の変更をoptions(オブジェクト)で指定された条件に従い監視するよう指示します。
options 引数では、オブジェクトメンバーで監視内容を指定します。利用可能なメンバーは次の通りです:
childList- targetの子への変更を監視する場合はtrueにします。
attributes- targetの属性への変更を監視する場合はtrueにします。
attributeOldValueまたはattributeFilterが指定されている場合は省略可能です。 characterData- targetのデータへの変更を監視する場合はtrueにします。
characterDataOldValueが指定されている場合は省略可能です。 subtree- targetだけでなくtargetの子孫への変更まで監視する場合はtrueにします。
attributeOldValue-
attributesがtrueまたは省略時で、targetの属性の値(変更前)も記録する場合はtrueにします。 characterDataOldValue-
characterDataがtrueまたは省略時で、targetのデータ(変更前)も記録する場合はtrueにします。 attributeFilter-
attributesがtrueまたは省略時で、すべての属性を監視しない場合は、監視したい属性のローカル名(名前空間なし)のリストを指定します。
observer .disconnect()- observerによる監視を全て停止します。
observe()メソッドが再度呼ばれるまで、observerのコールバックは呼び出されません。 observer .takeRecords()- レコードキューを空にし、そこにあった内容を返します。
observe(target, options)
メソッドの手順は以下のとおり:
-
もしoptions["
attributeOldValue"] または options["attributeFilter"] が存在し、かつ options["attributes"] が存在しない場合、options["attributes"] をtrueに設定する。 -
もしoptions["
characterDataOldValue"] が存在し、かつoptions["characterData"] が存在しない場合、options["characterData"] をtrueに設定する。 -
options["
childList"], options["attributes"], options["characterData"] のいずれもtrueでなければ、TypeErrorを投げる。 -
もしoptions["
attributeOldValue"] がtrueであり、かつ options["attributes"] がfalseである場合、TypeErrorを投げる。 -
もしoptions["
attributeFilter"] が存在し、かつ options["attributes"] がfalseである場合、TypeErrorを投げる。 -
もしoptions["
characterDataOldValue"] がtrueであり、かつ options["characterData"] がfalseである場合、TypeErrorを投げる。 -
各targetのregistered observer listのregisteredについて、registeredの observerがthisであれば:
-
各thisの node listのnodeについて、nodeのregistered observer listから transient registered observersのうち sourceがregisteredであるものをすべて削除する。
-
registeredのoptionsをoptionsに設定する。
-
-
それ以外の場合:
-
新しいregistered observerで observerがthis、 optionsがoptions であるものをtargetのregistered observer listに追加する。
-
disconnect() メソッドの手順は以下のとおり:
-
各 thisの node listのnodeについて:nodeの registered observer のうち、 thisがobserverであるものをすべて取り除く。
-
thisの record queue を空にする。
takeRecords() メソッドの手順は以下のとおり:
-
recordsをthisの record queue のクローンに設定する。
-
thisの record queue を空にする。
-
recordsを返す。
4.3.2. ミューテーションレコードのキューイング
ミューテーションレコードをキューに入れるには、type・target・name・namespace・oldValue・addedNodes・removedNodes・previousSibling・nextSiblingを使って次を行う:
-
interestedObservers を空の マップにする。
-
nodes を target の包括的な祖先にする。
-
各 nodes の node について、さらに 各 node の registered observer list の registered について:
-
options を registered の optionsにする。
-
次のいずれも真でない場合:
- node が target でなく、options["
subtree"] が false - type が "
attributes" で、options["attributes"] が 存在しない か false である - type が "
attributes"、options["attributeFilter"] が 存在 し、かつ options["attributeFilter"] が name を含まず、または namespace が null でない - type が "
characterData" で、options["characterData"] が 存在しない か false である - type が "
childList" で、options["childList"] が false
ならば:
-
mo を registered の observer にする。
-
もし interestedObservers[mo] が 存在しなければ、interestedObservers[mo] に null を設定する。
-
type が "
attributes" かつ options["attributeOldValue"] が true、または type が "characterData" かつ options["characterDataOldValue"] が true であれば、 interestedObservers[mo] に oldValue を設定する。
- node が target でなく、options["
-
-
interestedObservers の各 observer → mappedOldValue について:
-
record を新しい
MutationRecordオブジェクトにし、そのtypeに type、targetに target、attributeNameに name、attributeNamespaceに namespace、oldValueに mappedOldValue、addedNodesに addedNodes、removedNodesに removedNodes、previousSiblingに previousSibling、nextSiblingに nextSibling を設定する。 -
record を observer の record queue にキューする。
-
observer を surrounding agent の pending mutation observers に追加する。
-
ツリーミューテーションレコードをキューに入れるには、target・addedNodes・removedNodes・previousSibling・nextSibling を使って次を行う:
-
ミューテーションレコードをキューに入れるとき、"
childList"・target・null・null・null・addedNodes・removedNodes・previousSibling・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"を返します。 record .target-
変更が影響したノードを返します。
typeによって結果が異なります。 "attributes"の場合、変更された要素です。 "characterData"の場合、CharacterDataノードです。 "childList"の場合、子ノードが変更されたノードです。 record .addedNodesrecord .removedNodes- それぞれ追加されたノードと削除されたノードを返します。
record .previousSiblingrecord .nextSibling- 追加または削除されたノードのそれぞれ前の兄弟および後の兄弟を返します。該当しなければ null です。
record .attributeName- 変更された属性のローカル名を返します。該当しなければ null です。
record .attributeNamespace- 変更された属性の名前空間を返します。該当しなければ null です。
record .oldValue-
返す値は
typeによって異なります。 "attributes"の場合は、変更された属性の変更前の値です。 "characterData"の場合は、変更されたノードの変更前のデータです。 "childList"の場合は null です。
type、target、
addedNodes、
removedNodes、
previousSibling、
nextSibling、
attributeName、
attributeNamespace、
oldValueの各属性は、それぞれ初期化された値を返す。
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 = 5; // legacyENTITY_REFERENCE_NODE const unsigned short = 6; // legacyENTITY_NODE 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 = 12; // legacyNOTATION_NODE 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 ?); // legacy alias of ===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 は、すべての ノード
が利用する抽象インターフェイスです。直接インスタンス化することはできません。
各ノードは、作成時に設定される ノード文書 を持ちます。これは文書です。
ノードのノード文書は、adoptアルゴリズムによって変更されることがあります。
ノードの親を取得するアルゴリズムは、eventを与えた場合、ノードが割り当てられたスロットを持つ場合はそれを返します(ノードが割り当て済みの場合)。そうでなければ、ノードの親を返します。
各ノードは登録済みオブザーバーリストも持ちます。
node .nodeType-
nodeの型に応じた数値を次のように返します:
Element(1)。Node.ELEMENT_NODEAttr(2)。Node.ATTRIBUTE_NODE- 単独の
Textノード (3)。Node.TEXT_NODECDATASection(4)。Node.CDATA_SECTION_NODEProcessingInstruction(7)。Node.PROCESSING_INSTRUCTION_NODEComment(8)。Node.COMMENT_NODEDocument(9)。Node.DOCUMENT_NODEDocumentType(10)。Node.DOCUMENT_TYPE_NODEDocumentFragment(11)。Node.DOCUMENT_FRAGMENT_NODE
node .nodeName-
nodeの型に応じた文字列を次のように返します:
Element- HTML大文字化された修飾名。
Attr- 修飾名。
- 単独の
Textノード - "
#text"。 CDATASection- "
#cdata-section"。 ProcessingInstruction- target。
Comment- "
#comment"。 Document- "
#document"。 DocumentType- name。
DocumentFragment- "
#document-fragment"。
nodeTypeゲッターの手順は、インターフェースthisがimplementsする型によって最初に一致するものを返します:
ElementELEMENT_NODE(1)AttrATTRIBUTE_NODE(2);- 単独の
Textノード TEXT_NODE(3);CDATASectionCDATA_SECTION_NODE(4);ProcessingInstructionPROCESSING_INSTRUCTION_NODE(7);CommentCOMMENT_NODE(8);DocumentDOCUMENT_NODE(9);DocumentTypeDOCUMENT_TYPE_NODE(10);DocumentFragmentDOCUMENT_FRAGMENT_NODE(11).
nodeNameゲッターの手順は、インターフェースthisがimplementsする型によって最初に一致するものを返します:
Element- そのHTML大文字化修飾名。
Attr- その修飾名。
- 単独の
Textノード - "
#text"。 CDATASection- "
#cdata-section"。 ProcessingInstruction- そのtarget。
Comment- "
#comment"。 Document- "
#document"。 DocumentType- そのname。
DocumentFragment- "
#document-fragment"。
node .baseURI- nodeのノード文書のドキュメントの基底URLを返す。
baseURIゲッターの手順は、
thisの
ノード文書の
ドキュメントの基底URLを直列化して返します。
node .isConnected-
nodeが接続済みならtrue、そうでなければfalseを返します。
node .ownerDocument- ノード文書を返します。 ドキュメントの場合はnullを返します。
node .getRootNode()- nodeのルートを返します。
node . getRootNode({ composed:true })- nodeのシャドウ含むルートを返します。
node .parentNode- 親を返します。
node .parentElement- 親要素を返します。
node .hasChildNodes()- nodeが子を持つかどうか返します。
node .childNodes- 子を返します。
node .firstChild- 最初の子を返します。
node .lastChild- 最後の子を返します。
node .previousSibling- 前の兄弟を返します。
node .nextSibling- 次の兄弟を返します。
isConnected のgetterの手順は、this が connected であれば true を返し、そうでなければ false を返すことです。
ownerDocument のgetterの手順は、this が document であれば null を返し、そうでなければ this の ノード文書
を返すことです。
document の ノード文書 は、その document 自身です。すべての ノードは、常に ノード文書 を持ちます。
getRootNode(options)メソッドの手順は、
options["composed"]がtrueなら
thisの
シャドウ含むルートを返し、そうでなければ
thisのルートを返します。
parentNodeゲッターの手順は、
thisの親を返します。
parentElementゲッターの手順は、
thisの親要素を返します。
hasChildNodes()メソッドの手順は、
thisが子を持つならtrue、そうでなければfalseを返します。
childNodesゲッターの手順は、
thisをルートとし、子のみに一致する
NodeListを返します。
firstChildゲッターの手順は、
thisの最初の子を返します。
lastChildゲッターの手順は、
thisの最後の子を返します。
previousSiblingゲッターの手順は、
thisの前の兄弟を返します。
nextSiblingゲッターの手順は、
thisの次の兄弟を返します。
nodeValueゲッターの手順は、
インターフェースthisがimplementsする型によって次のように返します:
Attr- thisの値。
CharacterData- thisのデータ。
- その他
- Null。
nodeValueセッターの手順は、
渡された値がnullの場合は空文字列として扱い、その後以下の通りに実行します。インターフェースthis
implementsによって切り替えます:
テキストコンテンツ取得は、 ノードnodeについて、インターフェースnodeがimplementsする型によって次のように返します:
DocumentFragmentElement- nodeの子孫テキストコンテンツ。
Attr- nodeの値。
CharacterData- nodeのデータ。
- その他
- Null。
この textContent の getter 手順は、get text content を this に対して実行した結果を返すことです。
文字列 string を使って node parent 内で string replace all を行うには、次の手順を実行します:
-
node を null にします。
-
もし string が空文字列でないなら、node を新しい
Textnode に設定します。このノードの data は string であり、node document は parent の node document です。 -
Replace all を parent 内で node を用いて行います。
set text content を node node と文字列 value で実行するには、以下の定義に従い、インターフェイス node がどの implements しているかによって処理を切り替えます:
DocumentFragmentElement-
String replace all を node 内で value を用いて行います。
Attr-
既存の属性値を設定する を node と value で実行します。
CharacterData- それ以外
-
何もしません。
この textContent
セッターの手順は、与えられた値が null の場合は空文字列として扱い、その後 set text content を this と与えられた値で実行することです。
node .normalize()- 空 の専有
Textノードを削除し、残りの 連続した専有Textノードの データ を、それらの最初の ノードに連結します。
normalize() メソッドの手順は、子孫の 専有
Text ノード node に対して以下の手順を実行します(this のノードについて):
-
length を node の 長さ とする。
-
もし length が0なら、node を削除し、次の 専有
Textノード(あれば)に進む。 -
data を node の 連続した(自身を除く)専有
Textノードの データ を ツリー順 で連結したものとする。 -
node のデータを length, 0, そして data で置き換える。
-
currentNode を node の 次の兄弟 とする。
-
currentNode が 専有
Textノードである間、次を繰り返す:-
currentNode が開始ノードである live range それぞれに対し:start offset に length を加え、start node を node とする。
-
currentNode が終了ノードである live range それぞれに対し:end offset に length を加え、end node を node とする。
-
currentNode の親ノードで start offset が currentNode の index の live range それぞれに対し、 start node を node、start offset を length に設定する。
-
currentNode の親ノードで end offset が currentNode の index の live range それぞれに対し、 end node を node、end offset を length に設定する。
-
length に currentNode の 長さ を加える。
-
currentNode をその 次の兄弟 に更新する。
-
-
node の、(自身を除く)連続した専有
Textノード を ツリー順 で削除する。
node . cloneNode([subtree = false])- node のコピーを返します。subtree が true の場合、コピーには node の子孫も含まれます。
node . isEqualNode(otherNode)- node と otherNode が同じプロパティを持つかどうかを返します。
HTML では クローン手順 を複数の要素(例:
input、script、template)に定義しています。SVG
も
script
要素に対して同様の定義をすべきですが、現時点では定義されていません。
ノードを複製するには、node
node、オプションとしてdocument document(初期値は
node のノード文書)、boolean型 subtree(初期値は false)、nodeまたはnull parent(初期値は null)、nullまたはCustomElementRegistryオブジェクト
fallbackRegistry(初期値は null)で行う:
-
copy を、単一ノードを複製するを node, document, fallbackRegistry で実行した結果とする。
-
parent が null でなければ、append で copy を parent に追加する。
-
subtree が true の場合、node の子それぞれについて、ツリー順で ノードを複製する(child、document=document、subtree=subtree、parent=copy、fallbackRegistry=fallbackRegistryで実行)を行う。
-
node が要素かつシャドウホストであり、node のシャドウルートの複製可能がtrueなら:
-
Assert: copy は shadow host ではありません。
-
shadowRootRegistry を node の shadow root の custom element registry にします。
-
shadowRootRegistry が global custom element registry の場合、 shadowRootRegistry を document の effective global custom element registry に設定します。
-
shadow root を付加します。 copy、node の shadow root の mode、true、 node の shadow root の serializable、node の shadow root の delegates focus、node の shadow root の slot assignment と shadowRootRegistry を使用します。
-
copy の shadow root の declarative を node の shadow root の declarative に設定します。
-
copy の shadow root の keep custom element registry null を node の shadow root の keep custom element registry null に設定します。
-
node の shadow root の children のそれぞれの child について、tree order で:ノードをクローンします。child に document を document、 subtree を subtree に、さらに parent を copy の shadow root に設定します。
これは意図的に fallbackRegistry 引数を渡しません。
-
-
copy を返す。
単一ノードを複製するには、node node、document
document、nullまたはCustomElementRegistry
オブジェクト fallbackRegistry で行う:
-
copy を null とする。
-
node が要素なら:
-
registry を node のcustom element registryとする。
-
registry が null なら registry = fallbackRegistry とする。
-
registry がグローバルcustom element registryなら、 registry = documentのeffective global custom element registryとする。
-
copy を要素を生成する(document、nodeのローカル名、nodeの名前空間、nodeの名前空間プレフィックス、nodeの
is値、false、registry)の結果とする。 -
-
copyAttribute を 単一ノードを複製する(attribute、document、null)で取得する。
-
appendで copyAttribute を copy に追加する。
-
-
-
それ以外の場合、copy を ノード(nodeが実装するインターフェイスと等しいもの)で、以下追加要件を満たすものとする。nodeの実装するインターフェイスにより分岐:
Document-
-
copyのエンコーディング、content type、URL、origin、type、mode、allow declarative shadow roots を nodeの値に設定する。
-
もしnodeのcustom element registryのis scopedがtrueなら、copyのcustom element registryをnodeのcustom element registryに設定する。
-
DocumentTypeAttr-
copyの名前空間、名前空間プレフィックス、ローカル名、値 を nodeの値に設定する。
TextComment-
copyのデータを nodeのデータに設定する。
ProcessingInstruction- それ以外
-
何もしない。
-
node がdocumentなら、document = copyとする。
-
copyのノード文書をdocumentに設定する。
-
copyを返す。
cloneNode(subtree) メソッドの手順は次の通りです:
-
this がシャドウルートなら、"
NotSupportedError"DOMExceptionを投げる。
ノード Aは、以下すべてが true の場合 等しいと判定されます:
-
A と B は、同じインターフェイスを実装している。
-
以下は、Aの実装するインターフェイスにより:
-
AとBは子の数が等しい。
isSameNode(otherNode)
メソッドの手順は、otherNode が this そのものであれば true、そうでなければ false を返します。
node .compareDocumentPosition(other)-
otherがnodeに対してどの位置にあるかを示すビットマスクを返します。設定されうるビットは以下の通りです:
(1)Node.DOCUMENT_POSITION_DISCONNECTED- nodeとotherが同じツリーに属していない場合に設定されます。
(2)Node.DOCUMENT_POSITION_PRECEDING- otherがnodeより先行している場合に設定されます。
(4)Node.DOCUMENT_POSITION_FOLLOWING- otherがnodeより後続している場合に設定されます。
(8)Node.DOCUMENT_POSITION_CONTAINS- otherがnodeの祖先である場合に設定されます。
(16, 10進数で16、16進数で10)Node.DOCUMENT_POSITION_CONTAINED_BY- otherがnodeの子孫である場合に設定されます。
node .contains(other)- otherがnodeの包括的子孫であればtrue、それ以外(nullを含む)はfalseを返します。
これらはcompareDocumentPosition()
がマスクとして返す定数です:
DOCUMENT_POSITION_DISCONNECTED(1);DOCUMENT_POSITION_PRECEDING(2);DOCUMENT_POSITION_FOLLOWING(4);DOCUMENT_POSITION_CONTAINS(8);DOCUMENT_POSITION_CONTAINED_BY(16, 10進数で16、16進数で10);DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC(32, 10進数で32、16進数で20)。
compareDocumentPosition(other)
メソッドの手順は以下の通りです:
-
もし this が other であれば、ゼロを返します。
-
node1 を other に、node2 を this にします。
-
attr1 と attr2 を null にします。
-
もし node1 が attribute であれば、attr1 を node1 に設定し、node1 を attr1 の element にします。
-
もし node2 が attribute の場合:
-
attr2 を node2 に設定し、node2 を attr2 の element にします。
-
もし attr1 と node1 が非 null で、かつ node2 が node1 であれば:
-
For each attr を node2 の attribute list の各要素について行います:
-
もし attr が equals attr1 であれば、次を返します:
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFICとDOCUMENT_POSITION_PRECEDINGを加えた結果。 -
もし attr が equals attr2 であれば、次を返します:
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFICとDOCUMENT_POSITION_FOLLOWINGを加えた結果。
-
-
-
-
もし node1 または node2 が null であるか、あるいは node1 の root が node2 の root と異なる場合、次を返します:
DOCUMENT_POSITION_DISCONNECTED、DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC、 および いずれかのDOCUMENT_POSITION_PRECEDINGまたはDOCUMENT_POSITION_FOLLOWINGを加えた結果を、一貫性を保つように返します。どちらを返すか(
DOCUMENT_POSITION_PRECEDINGかDOCUMENT_POSITION_FOLLOWING)は、通常ポインタ比較によって実装されます。JavaScript 実装ではキャッシュされたMath値を使用することができます。. random() -
もし node1 が ancestor であり node2 の先祖で、かつ attr1 が null である、または node1 が node2 で attr2 が非 null である場合、次を返します:
DOCUMENT_POSITION_CONTAINSとDOCUMENT_POSITION_PRECEDINGを加えた結果。 -
もし node1 が descendant であり node2 の子孫で、かつ attr2 が null である、または node1 が node2 で attr1 が非 null である場合、次を返します:
DOCUMENT_POSITION_CONTAINED_BYとDOCUMENT_POSITION_FOLLOWINGを加えた結果。 -
もし node1 が preceding node2 であれば、次を返します:
DOCUMENT_POSITION_PRECEDING。このアルゴリズムで属性が扱われる方法のため、ノードの属性は、そのノードの子より前にあるものとしてカウントされますが、属性自体は同じツリーには属していません。
-
次に
DOCUMENT_POSITION_FOLLOWINGを返します。
contains(other)メソッドの手順は、
otherが包括的子孫であればtrue、それ以外(null含む)はfalseを返すことです。
名前空間プレフィックスを特定する をelementに対してnamespaceで行うには、以下の手順を実行します:
-
elementの名前空間がnamespaceであり、 名前空間プレフィックスがnullでなければ、 その名前空間プレフィックスを返す。
-
もし element が 属性 を持ち、その 名前空間接頭辞 が "
xmlns" であり、 値 が namespace の場合、 element のそのような最初の 属性 の ローカル名 を返す。 -
elementの親要素がnullでなければ、 その要素に対して 名前空間プレフィックスを特定するをnamespaceで実行した結果を返す。
-
nullを返す。
名前空間を特定するは、 nodeに対しprefixを使い、interface nodeがimplementsする型によって分岐します:
Element-
-
prefixが"
xml"なら、XML名前空間を返す。 -
prefixが"
xmlns"なら、XMLNS名前空間を返す。 -
自身の名前空間がnullでなく、 名前空間プレフィックスがprefixなら 名前空間を返す。
-
もしそれが、属性を持ち、その名前空間がXMLNS 名前空間、名前空間接頭辞が"
xmlns"、ローカル名がprefix、またはprefixが null でそれが属性を持ち、その名前空間がXMLNS 名前空間、名前空間接頭辞が null、ローカル名が"xmlns"の場合、その値が空文字列でなければそれを返し、そうでなければ null を返す。 -
親要素がnullならnullを返す。
-
親要素に対してprefixで名前空間を特定するを実行した結果を返す。
-
DocumentDocumentTypeDocumentFragment-
nullを返す。
Attr- その他
lookupPrefix(namespace)メソッドの手順は:
-
namespaceがnullまたは空文字ならnullを返す。
-
interface thisがimplementsする型によって分岐する:
Element-
名前空間プレフィックスを特定するをthisにnamespaceで実行した結果を返す。
Document-
-
名前空間プレフィックスを特定するをthisの文書要素にnamespaceで実行した結果を返す。
DocumentTypeDocumentFragment-
nullを返す。
Attr-
-
名前空間プレフィックスを特定するをthisの要素にnamespaceで実行した結果を返す。
- その他
-
-
名前空間プレフィックスを特定するをthisの親要素にnamespaceで実行した結果を返す。
lookupNamespaceURI(prefix)メソッドの手順は:
isDefaultNamespace(namespace)メソッドの手順は:
-
namespaceが空文字ならnullに設定する。
-
defaultNamespaceがnamespaceと同じならtrue、そうでなければfalseを返す。
insertBefore(node, child)
メソッドの手順は、nodeを事前挿入としてthisにchildの前に挿入した結果を返すことです。
appendChild(node)メソッドの手順は、
nodeを追加としてthisに追加した結果を返すことです。
replaceChild(node, child)
メソッドの手順は、置換としてchildをnodeにthis内で置換した結果を返すことです。
removeChild(child)メソッドの手順は、
childを事前削除としてthisから削除した結果を返すことです。
qualifiedNameがqualifiedNameの要素リスト をroot(ノード)に対して取得するアルゴリズムは以下です:
-
qualifiedNameがU+002A(*)なら、rootをルートとし、フィルタが子孫要素のみに一致する
HTMLCollectionを返す。 -
そうでなく、rootのノード文書がHTMLドキュメントなら、 rootをルートとし、フィルタが以下の子孫要素に一致する
HTMLCollectionを返す: -
そうでなければ、rootをルートとし、フィルタが子孫要素で、 修飾名がqualifiedNameのものに一致する
HTMLCollectionを返す。
同じ引数で呼び出した場合、かつrootのノード文書の型が変更されていなければ、同じHTMLCollectionオブジェクトが返されることがあります。
namespaceがnamespace、localNameがlocalNameの要素リスト をroot(ノード)に対して取得するアルゴリズムは以下です:
-
namespaceが空文字ならnullに設定する。
-
namespaceとlocalNameが両方U+002A(*)なら、 rootをルートとし、フィルタが子孫要素に一致する
HTMLCollectionを返す。 -
namespaceがU+002A(*)なら、 rootをルートとし、フィルタが子孫要素でローカル名がlocalNameのものに一致する
HTMLCollectionを返す。 -
localNameがU+002A(*)なら、 rootをルートとし、フィルタが子孫要素で名前空間がnamespaceのものに一致する
HTMLCollectionを返す。 -
rootをルートとし、フィルタが子孫要素で名前空間がnamespace・ローカル名がlocalNameのものに一致する
HTMLCollectionを返す。
同じ引数で呼び出した場合、同じHTMLCollectionオブジェクトが返されることがあります。
classNamesがclassNamesの要素リスト をroot(ノード)に対して取得するアルゴリズムは以下です:
- classesをclassNamesに対して順序付き集合パーサーを実行した結果とする。
-
classesが空集合なら、空の
HTMLCollectionを返す。 -
rootをルートとし、フィルタが子孫要素のうち、そのすべてのクラスがclassesに含まれているものに一致する
HTMLCollectionを返す。そのクラスの比較は、rootのノード文書のモードが"
quirks"ならASCII大文字小文字無視、それ以外は完全一致で行うこと。
同じ引数で呼び出した場合、同じHTMLCollectionオブジェクトが返されることがあります。
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 ; // legacy alias of .characterSetreadonly attribute DOMString inputEncoding ; // legacy alias of .characterSetreadonly 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 or ImportNodeOptions )=options false ); [CEReactions ]Node adoptNode (Node ); [node NewObject ]Attr createAttribute (DOMString ); [localName NewObject ]Attr createAttributeNS (DOMString ?,namespace DOMString ); [qualifiedName NewObject ]Event createEvent (DOMString ); // legacy [interface NewObject ]Range createRange (); // NodeFilter.SHOW_ALL = 0xFFFFFFFF [NewObject ]NodeIterator createNodeIterator (Node ,root optional unsigned long = 0xFFFFFFFF,whatToShow optional NodeFilter ?=filter null ); [NewObject ]TreeWalker createTreeWalker (Node ,root optional unsigned long = 0xFFFFFFFF,whatToShow optional NodeFilter ?=filter null ); }; [Exposed =Window ]interface :XMLDocument Document {};dictionary {ElementCreationOptions CustomElementRegistry ?;customElementRegistry DOMString ; };is dictionary {ImportNodeOptions CustomElementRegistry ;customElementRegistry boolean =selfOnly false ; };
Document ノードは、単に 文書として知られています。
各文書は、次の関連する値を持ちます:エンコーディング(エンコーディング)、コンテントタイプ(文字列)、URL(URL)、オリジン(オリジン)、型("xml"または"html")、モード("no-quirks"、"quirks"、または"limited-quirks")、宣言的シャドウルートを許可(boolean)、custom
element registry(null あるいはCustomElementRegistryオブジェクト)。
[ENCODING]
[URL]
[HTML]
特に記載がなければ、文書の エンコーディングは utf-8 エンコーディング、コンテントタイプは "application/xml"、URLは
"about:blank"、オリジンは 不透明なオリジン、型は"xml"、モードは"no-quirks"、宣言的シャドウルートを許可はfalse、custom element
registryはnullです。
文書は、その型が"xml"であればXML文書と言い、そうでなければHTML文書です。文書が HTML文書 か XML文書 かによって、特定のAPIの挙動が変わります。
文書は、no-quirksモード(モードが"no-quirks")、quirksモード(モードが"quirks")、limited-quirksモード(モードが"limited-quirks")にあると言います。
モードは、文書がHTMLパーサにより、DOCTYPE文字列の有無や値に基づいて作成された場合、初期"about:blank"の新しいブラウジングコンテキストによってのみ、デフォルトから変更されます。[HTML]
no-quirksモードは元々「standards mode」と呼ばれていました。また、limited-quirksモードはかつて「almost standards mode」と呼ばれていました。これらの名称は標準で詳細が定義されたため改名されました。(Ian Hicksonが「元の名前は意味不明」として却下したためでもあります。)
文書の親を取得するアルゴリズムは、eventが与えられた時、eventのtype属性の値が"load"の場合や、文書がブラウジングコンテキストを持たない場合はnullを返し、そうでなければ文書の関連グローバルオブジェクトを返します。
document = newDocument()- 新しい文書を返します。
document .implementation- documentの
DOMImplementationオブジェクトを返します。 document .URLdocument .documentURI- documentのURLを返します。
document .compatMode-
documentのモードが"
quirks"のときは文字列"BackCompat"、そうでなければ"CSS1Compat"を返します。 document .characterSet- documentのエンコーディングを返します。
document .contentType- documentのコンテントタイプを返します。
new Document()コンストラクターの手順は、thisのオリジンを、オリジン(current global objectの関連するDocumentのもの)に設定することです。[HTML]
createDocument()と異なり、このコンストラクターはXMLDocumentオブジェクトではなく、文書(Documentオブジェクト)を返します。
implementationのgetter手順は、thisに関連付けられたDOMImplementationオブジェクトを返します。
URLおよびdocumentURIのgetter手順は、thisのURL(シリアライズ済み)を返します。
compatModeのgetter手順は、thisのモードが"quirks"なら"BackCompat"、そうでなければ"CSS1Compat"を返します。
characterSet、charset、inputEncodingのgetter手順は、thisのエンコーディングの名前を返します。
contentTypeのgetter手順は、thisのコンテントタイプを返します。
- document .
doctype - ドキュメント型宣言を返します。存在しない場合は null を返します。
- document .
documentElement - ドキュメント要素を返します。
collection = document . getElementsByTagName(qualifiedName)-
qualifiedName が "
*" の場合、全ての子孫 要素を含むHTMLCollectionを返します。そうでない場合、qualifiedName が一致する子孫要素全てを含む
HTMLCollectionを返します。(HTML要素との比較は HTML名前空間 および HTML文書を対象として、大文字小文字を区別しません。) collection = document . getElementsByTagNameNS(namespace, localName)-
namespace と localName の両方が "
*" の場合、全ての子孫 要素を含むHTMLCollectionを返します。namespaceのみが"
*" の場合、localName が一致する全ての子孫 ローカル名を持つ 要素を含むHTMLCollectionを返します。localNameのみが"
*" の場合、namespace が一致する全ての子孫 名前空間を持つ 要素を含むHTMLCollectionを返します。それ以外の場合、namespaceとlocalName両方が一致する全ての子孫 要素を含む
HTMLCollectionを返します。 collection = document . getElementsByClassName(classNames)collection = element . getElementsByClassName(classNames)-
そのオブジェクト(文書または要素)内でclassNamesで指定されたすべてのクラスを持つ要素の
HTMLCollectionを返します。classNames引数は空白区切りのクラスのリストとして解釈されます。
doctypeゲッターの手順は、thisの子のうちdoctypeであるものを返し、なければnullを返すことです。
documentElementゲッターの手順は、thisの文書要素を返すことです。
getElementsByTagName(qualifiedName)
メソッドの手順は、修飾名がqualifiedNameの要素リストをthisで取得して返すことです。
したがって、HTMLドキュメントでは、
document
は
HTML名前空間ではない<FOO>要素と、
HTML名前空間の<foo>要素には一致しますが、
HTML名前空間の<FOO>要素には一致しません。
getElementsByTagNameNS(namespace, localName)
メソッドの手順は、namespaceがnamespaceかつlocalNameがlocalNameの要素リストをthisで取得して返すことです。
getElementsByClassName(classNames)
メソッドの手順は、classNamesがclassNamesの要素リストをthisで取得して返すことです。
< div id = "example" >
< p id = "p1" class = "aaa bbb" />
< p id = "p2" class = "aaa ccc" />
< p id = "p3" class = "bbb ccc" />
</ div >
document
の呼び出しは、HTMLCollection
を返し、その中には2つの段落
p1 と p2 が含まれる。
getElementsByClassName
の呼び出しは、ただ1つのノード、つまり p3 のみを返す。一方、
document
の呼び出しでも同じ結果が返る。
getElementsByClassName
の呼び出しは、ノードを何も返さない。上記の要素のいずれも aaa,bbb クラスには属していないためである。
element = document . createElement(localName [, options])-
localName を ローカル名として持つ要素を返します(document が HTML文書の時は localName は小文字化されます)。その名前空間は、documentが HTML文書、または document のコンテントタイプが "
application/xhtml+xml" の場合は HTML名前空間、それ以外は null です。options の
customElementRegistryを指定すれば、CustomElementRegistryを設定可能です。options の
isを指定すれば、カスタマイズ組込み要素を作成できます。localName が 有効な要素ローカル名でない場合、"
InvalidCharacterError"DOMExceptionが投げられます。options の
customElementRegistryとisの両方が指定された場合、"NotSupportedError"DOMExceptionが投げられます。 element = document . createElementNS(namespace, qualifiedName [, options])-
名前空間が namespace の要素を返します。名前空間プレフィックスは qualifiedName の U+003A (:) の前部分か null。ローカル名は U+003A (:) の後部分か qualifiedNameです。
options の
customElementRegistryを指定すれば、CustomElementRegistryを設定可能です。options の
isを指定すれば、カスタマイズ組込み要素を作成できます。qualifiedName が(プレフィックス付きでも)有効な要素ローカル名でない場合、"
InvalidCharacterError"DOMExceptionが投げられます。以下のいずれかが真なら"
NamespaceError"DOMExceptionが投げられます:- 名前空間プレフィックスがnull以外で、namespaceが空文字列である。
- 名前空間プレフィックスが"
xml"で、namespaceがXML名前空間でない。 - qualifiedNameまたは名前空間プレフィックスが"
xmlns"で、namespaceがXMLNS名前空間でない。 - namespaceがXMLNS名前空間であり、qualifiedNameも名前空間プレフィックスも"
xmlns"でない。
options の
customElementRegistryとisの両方が指定された場合、"NotSupportedError"DOMExceptionが投げられます。 documentFragment = document .createDocumentFragment()DocumentFragment型のノードを返します。text = document .createTextNode(data)Text型のノードで、dataがdataのものを返します。text = document .createCDATASection(data)CDATASection型のノードで、dataがdataのものを返します。comment = document .createComment(data)Comment型のノードで、dataがdataのものを返します。processingInstruction = document .createProcessingInstruction(target, data)-
ProcessingInstruction型のノードで、targetがtarget、dataがdataのものを返します。targetがName生成規則と一致しない場合、"InvalidCharacterError"DOMExceptionが投げられます。dataに"?>"を含む場合も同様です。
要素インターフェースは、nameとnamespaceに対して特に指定がない限り Element です。
HTML標準では、例えばhtmlとHTML名前空間の場合は HTMLHtmlElement
インターフェースが使用されることが定義されています。[HTML]
createElement(localName, options)
メソッドの手順は以下の通りです:
-
localNameが有効な要素ローカル名でない場合は InvalidCharacterError(
InvalidCharacterError・DOMException)を投げる。 -
thisがHTMLドキュメントの場合、localNameをASCII小文字化する。
-
registryとisをoptionsとthisで要素生成オプションを平坦化するで取得する。
-
namespaceを、HTML名前空間とし、 thisがHTMLドキュメントまたは thisのコンテントタイプが"
application/xhtml+xml"の場合はHTML名前空間、それ以外はnull。 -
要素生成を this、localName、namespace、null、is、true、registryで実行した結果を返す。
内部
createElementNS
手順は、document、namespace、qualifiedName、optionsを受け取って以下の手順を実行します:
-
(namespace, prefix, localName)を、"
element"を与えてnamespaceとqualifiedNameを検証・抽出した結果とする。 -
registryとisを、optionsとthisで要素生成オプションの平坦化を行った結果とする。
-
要素生成をdocument、localName、namespace、prefix、is、true、registryで実行した結果を返す。
createElementNS(namespace, qualifiedName, options)
メソッドの手順は、内部 createElementNS 手順を
this、namespace、qualifiedName、optionsで実行した結果を返すことです。
要素生成オプションの平坦化は、文字列または
ElementCreationOptions
辞書optionsとdocument documentを受け取って以下の手順を実行します:
-
registry を、document を与えて カスタム要素レジストリを検索する の結果とする。
-
is を null にする。
-
もし options が辞書である場合:
-
もし options["
customElementRegistry"] 存在する 場合:-
もし is が null でなければ、throw a "
NotSupportedError"DOMExceptionを投げる。 -
registry を options["
customElementRegistry"] に設定する。
-
-
もし registry が null でなく、registry の is scoped が false であり、かつ registry が document の custom element registry でない場合、throw a "
NotSupportedError"DOMExceptionを投げる。
-
registry と is を返す。
createElement()
および createElementNS()
の options
パラメータは、Web互換性のため文字列も許容されます。
createDocumentFragment() メソッドの手順は、DocumentFragment型の新しいノードを返すことです。そのノード文書はthisです。
createTextNode(data) メソッドの手順は、Text型の新しいノードを返すことです。そのdataはdata、ノード文書はthisです。
createCDATASection(data) メソッドの手順:
-
this がHTML文書なら、"
NotSupportedError"DOMExceptionを投げる。 -
dataに文字列"
]]>"が含まれる場合、"InvalidCharacterError"DOMExceptionを投げる。 -
新しい
CDATASection型のノードを返す。dataはdata、ノード文書はthis。
createComment(data) メソッドの手順は、新しいComment型のノードを返すことです。dataはdata、ノード文書はthisです。
createProcessingInstruction(target, data)
メソッドの手順:
- targetが
Name生成規則と一致しない場合、"InvalidCharacterError"DOMExceptionを投げる。 - dataに"
?>"が含まれる場合、"InvalidCharacterError"DOMExceptionを投げる。 ProcessingInstruction型の新しいノードを返す。targetはtarget、dataはdata、ノード文書はthis。
clone = document . importNode(node [, options = false])-
nodeのコピーを返します。optionsがtrue、またはoptionsの
selfOnlyがfalseのとき、コピーにはnodeの子孫も含まれます。optionsの
customElementRegistryで、CustomElementRegistryのない要素に設定できます。nodeが文書やシャドウルートの場合、"
NotSupportedError"DOMExceptionが投げられます。 node = document . adoptNode(node)-
nodeを他の文書から移動して返します。
nodeが文書の場合、"
NotSupportedError"DOMExceptionが投げられます。nodeがシャドウルートの場合、"HierarchyRequestError"DOMExceptionが投げられます。
importNode(node, options)
メソッドの手順:
-
nodeが文書またはシャドウルートの場合、"
NotSupportedError"DOMExceptionを投げる。 -
subtree をfalseとする。
-
registry をnullとする。
-
optionsがbooleanなら、subtreeをoptionsとする。
-
それ以外:
-
subtreeをoptions["
selfOnly"]の否定で設定。 -
options["
customElementRegistry"]が存在するなら、registryにそれを設定。 -
registryのis scopedがfalse、かつregistryがthisのcustom element registryと異なる場合、"
NotSupportedError"DOMExceptionを投げる。
-
-
registryがnullなら、custom element registryを検索した結果をregistryに代入。
-
ノードを複製する(node、document=this、subtree=subtree、fallbackRegistry=registry)の結果を返す。
adoptは、ノード node を文書 documentに入れる:
-
oldDocumentをnodeのノード文書とする。
-
documentがoldDocumentでないなら:
-
nodeの影を含む包含子孫それぞれについて、影込みツリー順で:
-
inclusiveDescendantのノード文書をdocumentに変更。
-
inclusiveDescendantがシャドウルートで以下のいずれかがtrueの場合:
-
inclusiveDescendantのcustom element registryがnullで、null維持がfalse。
-
inclusiveDescendantのcustom element registryがグローバルcustom element registry。
ならinclusiveDescendantのcustom element registryをdocumentのeffective global custom element registryに設定。
-
-
それ以外の場合、inclusiveDescendantが要素の場合:
-
inclusiveDescendantのcustom element registryがnull、またはcustom element registryのis scopedがfalseの場合、inclusiveDescendantのcustom element registryをdocumentのeffective global custom element registryに設定。
-
-
nodeの影を含む包含子孫でcustomなものそれぞれについて、影込みツリー順でcustom element callback reactionを inclusiveDescendant、callback名 "
adoptedCallback"、«oldDocument, document»でenqueue。 -
nodeの影を含む包含子孫それぞれについて、影込みツリー順でadopt手順をinclusiveDescendant, oldDocumentで実行。
-
adoptNode(node) メソッドの手順:
-
nodeが文書なら、"
NotSupportedError"DOMExceptionを投げる。 -
nodeがシャドウルートなら、"
HierarchyRequestError"DOMExceptionを投げる。 -
nodeが
DocumentFragment型のノードで、hostがnullでなければ、return。 -
nodeを返す。
nullまたはCustomElementRegistry型オブジェクトregistryは、registryがnullでなく、かつregistryのis scopedがfalseならグローバルcustom element registryである。
文書documentのeffective global custom element registryは:
-
documentのcustom element registryがグローバルcustom element registryなら、それを返す。
-
nullを返す。
createAttribute(localName) メソッドの手順:
-
localNameが有効な属性ローカル名でなければ、"
InvalidCharacterError"DOMExceptionを投げる。 - thisがHTML文書なら、localNameをASCII小文字に変換。
createAttributeNS(namespace, qualifiedName)
メソッドの手順:
-
(namespace, prefix, localName) を validate and extract(namespace, qualifiedName, "
attribute")した結果とする。 -
新しい属性を返す。名前空間がnamespace、名前空間プレフィックスがprefix、ローカル名がlocalName、ノード文書がthis。
createEvent(interface) メソッドの手順:
-
constructor をnullとする。
-
interfaceが下表の左欄の文字列とASCII大文字小文字区別無し一致なら、右欄のインターフェイスをconstructorにセット:
文字列 インターフェイス 備考 " 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" -
constructorがnullなら、"
NotSupportedError"DOMExceptionを投げる。 -
constructorで示されるインターフェイスがrelevant global objectに公開されていない場合、"
NotSupportedError"DOMExceptionを投げる。通常はユーザーエージェントが特定構成でタッチイベントを無効化するため、
TouchEventインターフェイスでこの条件になる。 -
constructorを使いイベントを生成し、eventとする。
-
eventの
type属性を空文字列で初期化。 -
eventの
timeStamp属性を、current high resolution time(thisのrelevant global object)で初期化。 -
eventの
isTrusted属性をfalseで初期化。 -
eventのinitialized flagをUnset。
-
eventを返す。
Eventのコンストラクターの利用が推奨されます。
createRange() メソッドの手順は、(this, 0)を開始・終端とする新しいライブ範囲を返すこと。
Range()コンストラクターも利用できます。
createNodeIterator(root, whatToShow, filter)
メソッドの手順:
-
iteratorを新しい
NodeIteratorオブジェクトとする。 -
iteratorのpointer before referenceをtrueに設定。
-
iteratorのwhatToShowをwhatToShowに設定。
-
iteratorのfilterをfilterに設定。
-
iteratorを返す。
createTreeWalker(root, whatToShow, filter)
メソッドの手順:
-
walkerを新しい
TreeWalkerオブジェクトとする。 -
walkerのwhatToShowをwhatToShowに設定。
-
walkerのfilterをfilterに設定。
-
walkerを返す。
4.5.1.
インターフェース DOMImplementation
ユーザーエージェントはドキュメントが
作成されるたびにDOMImplementation
オブジェクトを生成し、そのドキュメントに関連付けなければならない。
[Exposed =Window ]interface { [DOMImplementation NewObject ]DocumentType createDocumentType (DOMString ,name DOMString ,publicId DOMString ); [systemId NewObject ]XMLDocument createDocument (DOMString ?, [namespace LegacyNullToEmptyString ]DOMString ,qualifiedName optional DocumentType ?=doctype null ); [NewObject ]Document createHTMLDocument (optional DOMString );title boolean hasFeature (); // useless; always returns true };
doctype = document .implementation.createDocumentType(name, publicId, systemId)-
指定されたname、publicId、systemIdでdoctypeを返します。
nameが有効なドキュメント型名でない場合、"
InvalidCharacterError"DOMExceptionが投げられます。 doc = document .implementation. createDocument(namespace, qualifiedName [, doctype = null])-
XMLDocumentを返します。 文書要素の ローカル名がqualifiedNameで、 名前空間がnamespace(qualifiedNameが空文字列でない場合)となります。また、doctypeが指定されていればそのdoctypeも持ちます。このメソッドは
createElementNS()メソッドと同じ例外を、namespaceとqualifiedNameを指定した場合に投げます。 doc = document .implementation. createHTMLDocument([title])-
documentを返します。
基本的なツリーが既に構築されており、
title要素も含まれます(title引数が省略された場合を除く)。
createDocumentType(name, publicId, systemId)
メソッドの手順は次の通りです:
-
もし name が有効な doctype 名でなければ、"
InvalidCharacterError"DOMExceptionを投げる。 -
新しいdoctype を返す。その name は name、public ID は publicId、system ID は systemId、ノードドキュメント は document(this に関連するもの)に設定される。
createDocument(namespace, qualifiedName, doctype)
メソッドの手順は次の通りです:
-
document を新しい
XMLDocumentとする。 -
element を null にする。
-
もし qualifiedName が空文字列でなければ、element に internal
createElementNSステップ を document, namespace, qualifiedName, 空辞書を渡して実行した結果をセットする。 -
もし doctype が null でなければ、append で doctype を document に追加する。
-
もし element が null でなければ、append で element を document に追加する。
-
document の content type は namespace に応じて次を値にする:
-
document を返す。
createHTMLDocument(title)
メソッドの手順は次の通りです:
-
doc の コンテントタイプを "
text/html" に設定する。 -
もし title が与えられている場合:
-
docを返す。
hasFeature()
メソッドの手順は true を返すことである。
hasFeature()
は元々ユーザーエージェントが指定した DOM
機能をサポートしているかどうかを報告するためのものでしたが、実際には求めるオブジェクトや属性、メソッドの有無を直接確認する方が遥かに確実かつ細やかであることが分かりました。そのため、現在では使用するべきではありませんが、古いページが動作しなくならないよう残っており(単に
true を返します)、新たな用途には利用されるべきではありません。
4.6. インターフェース DocumentType
[Exposed =Window ]interface :DocumentType Node {readonly attribute DOMString name ;readonly attribute DOMString publicId ;readonly attribute DOMString systemId ; };
DocumentType
ノードは単に
doctypeとして知られています。
Doctypeには、 関連付けられた name、 public ID、 system ID があります。
Doctypeが作成されるとき、 nameは 必ず与えられます。Doctypeが作成される際に明示的に与えられない限り、 public IDと system IDは 空文字列になります。
nameゲッター手順は、
thisの
nameを返すことです。
publicIdゲッター手順は、
thisの
public
IDを返すことです。
systemIdゲッター手順は、
thisの
system
IDを返すことです。
4.7.
インターフェイス DocumentFragment
[Exposed =Window ]interface :DocumentFragment Node {constructor (); };
DocumentFragment型のノードは、関連するhost(null または異なるノードツリー内の要素)を持ちます。特に明記されていない場合は null です。
オブジェクトAがオブジェクトBのhost込み包含祖先であるとは、AがBの包含祖先である場合、またはBの根が非nullのhostを持ち、かつAがBの根のhostのhost込み包含祖先である場合です。
DocumentFragment型のノードのhostという概念は、HTMLのtemplate要素やシャドウルートで役立ち、pre-insertやreplaceアルゴリズムにも影響します。
tree = newDocumentFragment()- 新しい
DocumentFragment型ノードを返します。
new DocumentFragment()コンストラクターの手順は、thisのノード文書をcurrent global objectに関連付けられた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
ノードは単に
シャドウルートとして知られている。
シャドウルートには
モード
("open" または "closed")が関連付けられている。
シャドウルートには delegates focus (真偽値)が関連付けられている。初期値はfalseである。
シャドウルートには available to element internals (真偽値)が関連付けられている。初期値はfalseである。
シャドウルートには declarative (真偽値)が関連付けられている。初期値はfalseである。
シャドウルートには
slot assignment
("manual" または "named")が関連付けられている。
シャドウルートには clonable (真偽値)が関連付けられている。初期値はfalseである。
シャドウルートには serializable (真偽値)が関連付けられている。初期値はfalseである。
シャドウルートには
カスタム要素レジストリ
(null または CustomElementRegistry
オブジェクト)が関連付けられている。初期値はnullである。
シャドウルートには keep custom element registry null (真偽値)が関連付けられている。初期値はfalseである。
これは宣言的シャドウルートと組み合わせてのみ真になり得る。また、シャドウルートの カスタム要素レジストリ がnullである間だけ意味がある。
シャドウルートの 親を取得 アルゴリズムは、eventを受け取り、eventのcomposed flagがunsetで シャドウルートが eventのパスの最初のstructの 起動ターゲットの rootの場合、nullを返す; それ以外はシャドウルートの ホストを返す。
mode
のゲッターの手順は
thisの
モードを返すことである。
delegatesFocus
のゲッターの手順は
thisの
delegates focus
を返すことである。
slotAssignment
のゲッターの手順は
thisの
slot
assignment
を返すことである。
clonable
のゲッターの手順は
thisの
clonable
を返すことである。
serializable
のゲッターの手順は
thisの
serializable
を返すことである。
host
のゲッターの手順は
thisの
host
を返すことである。
onslotchange
属性は
イベントハンドラーIDL属性
であり、
onslotchange
イベントハンドラーである。その
イベントハンドラーイベント型
は slotchange
である。
シャドウを含む木順は、 シャドウを含む先行・深さ優先走査 によりノードツリーを辿る。 シャドウを含む先行・深さ優先走査 とは、ノードツリー tree に対して、tree内で遭遇した各シャドウホストについて、その シャドウルートの ノードツリーも、 その直後に同様の走査を行う、という形での先行・深さ優先探索である。
シャドウを含むroot とは、オブジェクトのrootが シャドウルートである場合、 そのホストの シャドウを含むrootがそれに該当し、 そうでなければ単にそのrootとなる。
オブジェクトAが、オブジェクトBの シャドウを含む子孫 であるとは、AがBの子孫である場合、 またはAのrootが シャドウルートで、かつ Aのrootの ホストが Bのシャドウを含む包含する子孫で ある場合である。
シャドウを含む包含する子孫 とは、自分自身またはそのシャドウを含む子孫の一つである。
オブジェクトAが、オブジェクトBの シャドウを含む祖先 であるとは、かつその時に限り、BがAのシャドウを含む子孫である場合である。
シャドウを含む包含する祖先 とは、自分自身またはそのシャドウを含む祖先の一つである。
ノードAが ノードBから closed-shadow-hidden になるとは、次のすべての条件が成り立つときである:
オブジェクトAをオブジェクトBに対して retarget するには、オブジェクトが返るまで次の手順を繰り返す:
-
以下のいずれかが真の場合:
その場合、A を返す。
retargeting アルゴリズムは イベントディスパッチ や他の仕様(例えば 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 TrustedType or DOMString )); [value CEReactions ]undefined setAttributeNS (DOMString ?,namespace DOMString , (qualifiedName TrustedType or 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 ;readonly attribute CustomElementRegistry ?customElementRegistry ;Element ?closest (DOMString );selectors boolean matches (DOMString );selectors boolean webkitMatchesSelector (DOMString ); // legacy alias of .matchesselectors HTMLCollection getElementsByTagName (DOMString );qualifiedName HTMLCollection getElementsByTagNameNS (DOMString ?,namespace DOMString );localName HTMLCollection getElementsByClassName (DOMString ); [classNames CEReactions ]Element ?insertAdjacentElement (DOMString ,where Element ); // legacyelement undefined insertAdjacentText (DOMString ,where DOMString ); // legacy };data dictionary {ShadowRootInit required ShadowRootMode ;mode boolean =delegatesFocus false ;SlotAssignmentMode = "named";slotAssignment boolean =clonable false ;boolean =serializable false ;CustomElementRegistry ?; };customElementRegistry
ShadowRootInit
はやや珍しく、undefinedおよびnullの両方を
customElementRegistry
メンバーに渡すことができ、Web
開発者が辞書ではなくShadowRoot
ノードをattachShadow()
に渡せるようにしています。
要素には、次の関連付けられた値があります:
- 名前空間
- null または空でない文字列。
- 名前空間接頭辞
- null または空でない文字列。
- ローカル名
- 空でない文字列。
- カスタム要素レジストリ
- null または
CustomElementRegistryオブジェクト。 - カスタム要素状態
- "
undefined", "failed", "uncustomized", "precustomized", または "custom"。 - カスタム要素定義
- null または カスタム要素定義。
is値- null または 有効なカスタム要素名。
要素が作成されるとき、 これらすべての値が 初期化されます。
要素のカスタム要素状態が
"uncustomized" または "custom" である場合、
定義済みとされます。要素の
カスタム要素状態が "custom" である場合、
カスタムとされます。
要素が定義済みかどうかは、
:defined
疑似クラスの挙動を決定するために使われます。要素がカスタムかどうかは
mutation アルゴリズムの挙動を決定するために使われます。
"failed"および"precustomized"状態は、
カスタム要素コンストラクタが初回に正しく実行されない場合、
upgradeによって再度実行されないよう保証するために使われます。
以下のコードは、これら4つの状態それぞれの要素を示します:
<!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() intentionally omitted for this example
}
})
</ script >
<!-- "undefined" (未定義、カスタムでない) -->
< sw-han ></ sw-han >
< p is = "sw-luke" ></ p >
< p is = "asdf" ></ p >
<!-- "failed" (未定義、カスタムでない) -->
< sw-kylo ></ sw-kylo >
<!-- "uncustomized" (定義済み、カスタムでない) -->
< p ></ p >
< asdf ></ asdf >
<!-- "custom" (定義済み、カスタム) -->
< sw-rey ></ sw-rey >
< p is = "sw-finn" ></ p >
要素にも、 関連付けられた シャドウルート(null または シャドウルート)があります。特別な記述がない限り null です。 要素は、 そのシャドウルートが null でない場合、 シャドウホストとされます。
要素の
qualified name(修飾名)は、
名前空間接頭辞が null の場合は
ローカル名、
そうでなければ、
名前空間接頭辞、":"、そして
ローカル名を順に連結したものです。
要素の HTML大文字修飾名は、次の手順の戻り値です:
ユーザーエージェントは 修飾名や HTML大文字修飾名を内部スロットに格納することで最適化可能です。
要素を作成するには、
document
document、文字列 localName、文字列または null namespace、
オプションで文字列または null prefix(省略時は null)、文字列または null is(省略時は null)、
真偽値 synchronousCustomElements(省略時は false)、
"default"、null、または CustomElementRegistry
オブジェクト registry(省略時は "default")を与えて次の手順を実行します:
-
result を null にする。
-
registry が "
default" なら、 registry を カスタム要素レジストリの検索の結果にする(引数は document)。 -
definition を カスタム要素定義の検索 の結果にする(引数は registry, namespace, localName, is)。
-
definition が null でなく、かつ definition の name が local name と等しくない場合(つまり カスタマイズされた組み込み要素の場合):
-
interface を element interfaceの localName と HTML名前空間に対するものにする。
-
result を 要素内部の作成の結果にする (引数は document, interface, localName, HTML名前空間, prefix, "
undefined", is, registry)。 -
synchronousCustomElements が true の場合、例外をキャッチしつつ下記を実行:
このステップで例外 exception が発生した場合:
-
例外を報告する exception を definition の constructor に対応する JavaScript オブジェクトの 関連付けられた realm の グローバルオブジェクト に対して報告する。
-
result の カスタム要素状態を "
failed" に設定する。
-
-
それ以外の場合は カスタム要素アップグレードリアクションをキューする (引数は result と definition)。
-
-
それ以外で definition が null でない場合:
-
synchronousCustomElements が true の場合:
-
C を definition の constructor とする。
-
surrounding agent の active custom element constructor map[C] に registry を設定する。
-
例外をキャッチしつつ次を実行:
-
result を C を構築する結果にする(引数なし)。
-
Assert: result の 名前空間は HTML 名前空間。
IDL により result は
HTMLElementオブジェクトとなり、すべて HTML 名前空間を使用します。 -
result の 属性リストが 空でない場合は、 NotSupportedError
DOMExceptionをスローする。 -
result に 子がある場合は、 NotSupportedError
DOMExceptionをスローする。 -
result の 親が null でない場合は NotSupportedError
DOMExceptionをスローする。 -
result の ノード文書が documentでない場合は NotSupportedError
DOMExceptionをスローする。 -
result の ローカル名が localNameと等しくない場合は NotSupportedError
DOMExceptionをスローする。 -
result の 名前空間接頭辞を prefixに設定する。
-
result の
is値を null に設定する。 -
result の カスタム要素レジストリを registryに設定する。
これらのステップで例外 exception が発生した場合:
-
例外を報告する exception を definition の constructor に対応する JavaScript オブジェクトの 関連付けられた realm の グローバルオブジェクト に対して報告する。
-
result を 要素内部の作成の結果にする (引数は document,
HTMLUnknownElement, localName, HTML名前空間, prefix, "failed", null, registry)。
-
-
surrounding agent の active custom element constructor map[C] を削除する。
通常はこの時点でもう削除されているはずです。
-
-
それ以外の場合:
-
result を 要素内部の作成の結果にする (引数は document,
HTMLElement, localName, HTML名前空間, prefix, "undefined", null, registry)。 -
カスタム要素アップグレードリアクションをキューする (引数は result と definition)。
-
-
-
それ以外の場合:
-
interface を element interface の localName と namespaceに対するものにする。
-
result を 要素内部の作成の結果にする (引数は document, interface, localName, namespace, prefix, "
uncustomized", is, registry)。 -
namespace が HTML名前空間であり、 localName が 有効なカスタム要素名であるか、is が null でない場合は result の カスタム要素状態を "
undefined" に設定する。
-
-
result を返す。
要素内部を作成するには、document document、インターフェイス interface、文字列
localName、文字列または null namespace、文字列または null prefix、文字列
state、文字列または null is、null または CustomElementRegistry
オブジェクト registry を与えて次の手順を実行します:
-
element を新しい要素(interfaceを実装し、 名前空間を namespace、 名前空間接頭辞を prefix、 ローカル名を localName、 カスタム要素レジストリを registry、 カスタム要素状態を state、 カスタム要素定義を null、
is値を is、 ノード文書を documentに設定したもの)とする。 -
elementを返す。
要素には
属性リストもあり、これは
リストで
NamedNodeMap
を通して公開されます。
要素が作成される際に明示的に与えられない限り、
その属性リストは
空です。
要素は 属性を持つとは、その属性リストが 属性Aを 含む場合です。
これおよび他の仕様は 属性変更手順を 要素に対して定義することができます。アルゴリズムには element、localName、 oldValue、value、namespaceが渡されます。
属性変更を処理するには、 属性 attribute、element、oldValue、newValueを使い、下記手順を実行します:
-
mutation record の "
attributes" を elementに対して、attributeのローカル名、attributeの 名前空間、oldValue、« »、« »、null、null で キューする。 -
element が カスタムなら、 カスタム要素コールバックリアクションをキューする (引数は element、コールバック名 "
attributeChangedCallback"、« attributeのローカル名、 oldValue、newValue、attributeの名前空間 »)。 -
属性変更手順を element、attributeの ローカル名、oldValue、 newValue、attributeの 名前空間で実行する。
属性を変更するには、 属性 attribute を valueに変更する場合、次の手順を実行します:
属性を追加するには、 属性 attribute を 要素 element に追加する場合、次の手順を実行します:
-
attributeの要素を elementに設定する。
属性を除去するには、 属性 attribute を除去する場合、次の手順を実行します:
属性を置換するには、 属性 oldAttribute を 属性 newAttributeで置換する場合:
-
element を oldAttributeの要素とする。
-
newAttributeの要素を elementに設定する。
-
oldAttributeの要素を null に設定する。
-
属性変更を処理する(引数は oldAttribute、element、oldAttributeの値、newAttributeの 値)。
文字列 qualifiedName と要素 elementを与えて 名前で属性を取得するには:
null または文字列 namespace、文字列 localName、要素 elementを与えて 名前空間とローカル名で属性を取得するには:
要素 element、文字列 localName、オプションの null または文字列 namespace(省略時は null)を与えて 属性値を取得するには:
属性を設定するには、 属性 attr と 要素 element を与える:
-
verifiedValue を、 get trusted type compliant attribute value に attr の local name、 attr の namespace、 element、 attr の value を渡して呼び出した結果とする。[TRUSTED-TYPES]
-
もし attr の element が null でもなく、かつ element でもない場合は、 throw し、 "
InUseAttributeError"DOMExceptionを発生させる。 -
oldAttr を、 属性を取得する(attr の namespace、attr の local name、element を与える)した結果とする。
-
もし oldAttr が attr であれば、attr を返す。
-
attr の value を verifiedValue に設定する。
-
oldAttr が null でなければ、置換する(oldAttr を attr で)。
-
そうでなければ、追加する(attr を element に)。
-
oldAttr を返す。
属性値を設定するには、 要素 element、文字列 localName、文字列 value、 省略可能な null または文字列 prefix(既定値は null)、省略可能な null または文字列 namespace(既定値は null)を与える:
文字列 qualifiedName と要素 elementを与えて 名前で属性を除去するには:
-
attr を 名前で属性を取得するの結果とする(引数は qualifiedName, element)。
-
attr が null でなければ、除去 attr。
-
attr を返す。
null または文字列 namespace、文字列 localName、要素 elementを与えて 名前空間とローカル名で属性を除去するには:
要素は 一意な識別子(ID)を持つことができます。
歴史的に、要素は複数の識別子を持つことができました。たとえば、HTMLのid属性やDTDを使用することによってです。本仕様はIDをDOMの概念とし、要素ごとに一つだけ、id属性によって与えられるようにしています。
-
もし localName が
idであり、namespace が null かつ value が null または空文字列であれば、element の ID を未設定にする。 -
それ以外で localName が
idかつ namespace が null の場合、element の ID を value に設定する。
本仕様は、あらゆる 要素 における class、id、
slot 属性について要件を定義しているが、それらを使用することが適合であるかどうかは定めていない。
ノードの親が
Element
型の場合、それはそのノードの
親要素と呼ばれます。もしノードの親が異なる型であれば、
その親要素は null となります。
- namespace = element .
namespaceURI - 名前空間を返します。
- prefix = element .
prefix - 名前空間接頭辞を返します。
- localName = element .
localName - ローカル名を返します。
- qualifiedName = element .
tagName - HTML大文字修飾名を返します。
namespaceURIゲッター手順は
thisの名前空間を返すことです。
prefixゲッター手順は
thisの名前空間接頭辞を返すことです。
localNameゲッター手順は
thisのローカル名を返すことです。
tagNameゲッター手順は
thisのHTML大文字修飾名を返すことです。
element . id [ = value ]-
elementの
id内容属性の値を返します。設定することで値を変更できます。 element . className [ = value ]-
elementの
class内容属性の値を返します。設定することで値を変更できます。 element . classList-
elementの
class内容属性をDOMTokenListオブジェクトを通じて、空白区切りのトークン集合として操作できます。 element . slot [ = value ]-
elementの
slot内容属性の値を返します。設定することで値を変更できます。
文字列nameを反映するよう定義されたIDL属性は、以下のgetter・setter手順を持ちます:
id属性は「id」を反映しなければなりません。
className属性は
「class」を反映しなければなりません。
classListゲッター手順は、
DOMTokenList
オブジェクトを返すことです。関連付けられた要素はthis、関連付けられた
属性のローカル名は「class」です。この
DOMTokenList
オブジェクトのトークン集合は、要素の
クラスとも呼ばれます。
slot属性は「slot」を反映しなければなりません。
id、class、slotは、どの要素にも現れることができ、
要素がどの名前空間に属していても有効な、事実上のスーパーグローバル属性です。
element . hasAttributes()-
element が属性を持っていれば true を返し、そうでなければ false を返す。
element . getAttributeNames()element . getAttribute(qualifiedName)element . getAttributeNS(namespace, localName)-
namespace かつ localName に該当する 属性を返し、該当がなければ null を返す。
element . setAttribute(qualifiedName, value)-
qualifiedName の最初の 属性の値を value に設定する。
element . setAttributeNS(namespace, localName, value)-
namespace かつ localName の 属性の値を value に設定する。
element . removeAttribute(qualifiedName)-
qualifiedName の最初の 属性を削除する。
element . removeAttributeNS(namespace, localName)-
namespace かつ localName の 属性を削除する。
element . toggleAttribute(qualifiedName [, force])-
force が指定されていない場合は qualifiedName を「トグル」し、存在すれば削除し、存在しなければ追加する。force が true なら追加、false なら削除。
qualifiedName が現在存在すれば true、そうでなければ false を返す。
element . hasAttribute(qualifiedName)-
qualifiedName を持つ 属性があれば true、なければ false を返す。
element . hasAttributeNS(namespace, localName)-
namespace かつ localName を持つ 属性があれば true を返す。
attributes ゲッターの手順は、関連付けられた
NamedNodeMap
を返す。
getAttribute(qualifiedName)
メソッドの手順は以下の通り:
getAttributeNS(namespace, localName)
メソッドの手順は以下の通り:
-
attr を 名前空間で属性を取得した結果(namespace, localName, this)とする。
-
attr が null なら、null を返す。
-
attr の 値 を返す。
setAttribute(qualifiedName, value)
メソッドの手順は以下の通り:
-
qualifiedName が 有効な属性ローカル名 でなければ、 "
InvalidCharacterError"DOMExceptionを throw する。パラメータ名にかかわらず、 qualifiedName はすでにその名前の 属性 があれば修飾名として、なければ新しい属性の ローカル名 として使われるため、 後者の場合のみバリデーションが必要となる。
-
this が HTML 名前空間 かつ ノード文書 が HTML document なら、 qualifiedName を ASCII小文字 にする。
-
verifiedValue を 信頼された型の属性値取得関数 (qualifiedName, null, this, value)の結果とする。
-
qualified name が qualifiedName である最初の 属性(なければ null)を attribute とする。
-
attribute が null でなければ 変更し、attribute を verifiedValue にして return。
-
新規の 属性(ローカル名は qualifiedName、値は verifiedValue、 ノード文書は this の ノード文書とする)を attribute とする。
setAttributeNS(namespace, qualifiedName, value)
メソッドの手順は以下の通り:
-
(namespace, prefix, localName) を 検証と抽出(namespace, qualifiedName, "
attribute")の結果とする。 -
verifiedValue を 信頼された型の属性値取得関数 (localName, namespace, this, value)の結果とする。
-
属性値を設定(this, localName, verifiedValue, prefix, namespace)を行う。
removeAttributeNS(namespace, localName)
メソッドの手順は、名前空間で属性を削除(namespace,
localName, this)し、undefined を返す。
hasAttribute(qualifiedName)
メソッドの手順は以下の通り:
-
this が HTML 名前空間 かつ ノード文書 が HTML document なら、 qualifiedName を ASCII小文字 にする。
-
has メソッドで 属性(qualified name が qualifiedName)が存在すれば true、なければ false を返す。
toggleAttribute(qualifiedName, force)
メソッドの手順は以下の通り:
-
qualifiedName が 有効な属性ローカル名 でなければ、 "
InvalidCharacterError"DOMExceptionを throw する。「ローカル名」としてバリデーションする理由は上記の議論を参照。
-
this が HTML 名前空間 かつ ノード文書 が HTML document なら、 qualifiedName を ASCII小文字 にする。
-
qualified name が qualifiedName である最初の 属性(なければ null)を attribute とする。
-
attribute が null の場合:
-
それ以外で force が指定されていないか false なら、 名前で属性を削除(qualifiedName, this)して false を返す。
-
true を返す。
hasAttributeNS(namespace, localName)
メソッドの手順は以下の通り:
getAttributeNode(qualifiedName)
メソッドの手順は
qualifiedNameで属性を取得し
thisとともに返します。
getAttributeNodeNS(namespace, localName)
メソッドの手順は
namespaceで属性を取得し
namespace・localName・thisで返します。
removeAttributeNode(attr)メソッドの手順は以下の通りです:
-
this の 属性リストに attrが含まれて いなければ、 例外を投げ、 "
NotFoundError"DOMExceptionとします。 -
attrを削除します。
-
attrを返します。
shadow = element .attachShadow(init)-
elementにシャドウルートを生成し、それを返します。
shadow = element .shadowRoot-
elementのシャドウルート(存在する場合、かつシャドウルートのmodeが"
open"の場合)を返します。そうでなければnull。
有効なシャドウホスト名は:
- 有効なカスタム要素名
- "
article", "aside", "blockquote", "body", "div", "footer", "h1", "h2", "h3", "h4", "h5", "h6", "header", "main", "nav", "p", "section", または "span"
attachShadow(init) メソッドの手順は以下の通り:
-
registry を this の node document の カスタム要素レジストリ とする。
-
もし init["
customElementRegistry"] が 存在する 場合、 registry にその値を設定する。 -
もし registry が non-null で、registry の is scoped が false であり、かつ registry が this の node document の custom element registry でない場合、throw a "
NotSupportedError"DOMExceptionを投げる。 -
シャドウルートをアタッチする を this, init["
mode"], init["clonable"], init["serializable"], init["delegatesFocus"], init["slotAssignment"], および registry で実行する。
シャドウルートを付与するには、
要素
element、文字列 mode、真偽値 clonable、
真偽値 serializable、真偽値 delegatesFocus、文字列
slotAssignment、null または CustomElementRegistry
オブジェクト registryを与える:
-
elementの名前空間がHTML名前空間でない場合、 NotSupportedError
NotSupportedErrorDOMExceptionをスローする。 -
elementのローカル名が 有効なシャドウホスト名でない場合、 NotSupportedError
NotSupportedErrorDOMExceptionをスローする。 -
elementのローカル名が有効なカスタム要素名である、または elementの
is値がnullでない場合:-
definition を カスタム要素定義の検索 (引数は elementのカスタム要素レジストリ、名前空間、ローカル名、
is値)とする。 -
definitionが null でなく、かつ definitionの disable shadowがtrueなら、 NotSupportedError
NotSupportedErrorDOMExceptionをスローする。
-
-
elementがシャドウホストの場合:
-
currentShadowRoot を elementのシャドウルートとする。
-
以下いずれかが真の場合:
-
currentShadowRootのdeclarativeがfalse
-
currentShadowRootのmodeが modeと異なる
この場合は NotSupportedError
NotSupportedErrorDOMExceptionをスローする。 -
-
それ以外の場合:
-
currentShadowRootのdeclarativeをfalseにする。
-
return。
-
-
shadow を新しい シャドウルート とし、その ノード文書 は element の ノード文書、ホスト は element、モード は mode である。
-
shadowのdelegates focusを delegatesFocusに設定する。
-
elementのカスタム要素状態が"
precustomized"または"custom"の場合、 shadowのelement internalsで利用可能をtrueにする。 -
shadowのslot assignmentを slotAssignmentに設定する。
-
shadowのdeclarativeをfalseに設定する。
-
shadowのclonableを clonableに設定する。
-
shadowのserializableを serializableに設定する。
-
shadowのcustom element registryを registryに設定する。
-
elementのシャドウルートを shadowに設定する。
shadowRoot ゲッターの手順は次の通り:
-
registry = element .customElementRegistry -
element の
CustomElementRegistryオブジェクト(存在する場合)、なければ null を返す。
customElementRegistry ゲッターの手順は、
this の
カスタム要素レジストリを返すこと。
-
element .closest(selectors) - element から始めて、selectors にマッチする最初の 包含祖先を返し、見つからなければ null を返す。
-
element .matches(selectors) - element の ルート で selectors をマッチングしたときに element が得られれば true、そうでなければ false を返す。
closest(selectors) メソッドの手順は次の通りです:
-
selector を selectors から セレクターを構文解析した結果とする。 [SELECTORS4]
-
もし selector が失敗なら、throw して "
SyntaxError"DOMExceptionを投げる。 -
elements の各 element について:セレクターを要素にマッチ(selector・element・スコーピングルート this) が成功なら element を返す。 [SELECTORS4]
-
null を返す。
matches(selectors) および
webkitMatchesSelector(selectors)
メソッドの手順は次の通りです:
-
selector を selectors から セレクターを構文解析した結果とする。 [SELECTORS4]
-
もし selector が失敗なら、throw して "
SyntaxError"DOMExceptionを投げる。 -
セレクターを要素にマッチ(selector、this、スコーピングルート this) が成功なら true を、そうでなければ false を返す。 [SELECTORS4]
getElementsByTagName(qualifiedName)
メソッドの手順は、qualifiedName を持つ要素のリスト を
this について返すこと。
getElementsByTagNameNS(namespace, localName)
メソッドの手順は、namespace と localName を持つ要素のリスト を
this について返すこと。
getElementsByClassName(classNames)
メソッドの手順は、classNames を持つ要素のリスト を
this について返すこと。
隣接挿入するには、 要素 element、文字列 where、 そして ノード node を受け取り、 where に対する最初の ASCII大文字小文字無視一致に関連付けられた手順を実行する:
- "
beforebegin" -
もし element の 親 が null なら、null を返す。
- "
afterbegin" - "
beforeend" -
element において null の前で node を 事前挿入した結果を返す。
- "
afterend" -
もし element の 親 が null なら、null を返す。
- それ以外
insertAdjacentElement(where, element)
メソッドの手順は、隣接挿入を実行し、
this、where、element を与えて返すことである。
insertAdjacentText(where, data)
メソッドの手順は以下の通り:
このメソッドは我々が設計する前から存在していたため何も返さない。
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には、関連付けられた要素(element)があります。
NamedNodeMapオブジェクトの属性リストは、その要素の属性リストです。
NamedNodeMapオブジェクトのサポートされるプロパティインデックスは、ゼロから属性リストのサイズ−1までの範囲の番号です。ただし、属性リストが空の場合は、サポートされるプロパティインデックスはありません。
lengthゲッターの手順は、属性リストのサイズを返すことです。
item(index)メソッドの手順:
NamedNodeMap
オブジェクトの サポートされているプロパティ名は、次の手順を実行した結果である:
-
names を、この
NamedNodeMapオブジェクトの 属性リスト内の 属性 の 修飾名(重複を除去し順序はそのまま)とする。 -
この
NamedNodeMapオブジェクトの 要素 が HTML 名前空間にあり、かつその ノードドキュメント が HTML ドキュメント である場合は、 各 names の name について:-
lowercaseName を name の ASCII 小文字とする。
-
もし lowercaseName と name が等しくないなら、names から name を削除する。
-
-
names を返す。
getNamedItem(qualifiedName)
メソッド手順は名前で属性を取得する(引数は qualifiedName, element)の結果を返すことです。
getNamedItemNS(namespace, localName)
メソッド手順は名前空間とローカル名で属性を取得する(引数は
namespace, localName, element)の結果を返すことです。
setNamedItem(attr)および
setNamedItemNS(attr)メソッド手順は
属性を設定する(引数は attr, element)の結果を返すことです。
removeNamedItem(qualifiedName)
メソッド手順は:
-
attr を 名前で属性を除去する(引数は qualifiedName, element)の結果とする。
-
attr が null なら、NotFoundError
NotFoundErrorDOMExceptionをスローする。 -
attr を返す。
removeNamedItemNS(namespace, localName)
メソッド手順は:
-
attr を 名前空間とローカル名で属性を除去する(引数は namespace, localName, element)の結果とする。
-
attr が null なら、NotFoundError
NotFoundErrorDOMExceptionをスローする。 -
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 ; // useless; always returns true };
Attr ノードは単に
属性として知られています。混乱を避けるために 内容属性 と呼ばれることもあります(IDL属性と区別するため)。
属性は、 名前空間(null または空でない文字列)、 名前空間プリフィックス(null または空でない文字列)、 ローカル名(空でない文字列)、 値(文字列)、および 要素(null または 要素)を持ちます。
もし今設計されるなら、名前と値だけを持たせただろう、とのことです。☹
属性の
修飾名は、
名前空間プリフィックスが null であれば
ローカル名であり、
そうでなければ
名前空間プリフィックス+":"+
ローカル名となります。
ユーザーエージェントは最適化のためにこれを内部スロットとして持つことができます。
属性が作成されるとき、 そのローカル名が与えられます。 属性が作成されるときに明示的に与えられない限り、 その 名前空間、 名前空間プリフィックス、 要素 は null になり、 値 は空文字列に設定されます。
A 属性
とは、属性で、
ローカル名が
A であり、
名前空間 と
名前空間プリフィックス が null であるものを指します。
namespaceURI ゲッターの手順は、
this の
名前空間 を返すことです。
prefix ゲッターの手順は、
this の
名前空間プリフィックス を返すことです。
localName ゲッターの手順は、
this の
ローカル名 を返すことです。
name ゲッターの手順は、
this の
修飾名 を返すことです。
value ゲッターの手順は、
this の
値
を返すことです。
既存の属性値を設定するには、属性 attribute と文字列 value を与えて次の手順を実行します:
-
もし attribute の 要素 が null であれば、 attribute の 値 を value に設定して return する。
-
element を attribute の 要素 とする。
-
verifiedValue を、 get trusted type compliant attribute value に attribute の ローカル名、attribute の 名前空間、element、value を渡して呼び出した結果とする。[TRUSTED-TYPES]
-
もし attribute の 要素 が null であれば、 attribute の 値 を verifiedValue に設定して return する。
-
変更 attribute を verifiedValue にする。
value
セッターの手順は、既存の属性値を設定する(this と与えられた値)を実行することです。
ownerElement ゲッターの手順は、
this の 要素
を返すことです。
specified ゲッターの手順は 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
インターフェイスから継承したものは、data という可変の文字列を持ちます。
データを置換するには、ノード node、整数 offset、整数 count、文字列 data をとる:
-
length を node の length とする。
-
もし offset が length より大きければ、"
IndexSizeError"DOMExceptionを投げる。 -
もし offset + count が length より大きければ、count を length − offset にする。
-
キューへ変異記録を追加("
characterData"、node、null、null、nodeの data、« »、« »、null、null)。 -
deleteOffset を offset + data の長さとする。
-
各ライブ範囲で、開始ノードが node かつ 開始オフセットが offset より大きく offset + count 以下の場合は、その 開始オフセット を offset に設定。
-
各ライブ範囲で、終了ノードが node かつ 終了オフセットが offset より大きく offset + count 以下の場合は、その 終了オフセット を offset に設定。
-
各ライブ範囲で、開始ノードが node かつ 開始オフセットが offset + count より大きい場合、開始オフセットを dataの長さだけ増やし count 分減らす。
-
各ライブ範囲で、終了ノードが node かつ 終了オフセットが offset + count より大きい場合、終了オフセットを dataの長さだけ増やし count 分減らす。
データの部分文字列を取得するには、ノード node、整数 offset、整数 count をとる:
-
length を node の length とする。
-
もし offset が length より大きければ、"
IndexSizeError"DOMExceptionを投げる。 -
もし offset + count が length より大きければ、node の data の offset番目以降のコード単位から末尾までの文字列を返す。
-
それ以外の場合、node の data の offset番目から offset+count 番目までのコード単位の文字列を返す。
data のgetter手順は、this の data を返すことです。setter手順は、replace data を
0, this の
length、与えられた値で呼び出すことです。
substringData(offset, count)
メソッドの手順は、substring data を this と
offset、count で呼び出した結果を返すことです。
appendData(data) メソッドの手順は、replace data を
this と this の length、0、data で呼び出すことです。
insertData(offset, data)
メソッドの手順は、replace
data を this と offset、0、data で呼び出すことです。
deleteData(offset, count)
メソッドの手順は、replace
data を this と offset、count、空文字列で呼び出すことです。
replaceData(offset, count, data)
メソッドの手順は、replace
data を this と offset、count、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 = ""])- 新しい
Text型ノードを返します。そのdataはdataです。 text .splitText(offset)- dataをoffsetで分割し、残り部分を新しい
Text型ノードとして返します。 text .wholeText- 全ての同一階層の
Text型ノード兄弟のdataを連結して返します。
排他的な Textノードは、Text型ノードであり、CDATASection型ノードではありません。
連続する Textノードは、ノード
nodeについて、node自身とその前の兄弟のText型ノード(あれば)およびその連続するTextノード、さらにnodeの次の兄弟のText型ノード(あれば)およびその連続するTextノードからなり、重複は除外します。
連続する排他的
Textノードは、ノード
nodeについて、node自身とその前の兄弟の排他的Textノード(あれば)およびその連続する排他的Textノード、さらにnodeの次の兄弟の排他的Textノード(あれば)およびその連続する排他的Textノードからなり、重複は除外します。
new Text(data)コンストラクターの手順は、thisのdataをdataに設定し、thisのノード文書をcurrent global objectの関連するDocumentに設定することです。
Textノードを分割するには、Text型ノード
node、整数offsetを受け取る:
-
length を node の lengthとする。
-
もしoffsetがlengthより大きければ、"
IndexSizeError"DOMExceptionを投げる。 -
countをlength−offsetとする。
-
newDataをsubstringing dataをnode、offset、countで呼び出した結果とする。
-
parentをnodeの親とする。
-
もしparentがnullでなければ:
-
各ライブ範囲について、開始ノードがnodeかつ開始オフセットがoffsetより大きい場合は、開始ノードをnewNodeにして開始オフセットをoffsetだけ減らす。
-
各ライブ範囲について、終了ノードがnodeかつ終了オフセットがoffsetより大きい場合は、終了ノードをnewNodeにして終了オフセットをoffsetだけ減らす。
-
各ライブ範囲について、開始ノードがparentかつ開始オフセットがnodeのインデックス+1に等しい場合は、開始オフセットを1増やす。
-
各ライブ範囲について、終了ノードがparentかつ終了オフセットがnodeのインデックス+1に等しい場合は、終了オフセットを1増やす。
-
replace dataでnodeのoffset、count、空文字列を指定して呼び出す。
-
newNodeを返す。
wholeTextゲッターの手順は、連結した連続するTextノードの全dataを、thisに対し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 = ""])- 新しい
Commentノードを返します。そのデータは data です。
new Comment(data)
コンストラクタの手順は、this の データを data に、
this の ノードドキュメントを
現在のグローバルオブジェクト の
関連付けられた Document に設定することです。
5. Range(範囲)
5.1. 「DOM Range」について
StaticRange
と Range オブジェクト(範囲)は、
ノードツリー内の内容の連続した部分を表します。各範囲は開始と終了を持ち、
それらは境界点です。境界点は、
タプルであり、
ノードとオフセットから構成されます。つまり、
範囲は
ノードツリー内の
2つの境界点間の内容を表します。
範囲は編集時に選択やコピーなどでよく使われます。
-
Element:p
上記のノードツリーでは、範囲を使って
“syndata is awes”という連続部分を表すことができます。pが
p 要素に、
emがem
要素に割り当てられていた場合、次のようになります:
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 now stringifies to the aforementioned quote
属性(例えば上記ノードツリーのsrcやaltなど)は
範囲で表すことはできません。範囲は
ノード専用です。
Range オブジェクトは
StaticRange
オブジェクトとは異なり、
ノードツリーの変更の影響を受けます。したがってこれらはライブ範囲とも呼ばれます。そのような変更によって範囲が無効になることはなく、同じ内容部分を表し続けるようにします。
必然的に、ライブ範囲自身も
ノードツリーの変更(例えば一部内容が変更された場合など)の際に修正される場合があります。
挿入や除去アルゴリズム、
normalize()
メソッド、データ置換やテキスト分割
アルゴリズムも参照してください。
ノードツリーの変更に応じて
ライブ範囲を更新するのは負荷が高い場合があります。ノードツリーが変化するたび、
影響を受けるRange
オブジェクトすべてが更新されます。アプリケーションが一部のライブ範囲に関心がなくても、変更が発生した時に全てを最新化するコストがかかります。
StaticRange
オブジェクトは、ノードツリーが変更されても更新されない軽量な範囲です。
したがってライブ範囲と比べ保守コストがかかりません。
5.2. 境界点
境界点は、タプル であり、次の要素から構成されます。 ノード(ノード)と、 オフセット(0以上の整数)。
正しい境界点のオフセットは 0以上、かつ境界点のノードの 長さ以下の値になります。
位置は、 境界点 (nodeA, offsetA)が、境界点 (nodeB, offsetB)に対して 前、 等しい、 後のいずれかとなり、以下の手順で判定されます。
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
インターフェイスを実装するオブジェクトは
範囲
と呼ばれます。
便宜上、範囲の 開始ノードは、その開始の ノード、 開始オフセットは 開始のオフセット、 終了ノードは 終了の ノード、 終了オフセットは 終了の オフセットです。
node = range . startContainer- rangeの開始ノードを返します。
offset = range . startOffset- rangeの開始オフセットを返します。
node = range . endContainer- rangeの終了ノードを返します。
offset = range . endOffset- rangeの終了オフセットを返します。
collapsed = range . collapsed- rangeが折り畳み済みならtrue、それ以外は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
new StaticRange(init)
コンストラクタの手順は次のとおりです:
-
もし init["
startContainer"] または init["endContainer"] がDocumentTypeまたはAttrノード であれば、throw して"InvalidNodeTypeError"DOMExceptionを送出する。 -
this の 開始 を (init["
startContainer"], init["startOffset"]) に、終了 を (init["endContainer"], init["endOffset"]) に設定する。
StaticRange
が 有効 となるのは、以下すべてが成り立つ場合です:
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 = 0;START_TO_START const unsigned short = 1;START_TO_END const unsigned short = 2;END_TO_END const unsigned short = 3;END_TO_START 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
インターフェイスを実装するオブジェクトは
ライブ範囲
と呼ばれます。
ツリーを変更するアルゴリズム(特に 挿入、 除去、移動、データ置換、分割 アルゴリズム)は、そのツリーに関連付けられたライブ範囲を変更します。
ノード node が contained であるとは、ある live range range において、node の root が range の root と等しく、(node, 0) が range の start より after であり、(node, node の length) が range の end より before である場合をいう。
ノードがライブ範囲に一部含まれるとは、そのノードがライブ範囲の開始ノードの包含祖先であり、終了ノードではない場合、またはその逆の場合です。
これらの定義をよりよく理解するための事実:
-
ライブ範囲内にあると考えられる内容は、全ての含まれるノード、加えて開始ノードや終了ノードが
CharacterData型ノードの場合は、その一部内容も含まれます。 -
ライブ範囲の開始ノードおよび終了ノードは、その範囲内で含まれることはありません。
-
最初の含まれるノード(存在する場合)は常に開始ノードの後にあり、最後の含まれるノードは終了ノードの最後の子孫より前または等しいです。
-
commonAncestorContainer属性値は、含まれるノードにも一部含まれるノードにも該当しません。 -
開始ノードが終了ノードの祖先である場合、共通包含祖先は開始ノードとなります。子のうち、ただ一つが一部含まれる状態となり、もう一方の子ノードはその一部含まれる子より前ならば、完全に含まれることになります。逆も同様に成立します。
-
開始ノードが終了ノードの包含祖先でなく、終了ノードが開始ノードの包含祖先でもない場合、共通包含祖先は両ノードと異なるものとなります。その場合、2つの子が一部含まれることになり、両者の間にある子ノードだけが完全に含まれます。
ライブ範囲の削除前手順は、ノード nodeを与えて:
-
parentをnodeの親とする。
-
検証:parentはnullでない。
-
indexをnodeのインデックスとする。
-
nodeを含むライブ範囲のうち、開始ノードがnodeの包含子孫であるものについては、その開始位置を(parent, index)に設定する。
-
nodeを含むライブ範囲のうち、終了ノードがnodeの包含子孫であるものについては、その終了位置を(parent, index)に設定する。
-
開始ノードがparentで、開始オフセットがindexより大きいライブ範囲については、開始オフセットを1減らす。
-
終了ノードがparentで、終了オフセットがindexより大きいライブ範囲については、終了オフセットを1減らす。
range = new Range()- 新しい live range を返す。
new Range() コンストラクタの手順は、
this の start および end を (current global object の 関連付けられた Document, 0) に設定することである。
- container = range .
commonAncestorContainer - range の 開始ノード と 終了ノードの両方の 祖先であり、文書から最も遠い ノードを返します。
commonAncestorContainer のgetter手順は次の通り:
-
container を start node にする。
-
container が end node の inclusive ancestor でなければ、 container を container の 親に置き換えて繰り返す。
-
container を返す。
開始または終了を設定するには、range を 境界点 (node, offset) に設定する:
-
もし node が doctype であれば、throw して "
InvalidNodeTypeError"DOMExceptionを送出する。 -
もし offset が node の 長さ より大きければ、throw して "
IndexSizeError"DOMExceptionを送出する。 -
boundaryPoint を 境界点 (node, offset) とする。
-
- この手順が "set the start" として呼ばれた場合
- この手順が "set the end" として呼ばれた場合
setStart(node, offset) メソッドの手順は、set the
start を this に対して境界点 (node, offset) で実行すること。
setEnd(node, offset) メソッドの手順は、set the end
を this
に対して境界点 (node, offset) で実行すること。
setStartBefore(node) メソッドの手順は次の通り:
-
parent を node の 親 とする。
-
もし parent が null であれば、throw して "
InvalidNodeTypeError"DOMExceptionを送出する。 -
Set the start を this に対して境界点 (parent, node の index) で設定する。
setStartAfter(node) メソッドの手順は次の通り:
-
parent を node の 親 とする。
-
もし parent が null であれば、throw して "
InvalidNodeTypeError"DOMExceptionを送出する。 -
Set the start を this に対して境界点 (parent, node の index + 1) で設定する。
setEndBefore(node) メソッドの手順は次の通り:
-
parent を node の 親 とする。
-
もし parent が null であれば、throw して "
InvalidNodeTypeError"DOMExceptionを送出する。 -
Set the end を this に対して境界点 (parent, node の index) で設定する。
setEndAfter(node) メソッドの手順は次の通り:
-
parent を node の 親 とする。
-
もし parent が null であれば、throw して "
InvalidNodeTypeError"DOMExceptionを送出する。 -
Set the end を this に対して境界点 (parent, node の index + 1) で設定する。
range range 内の ノード node を 選択するには:
-
parent を node の 親 とする。
-
もし parent が null であれば、throw して "
InvalidNodeTypeError"DOMExceptionを送出する。 -
index を node の index とする。
selectNodeContents(node)
メソッドの手順は次の通り:
-
もし node が doctype であれば、throw して "
InvalidNodeTypeError"DOMExceptionを送出する。 -
length を node の 長さ とする。
compareBoundaryPoints(how, sourceRange)
メソッドの手順は次のとおりです:
-
how が以下のいずれでもない場合:
その場合は throw "
NotSupportedError"DOMExceptionを送出する。 -
this の root が sourceRange の root と異なる場合は、 throw "
WrongDocumentError"DOMExceptionを送出する。 -
thisPoint および sourcePoint を null に設定する。
-
how に応じて、次を実行する:
START_TO_START:-
thisPoint を this の start に、 sourcePoint を sourceRange の start にそれぞれ設定する。
START_TO_END:-
thisPoint を this の end に、 sourcePoint を sourceRange の start に設定する。
END_TO_END:-
thisPoint を this の end に、 sourcePoint を sourceRange の end に設定する。
END_TO_START:-
thisPoint を this の start に、 sourcePoint を sourceRange の end に設定する。
-
thisPoint と sourcePoint の 関係に基づき、次を実行する:
deleteContents()メソッドの手順は次の通り:
-
originalStartNode、originalStartOffset、originalEndNode、originalEndOffsetを、それぞれthisの開始ノード、開始オフセット、終了ノード、終了オフセットとする。
-
originalStartNodeがoriginalEndNodeと等しく、かつ
CharacterData型ノードであれば:-
Replace dataをoriginalStartNodeに対しoriginalStartOffset、originalEndOffset−originalStartOffset、空文字列で実行する。
-
戻る。
-
-
nodesToRemoveを、thisに含まれるノード全てのリストとする(ツリー順、親もthisに含まれる場合はその子ノードを除外)。
-
newNodeとnewOffsetをnullにする。
-
originalStartNodeがoriginalEndNodeの包含祖先の場合、newNodeをoriginalStartNodeに、newOffsetをoriginalStartOffsetに設定する。
-
そうでなければ:
-
originalStartNodeが
CharacterData型ノードなら、replace dataをoriginalStartNodeに対し、originalStartOffset、originalStartNodeのlength−originalStartOffset、空文字列で実行する。 -
nodesToRemoveに入っている各nodeに対し、removeを実行する(ツリー順)。
-
originalEndNodeが
CharacterData型ノードなら、replace dataをoriginalEndNodeに対し、0、originalEndOffset、空文字列で実行する。
ライブ範囲を抽出するには:
-
fragmentを新しい
DocumentFragment型ノード(rangeのstart nodeのnode document)とする。 -
rangeが折りたたみ済みならfragmentを返す。
-
originalStartNode、originalStartOffset、originalEndNode、originalEndOffsetをrangeのstart node、start offset、end node、end offsetとする。
-
originalStartNodeがoriginalEndNodeと等しく、かつ
CharacterData型ノードの場合:-
cloneをoriginalStartNodeのcloneとする。
-
cloneのdataをsubstringing data(originalStartOffset, originalEndOffset − originalStartOffset)で設定する。
-
appendでcloneをfragmentに追加する。
-
replace dataをoriginalStartNodeに対しoriginalStartOffset、originalEndOffset−originalStartOffset、空文字列で実行。
- 戻り値はfragment。
-
-
commonAncestorをoriginalStartNodeとする。
-
commonAncestorがoriginalEndNodeのinclusive ancestorでない限り、親ノードへ進める。
-
firstPartiallyContainedChildをnullにする。
-
originalStartNodeがoriginalEndNodeのinclusive ancestorでなければ、commonAncestorの最初のpartially containedな子をセット。
-
lastPartiallyContainedChildをnullにする。
-
originalEndNodeがoriginalStartNodeのinclusive ancestorでなければ、commonAncestorの最後のpartially containedな子をセット。
この2つの変数は必ず意味がある値になる。2つとも存在するときは値は異なる。
-
containedChildrenをcommonAncestorのうちrangeにcontainedである子全てのリスト(ツリー順)とする。
-
containedChildrenにdoctypeが含まれていたら、"
HierarchyRequestError"DOMExceptionを投げる。境界子や一部含むノードでdocttypeは問題にならない。doctypeは範囲境界にも部分含まれにもなれないため。
-
newNodeとnewOffsetをnullにする。
-
originalStartNodeがoriginalEndNodeのinclusive ancestorならnewNodeはoriginalStartNode、newOffsetはoriginalStartOffset。
-
そうでなければ:
-
referenceNodeをoriginalStartNodeにする。
-
referenceNodeの親がnullでなく、かつoriginalEndNodeのinclusive ancestorでない間、親に進める。
-
newNodeをreferenceNodeの親に、newOffsetをreferenceNodeのindex+1にする。
親がnullの場合はこの分岐に到達しない。
-
-
firstPartiallyContainedChildが
CharacterData型ノードなら:この場合、firstPartiallyContainedChildはoriginalStartNode。
-
cloneをoriginalStartNodeのcloneとする。
-
cloneのdataをsubstringing data(originalStartOffset, originalStartNodeのlength−originalStartOffset)でセットする。
-
appendでcloneをfragmentに追加。
-
replace dataをoriginalStartNodeに対し、originalStartOffset、originalStartNodeのlength−originalStartOffset、空文字列で実行。
-
-
それ以外でfirstPartiallyContainedChildがnullでなければ:
-
containedChildrenの各contained childについて、appendでfragmentへ追加する。
-
lastPartiallyContainedChildが
CharacterData型ノードなら:この場合、lastPartiallyContainedChildはoriginalEndNode。
-
cloneをoriginalEndNodeのcloneとする。
-
cloneのdataをsubstringing data(0, originalEndOffset)で設定。
-
appendでcloneをfragmentへ追加。
-
replace dataをoriginalEndNodeに対し0、originalEndOffset、空文字列で実行。
-
-
それ以外でlastPartiallyContainedChildがnullでなければ:
-
fragmentを返す。
extractContents() メソッドの手順は
extracting
this
の結果を返すことである。
ライブ範囲 range の 内容を複製するには:
-
fragment を新しい
DocumentFragment型ノード(rangeの開始ノードのノード文書)として作成する。 -
rangeが折りたたみ済みならfragmentを返す。
-
originalStartNode、originalStartOffset、originalEndNode、originalEndOffsetをrangeの開始ノード、開始オフセット、終了ノード、終了オフセットとする。
-
originalStartNode と originalEndNode が同じで、かつ
CharacterData型ノードなら: -
commonAncestorをoriginalStartNodeとする。
-
commonAncestorがoriginalEndNodeの包含祖先でない間、親に進める。
-
firstPartiallyContainedChildをnullとする。
-
originalStartNodeがoriginalEndNodeの包含祖先でない場合、commonAncestorの最初の一部含まれる子をfirstPartiallyContainedChildとする。
-
lastPartiallyContainedChildをnullとする。
-
originalEndNodeがoriginalStartNodeの包含祖先でない場合、commonAncestorの最後の一部含まれる子をlastPartiallyContainedChildとする。
この変数代入は常に意味がある。例えばoriginalStartNodeがoriginalEndNodeの包含祖先でなければ、originalStartNode自身やその祖先も範囲に一部含まれることになり、両方定義される場合は異なる値になる。
-
containedChildrenをcommonAncestorのうちrangeに完全に含まれる子すべてのリスト(ツリー順)とする。
-
containedChildrenの中にdoctypeがあれば、"
HierarchyRequestError"DOMExceptionを投げる。最初や最後の一部含まれるノードは気にしなくて良い。doctypeは部分含まれることも境界点にもなれないため。
-
firstPartiallyContainedChildが
CharacterData型ノードの場合:この場合、firstPartiallyContainedChildはoriginalStartNode。
-
それ以外でfirstPartiallyContainedChildがnullでなければ:
-
containedChildrenの各contained childについて:
-
lastPartiallyContainedChildが
CharacterData型ノードの場合:この場合、lastPartiallyContainedChildはoriginalEndNode。
-
それ以外でlastPartiallyContainedChildがnullでなければ:
-
fragmentを返す。
cloneContents()メソッドの手順は、内容の複製をthisで呼び出した結果を返します。
ライブ範囲 range に ノード node を 挿入するには:
-
rangeの開始ノードが
ProcessingInstructionまたはComment型ノード、Text型ノードで親がnull、またはnode自身の場合、"HierarchyRequestError"DOMExceptionを投げる。 -
referenceNodeをnullとする。
-
そうでない場合、referenceNodeをrangeの開始ノードの子(インデックスがrangeの開始オフセットであるもの、なければnull)とする。
-
parentを、referenceNodeがnullならrangeの開始ノード、そうでなければreferenceNodeの親とする。
-
事前挿入の妥当性をnode、parent、referenceNodeで確保する。
-
rangeの開始ノードが
Text型ノードなら、referenceNodeをそれをrangeの開始オフセットで分割した結果に更新。 -
nodeがreferenceNodeなら、referenceNodeをその次兄弟に更新。
-
newOffsetをreferenceNodeがnullならparentの長さ、そうでなければreferenceNodeのインデックスに設定。
-
nodeが
DocumentFragment型ノードなら、newOffsetをnodeの長さ増やす。そうでなければ1増やす。 -
pre-insertでnodeをparentにreferenceNodeの前へ挿入。
surroundContents(newParent) メソッドの手順:
-
非
Text型ノードが一部含まれる状態で thisに存在する場合、「InvalidStateError」DOMExceptionを投げる。 -
newParentが
Document、DocumentType、またはDocumentFragment型ノードの場合、「InvalidNodeTypeError」DOMExceptionを投げる。歴史的な理由で
CharacterData型ノードはここでチェックされず、後の副作用で例外が投げられる。 -
fragmentをextractingでthisから取得する。
-
newParentに子が存在する場合、replace allで中身をnullにする。
-
appendでfragmentをnewParentに追加する。
cloneRange() メソッドの手順は新しい
live range
を生成し、
start および end を this
と同じに設定して返すこと。
detach() メソッドの手順は何もしない。
この機能(Range
オブジェクトを無効化する)は削除されたが、
互換性のためにメソッド自体は残されている。
- position = range .
comparePoint(node, offset) - 点が範囲の前にあれば −1、範囲内にあれば 0、範囲の後にあれば 1 を返します。
- intersects = range .
intersectsNode(node) - range が node と交差するかどうかを返します。
isPointInRange(node, offset)
メソッドの手順は次の通り:
-
node が doctype の場合、throw "
InvalidNodeTypeError"DOMExceptionを送出する。 -
offset が node の length より大きい場合、throw "
IndexSizeError"DOMExceptionを送出する。 -
true を返す。
comparePoint(node, offset)
メソッドの手順は次の通り:
-
node の root が this の root と異なる場合、throw "
WrongDocumentError"DOMExceptionを送出する。 -
node が doctype の場合、throw "
InvalidNodeTypeError"DOMExceptionを送出する。 -
offset が node の length より大きい場合、throw "
IndexSizeError"DOMExceptionを送出する。 -
(node, offset) が start より前なら −1 を返す。
-
(node, offset) が end の後なら 1 を返す。
-
0 を返す。
intersectsNode(node)
メソッドの手順は次の通り:
stringification behavior は以下の手順を実行する:
createContextualFragment()、
getClientRects()、
getBoundingClientRect()
メソッドは他の仕様で定義されている。
[DOM-Parsing]
[CSSOM-VIEW]
6. 走査
NodeIteratorおよびTreeWalkerオブジェクトは、ノードツリーのフィルタリングや走査に利用できます。
各NodeIteratorおよびTreeWalkerオブジェクトは、再帰呼び出しを防ぐための関連ブール型is activeを持ちます。初期値はfalseです。
各NodeIteratorとTreeWalkerオブジェクトには、root(ノード)、whatToShow(ビットマスク)、およびfilter(コールバック)が関連付けられています。
フィルターするには、ノードnodeを、NodeIteratorまたはTreeWalkerオブジェクトtraverserで:
-
traverserのis activeがtrueの場合、"
InvalidStateError"DOMExceptionを投げる。 -
nをnodeの
nodeType属性値−1とする。 -
traverserのwhatToShowのnビット(0が最下位ビット)がセットされていなければ、
FILTER_SKIPを返す。 -
traverserのfilterがnullなら、
FILTER_ACCEPTを返す。 -
traverserのis activeをtrueに設定する。
-
resultを、ユーザーオブジェクトの操作を呼び出す(traverserのfilter、"
acceptNode"、« node »)の戻り値として取得する。これで例外が発生した場合は、traverserのis activeをfalseにして、その例外を再スローする。 -
traverserのis activeをfalseに設定する。
-
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
オブジェクトは、関連する iterator collection を持ちます。これは NodeIterator
オブジェクトの root
を根とした コレクションで、フィルターは任意のノードに一致します。
各 NodeIterator
オブジェクトは、関連する reference(ノード)と pointer before
reference(ブール値)も持ちます。
前述の通り、NodeIterator
オブジェクトには is
active・root・whatToShow・filter
も関連付けられています。
NodeIterator pre-remove steps は、NodeIterator
オブジェクト nodeIterator と ノード toBeRemovedNode を与えると:
-
toBeRemovedNode が nodeIterator の reference の 包含祖先でない、または toBeRemovedNode が nodeIterator の root である場合、return。
-
nodeIterator の pointer before reference が true の場合:
-
nodeIterator の reference を toBeRemovedNode の parent(もし toBeRemovedNode の previous sibling が null なら)あるいは toBeRemovedNode の previous sibling の 包含子孫で、ツリー順で最後に現れるものに設定する。
pointerBeforeReferenceNode
のgetter手順は、this の pointer before reference を返すことです。
whatToShow のgetter手順は、this の whatToShow
を返すことです。
traverse は、NodeIterator
オブジェクト iterator と "next" または "previous" type を受け取る:
-
node を iterator の reference とする。
-
beforeNode を iterator の pointer before reference とする。
-
以下を繰り返す:
-
type が
nextの場合:-
beforeNode が false なら node を iterator の iterator collection 内で node の最初の following ノードに設定する。なければ return null。
-
beforeNode が true なら false にする。
-
-
そうでなければ:
-
beforeNode が true なら node を iterator の iterator collection 内で node の最初の preceding ノードに設定する。なければ return null。
-
beforeNode が false なら true にする。
-
-
result を filtering (node・iterator) の結果とする。
-
result が
FILTER_ACCEPTの場合 break。
-
-
iterator の reference を node に設定する。
-
iterator の pointer before reference を beforeNode に設定する。
-
node を返す。
detach() の手順は何もしないことです。
NodeIterator
オブジェクトの無効化という機能は削除されていますが、互換性維持のためメソッド自体は残っています。
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
オブジェクトは、関連付けられた current(
ノード)を持ちます。
前述の通り、TreeWalker
オブジェクトには、
root,
whatToShow,
filter
も関連付けられています。
whatToShow の getter 手順は、
this の whatToShow を返すこと。
currentNode
の setter 手順は、this の
current
に与えられた値を設定すること。
parentNode() メソッドの手順は次の通り:
traverse children は、TreeWalker
オブジェクト walker と "first" または "last"
type を与えて実行する:
-
node を walker の current とする。
-
もし type が "
first" なら node を node の first child に、そうでなければ last child に設定する。 -
node が null でない間、次の手順を繰り返す:
-
result を filtering で walker 内の node を評価した結果とする。
-
もし result が
FILTER_ACCEPTなら、walker の current に node を設定し、node を返す。 -
もし result が
FILTER_SKIPなら:-
もし type が "
first" なら child を node の first child に、そうでなければ last child に設定する。 -
child が null でなければ、node を child に設定して continue する。
-
-
次の間、node が null でない間、繰り返す:
-
もし type が "
first" なら sibling を node の next sibling に、そうでなければ previous sibling に設定する。 -
sibling が null でなければ、node を sibling に設定し break する。
-
parent を node の parent に設定する。
-
もし parent が null または walker の root または walker の current であれば null を返す。
-
node を parent に設定する。
-
-
-
null を返す。
firstChild() メソッド手順は、
traverse children を this と "first"
で実行すること。
lastChild() メソッド手順は、
traverse children を this と "last"
で実行すること。
traverse
siblings は、
TreeWalker
オブジェクト walker および "next" または "previous" type を与えて実行する:
-
node を walker の current とする。
-
node が root であれば null を返す。
-
while true:
-
もし type が "
next" なら sibling を node の next sibling に、そうでなければ previous sibling に設定する。 -
sibling が null でない間、次を繰り返す:
-
node を sibling に設定する。
-
result を filtering で walker 内の node を評価した結果とする。
-
もし result が
FILTER_ACCEPTなら、walker の current に node を設定し node を返す。 -
もし type が "
next" なら sibling を node の first child に、そうでなければ last child に設定する。 -
もし result が
FILTER_REJECTまたは sibling が null ならば、 sibling を type が "next" なら node の next sibling に、そうでなければ previous sibling に設定する。
-
-
node を node の parent に設定する。
-
node が null または walker の root であれば null を返す。
-
filtering で walker 内の node を評価した結果が
FILTER_ACCEPTなら null を返す。
-
nextSibling() メソッド手順は、
traverse siblings を this と "next"
で実行すること。
previousSibling() メソッド手順は、
traverse siblings を this と
"previous" で実行すること。
previousNode() メソッドの手順は次の通り:
-
-
sibling を node の previous sibling に設定する。
-
sibling が null でない間、繰り返す:
-
node を sibling に設定する。
-
次の間、 result が
FILTER_REJECTでなく、かつ node が 子をもつ間、繰り返す:-
node を node の last child に設定する。
-
-
もし result が
FILTER_ACCEPTであれば、 this の current に node を設定し、 node を返す。 -
sibling を node の previous sibling に設定する。
-
-
node を node の parent に設定する。
-
filtering で this 内の node を評価した結果が
FILTER_ACCEPTの場合、this の current を node に設定し、node を返す。
-
-
null を返す。
nextNode() メソッドの手順は次の通り:
-
result を
FILTER_ACCEPTに設定する。 -
while true:
-
result が
FILTER_REJECTでなく、かつ node が 子 を持つあいだ:-
node を node の first child に設定する。
-
もし result が
FILTER_ACCEPTであれば、this の current に node を設定し node を返す。
-
-
sibling を null に設定する。
-
temporary を node に設定する。
-
temporary が null でない間、次を繰り返す:
-
sibling を temporary の next sibling に設定する。
-
sibling が null でなければ、node を sibling に設定し break する。
-
temporary を temporary の parent に設定する。
-
もし result が
FILTER_ACCEPTであれば、this の current に node を設定し node を返す。
-
6.3. インターフェイス NodeFilter
[Exposed =Window ]callback interface { // Constants for acceptNode()NodeFilter const unsigned short FILTER_ACCEPT = 1;const unsigned short FILTER_REJECT = 2;const unsigned short FILTER_SKIP = 3; // Constants for whatToShowconst 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 = 0x10; // legacySHOW_ENTITY_REFERENCE const unsigned long = 0x20; // legacySHOW_ENTITY 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 = 0x800; // legacySHOW_NOTATION unsigned short (acceptNode Node ); };node
NodeFilter
オブジェクトは、filterとして
NodeIterator
や
TreeWalker
オブジェクトで利用でき、さらに
whatToShow ビットマスク用の定数も提供します。NodeFilter
オブジェクトは通常、JavaScript関数として実装されます。
以下の定数はfilterの戻り値として利用できます:
FILTER_ACCEPT(1);FILTER_REJECT(2);FILTER_SKIP(3);
以下の定数はwhatToShowに利用できます:
SHOW_ALL(4294967295, 16進数でFFFFFFFF);SHOW_ELEMENT(1);SHOW_ATTRIBUTE(2);SHOW_TEXT(4);SHOW_CDATA_SECTION(8);SHOW_PROCESSING_INSTRUCTION(64, 16進数で40);SHOW_COMMENT(128, 16進数で80);SHOW_DOCUMENT(256, 16進数で100);SHOW_DOCUMENT_TYPE(512, 16進数で200);SHOW_DOCUMENT_FRAGMENT(1024, 16進数で400);
7. 集合
DOMTokenList
という名前は、残念ながらレガシーの名残りです。
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
オブジェクトには、関連付けられた
token set(集合)があり、これは初期状態では空です。
DOMTokenList
オブジェクトには、関連付けられたelement
(要素)と、attribute name(属性の
ローカル名)も持ちます。
仕様によって、
supported tokensが、DOMTokenListの
elementとattribute nameに定義される場合があります。
DOMTokenList
オブジェクトの set の
validation steps は、指定された
token に対して次の通りです:
-
もし set の elementと attribute name がsupported tokensを定義していない場合は、 TypeError をスローします。
-
lowercaseToken を token の ASCII小文字に変換します。
-
もし lowercaseToken が supported tokens の set の element と attribute name 内に存在する場合は true を返します。
-
false を返します。
DOMTokenList
オブジェクト set の
update steps は次の通りです:
-
もし 名前空間およびローカル名で属性を取得 を null, set の attribute name, および set のelementを指定して実行するとnullを返し、さらに set のtoken set が空の場合、何も行わずに終了します。
-
属性値を設定 を、set の element、set の attribute name、および ordered set serializer を set の token set で実行した結果で呼び出します。
DOMTokenList
オブジェクト set の
serialize steps は、次の通りです:
属性値を取得 を set の element と
set の attribute name を指定して実行した結果を返します。
DOMTokenList
オブジェクト set に対する attribute change steps は、
set の element に対して以下の通りです:
-
もし localName が set の attribute name、 namespace が null、かつ value が null の場合は 空 のtoken setにします。
-
それ以外の場合で、localName が set の attribute name かつ namespace が null の場合は、 set の token set を、 value を parsed した結果に設定します。
DOMTokenList
オブジェクト set を作成したとき:
-
element を set の element とします。
-
attributeName を set の attribute name とします。
-
value を、 属性値を取得 を element と attributeName で実行した結果とします。
-
attribute change steps を element, attributeName、value, value, null で実行します。
-
tokenlist .length -
トークンの数を返します。
-
tokenlist .item(index)tokenlist[index] -
インデックス index のトークンを返します。
-
tokenlist .contains(token) -
token が存在する場合は true、そうでなければ false を返します。
-
tokenlist . add(tokens…) -
渡された引数のうち、まだ存在しないものをすべて追加します。
どれかの引数が空文字列なら "
SyntaxError"DOMExceptionを投げます。どれかの引数に ASCII空白 が含まれていれば "
InvalidCharacterError"DOMExceptionを投げます。 -
tokenlist . remove(tokens…) -
渡された引数が存在すれば削除します。
どれかの引数が空文字列なら "
SyntaxError"DOMExceptionを投げます。どれかの引数に ASCII空白 が含まれていれば "
InvalidCharacterError"DOMExceptionを投げます。 -
tokenlist . toggle(token [, force]) -
force が指定されていなければ token をトグルします。存在する場合は削除し、存在しない場合は追加します。force が true なら token を追加し(
add()と同じ)、false なら削除します(remove()と同じ)。今 token が存在していれば true、そうでなければ false を返します。
token が空文字列なら "
SyntaxError"DOMExceptionを投げます。token に空白が含まれていれば "
InvalidCharacterError"DOMExceptionを投げます。 -
tokenlist . replace(token, newToken) -
token を newToken で置き換えます。
token が newToken で置換された場合は true、それ以外は false を返します。
どちらかの引数が空文字列なら "
SyntaxError"DOMExceptionを投げます。どちらかの引数に ASCII空白 が含まれていれば "
InvalidCharacterError"DOMExceptionを投げます。 -
tokenlist . supports(token) -
token が関連付けられた属性のサポートされるトークンに含まれる場合は true、そうでなければ false を返します。
関連付けられた属性にサポートされるトークンが定義されていない場合は
TypeErrorを投げます。 -
tokenlist .value -
関連付けられた集合を文字列で返します。
セットも可能で、関連付けられた属性を変更できます。
このオブジェクトの サポートされるプロパティインデックス は、ゼロからオブジェクトの トークン集合 の サイズ − 1 までの数です。ただし、トークン集合 が 空 の場合、サポートされるプロパティインデックスはありません。
add(tokens…)メソッドの手順は以下の通りです:
-
各tokensのtokenについて:
-
tokenが空文字列の場合、"SyntaxError"
例外、DOMExceptionをスローします。 -
tokenがASCIIホワイトスペースを含む場合、"InvalidCharacterError"
例外、DOMExceptionをスローします。
-
-
各tokensのtokenについて、token setに追加します。
-
update stepsを実行します。
remove(tokens…)メソッドの手順は以下の通りです:
-
各tokensのtokenについて:
-
tokenが空文字列の場合、"SyntaxError"
例外、DOMExceptionをスローします。 -
tokenがASCIIホワイトスペースを含む場合、"InvalidCharacterError"
例外、DOMExceptionをスローします。
-
-
update stepsを実行します。
toggle(token, force)メソッドの手順は以下の通りです:
-
tokenが空文字列の場合、"SyntaxError"
例外、DOMExceptionをスローします。 -
tokenがASCIIホワイトスペースを含む場合、"InvalidCharacterError"
例外、DOMExceptionをスローします。 -
-
forceが指定されていないか、falseの場合、token setから削除し、update stepsを実行し、falseを返します。
-
trueを返します。
-
-
それ以外の場合、forceが未指定またはtrueの場合、token setにtokenを追加し、update stepsを実行し、trueを返します。
-
falseを返します。
toggle()に関しては、Web互換性のためupdate
stepsが常に実行されるとは限りません。
replace(token, newToken)メソッドの手順は以下の通りです:
-
tokenまたはnewTokenのいずれかが空文字列の場合、"SyntaxError"
例外、DOMExceptionをスローします。 -
tokenまたはnewTokenのいずれかがASCIIホワイトスペースを含む場合、"InvalidCharacterError"
例外、DOMExceptionをスローします。 -
update stepsを実行します。
-
trueを返します。
replace()に関しては、Web互換性のためupdate
stepsが常に実行されるとは限りません。
supports(token)メソッドの手順は以下の通りです:
-
resultを、validation stepsをtokenで呼び出した戻り値とします。
-
resultを返します。
valueのgetter手順は、thisのserialize stepsを実行した結果を返すことです。
8. XPath
DOM Level 3 XPathはXPath 1.0 式の評価APIを定義しました。これらのAPIは広く実装されていますが、保守されていません。インターフェイス定義はWeb IDLの変更時に更新できるようここで維持されています。 これらAPIの完全な定義は依然必要であり、その作業はwhatwg/dom#67で追跡およびコントリビュートできます。 [DOM-Level-3-XPath] [XPath] [WEBIDL]
8.1. インターフェイス XPathResult
[Exposed =Window ]interface {XPathResult const unsigned short = 0;ANY_TYPE const unsigned short = 1;NUMBER_TYPE const unsigned short = 2;STRING_TYPE const unsigned short = 3;BOOLEAN_TYPE const unsigned short = 4;UNORDERED_NODE_ITERATOR_TYPE const unsigned short = 5;ORDERED_NODE_ITERATOR_TYPE const unsigned short = 6;UNORDERED_NODE_SNAPSHOT_TYPE const unsigned short = 7;ORDERED_NODE_SNAPSHOT_TYPE const unsigned short = 8;ANY_UNORDERED_NODE_TYPE const unsigned short = 9;FIRST_ORDERED_NODE_TYPE 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 { // XPathResult.ANY_TYPE = 0XPathExpression XPathResult (evaluate Node ,contextNode optional unsigned short = 0,type optional XPathResult ?=result null ); };
8.3. ミックスイン XPathEvaluatorBase
callback interface {XPathNSResolver DOMString ?(lookupNamespaceURI DOMString ?); };prefix interface mixin { [XPathEvaluatorBase NewObject ]XPathExpression (createExpression DOMString ,expression optional XPathNSResolver ?=resolver null );Node createNSResolver (Node ); // legacy // XPathResult.ANY_TYPE = 0nodeResolver XPathResult (evaluate DOMString ,expression Node ,contextNode optional XPathNSResolver ?=resolver null ,optional unsigned short = 0,type optional XPathResult ?=result null ); };Document includes XPathEvaluatorBase ;
createNSResolver(nodeResolver)
メソッド手順はnodeResolverを返すこと。
このメソッドは歴史的理由で存在しています。
8.4. インターフェイス XPathEvaluator
[Exposed =Window ]interface {XPathEvaluator (); };constructor XPathEvaluator includes XPathEvaluatorBase ;
歴史的理由により、XPathEvaluator
をコンストラクトすることも、同じ
メソッドにDocument
上からアクセスすることもできます。
9. XSLT
XSL Transformations (XSLT)はXML文書を他のXML文書に変換する言語です。 この章で定義されているAPIは広く実装されており、Web IDLの変更時に更新できるようここで維持されています。APIの完全な定義は依然として必要であり、その作業は 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. セキュリティとプライバシーの考慮事項
この標準には、既知のセキュリティやプライバシーの考慮事項はありません。
11. 歴史的事項
この標準には、かつて含まれていたが削除された複数のインターフェイスやインターフェイスメンバーがあります。
以下のインターフェイスは削除されました:
DOMConfigurationDOMErrorDOMErrorHandlerDOMImplementationListDOMImplementationSourceDOMLocatorDOMObjectDOMUserDataEntityEntityReferenceMutationEventMutationNameEventNameListNotationRangeExceptionTypeInfoUserDataHandler
また、以下のインターフェイスメンバーが削除されました:
Attr-
schemaTypeInfoisId
Document-
createEntityReference()xmlEncodingxmlStandalonexmlVersionstrictErrorCheckingdomConfignormalizeDocument()renameNode()
DocumentType-
entitiesnotationsinternalSubset
DOMImplementation-
getFeature()
Element-
schemaTypeInfosetIdAttribute()setIdAttributeNS()setIdAttributeNode()
Node-
isSupportedgetFeature()getUserData()setUserData()
NodeIterator-
expandEntityReferences
Text-
isElementContentWhitespacereplaceWholeText()
TreeWalker-
expandEntityReferences
謝辞
DOM の相互運用性向上に長年にわたり貢献してくださった多くの方々に感謝します。同様に、この標準が今日の形となるまで支えてくださった方々にも感謝いたします。
以下の皆様に心より感謝いたします: 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、 Evgeny Kapun、 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、 Jayson Chen、 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、 Simon Wülker、 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、 Zack Weinberg の皆様、素晴らしいご協力ありがとうございました!
この標準は Anne van Kesteren (Apple, annevk@annevk.nl) によって執筆され、 Aryeh Gregor (ayg@aryeh.name) と Ms2ger (ms2ger@gmail.com) の多大な貢献を受けています。
知的財産権
Copyright © WHATWG (Apple, Google, Mozilla, Microsoft)。この作品は クリエイティブ・コモンズ 表示 4.0 国際ライセンス の下でライセンスされています。ソースコードに組み込まれている部分については、BSD 3-Clause License の下でライセンスされます。
これはリビングスタンダードです。特許レビュー版に関心がある方は Living Standard Review Draft をご覧ください。