1. 基盤
この仕様はInfra Standardに依存しています。[INFRA]
この仕様で使用される用語の一部は、Encoding、 Selectors、Trusted Types、Web IDL、XML、 Namespaces in XML、およびAssociating Style Sheets with XML documentsで定義されている。 [ENCODING] [SELECTORS4] [TRUSTED-TYPES] [WEBIDL] [XML] [XML-NAMES] [XML-STYLESHEET]
拡張が必要な場合、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 (:) を含む場合:
-
prefix を qualifiedName の最初の U+003A(:)より前の部分に設定する。
-
localName を qualifiedName の最初の U+003A(:)より後ろの部分に設定する。
-
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]
イベントには、関連付けられた
パスがある。
パスは、リストであり、イベントパス項目からなる。イベントパス項目は、構造体であり、
呼び出し対象
(EventTarget
オブジェクト)、
シャドウツリー内の呼び出し対象
(真偽値)、
シャドウ調整済み対象(
潜在的なイベント
ターゲット)、
relatedTarget(
潜在的なイベント
ターゲット)、
タッチ対象リスト(
リストであり、潜在的なイベント
ターゲットからなる)、
閉じたツリーのルート(真偽値)、
および 閉じたツリー内のスロット(
真偽値)から構成される。パスは、初期状態では
空リストである。
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オブジェクトである。 -
currentTarget を composedPath に追加する。
-
currentTargetIndex を 0 とする。
-
currentTargetHiddenSubtreeLevel を 0 とする。
-
index を path のサイズ − 1 とする。
-
index が 0 以上である間:
-
path[index] の閉じたツリーのルートが true なら、currentTargetHiddenSubtreeLevel を 1 増やす。
-
path[index] の呼び出し対象が currentTarget なら、currentTargetIndex を index に設定し、 中断する。
-
path[index] の閉じたツリー内のスロットが true なら、currentTargetHiddenSubtreeLevel を 1 減らす。
-
index を 1 減らす。
-
-
currentHiddenLevel および maxHiddenLevel を currentTargetHiddenSubtreeLevel とする。
-
index を currentTargetIndex − 1 に設定する。
-
index が 0 以上である間:
-
path[index] の閉じたツリーのルートが true なら、currentHiddenLevel を 1 増やす。
-
currentHiddenLevel が maxHiddenLevel 以下なら、 path[index] の 呼び出し対象を composedPath に前置する。
-
path[index] の閉じたツリー内のスロットが true なら:
-
currentHiddenLevel を 1 減らす。
-
currentHiddenLevel が maxHiddenLevel より小さいなら、 maxHiddenLevel を currentHiddenLevel に設定する。
-
-
index を 1 減らす。
-
-
currentHiddenLevel および maxHiddenLevel を currentTargetHiddenSubtreeLevel に設定する。
-
index を currentTargetIndex + 1 に設定する。
-
index が path のサイズ未満である間:
-
path[index] の閉じたツリー内のスロットが true なら、currentHiddenLevel を 1 増やす。
-
currentHiddenLevel が maxHiddenLevel 以下なら、 path[index] の 呼び出し対象を composedPath に追加する。
-
path[index] の閉じたツリーのルートが 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を持ちません。
将来的には、カスタムの親を取得するアルゴリズムを許可できるかもしれません。これが
有用であれば、issue #583 を支援してください。現時点では、すべての
作者が作成した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. イベントのディスパッチ
イベント
event を
EventTarget
オブジェクト target へ、任意の legacy target override flag および
任意の legacyOutputDidListenersThrowFlag とともに
配送するには:
-
event の dispatch flag を設定する。
-
legacy target override flag が与えられていない場合は target を、 そうでない場合は target の 関連付けられた
Documentを targetOverride とする。 [HTML]legacy target override flag は HTML によってのみ、 かつ target が
Windowオブジェクトである場合にのみ使用される。 -
activationTarget を null とする。
-
event の relatedTarget を target に対して リターゲットした結果を relatedTarget とする。
-
clearTargets を false とする。
-
target が relatedTarget でない、または target が event の relatedTarget である場合:
-
touchTargets を新しい リストとする。
-
event の touch target list の各 touchTarget について: touchTarget を target に対して リターゲットした結果を touchTargets に 追加する。
-
event, target, targetOverride, relatedTarget, touchTargets, および false を用いて イベントパスに追加する。
-
event が
MouseEventオブジェクトであり、 event のtype属性が "click" である場合は isActivationEvent を true とし、 そうでなければ false とする。 -
isActivationEvent が true で、かつ target が activation behavior を持つ場合は、 activationTarget を target に設定する。
-
target が slottable であり、かつ 割り当て済みである場合は target を slottable とし、そうでなければ null とする。
-
slotInClosedTree を false とする。
-
target の get the parent を event とともに呼び出した結果を parent とする。
-
parent が非 null の間:
-
slottable が非 null である場合:
-
アサート: parent は slot である。
-
slottable を null に設定する。
-
parent の root が shadow root であり、その mode が "
closed" である場合は、slotInClosedTree を true に設定する。
-
-
parent が slottable であり、かつ 割り当て済み である場合は、slottable を parent に設定する。
-
event の relatedTarget を parent に対して リターゲットした結果を relatedTarget とする。
-
touchTargets を新しい リストとする。
-
event の touch target list の各 touchTarget について: touchTarget を parent に対して リターゲットした結果を touchTargets に 追加する。
-
parent が
Windowオブジェクトである、または parent が node であり、 target の root が parent の shadow-including inclusive ancestor である場合:-
isActivationEvent が true、event の
bubbles属性が true、activationTarget が null、かつ parent が activation behavior を持つ場合は、activationTarget を parent に設定する。 -
event, parent, null, relatedTarget, touchTargets, および slotInClosedTree を用いて イベントパスに追加する。
-
-
そうでなく、parent が relatedTarget である場合は、 parent を null に設定する。
-
そうでない場合:
-
target を parent に設定する。
-
isActivationEvent が true、activationTarget が null、かつ target が activation behavior を持つ場合は、 activationTarget を target に設定する。
-
event, parent, target, relatedTarget, touchTargets, および slotInClosedTree を用いて イベントパスに追加する。
-
-
parent が非 null である場合は、 parent の get the parent を event とともに呼び出した結果に parent を設定する。
-
slotInClosedTree を false に設定する。
-
-
event の path における、 shadow-adjusted target が 非 null である最後の event path item を clearTargetsItem とする。
-
clearTargetsItem の shadow-adjusted target、 clearTargetsItem の relatedTarget、または clearTargetsItem の touch target list 内の
EventTargetオブジェクトが、 その root が shadow root である node である場合: clearTargets を true に設定する。 -
activationTarget が非 null で、かつ activationTarget が legacy-pre-activation behavior を持つ場合は、activationTarget の legacy-pre-activation behavior を実行する。
-
event の path の各 item について、逆順で:
-
item の shadow-adjusted target が非 null である場合は、 event の
eventPhase属性をAT_TARGETに設定する。 -
そうでない場合は、event の
eventPhase属性をCAPTURING_PHASEに設定する。 -
item, event, "
capturing", および 与えられていれば legacyOutputDidListenersThrowFlag を用いて 呼び出す。
-
-
event の path の各 item について:
-
item の shadow-adjusted target が非 null である場合は、 event の
eventPhase属性をAT_TARGETに設定する。 -
そうでない場合:
-
event の
eventPhase属性をBUBBLING_PHASEに設定する。
-
item, 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、
EventTarget
オブジェクト invocationTarget、
潜在的な
イベントターゲット shadowAdjustedTarget、潜在的なイベントターゲット
relatedTarget、リストである 潜在的なイベントターゲットたち
touchTargets、およびブール値 slotInClosedTree が与えられたとき、
イベントパスに
追加するには:
-
invocationTargetInShadowTree を false とする。
-
invocationTarget が node であり、その root が shadow root である場合は、invocationTargetInShadowTree を true に設定する。
-
rootOfClosedTree を false とする。
-
invocationTarget が、その mode が "
closed" である shadow root の場合は、 rootOfClosedTree を true に設定する。 -
event の path に、 新しい event path item を 追加する。その invocation target は invocationTarget、 invocation-target-in-shadow-tree は invocationTargetInShadowTree、 shadow-adjusted target は shadowAdjustedTarget、 relatedTarget は relatedTarget、 touch target list は touchTargets、 root-of-closed-tree は rootOfClosedTree、かつ slot-in-closed-tree は slotInClosedTree である。
event path item pathItem、イベント event、文字列 phase、および任意の legacyOutputDidListenersThrowFlag が与えられたとき、 呼び出すには:
-
targetItem を pathItem とする。
-
targetItem の shadow-adjusted target が null である間: event の path において targetItem の直前にある event path item に targetItem を設定する。
-
event の target を、targetItem の shadow-adjusted target に設定する。
-
event の relatedTarget を、pathItem の relatedTarget に設定する。
-
event の touch target list を、pathItem の touch target list に設定する。
-
event の stop propagation flag が設定されている場合は、return する。
-
event の
currentTarget属性を、pathItem の invocation target に初期化する。 -
event の
currentTarget属性値の event listener list の 複製を listeners とする。これにより、この時点以降に追加された event listener が 実行されることを防ぐ。なお、削除は removed フィールドにより 依然として効果を持つ。
-
pathItem の invocation-target-in-shadow-tree を invocationTargetInShadowTree とする。
-
event, listeners, phase, invocationTargetInShadowTree, および 与えられていれば legacyOutputDidListenersThrowFlag を用いて inner invoke を実行した結果を found とする。
-
found が false で、かつ event の
isTrusted属性が true である場合:-
event の
type属性値を originalEventType とする。 -
event の
type属性値が次の表の第 1 列にある文字列のいずれかに一致する場合は、 event のtype属性値を、 一致した文字列と同じ行の第 2 列にある文字列に設定し、そうでなければ return する。イベント型 レガシーイベント型 " animationend"" webkitAnimationEnd"" animationiteration"" webkitAnimationIteration"" animationstart"" webkitAnimationStart"" transitionend"" webkitTransitionEnd" -
event, listeners, phase, invocationTargetInShadowTree, および 与えられていれば legacyOutputDidListenersThrowFlag を用いて Inner invoke する。
-
event の
type属性値を originalEventType に設定する。
-
イベント event、リストである event listenerたち listeners、 文字列 phase、ブール値 invocationTargetInShadowTree、および任意の legacyOutputDidListenersThrowFlag が与えられたとき、 inner invoke するには:
-
found を false とする。
-
listeners の各 listener のうち、その removed が false であるものについて:
-
found を true に設定する。
-
phase が "
capturing" であり、かつ listener の capture が false である場合は、 continue する。 -
phase が "
bubbling" であり、かつ listener の capture が true である場合は、 continue する。 -
listener の once が true である場合は、 event の
currentTarget属性値 および listener が与えられたものとして イベントリスナーを削除する。 -
listener の callback の 関連付けられたレルムの グローバルオブジェクトを global とする。
-
currentEvent を undefined とする。
-
global が
Windowオブジェクトである場合:-
global の current event を currentEvent に設定する。
-
invocationTargetInShadowTree が false である場合は、 global の current event を event に設定する。
-
-
listener の passive が true である場合は、 event の in passive listener flag を設定する。
-
global が
Windowオブジェクトである場合は、 event および listener が与えられたものとして イベントリスナーのタイミング情報を記録する。 -
listener の callback、"
handleEvent"、« event »、および event のcurrentTarget属性値を用いて ユーザーオブジェクトの操作を呼び出す。 これが例外 exception を投げた場合:-
listener の callback に対応する JavaScript オブジェクトの 関連付けられたレルムの グローバルオブジェクトについて、 exception を 報告する。
-
与えられていれば 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 は、 作成、 初期化、および 配送を行うことを指す、 イベントについての短縮表現である。 イベントを発火するは、 その処理を書き下しやすくする。
イベントがその
bubbles
または cancelable
属性を初期化する必要がある場合、
「target で submit という名前のイベントを発火する。その
cancelable
属性は true に初期化する」と書ける。
また、カスタムコンストラクターが必要な場合は、
「MouseEvent
を用いて target で click という名前のイベントを発火する。その detail
属性は 1 に初期化する」と書ける。
戻り値が重要になることもある:
-
target で
likeという名前のイベントを発火する結果を doAction とする。 -
doAction が true である場合は、…
2.11. アクションと発生の違い
イベントは、
アクションではなく、発生した事柄を意味する。別の言い方をすれば、それは
アルゴリズムからの通知を表し、そのアルゴリズムの今後の進行に影響を与えるために
使用できる(例: preventDefault()
を呼び出すことによって)。
イベントは、
何らかのアルゴリズムの実行開始を引き起こすアクションや開始要因として
使用してはならない。それはイベントの目的ではない。
ここでこれを特に明記しているのは、DOM の以前の 反復版には、イベントに関連付けられた "default actions" という概念があり、人々にまったく誤った考えを与えていたためである。 イベントはアクションを表すものでも、 アクションを引き起こすものでもなく、進行中のアクションに影響を与えるためにのみ使用できる。
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,
or Attr。
DocumentFragment
を実装するオブジェクトは、ときに ShadowRoot
を実装する。
Element
を実装するオブジェクトは、通常、
HTMLAnchorElement
などの継承されたインターフェイスも実装する。
CharacterData
を実装するオブジェクトは、継承されたインターフェイスも実装する: Text,
ProcessingInstruction,
or Comment。
Text
を実装するオブジェクトは、ときに
CDATASection
を実装する。
したがって、すべてのノードの一次インターフェイスは、次のいずれかである: Document,
DocumentType,
DocumentFragment,
ShadowRoot,
Element または
Element
の継承されたインターフェイス,
Attr, Text, CDATASection,
ProcessingInstruction,
or 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 の データの長さを返す。 -
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. 変更アルゴリズム
ノード node、ノード parent、null または ノード child、およびリストである ノード群 childrenToExcludeが与えられたとき、挿入前の妥当性を確保するには、次を実行する:
-
parentが
Document、DocumentFragment、 またはElementノードでない場合、 "HierarchyRequestError"DOMExceptionを投げる。 -
nodeがparentのホストを含む包括的祖先である場合、 "
HierarchyRequestError"DOMExceptionを投げる。 -
childが非 null であり、その親がparentでない場合、 "
NotFoundError"DOMExceptionを投げる。 -
nodeが
DocumentFragment、DocumentType、Element、 またはCharacterDataノードでない場合、 "HierarchyRequestError"DOMExceptionを投げる。 -
parentが文書でない場合:
-
nodeが文書型である場合、 "
HierarchyRequestError"DOMExceptionを投げる。 -
返す。
-
-
nodeが
Textノードである場合、 "HierarchyRequestError"DOMExceptionを投げる。 -
nodeが
CharacterDataノードである場合、返す。 -
nodeが
DocumentFragmentノードである場合:-
nodeに複数の要素子があるか、
Textノードの子がある場合、 "HierarchyRequestError"DOMExceptionを投げる。
-
-
nodeが
DocumentFragmentまたはElementノードである場合:-
次のいずれかが真である場合:
その場合、"
HierarchyRequestError"DOMExceptionを投げる。 -
返す。
-
-
次のいずれかが真である場合:
その場合、"
HierarchyRequestError"DOMExceptionを投げる。
ノード nodeを、ノードparent内の、null またはノード childの前に事前挿入するには、次を実行する:
-
node、parent、child、および « » を与えて、 挿入前の妥当性を確保する。
-
referenceChildをchildとする。
-
referenceChildがnodeである場合、referenceChildを nodeの次の兄弟に設定する。
-
nodeをparent内のreferenceChildの前に挿入する。
-
nodeを返す。
仕様は、すべてまたは一部のノードについて、挿入手順を定義してもよい。 下記の挿入アルゴリズムに示すように、このアルゴリズムには insertedNodeが渡される。これらの手順は、insertedNodeが属するノードツリーを変更したり、閲覧コンテキストを作成したり、イベントを発火したり、その他の方法で JavaScript を実行したりしてはならない。ただし、これらの手順は、これらの処理を非同期に行うタスクをキューに入れることができる。
挿入手順は、(その他の処理とともに)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)' ; // 'rgb(255, 0, 0)' を記録する
style. innerText = 'h1 {color: rgb(255, 0, 0);}' ;
document. body. append( fragment);
上記の例のスクリプトがを記録するのは、
次の処理が順に行われるためである:
仕様は、すべてまたは一部のノードについて、 接続後手順を定義してもよい。下記の挿入アルゴリズムに示すように、このアルゴリズムには connectedNodeが渡される。
接続後手順の目的は、ノードが、connectedNodeの属するノードツリーを変更したり、閲覧コンテキストを作成したり、その他の方法で JavaScript を 実行したりする、接続関連の処理を行う機会を提供することである。これらの手順により、複数のノードを、 スクリプトに対して不可分に挿入でき、主要な副作用は、ノードツリーへの一括挿入が完了した 後にすべて発生する。これにより、保留中のすべてのノードツリーへの挿入が完全に終了してから、 さらなる挿入が行われることが保証される。
ノード nodeを、ノードparent内の、null またはノード childの前に、任意選択の真偽値suppressObservers(既定値は false)を指定して 挿入するには、次を実行する:
-
nodeが
DocumentFragmentノードである場合は、nodesを nodeの子群とし、そうでない場合は « node » とする。 -
countをnodesのサイズとする。
-
countが 0 の場合、返す。
-
nodeが
DocumentFragmentノードである場合:-
suppressObserversを true に 設定して、その子群を除去する。
-
« »、nodes、null、および null を指定して、nodeについて ツリー変更レコードをキューに入れる。
この手順は、意図的にsuppressObserversを考慮しない。
-
-
childが非 null である場合:
-
childが非 null の場合はchildの前の兄弟を、childが null の場合は parentの最後の子を、previousSiblingとする。
-
nodes内の各nodeについて、ツリー順で:
-
parentが、シャドウルートのスロット割り当てが "
named" であるシャドウホストであり、 nodeがスロット可能である場合、 nodeにスロットを割り当てる。 -
parentのルートがシャドウルートであり、 parentが、割り当てられたノード群が空のリストである スロットである場合、parentについて スロット変更を通知する。
-
nodeのルートを指定して、ツリーのスロット可能要素を割り当てる。
-
nodeの各シャドウを含む包括的子孫 inclusiveDescendantについて、シャドウを含むツリー順で:
-
inclusiveDescendantを指定して、挿入手順を実行する。
-
inclusiveDescendantが要素であり、 inclusiveDescendantのカスタム要素レジストリが 非 null である場合:
-
inclusiveDescendantのカスタム要素レジストリの スコープ付きであるが true の場合、 inclusiveDescendantのノード文書を、 inclusiveDescendantのカスタム要素レジストリの スコープ付き文書集合に付加する。
-
inclusiveDescendantがカスタムである場合、 inclusiveDescendant、コールバック名 "
connectedCallback"、および « » を指定して、 カスタム要素コールバック反応をキューに入れる。 -
そうでない場合、inclusiveDescendantのアップグレードを試みる。
これによって inclusiveDescendantが正常にアップグレードされた場合、 その
connectedCallbackは、要素をアップグレードする アルゴリズムの実行中に自動的にキューへ入れられる。
-
-
そうでなく、inclusiveDescendantがシャドウルートであり、 inclusiveDescendantのカスタム要素レジストリが 非 null であり、そのカスタム要素レジストリの スコープ付きであるが true の場合、 inclusiveDescendantのノード文書を、 inclusiveDescendantのカスタム要素レジストリの スコープ付き文書集合に付加する。
-
-
suppressObserversが false の場合、nodes、« »、 previousSibling、およびchildを指定して、parentについて ツリー変更レコードをキューに入れる。
-
parentについて子変更手順を実行する。
-
staticNodeListを、初期状態が « » であるノードのリストとする。
いずれかの接続後手順を呼び出す前に すべてのノードを収集し、ノードツリーを走査 しながら接続後手順を呼び出さない。これは、 接続後手順がツリー構造を変更できるため、 ライブ走査が安全でなくなり、同じノードについて接続後手順が複数回呼び出される可能性があるためである。
-
nodesの各nodeについて、ツリー順で:
-
nodeの各シャドウを含む包括的子孫 inclusiveDescendantについて、シャドウを含むツリー順で、 inclusiveDescendantをstaticNodeListに付加する。
-
-
staticNodeListの各nodeについて、nodeが 接続済みである場合、nodeを指定して接続後手順を実行する。
仕様は、すべてまたは一部のノードについて、 移動手順を定義してもよい。下記の移動アルゴリズムに示すように、このアルゴリズムには ノードmovedNode、真偽値 isSubtreeRoot、およびノードoldAncestorが渡される。 挿入手順と同様に、これらの手順は、 movedNodeが属するノードツリーを変更したり、閲覧コンテキストを作成したり、イベントを発火したり、その他の方法で JavaScript を実行したりしてはならない。ただし、これらの手順は、これらの処理を非同期に行うタスクをキューに 入れることができる。
ノード nodeを、ノードnewParent内の、null またはノード childの前に移動するには、次を実行する:
-
newParentのシャドウを含むルートが、 nodeのシャドウを含むルートと同一でない場合、 "
HierarchyRequestError"DOMExceptionを投げる。これには、newParentの接続済み状態がnodeの接続済み状態と同じ場合にのみ移動が行われることを保証する副作用がある。
-
nodeがnewParentのホストを含む包括的祖先である場合、 "
HierarchyRequestError"DOMExceptionを投げる。 -
childが非 null であり、その親がnewParentでない場合、 "
NotFoundError"DOMExceptionを投げる。 -
nodeが
ElementまたはCharacterDataノードでない場合、 "HierarchyRequestError"DOMExceptionを投げる。 -
nodeが
Textノードであり、 newParentが文書である場合、"HierarchyRequestError"DOMExceptionを投げる。 -
newParentが文書であり、nodeが
Elementノードであり、 かつ、newParentに要素子があるか、 childが文書型であるか、またはchildが非 null であり、 文書型がchildに後続する場合、"HierarchyRequestError"DOMExceptionを投げる。 -
oldParentをnodeの親とする。
-
表明:oldParentは非 null である。
-
nodeを指定して、ライブ範囲の除去前手順を実行する。
-
ルートのノード文書が nodeのノード文書である、各
NodeIteratorオブジェクトiteratorについて、nodeとiteratorを指定して、NodeIteratorの除去前手順を 実行する。 -
oldPreviousSiblingをnodeの前の兄弟とする。
-
oldNextSiblingをnodeの次の兄弟とする。
-
nodeが割り当て済みである場合、nodeの割り当て先スロットについてスロット可能要素を割り当てる。
-
oldParentのルートがシャドウルートであり、 oldParentが、割り当てられたノード群が空であるスロットである場合、 oldParentについてスロット変更を通知する。
-
-
oldParentのルートを指定して、ツリーのスロット可能要素を割り当てる。
-
nodeを指定して、ツリーのスロット可能要素を割り当てる。
-
-
childが非 null である場合:
-
childが非 null の場合はchildの前の兄弟を、そうでない場合は newParentの最後の子を、newPreviousSiblingとする。
-
newParentが、シャドウルートのスロット割り当てが "
named" であるシャドウホストであり、nodeが スロット可能である場合、nodeに スロットを割り当てる。 -
newParentのルートがシャドウルートであり、 newParentが、割り当てられたノード群が空であるスロットである場合、 newParentについてスロット変更を通知する。
-
nodeのルートを指定して、ツリーのスロット可能要素を割り当てる。
-
nodeの各シャドウを含む包括的子孫 inclusiveDescendantについて、シャドウを含むツリー順で:
-
inclusiveDescendantがnodeである場合は isSubtreeRootを true とし、そうでない場合は false とする。
-
inclusiveDescendant、isSubtreeRoot、および oldParentを指定して、移動手順を実行する。
移動アルゴリズムは、挿入および除去とは別のプリミティブであるため、 inclusiveDescendantについて挿入手順または除去手順を呼び出さない。
-
inclusiveDescendantがカスタムであり、 newParentが接続済みである場合、 inclusiveDescendant、コールバック名 "
connectedMoveCallback"、および « » を指定して、カスタム要素コールバック反応をキューに入れる。
-
-
« »、« node »、oldPreviousSibling、および oldNextSiblingを指定して、oldParentについてツリー変更レコードをキューに入れる。
-
« node »、« »、newPreviousSibling、および childを指定して、newParentについてツリー変更レコードをキューに入れる。
ノード parent内のノードchildを、ノードnodeで 置換するには、次を実行する:
-
node、parent、child、および « child » を指定して、挿入前の妥当性を確保する。
-
referenceChildをchildの次の兄弟とする。
-
referenceChildがnodeである場合、 referenceChildをnodeの次の兄弟に設定する。
-
previousSiblingをchildの前の兄弟とする。
-
removedNodesを空集合とする。
-
childの親が非 null である場合:
-
removedNodesを « child » に設定する。
-
suppressObserversを true に 設定して、childを除去する。
上記が false になり得るのは、childが nodeである場合のみである。
-
-
nodeが
DocumentFragmentノードである場合は、nodesを nodeの子群とし、そうでない場合は « node » とする。 -
suppressObserversを true に設定して、 nodeをparent内のreferenceChildの前に挿入する。
-
nodes、removedNodes、previousSibling、および referenceChildを指定して、parentについてツリー変更レコードをキューに入れる。
-
childを返す。
ノードまたは null であるnodeを用いて、ノードparent内をすべて置換するには、次を実行する:
-
removedNodesをparentの子群とする。
-
addedNodesを空集合とする。
-
nodeが
DocumentFragmentノードである場合、addedNodesを nodeの子群に設定する。 -
そうでなく、nodeが非 null である場合、addedNodesを « node » に設定する。
-
suppressObserversを true に設定して、 parentのすべての子を、ツリー順で除去する。
-
nodeが非 null である場合、suppressObserversを true に設定して、 nodeをparent内の null の前に挿入する。
-
addedNodesまたはremovedNodesのいずれかが空でない場合、addedNodes、 removedNodes、null、および null を指定して、parentについて ツリー変更レコードをキューに入れる。
このアルゴリズムは、ノードツリーの制約に関する チェックを一切行わない。仕様作成者は、これを慎重に使用する必要がある。
ノード childをノードparentから事前除去するには、次を実行する:
-
childの親がparentでない場合、 "
NotFoundError"DOMExceptionを投げる。 -
childを除去する。
-
childを返す。
仕様は、すべてまたは一部のノードについて、 除去手順を定義してもよい。下記の除去アルゴリズムに示すように、このアルゴリズムには ノードremovedNode、真偽値 isSubtreeRoot、およびノードoldAncestorが渡される。
ノード nodeを、任意選択の真偽値suppressObservers(既定値は false)を指定して 除去するには、次を実行する:
-
parentをnodeの親とする。
-
表明:parentは非 null である。
-
nodeを指定して、ライブ範囲の除去前手順を実行する。
-
ルートのノード文書が nodeのノード文書である、各
NodeIteratorオブジェクトiteratorについて、nodeとiteratorを指定して、NodeIteratorの除去前手順を 実行する。 -
oldPreviousSiblingをnodeの前の兄弟とする。
-
oldNextSiblingをnodeの次の兄弟とする。
-
nodeが割り当て済みである場合、nodeの割り当て先スロットについてスロット可能要素を割り当てる。
-
parentのルートがシャドウルートであり、 parentが、割り当てられたノード群が空のリストである スロットである場合、parentについて スロット変更を通知する。
-
-
parentのルートを指定して、ツリーのスロット可能要素を割り当てる。
-
nodeを指定して、ツリーのスロット可能要素を割り当てる。
-
-
node、true、およびparentを指定して、除去手順を実行する。
-
isParentConnectedをparentの接続済み状態とする。
-
nodeがカスタムであり、 isParentConnectedが true である場合、node、コールバック名 "
disconnectedCallback"、および « » を指定して、カスタム要素コールバック反応をキューに入れる。 -
nodeの各シャドウを含む子孫 descendantについて、シャドウを含むツリー順で:
-
descendant、false、およびparentを指定して、除去手順を実行する。
-
descendantがカスタムであり、 isParentConnectedが true である場合、descendant、 コールバック名 "
disconnectedCallback"、および « » を指定して、 カスタム要素コールバック反応をキューに入れる。
-
-
parentの各包括的祖先 inclusiveAncestorについて、次にinclusiveAncestorの 登録済みオブザーバーリスト内の registeredをそれぞれ処理し、registeredの オプション["
subtree"] が true の場合、オブザーバーが registeredのオブザーバーであり、 オプションが registeredのオプションであり、 ソースが registeredである新しい一時登録済みオブザーバーを、 nodeの登録済みオブザーバーリストに付加する。 -
suppressObserversが false の場合、« »、« node »、 oldPreviousSibling、およびoldNextSiblingを指定して、 parentについてツリー変更レコードをキューに入れる。
-
parentについて子変更手順を実行する。
4.2.4.
ミックスイン NonElementParentNode
Web 互換性により、getElementById()
メソッドは、要素上で公開されない(したがって
ParentNode
上でも公開されない)。
interface mixin {NonElementParentNode Element ?getElementById (DOMString ); };elementId Document includes NonElementParentNode ;DocumentFragment includes NonElementParentNode ;
ID で要素を取得するには、 ノード node と 文字列 elementId が与えられたとき、 node の子孫のうち、ツリー順で最初の、ID が elementId である要素を返す。 そのような要素が存在しない場合は、null を返す。
getElementById(elementId)
メソッドの手順は、this と
elementId が与えられたものとして、ID で要素を取得する結果を返すことである。
4.2.5.
ミックスイン DocumentOrShadowRoot
interface mixin {DocumentOrShadowRoot readonly attribute CustomElementRegistry ?customElementRegistry ; };Document includes DocumentOrShadowRoot ;ShadowRoot includes DocumentOrShadowRoot ;
registry = documentOrShadowRoot .customElementRegistry-
documentOrShadowRoot の
CustomElementRegistryオブジェクトがあればそれを返し、 そうでなければ null を返す。
customElementRegistry の
getter
手順は
次のとおりである:
-
this が文書である場合、this の カスタム要素レジストリを返す。
-
Assert: this は
ShadowRootノードである。 -
this のカスタム要素レジストリを返す。
DocumentOrShadowRoot
mixin は、文書と
シャドウルートの間で共有される
API を定義したい他の
標準によっても使用されることが期待されている。
4.2.6. ミックスイン ParentNode
リストであるノードおよび 文字列 nodes と、文書 document が与えられたとき、ノード群を 単一のノードに変換するには、次を行う:
-
nodes 内の各文字列を、document とその文字列を指定して テキストノードを作成した結果で 置き換える。
-
nodes のサイズが 1 ならば、nodes[0] を返す。
-
fragment を、document を指定して文書 フラグメントを作成した結果とする。
-
nodes の各 node について、node を fragment に付加する。
-
fragment を返す。
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 内の文字列を同等の
Textノードに 置き換えながら、nodes を node の最初の子の前に挿入する。ノードツリーの制約に違反する場合は、 "
HierarchyRequestError"DOMExceptionをスローする。 node . append(nodes)-
nodes 内の文字列を同等の
Textノードに 置き換えながら、nodes を node の最後の子の後に挿入する。ノードツリーの制約に違反する場合は、 "
HierarchyRequestError"DOMExceptionをスローする。 node . replaceChildren(nodes)-
nodes 内の文字列を同等の
Textノードに 置き換えながら、node のすべての子を nodes で置き換える。ノードツリーの制約に違反する場合は、 "
HierarchyRequestError"DOMExceptionをスローする。 node . moveBefore(movedNode, child)-
movedNode を最初に除去することなく、child が null でなければ child の後に、そうでなければ node の最後の子の後に、 node 内へ移動する。このメソッドは、movedNode に関連付けられた状態を 保持する。
ノードツリーの制約に違反する場合、または移動される ノードに関連付けられた状態を保持できない場合は、"
HierarchyRequestError"DOMExceptionをスローする。 node . querySelector(selectors)node . querySelectorAll(selectors)
children の取得手順は、this をルートとし、要素である子のみに一致する
HTMLCollection
コレクションを返すことである。
prepend(nodes) メソッドの手順は
次のとおりである:
append(nodes) メソッドの手順は
次のとおりである:
-
node を、nodes と this の ノード文書を指定してノード群を単一のノードに変換した結果とする。
replaceChildren(nodes)
メソッドの手順は
次のとおりである:
-
node を、nodes と this の ノード文書を指定してノード群を単一のノードに変換した結果とする。
-
node、this、null、および this の子を指定して、事前挿入の妥当性を確保する。
moveBefore(node, child)
メソッドの手順は次のとおりである:
querySelector(selectors)
メソッドの手順は、selectors を this に対して
セレクター文字列をスコープマッチする処理の最初の結果を、
結果が空のリストでない場合に返し、それ以外の場合は null を返すことである。
querySelectorAll(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 内の文字列を同等の
Textノードに 置き換えながら、nodes を node の直前に挿入する。ノードツリーの制約に違反する場合は、 "
HierarchyRequestError"DOMExceptionをスローする。 node .after(...nodes)-
nodes 内の文字列を同等の
Textノードに 置き換えながら、nodes を node の直後に挿入する。ノードツリーの制約に違反する場合は、 "
HierarchyRequestError"DOMExceptionをスローする。 node .replaceWith(...nodes)-
nodes 内の文字列を同等の
Textノードに 置き換えながら、node を nodes で置き換える。ノードツリーの制約に違反する場合は、 "
HierarchyRequestError"DOMExceptionをスローする。 node .remove()- node を除去する。
before(nodes) メソッドの手順は
次のとおりである:
-
parent が null ならば、返る。
-
viablePreviousSibling を、this に先行する 兄弟のうち、nodes 内にない最初のものとする。 そのようなものがなければ null とする。
-
node を、nodes と this の ノード文書を指定して、ノード群を単一のノードに変換した結果とする。
-
viablePreviousSibling が null ならば、それを parent の 最初の子に設定する。それ以外の場合は、 viablePreviousSibling の 次の兄弟に設定する。
-
事前挿入を用いて、node を viablePreviousSibling の前の parent 内に 挿入する。
after(nodes) メソッドの手順は
次のとおりである:
replaceWith(nodes) メソッドの手順は
次のとおりである:
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 を持つノードを返す。ノードはツリー順に並べられる。
オブジェクトのサポートされるプロパティインデックスは、0 から、 コレクションによって表されるノード数より 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]
- コレクションから、ID または名前が name である最初の要素を返す。
このオブジェクトのサポートされるプロパティインデックスは、 コレクションによって表される要素数より 1 少ない数までの、0 から始まる範囲内の数である。そのような 要素が存在しない場合、サポートされるプロパティインデックスは存在しない。
length の getter 手順は、
コレクションによって表されるノード数を返すことである。
item(index) メソッドの手順は、
コレクション内の
index番目の
要素を返すことである。コレクション内に
index番目の要素がない場合、このメソッドは
null を返さなければならない。
サポートされるプロパティ名は、次の手順によって 返されるリストの値である:
-
result を空リストとする。
-
コレクションによって表される各 element について、 ツリー順で:
-
result を返す。
namedItem(key) メソッドの手順は次のとおりである:
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 で発火させる。
各ノードは、登録済みオブザーバー リスト(0 個以上の登録済みオブザーバーからなるリスト)を持ち、これは初期状態では空である。
登録済み
オブザーバーは、
オブザーバー(MutationObserver
オブジェクト)と、
オプション(MutationObserverInit
辞書)からなる。
一時的な 登録済みオブザーバーは、 ソース(登録済みオブザーバー)も持つ 登録済み オブザーバーである。
一時的な登録済みオブザーバーは、ある
ノードが除去された後も、
その子孫内の変更を追跡するために使用される。これにより、
ノードの
親で
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
オブジェクトには、次の関連概念がある:
- 作成時に設定されるコールバック。
- ノードリスト(ノードへの弱参照からなるリスト)。これは初期状態では 空である。
- レコードキュー(0 個以上の
MutationRecordオブジェクトからなるキュー)。これは初期状態では空である。
observer = newMutationObserver(callback)MutationObserverオブジェクトを構築し、そのコールバックを callback に設定する。callback は、第 1 引数としてMutationRecordオブジェクトのリストを、第 2 引数として構築された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 に設定する。
attributeOldValueattributesが true または省略されており、 変更前の target の 属性の 値を記録する必要がある場合は、 true に設定する。characterDataOldValuecharacterDataが 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をそれぞれ処理し、registeredの オブザーバーがthisである場合:
-
thisのノードリスト内の各 nodeについて、nodeの登録済みオブザーバーリストから、 ソースが registeredであるすべての一時登録済みオブザーバーを除去する。
-
registeredのオプションを optionsに設定する。
-
-
そうでない場合:
-
オブザーバーがthisであり、オプションが optionsである新しい登録済みオブザーバーを、 targetの登録済みオブザーバーリストに付加する。
-
disconnect()メソッドの手順は、
次のとおりである:
-
thisのノードリスト内の各 nodeについて、thisがオブザーバーであるすべての 登録済みオブザーバーを、nodeの 登録済みオブザーバーリストから除去する。
4.3.2. ミューテーションレコードのキューイング
ミューテーションレコードをキューに入れるには、type・target・name・namespace・oldValue・addedNodes・removedNodes・previousSibling・nextSiblingを使って次を行う:
-
interestedObservers を空のマップとします。
-
nodes を target の包括的祖先とします。
-
nodes の各 node について、さらに node の登録済みオブザーバー リストの各 registered について反復する:
-
options を registered の options とします。
-
次のいずれも true でない場合
- 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 を、その
typeが type に設定され、targetが target に設定され、attributeNameが name に設定され、attributeNamespaceが namespace に設定され、oldValueが mappedOldValue に設定され、addedNodesが addedNodes に設定され、removedNodesが removedNodes に設定され、previousSiblingが previousSibling に設定され、かつnextSiblingが nextSibling に設定された、新しいMutationRecordオブジェクトとします。 -
observer を周囲のエージェントの 保留中のミューテーションオブザーバーに付加する。
-
ツリーミューテーションレコードをキューに入れるには、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 .targettypeに応じて、変更の影響を受けたノードを返す。 "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 は、すべての
ノードによって使用される抽象
インターフェイスである。このインターフェイスの直接のインスタンスを取得することはできない。
各ノードには、作成時に 設定される、文書である関連付けられた ノード 文書がある。
ノードのノード文書は、 採用アルゴリズムに よって変更できる。
ノードの親を取得するアルゴリズムは、 event が与えられたとき、ノードが割り当てられている場合は、 ノードの割り当てられたスロットを返し、 それ以外の場合は、ノードの親を返す。
各ノードには、登録済みオブザーバーリストもある。
文書 document が与えられたとき、インターフェイス interface を実装するノードを作成するには、次を行う:
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- そのターゲット。
Comment- "
#comment"。 Document- "
#document"。 DocumentType- その名前。
DocumentFragment- "
#document-fragment"。
nodeType の取得手順は、this が実装するインターフェイスに応じて分岐し、最初に一致する文を返すことである:
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 が実装するインターフェイスに応じて分岐し、最初に一致する文を返すことである:
Element- そのHTML 大文字化修飾名。
Attr- その修飾名。
- 排他的
Textノード - "
#text"。 CDATASection- "
#cdata-section"。 ProcessingInstruction- そのターゲット。
Comment- "
#comment"。 Document- "
#document"。 DocumentType- その名前。
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 の取得手順は、this が接続されている場合は true を返し、
それ以外の場合は false を返すことである。
ownerDocument の取得手順は、this が文書の場合は null を
返し、それ以外の場合はthis
のノード
文書を返すことである。
文書のノード文書は、その 文書自身である。すべての ノードは、常にノード 文書を持つ。
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 が実装するインターフェイスに応じて分岐し、次を返すことである:
Attr- this の値。
CharacterData- this のデータ。
- それ以外
- Null。
nodeValue
の設定手順は、指定された値が null の場合は代わりに空文字列であるかのように扱い、その後、this
が実装するインターフェイスに応じて分岐し、以下のように行うことである:
Attr-
this と指定された値を使用して、既存の属性値を設定する。
CharacterData- それ以外
-
何もしない。
ノード node を使用して テキスト内容を取得するには、 node が実装するインターフェイスに応じて分岐し、次を返す:
DocumentFragmentElement- node の子孫テキスト内容。
Attr- node の値。
CharacterData- node のデータ。
- それ以外
- Null。
textContent の取得手順は、
this を使用してテキスト内容を取得する処理を実行した結果を返すことである。
ノード parent 内で、 文字列 string を使用して文字列ですべて置換するには、次の手順を実行する:
-
node を null とする。
-
string が空文字列でない場合は、node を、parent のノード文書と string を指定してテキスト ノードを作成した結果に設定する。
-
parent 内のすべてを node で置き換える。
ノード node と文字列 value を使用してテキスト内容を設定するには、node が実装するインターフェイスに応じて分岐し、以下に定義されたとおりに行う:
DocumentFragmentElement-
node 内で value を使用して文字列ですべて 置換する。
Attr-
node と value を使用して既存の属性値を設定する。
CharacterData- それ以外
-
何もしない。
textContent
の設定手順は、指定された値が null の場合は代わりに空文字列であるかのように扱い、その後、this と指定された値を使用してテキスト内容を設定する処理を実行することである。
node .normalize()- 空の排他的
Textノードを除去し、残りの連続する排他的Textノードの データを、それらの ノードの最初のものに連結する。
normalize() メソッドの手順は、
this の各子孫である排他的 Text ノード
node について、次の手順を実行することである:
-
length を node の長さとする。
-
length が 0 の場合は、node を除去し、存在する場合は次の排他的
Textノードへ進む。 -
data を、node の 連続する排他的
Textノード(それ自身を除く)のデータを、ツリー順に連結したものとする。 -
node のデータを置換する。length、0、および data を使用する。
-
currentNode を node の次の兄弟とする。
-
currentNode が排他的
Textノードである間:-
開始 ノードが currentNode である各ライブ範囲について、その開始オフセットに length を加え、その 開始ノードを node に設定する。
-
終了ノードが currentNode である各ライブ範囲について、その終了オフセットに length を加え、その終了ノードを node に設定する。
-
開始 ノードが currentNode の 親であり、開始 オフセットが currentNode の インデックスである各ライブ範囲について、その開始 ノードを node に設定し、その 開始オフセットを length に 設定する。
-
終了ノードが currentNode の 親であり、終了 オフセットが currentNode の インデックスである各ライブ範囲について、その終了ノードを node に設定し、その 終了オフセットを length に 設定する。
-
currentNode の長さを length に加える。
-
currentNode を、その次の 兄弟に設定する。
-
-
node の連続する排他的
Textノード(それ自身を除く)を、ツリー順に除去する。
node . cloneNode([subtree = false])- node のコピーを返す。 subtree が true の場合、そのコピーには node の子孫も含まれる。
node . isEqualNode(otherNode)- node と otherNode が 同じプロパティを持つかどうかを返す。
HTML は、
input、
script、
および
template
など、いくつかの要素について複製手順を定義している。
SVG も、その
script
要素について同様に定義すべきであるが、定義していない。
ノード
node、省略可能な文書 document
(既定値は node のノード文書)、ブール値
subtree(既定値は false)、ノードまたは null の
parent(既定値は null)、および null または
CustomElementRegistry
オブジェクト fallbackRegistry
(既定値は null)が与えられたとき、ノードを複製するには、次を行う:
-
copy を、node、document、および fallbackRegistry を指定して単一のノードを複製した結果とする。
-
その他の適用可能な仕様で node について定義された複製手順を実行し、node、 copy、および subtree を引数として渡す。
-
parent が null でない場合は、copy を parent に付加する。
-
subtree が true の場合は、node の 子の各 child について、ツリー順に、child を指定してノードを複製する。その際、 document を document に、 subtree を subtree に、 parent を copy に、 fallbackRegistry を fallbackRegistry に設定する。
-
node が要素であり、node が シャドウ ホストであり、かつ node のシャドウルートの 複製可能が true の場合:
-
shadowRootRegistry を node のシャドウ ルートの カスタム要素レジストリとする。
-
shadowRootRegistry がグローバルカスタム要素 レジストリである場合、shadowRootRegistry を document の カスタム要素レジストリの有効なグローバルカスタム 要素レジストリに設定する。
-
シャドウルートをアタッチする(copy、 node の シャドウルートのmode、 node の シャドウルートのdelegates focus、 node の シャドウルートのserializable、 node の シャドウルートのslot assignment、true、および shadowRootRegistry を使用して実行する。
-
copy のシャドウルートの カスタム要素レジストリを null のままにするを、node の シャドウルートのカスタム要素レジストリを null のままにするに設定する。
-
node のシャドウルートの 子の各 child について、ツリー順に、child を指定してノードを複製する。その際、 document を document に、 subtree を true に、 parent を copy のシャドウルートに設定する。
これは意図的に fallbackRegistry 引数を 渡さない。
-
copy を返す。
ノード node、
文書
document、および null または CustomElementRegistry
オブジェクト
fallbackRegistry が与えられたとき、単一の
ノードを複製するには、次を行う:
-
copy を null とする。
-
node が要素である場合:
-
registry を node のカスタム要素レジストリとする。
-
registry が null の場合は、registry を fallbackRegistry に設定する。
-
registry がグローバルカスタム要素 レジストリである場合、registry を document のカスタム要素レジストリの 有効なグローバルカスタム 要素レジストリに設定する。
-
copy を、document、node のローカル 名、node の 名前空間、node の名前空間接頭辞、 node の
is値、false、および registry を指定して要素を 作成した結果に設定する。 -
node の 属性リストの各 attribute について反復する:
-
copyAttribute を、attribute、document、 および null を指定して単一のノードを複製した結果とする。
-
copyAttribute を copy に付加する。
-
-
-
それ以外で、node が文書である場合は、copy を、 document の関連するレルムを指定して、node と同じ インターフェイスを実装する文書を 作成した結果に設定する。
-
それ以外の場合は、copy を、document を指定して、 node と同じインターフェイスを実装するノードを作成した結果に設定する。
-
node が実装するインターフェイスに応じて分岐し、次の追加要件を満たす:
Document-
-
copy のエンコーディング、コンテンツ型、 URL、オリジン、型、 モード、および宣言的シャドウ ルートを許可するを、node のそれぞれの値に設定する。
-
node のカスタム要素レジストリの スコープ付きであるが true の場合は、 copy の カスタム要素レジストリを node の カスタム要素レジストリに 設定する。
-
DocumentTypeAttrTextComment-
copy のデータを node のデータに設定する。
ProcessingInstruction- それ以外
-
何もしない。
-
node が文書である場合は、document を copy に設定する。
-
copy のノード文書を document に設定する。
-
copy を返す。
cloneNode(subtree) メソッドの手順は
次のとおりである:
-
this がシャドウルートである場合は、 "
NotSupportedError"DOMExceptionをスローする。
isEqualNode(otherNode) メソッドの手順は、
otherNode が null でなく、かつthis が otherNode と等しい場合は true を返し、
それ以外の場合は false を返すことである。
isSameNode(otherNode) メソッドの手順は、
otherNode がthis である場合は true を返し、それ以外の場合は false を返すことである。
node .compareDocumentPosition(other)-
node に対する other の位置を示すビットマスクを返す。設定できるビットは
次のとおりである:
(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、16 進数では 10)Node.DOCUMENT_POSITION_CONTAINED_BY- other が node の子孫である場合に設定される。
node .contains(other)- other が node の包括的子孫である場合は true を返し、 それ以外の場合は false を返す。
compareDocumentPosition()
がマスクとして返す定数は次のとおりである:
DOCUMENT_POSITION_DISCONNECTED(1);DOCUMENT_POSITION_PRECEDING(2);DOCUMENT_POSITION_FOLLOWING(4);DOCUMENT_POSITION_CONTAINS(8);DOCUMENT_POSITION_CONTAINED_BY(16, 16 進数では 10);DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC(32、16 進数では 20)。
compareDocumentPosition(other)
メソッドの
手順は次のとおりである:
-
this が other である場合は、0 を返す。
-
node1 を other とし、node2 をthis とする。
-
attr1 と attr2 を null とする。
-
node2 が属性である場合:
-
attr2 を node2 に設定し、node2 を attr2 の 要素に設定する。
-
attr1 と node1 が null でなく、かつ node2 が node1 である場合:
-
node2 の 属性リストの各 attr について反復する:
-
attr が attr1 と等しい場合は、
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFICとDOCUMENT_POSITION_PRECEDINGを加算した結果を返す。 -
attr が attr2 と等しい場合は、
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFICとDOCUMENT_POSITION_FOLLOWINGを加算した結果を返す。
-
-
-
-
node1 または node2 が null であるか、node1 のルートが node2 のルートでない場合は、
DOCUMENT_POSITION_DISCONNECTED、DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC、 およびDOCUMENT_POSITION_PRECEDINGまたはDOCUMENT_POSITION_FOLLOWINGのいずれかを、一貫性が保たれるという制約の下で加算した結果を返す。DOCUMENT_POSITION_PRECEDINGとDOCUMENT_POSITION_FOLLOWINGのどちらを返すかは、通常、ポインター比較によって実装される。 JavaScript 実装では、キャッシュされたMath値を 使用できる。. random() -
node1 が node2 の祖先であり、かつ attr1 が null である場合、または node1 が node2 であり、かつ attr2 が null でない場合は、
DOCUMENT_POSITION_CONTAINSとDOCUMENT_POSITION_PRECEDINGを加算した結果を返す。 -
node1 が node2 の子孫であり、かつ attr2 が null である場合、または node1 が node2 であり、かつ attr1 が null でない場合は、
DOCUMENT_POSITION_CONTAINED_BYとDOCUMENT_POSITION_FOLLOWINGを加算した結果を返す。 -
node1 が node2 に先行する場合は、
DOCUMENT_POSITION_PRECEDINGを返す。このアルゴリズムにおける属性の処理方法により、属性が同じ ツリーに参加していないにもかかわらず、ノードの属性は、 そのノードの 子に 先行するものとして扱われる。
contains(other) メソッドの手順は、
other がthis の包括的子孫である場合は true を返し、
それ以外の場合は false を返すことである(other が null の場合を含む)。
namespace を使用して element の 名前空間接頭辞を特定するには、次の手順を実行する:
-
element の名前空間が namespace であり、その 名前空間接頭辞が null でない場合は、その 名前空間接頭辞を返す。
-
element が、名前空間接頭辞が "
xmlns" であり、値が namespace である属性を持つ場合は、element のそのような 最初の属性の ローカル名を返す。 -
element の親要素が null でない場合は、namespace を使用してその 要素に対して名前空間接頭辞を特定する処理を実行した結果を返す。
-
null を返す。
prefix を使用して node の名前空間を特定するには、node が実装するインターフェイスに応じて分岐する:
Element-
-
prefix が "
xml" の場合は、XML 名前空間を返す。 -
prefix が "
xmlns" の場合は、XMLNS 名前空間を返す。 -
その要素が、名前空間が XMLNS 名前空間で、名前空間接頭辞が "
xmlns" であり、 ローカル名が prefix である 属性を持つ場合、または prefix が null であり、かつその要素が、名前空間が XMLNS 名前空間で、名前空間接頭辞が null であり、ローカル名が "xmlns" である属性を持つ場合は、その値が空文字列でなければその値を返し、 それ以外の場合は null を返す。 -
その親 要素が null の場合は、null を返す。
-
DocumentDocumentTypeDocumentFragment-
null を返す。
Attr- それ以外
lookupPrefix(namespace) メソッドの手順は
次のとおりである:
-
namespace が null または空文字列の場合は、null を返す。
-
Element-
namespace を使用してthis の名前空間接頭辞を特定した結果を返す。
Document-
-
namespace を使用してthis の 文書要素の名前空間接頭辞を特定した結果を返す。
DocumentTypeDocumentFragment-
null を返す。
Attr-
-
namespace を使用してthis の 要素の名前空間接頭辞を特定した結果を返す。
- それ以外
-
-
namespace を使用してthis の 親要素の名前空間接頭辞を特定した結果を返す。
lookupNamespaceURI(prefix) メソッドの
手順は次のとおりである:
isDefaultNamespace(namespace) メソッドの
手順は次のとおりである:
-
namespace が空文字列の場合は、それを null に設定する。
-
defaultNamespace が namespace と同じ場合は true を返し、それ以外の場合は false を返す。
insertBefore(node, child)
メソッドの手順は、node を child の前のthis 内へ事前挿入した結果を返すことである。
appendChild(node) メソッドの手順は、
node をthis に付加した結果を返すことである。
replaceChild(node, child)
メソッドの手順は、this
内で child を node に置き換えた結果を返すことである。
removeChild(child) メソッドの手順は、
this から
child を事前除去した結果を返すことである。
ノード root の
修飾名
qualifiedName を持つ要素のリストは、次の
アルゴリズムによって返される HTMLCollection
である:
-
qualifiedName が U+002A (*) の場合は、root をルートとし、フィルターが 子孫要素のみに一致する
HTMLCollectionを返す。 -
それ以外で、root のノード文書がHTML 文書である場合は、 root をルートとし、フィルターが次の 子孫要素に一致する
HTMLCollectionを返す: -
それ以外の場合は、root をルートとし、フィルターが、修飾名が qualifiedName である子孫要素に一致する
HTMLCollectionを返す。
同じ引数で呼び出され、かつ root の
ノード
文書の型が変更されていない限り、以前の呼び出しで返されたものと
同じ HTMLCollection
オブジェクトを返してもよい。
ノード root の
名前空間
namespace とローカル名
localName を持つ要素のリストは、次のアルゴリズムによって返される
HTMLCollection
である:
-
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
オブジェクトを返してもよい。
ノード root の
クラス名
classNames を持つ要素のリストは、次の
アルゴリズムによって返される HTMLCollection
である:
- 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 ; };
各文書には、関連付けられた
エンコーディング(エンコーディング)、
コンテンツ型(文字列)、
URL(URL)、
オリジン(オリジン)、
型("xml" または "html")、
モード("no-quirks"、"quirks"、または
"limited-quirks")、
宣言的シャドウルートを許可する(ブール値)、および
カスタム要素レジストリ(null または CustomElementRegistry
オブジェクト)がある。
[ENCODING]
[URL]
[HTML]
別段の記載がない限り、文書のエンコーディングは
utf-8 エンコーディング、コンテンツ型は
"application/xml"、URL は "about:blank"、
オリジンは
不透明なオリジン、
型は
"xml"、モードは
"no-quirks"、宣言的シャドウルートを許可するは false、
カスタム要素レジストリは null である。
文書は、その
型が
"xml" である場合、XML
文書と呼ばれ、それ以外の場合はHTML
文書と呼ばれる。
文書が
HTML 文書であるか
XML 文書であるかは、
特定の API の動作に影響する。
文書は、その
モードが
"no-quirks" である場合、
非互換モードなし
モードにあるといい、そのモードが
"quirks" である場合、
互換モードに
あるといい、その
モードが
"limited-quirks" である場合、
限定互換
モードにあるという。
モードが
既定値から変更されるのは、DOCTYPE 文字列の有無または値に基づいて
HTML パーサーによって作成された文書、および新しい
閲覧コンテキスト(初期 "about:blank")に
限られる。[HTML]
非互換モードなしモードは、当初 「標準モード」と呼ばれ、限定互換モードは、かつて 「ほぼ標準モード」と呼ばれていた。現在ではその詳細が標準によって定義されているため、 名前が変更された。(また、Ian Hickson が、それらの元の名称は無意味であるという理由で 拒否したためでもある。)
文書の
親を取得する
アルゴリズムは、event が与えられたとき、event の type
属性値が "load" である場合、または
文書が
閲覧コンテキストを持たない場合は null を返し、
それ以外の場合は、文書の関連するグローバルオブジェクトを返す。
レルム realm が与えられたとき、インターフェイス interface を実装する 文書を 作成するには、次を行う:
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 のオリジンを、
現在のグローバルオブジェクトの関連付けられた Documentの
オリジンに設定することである。[HTML]
createDocument()
とは異なり、このコンストラクターは XMLDocument
オブジェクトではなく、文書(Document
オブジェクト)を返す。
implementation の取得手順は、
this に関連付けられた
DOMImplementation
オブジェクトを返すことである。
URL および
documentURI の取得手順は、this のURL を直列化して返すことである。
compatMode の取得手順は、
this のモードが
"quirks" である場合は "BackCompat" を返し、
それ以外の場合は "CSS1Compat" を返すことである。
characterSet、
charset、および
inputEncoding の取得手順は、
this のエンコーディングの名前を返すことである。
contentType の取得手順は、
this のコンテンツ型を返すことである。
- document .
doctype - 文書型を返し、 存在しない場合は null を返す。
- document .
documentElement - 文書要素を返す。
collection = document . getElementsByTagName(qualifiedName)-
qualifiedName が "
*" の場合、すべての 子孫要素からなるHTMLCollectionを返す。それ以外の場合、修飾名が qualifiedName である、 すべての子孫 要素からなる
HTMLCollectionを返す。(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 の子のうち、
文書型であるものを返し、それ以外の場合は null
を返すことである。
documentElement の取得手順は、
this の文書要素を返すことである。
getElementsByTagName(qualifiedName)
メソッドの手順は、this の
修飾名
qualifiedName を持つ要素のリストを
返すことである。
したがって、HTML
文書内では、
document
は、HTML 名前空間にない <FOO> 要素、および
HTML 名前空間にある <foo> 要素には一致するが、
HTML 名前空間にある <FOO> 要素には一致しない。
getElementsByTagNameNS(namespace, localName)
メソッドの手順は、this の
名前空間 namespace とローカル名
localName を持つ要素のリストを返すことである。
getElementsByClassName(classNames)
メソッドの手順は、this の
クラス名 classNames を持つ要素のリストを
返すことである。
< div id = "example" >
< p id = "p1" class = "aaa bbb" />
< p id = "p2" class = "aaa ccc" />
< p id = "p3" class = "bbb ccc" />
</ div >
document
を呼び出すと、2 つの段落 p1 と p2 を含む HTMLCollection
が返される。
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と options のisの両方が指定された場合、 "NotSupportedError"DOMExceptionがスローされる。 element = document . createElementNS(namespace, qualifiedName [, options])-
名前空間 namespace を持つ 要素を返す。その 名前空間接頭辞は、 qualifiedName 内の U+003A (:) より前のすべて、または null となる。その ローカル名は、 qualifiedName 内の U+003A (:) より後のすべて、または qualifiedName となる。
options が指定された場合、その
customElementRegistryを使用してCustomElementRegistryを設定できる。options が指定された場合、その
isを使用してカスタマイズされた組み込み要素を作成できる。qualifiedName が(接頭辞を持つ可能性のある) 妥当な要素ローカル名でない場合、 "
InvalidCharacterError"DOMExceptionがスローされる。次のいずれかの条件が true の場合、 "
NamespaceError"DOMExceptionがスローされる:- 名前空間接頭辞が null でなく、 namespace が空文字列である。
- 名前空間接頭辞が
"
xml" であり、namespace が XML 名前空間でない。 - qualifiedName または
名前空間接頭辞が
"
xmlns" であり、namespace が XMLNS 名前空間でない。 - namespace がXMLNS
名前空間であり、
qualifiedName と
名前空間接頭辞のいずれも
"
xmlns" でない。
options の
customElementRegistryと options のisの両方が指定された場合、 "NotSupportedError"DOMExceptionがスローされる。 documentFragment = document .createDocumentFragment()DocumentFragmentノードを返す。text = document .createTextNode(data)- データが data
である
Textノードを返す。 text = document .createCDATASection(data)- データが data
である
CDATASectionノードを返す。 comment = document .createComment(data)- データが data
である
Commentノードを返す。 processingInstruction = document .createProcessingInstruction(target, data)-
ターゲットが
target であり、
データが data
である
ProcessingInstructionノードを返す。 target がName生成規則に一致しない場合、 "InvalidCharacterError"DOMExceptionがスローされる。 data に "?>" が含まれる場合、 "InvalidCharacterError"DOMExceptionがスローされる。
任意の name と namespace に対する
要素
インターフェイスは、別段の記載がない限り Element である。
たとえば HTML 標準は、html と
HTML 名前空間に対して、HTMLHtmlElement
インターフェイスが使用されることを定義する。[HTML]
createElement(localName, options)
メソッドの手順は次のとおりである:
-
localName が妥当な要素ローカル名でない場合は、 "
InvalidCharacterError"DOMExceptionをスローする。 -
this がHTML 文書である場合は、localName を ASCII 小文字に変換した localName に設定する。
-
registry と is を、options と this を指定して要素作成オプションを平坦化した結果とする。
-
this がHTML 文書である場合、または this のコンテンツ型が "
application/xhtml+xml" である場合は、namespace を HTML 名前空間とし、それ以外の場合は null とする。 -
this、localName、 namespace、null、is、true、および registry を指定して 要素を作成した結果を返す。
document、namespace、qualifiedName、および
options が与えられたとき、
内部
createElementNS 手順は次のとおりである:
-
(namespace, prefix, localName) を、 "
element" を指定して namespace と qualifiedName を検証して抽出した結果とする。 -
registry と is を、options と this を指定して要素作成オプションを平坦化した結果とする。
-
document、localName、namespace、 prefix、is、true、および registry を指定して 要素を作成した結果を返す。
createElementNS(namespace, qualifiedName, options)
メソッドの手順は、this、
namespace、qualifiedName、および options を指定して
内部 createElementNS 手順を
実行した結果を返すことである。
文字列または ElementCreationOptions
辞書 options と文書 document が与えられたとき、
要素作成オプションを平坦化するには、次を行う:
-
registry を、document を指定してカスタム要素レジストリを検索した結果とする。
-
is を null とする。
-
options が辞書である場合:
-
options["
customElementRegistry"] が存在する場合:-
is が null でない場合は、 "
NotSupportedError"DOMExceptionをスローする。 -
registry を options["
customElementRegistry"] に設定する。
-
-
registry が null でなく、registry の スコープ付きであるが false であり、かつ registry が document のカスタム要素レジストリでない場合は、 "
NotSupportedError"DOMExceptionをスローする。
-
registry と is を返す。
createElement()
および createElementNS()
の options 引数には、ウェブ互換性のため文字列を使用することが許可されている。
createDocumentFragment() メソッドの
手順は、this
を指定して文書フラグメントを作成した結果を返すことである。
createTextNode(data) メソッドの
手順は、this と
data を指定してテキストノードを作成した結果を返すことである。
createCDATASection(data) メソッドの
手順は次のとおりである:
-
this がHTML 文書である場合は、 "
NotSupportedError"DOMExceptionをスローする。 -
data に文字列 "
]]>" が含まれる場合は、 "InvalidCharacterError"DOMExceptionをスローする。 -
node を、this を指定して
CDATASectionを実装するノードを作成した結果とする。 -
node のデータを data に設定する。
-
node を返す。
createComment(data) メソッドの手順は、
this と
data を指定してコメントノードを作成した結果を
返すことである。
createProcessingInstruction(target, data)
メソッドの手順は、this、
target、および data を指定して処理命令ノードを作成した結果を返すことである。
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 がブール値である場合は、subtree を options に設定する。
-
それ以外の場合:
-
subtree を options["
selfOnly"] の否定に設定する。 -
options["
customElementRegistry"] が存在する場合は、registry をそれに設定する。 -
registry のスコープ付きであるが false であり、かつ registry がthis のカスタム要素レジストリでない場合は、 "
NotSupportedError"DOMExceptionをスローする。
-
-
registry が null の場合は、this を指定してカスタム要素レジストリを検索した結果に registry を設定する。
-
node を指定してノードを複製した結果を返す。その際、 document をthis に、 subtree を subtree に、 fallbackRegistry を registry に設定する。
ノード node を文書 document に 採用するには、次を行う:
-
oldDocument を node のノード文書とする。
-
document が oldDocument でない場合は、node の シャドウを含む包括的子孫の 各 inclusiveDescendant について、シャドウを含むツリー順に:
-
inclusiveDescendant のノード文書を document に設定する。
-
inclusiveDescendant がシャドウルートであり、かつ次のいずれかが true である場合:
-
inclusiveDescendant の カスタム要素レジストリが null であり、かつ inclusiveDescendant の カスタム要素 レジストリを null のままにするが false である、または
-
inclusiveDescendant の カスタム要素レジストリが グローバルカスタム要素 レジストリである。
その場合は、inclusiveDescendant の カスタム要素レジストリを、 document のカスタム要素レジストリの 有効なグローバルカスタム要素 レジストリに設定する。
-
-
それ以外で、inclusiveDescendant が要素である場合:
-
inclusiveDescendant の カスタム要素レジストリが null であるか、または inclusiveDescendant の カスタム要素レジストリの スコープ付きであるが false である場合:
-
registry を null とする。
-
inclusiveDescendant の カスタム要素 レジストリが null でなく、 inclusiveDescendant の親が null であるか、 または inclusiveDescendant の親が 排他的
DocumentFragmentノードである場合は、 registry を document の カスタム要素 レジストリに設定する。 -
それ以外の場合は、inclusiveDescendant の 親を指定して カスタム要素 レジストリを検索した結果に registry を設定する。
-
inclusiveDescendant の カスタム要素 レジストリを、registry の 有効な グローバルカスタム要素レジストリに設定する。
-
-
inclusiveDescendant がカスタムである場合は、 inclusiveDescendant、コールバック名 "
adoptedCallback"、および « oldDocument, document » を指定してカスタム要素 コールバックリアクションをキューに入れる。
-
inclusiveDescendant と oldDocument を使用して 採用手順を実行する。
-
adoptNode(node) メソッドの手順は
次のとおりである:
-
node が文書である場合は、 "
NotSupportedError"DOMExceptionをスローする。 -
node がシャドウルートである場合は、 "
HierarchyRequestError"DOMExceptionをスローする。 -
node を返す。
null または CustomElementRegistry
オブジェクト registry は、registry が null でなく、かつ
registry のスコープ付きであるが false である場合、
グローバルカスタム要素レジストリである。
null または CustomElementRegistry
オブジェクト registry の
有効なグローバルカスタム要素レジストリは
次のとおりである:
-
registry がグローバルカスタム要素レジストリである 場合は、registry を返す。
-
null を返す。
createAttribute(localName) メソッドの
手順は次のとおりである:
-
localName が妥当な属性ローカル名でない場合は、 "
InvalidCharacterError"DOMExceptionをスローする。 - this がHTML 文書である場合は、localName を ASCII 小文字に変換した localName に設定する。
createAttributeNS(namespace, qualifiedName)
メソッドの手順は次のとおりである:
-
(namespace, prefix, localName) を、 "
attribute" を指定して namespace と qualifiedName を検証して抽出した結果とする。
createEvent(interface) メソッドの
手順は次のとおりである:
-
constructor を null とする。
-
interface が、次の表の第 1 列にあるいずれかの文字列と ASCII 大文字・小文字を区別せず一致する場合は、 constructor を、一致した文字列と同じ行の第 2 列にあるインターフェイスに設定する:
文字列 インターフェイス 注記 " 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 が示すインターフェイスが、this の関連するグローバルオブジェクトで公開されていない 場合は、 "
NotSupportedError"DOMExceptionをスローする。通常、ユーザーエージェントは一部の構成でタッチイベントの サポートを無効にする。その場合、この規定は
TouchEventインターフェイスに対して適用される。 -
event を、constructor を指定してイベントを作成した結果とする。
-
event の
type属性を空文字列に初期化する。 -
event の
timeStamp属性を、this の関連するグローバルオブジェクトを使用して 現在の高分解能時刻を呼び出した結果に 初期化する。 -
event の
isTrusted属性を false に初期化する。 -
event の初期化済みフラグを解除する。
-
event を返す。
代わりにイベントコンストラクターを使用すべきである。
createRange() メソッドの手順は、
(this, 0) をその開始および終了として持つ新しいライブ範囲を返すことである。
代わりに Range()
コンストラクターを使用できる。
createNodeIterator(root, whatToShow, filter)
メソッドの手順は次のとおりである:
-
iterator を新しい
NodeIteratorオブジェクトとする。 -
iterator のルートを root に設定する。
-
iterator の参照を (root, true) に設定する。
-
iterator のwhatToShow を whatToShow に設定する。
-
iterator のフィルターを filter に設定する。
-
iterator を返す。
createTreeWalker(root, whatToShow, filter)
メソッドの手順は次のとおりである:
-
walker を新しい
TreeWalkerオブジェクトとする。 -
walker のwhatToShow を whatToShow に設定する。
-
walker のフィルターを 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 (); // historical; always returns true };
doctype = document .implementation.createDocumentType(name, publicId, systemId)-
指定された name、publicId、および systemId を持つ
文書型を返す。
name が妥当な文書型名でない場合、 "
InvalidCharacterError"DOMExceptionがスローされる。 doc = document .implementation. createDocument(namespace, qualifiedName [, doctype = null])-
文書要素を持つ
XMLDocumentを返す。その文書要素の ローカル名は qualifiedName であり、 名前空間は namespace である(qualifiedName が 空文字列である場合を除く)。また、doctype が指定されている場合は、それを 文書型として持つ。このメソッドは、namespace と qualifiedName を指定して呼び出された
createElementNS()メソッドと同じ例外をスローする。 doc = document .implementation. createHTMLDocument([title])-
title 引数が省略されていない限り、
title要素を含む基本的な ツリーが あらかじめ構築された文書を返す。
createDocumentType(name, publicId, systemId)
メソッドの手順は次のとおりである:
-
name が妥当な文書型名でない場合は、 "
InvalidCharacterError"DOMExceptionをスローする。 -
this に関連付けられた文書、 name、publicId、および systemId を指定して 文書型を作成した結果を返す。
createDocument(namespace, qualifiedName, doctype)
メソッドの手順は次のとおりである:
-
document を、this の関連するレルムを指定して、
XMLDocumentを実装する文書を作成した結果とする。 -
element を null とする。
-
qualifiedName が空文字列でない場合は、 document、namespace、qualifiedName、および空の辞書を指定して 内部
createElementNS手順を 実行した結果に element を設定する。 -
doctype が null でない場合は、doctype を document に付加する。
-
element が null でない場合は、element を document に付加する。
-
document のコンテンツ型は namespace によって決定される:
-
document を返す。
createHTMLDocument(title)
メソッドの手順は次のとおりである:
-
doctype を、doc と "
html" を指定して 文書型を作成した結果とする。 -
doctype を doc に付加する。
-
doc、"
head"、およびHTML 名前空間を指定して 要素を作成した結果を、先に作成したhtml要素に付加する。 -
title が指定されている場合:
-
doc、"
body"、およびHTML 名前空間を指定して 要素を作成した結果を、先に作成したhtml要素に付加する。 -
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
ノードは、単に
文書型と呼ばれる。
文書型には、関連付けられた 名前(文字列)、 公開 ID(文字列)、および システム ID(文字列)がある。
文書 document、文字列 name、および省略可能な文字列 publicId(既定値は空文字列)と文字列 systemId(既定値は空文字列)が与えられたとき、文書型を作成するには、次を行う:
-
doctype を、document を指定して
DocumentTypeを実装するノードを作成した結果とする。 -
doctype の名前を name に、公開 IDを publicId に、システム IDを systemId に設定する。
-
doctype を返す。
name の取得手順は、
this の名前を返すことである。
publicId の取得手順は、
this の公開
IDを返すことである。
systemId の取得手順は、
this のシステム
IDを返すことである。
4.7.
インターフェイス DocumentFragment
[Exposed =Window ]interface :DocumentFragment Node {constructor (); };
tree = newDocumentFragment()- 新しい
DocumentFragmentノードを返す。
排他的 DocumentFragment
ノードとは、ShadowRoot
ノードではない DocumentFragment
ノードである。
DocumentFragment
ノードには、関連付けられた
ホスト(null、または異なるノードツリー内の
要素)がある。別段の
記載がない限り、これは null である。
オブジェクト A がオブジェクト B の ホストを含む包括的祖先であるのは、 A が B の包括的 祖先である場合、または B のルートが null でないホストを 持ち、かつ A が B のルートの ホストのホストを含む包括的祖先である場合である。
DocumentFragment
ノードのホストの
概念は、HTML の
template
要素およびシャドウルートに有用であり、
事前挿入
および置換
アルゴリズムに影響する。
文書
document が与えられたとき、文書フラグメントを作成するには、document を
指定して DocumentFragment
を実装するノードを作成した結果を返す。
new DocumentFragment()
コンストラクターの手順は、this のノード文書を、
現在のグローバルオブジェクトの関連付けられた Documentに設定することである。
4.8. インターフェイス ShadowRoot
[Exposed =Window ]interface :ShadowRoot DocumentFragment {readonly attribute ShadowRootMode mode ;readonly attribute boolean delegatesFocus ;readonly attribute boolean serializable ;readonly attribute SlotAssignmentMode slotAssignment ;readonly attribute boolean clonable ;readonly attribute Element host ;attribute EventHandler onslotchange ; };enum {ShadowRootMode ,"open" };"closed" enum {SlotAssignmentMode ,"manual" };"named"
ShadowRoot
ノードは、単に
シャドウルートと呼ばれる。
シャドウルートに 関連付けられたホストは、決して null ではない。
シャドウルートには、
関連付けられたモード("open"
または "closed")がある。
シャドウルートには、 関連付けられたフォーカスを委譲する (ブール値)がある。これは初期状態では false に設定される。
シャドウルートには、 関連付けられた 要素内部で利用可能(ブール値)がある。これは 初期状態では false に設定される。
シャドウルートには、 関連付けられた宣言的 (ブール値)がある。これは初期状態では false に設定される。
シャドウルートには、 関連付けられた serializable(真偽値)がある。 初期状態では false に設定される。
シャドウルートには、
関連付けられた slot assignment
("manual" または "named")がある。
シャドウルートには、 関連付けられた clonable(真偽値)がある。 初期状態では false に設定される。
シャドウルートには、
関連付けられたカスタム要素レジストリ
(null または CustomElementRegistry
オブジェクト)がある。これは初期状態では null である。
シャドウルートには、 関連付けられた カスタム要素レジストリを null のままにする (ブール値)がある。 これは初期状態では false である。
これが true になり得るのは、宣言的シャドウルートと組み合わせた場合のみである。 また、シャドウルートのカスタム 要素レジストリが null である間に限り意味を持つ。
シャドウルートの親を取得するアルゴリズムは、 event が与えられたとき、 event のcomposed フラグが設定されておらず、かつシャドウルートが event のパスの最初のイベントパス項目の 呼び出し対象のルートである場合は null を返し、 それ以外の場合はシャドウルートの ホストを返す。
mode の取得手順は、
this のモードを返すことである。
delegatesFocus の取得手順は、
this のフォーカスを委譲するを返すことである。
serializable getter steps は
this の serializable を返すことである。
slotAssignment getter steps は
this の slot
assignment を返すことである。
clonable getter steps は
this の clonable
を返すことである。
host の取得手順は、
this のホストを返すことである。
onslotchange 属性は、
onslotchange イベントハンドラーのためのイベントハンドラー IDL 属性であり、その
イベントハンドラーイベント型は slotchange
である。
シャドウを含むツリー順とは、 シャドウを含む前順深さ優先走査による ノードツリーの順序である。 ノードツリー tree のシャドウを含む前順深さ優先走査とは、 tree の前順深さ優先走査であり、tree 内で検出された各 シャドウホスト について、その検出直後に、その要素の シャドウルートのノードツリーの シャドウを含む前順深さ優先走査を 行うものである。
オブジェクトのシャドウを含むルートは、そのオブジェクトの ルートが シャドウルートである場合、その ルートの ホストのシャドウを含む ルートであり、それ以外の場合はその ルートである。
オブジェクト A がオブジェクト B のシャドウを含む子孫であるのは、 A が B の子孫である場合、または A の ルートが シャドウルートであり、かつ A のルートの ホストが B のシャドウを含む包括的子孫である場合である。
シャドウを含む包括的子孫とは、 あるオブジェクト自身、またはそのシャドウを含む子孫のいずれかである。
オブジェクト A がオブジェクト B のシャドウを含む祖先であるのは、 B が A のシャドウを含む子孫である場合、かつその場合に 限る。
シャドウを含む包括的祖先とは、 あるオブジェクト自身、またはそのシャドウを含む祖先のいずれかである。
ノード A は、 次のすべての条件が true である場合、ノード B から閉じたシャドウによって隠されている:
オブジェクト A をオブジェクト B に対して再ターゲットするには、 オブジェクトが返されるまで次の手順を繰り返す:
-
次のいずれかが true の場合
その場合、A を返す。
再ターゲット アルゴリズムは、イベントのディスパッチだけでなく、 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 ;boolean =serializable false ;SlotAssignmentMode = "named";slotAssignment boolean =clonable false ;CustomElementRegistry ?; };customElementRegistry
ShadowRootInit
はやや異例として、その customElementRegistry
メンバーに undefined と
null の両方を渡せるようにしている。これは、ウェブ開発者が attachShadow()
に辞書の代わりに ShadowRoot
ノードを渡せるようにするためである。
要素には、次のものが 関連付けられている:
- 名前空間
- Null または空でない文字列。
- 名前空間接頭辞
- Null または空でない文字列。
- ローカル名
- 空でない文字列。
- カスタム要素レジストリ
- Null または
CustomElementRegistryオブジェクト。 - カスタム要素状態
- "
undefined"、"failed"、"uncustomized"、 "precustomized"、または "custom"。 - カスタム要素定義
- Null またはカスタム要素定義。
is値- Null または有効なカスタム要素名。
要素のカスタム要素状態が
"uncustomized" または "custom" である場合、その要素は
定義済みであるという。要素の
カスタム要素状態が "custom" で
ある場合、その要素は
カスタムであるという。
要素が定義済みであるかどうかは、
:defined
擬似クラスの動作を決定するために使用される。要素がカスタムであるかどうかは、
変更アルゴリズムの動作を決定するために使用される。
"failed" 状態と "precustomized" 状態は、カスタム要素コンストラクターが最初に正しく実行されなかった
場合に、アップグレードによって再び実行されないことを保証するために
使用される。
次のコードは、これら 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() を省略している
}
})
</ 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 でない場合である。
要素の
修飾名は、その
ローカル
名である。ただし、その名前空間接頭辞が null でない場合は、その
名前空間接頭辞、それに続く ":"、
さらにそれに続く
ローカル
名である。
要素のHTML 大文字化修飾名は、次の手順の返値である:
ユーザーエージェントは、修飾名と HTML 大文字化修飾名を内部スロットに 格納することで最適化できる。
文書
document、文字列 localName、文字列または null の
namespace、および省略可能な文字列または null の prefix(既定値は null)、
文字列または null の is(既定値は null)、ブール値
synchronousCustomElements(既定値は false)、ならびに "default"、
null、または CustomElementRegistry
オブジェクト registry(既定値は "default")が与えられたとき、
要素を
作成するには:
-
result を null とする。
-
registry が "
default" である場合は、 document を指定してカスタム要素レジストリを検索した 結果に registry を設定する。 -
definition を、 registry、namespace、localName、および is を指定して カスタム要素定義を検索した結果とする。
-
definition が null でなく、かつ definition の 名前がその ローカル名と等しくない場合 (すなわち、definition が カスタマイズされた組み込み要素を表す場合):
-
interface を、localName と HTML 名前空間に対する要素インターフェイスとする。
-
result を、document、interface、 localName、HTML 名前空間、 prefix、"
undefined"、is、および registry を指定して要素を 内部的に作成した結果に設定する。 -
synchronousCustomElements が true の場合は、例外を捕捉しながら次の 手順を実行する:
-
definition を使用して result を アップグレードする。
この手順が例外 exception をスローした場合:
-
definition の コンストラクター に対応する JavaScript オブジェクトの 関連付けられたレルムのグローバルオブジェクトについて、 exception を報告する。
-
result のカスタム要素状態を "
failed" に設定する。
-
-
それ以外の場合は、result と definition を指定してカスタム要素アップグレード リアクションをキューに入れる。
-
-
それ以外で、definition が null でない場合:
-
synchronousCustomElements が true の場合:
-
C を、definition の コンストラクター とする。
-
previousRegistry を、周囲のエージェントの アクティブなカスタム要素 コンストラクターマップ[C] の値とし、値がない場合の 既定値は null とする。
-
周囲のエージェントの アクティブなカスタム要素 コンストラクターマップ[C] を registry に設定する。
-
例外を捕捉しながら次の手順を実行する:
-
result を、引数なしで C を 構築した結果に 設定する。
-
表明:次のいずれかが true である:
-
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 をスローした場合:
-
definition のコンストラクター に対応する JavaScript オブジェクトの関連付けられたレルムのグローバルオブジェクトについて、 exception を報告する。
-
result を、document、
HTMLUnknownElement、 localName、HTML 名前空間、 prefix、"failed"、null、および registry を指定して要素を内部的に作成した 結果に設定する。
-
-
previousRegistry が null の場合は、 周囲のエージェントの アクティブなカスタム要素 コンストラクターマップ[C] を除去する。
-
それ以外の場合は、周囲のエージェントの アクティブなカスタム要素 コンストラクターマップ[C] を previousRegistry に設定する。
-
-
それ以外の場合:
-
result を、 document、
HTMLElement、 localName、HTML 名前空間、 prefix、"undefined"、null、および registry を指定して要素を内部的に作成した結果に 設定する。 -
result と definition を指定して カスタム要素 アップグレードリアクションをキューに入れる。
-
-
-
それ以外の場合:
-
interface を、localName と namespace に対する要素インターフェイスとする。
-
result を、document、interface、 localName、namespace、 prefix、"
uncustomized"、is、および registry を指定して要素を 内部的に作成した結果に設定する。 -
namespace がHTML 名前空間であり、かつ localName が 有効なカスタム要素名であるか、 または is が null でない場合は、result の カスタム要素状態を "
undefined" に設定する。
-
-
result を返す。
文書
document、インターフェイス
interface、文字列 localName、文字列または null の
namespace、文字列または null の prefix、文字列
state、文字列または null の is、および null または CustomElementRegistry
オブジェクト registry が与えられたとき、要素を内部的に
作成するには:
要素には、さらに
属性リストがある。これは NamedNodeMap
を通じて公開される
リストである。
要素の作成時に
明示的に与えられない限り、その
属性
リストは空である。
要素は、その 属性リストが A を含む場合、 属性 A を持つ。
この仕様および他の仕様は、 要素について 属性変更手順を定義してもよい。このアルゴリズムには element、localName、 oldValue、value、および namespace が渡される。
属性 attribute の element、oldValue、および newValue を使用して 属性変更を 処理するには、次の手順を実行する:
-
element について、attribute のローカル名、attribute の 名前空間、oldValue、« »、« »、null、 および null を使用して、"
attributes" の変更レコードを キューに入れる。 -
element がカスタムである場合は、element、 コールバック名 "
attributeChangedCallback"、および « attribute の ローカル名、 oldValue、newValue、attribute の名前空間 » を 使用してカスタム要素コールバックリアクションを キューに入れる。 -
element、attribute の ローカル名、oldValue、 newValue、および attribute の 名前空間を使用して 属性変更手順を実行する。
属性 attribute を value に変更するには:
属性 attribute を除去するには:
文字列 qualifiedName と要素 element が与えられたとき、 名前によって属性を取得するには:
null または文字列 namespace、文字列 localName、および 要素 element が与えられたとき、 名前空間とローカル名によって属性を 取得するには:
要素 element、文字列 localName、および省略可能な null または文字列 namespace(既定値は null)が与えられたとき、 属性値を取得するには:
属性 attr と要素 element が与えられたとき、 属性を設定するには:
-
verifiedValue を、attr の ローカル名、attr の名前空間、element、および attr の値を使用して 信頼済み型に適合する属性値を 取得するを呼び出した結果とする。[TRUSTED-TYPES]
-
attr の要素が null でも element でもない場合は、 "
InUseAttributeError"DOMExceptionをスローする。 -
oldAttr を、attr の 名前空間、attr のローカル名、および element を指定して 属性を取得した結果とする。
-
oldAttr が attr である場合は、attr を返す。
-
attr の値を verifiedValue に設定する。
-
oldAttr が null でない場合は、oldAttr を attr で置換する。
-
それ以外の場合は、attr を element に付加する。
-
oldAttr を返す。
要素 element、文字列 localName、文字列 value、 省略可能な null または文字列 prefix(既定値は null)、および省略可能な null または文字列 namespace(既定値は null)が与えられたとき、 属性値を設定するには:
文字列 qualifiedName と要素 element が与えられたとき、 名前によって属性を除去するには:
null または文字列 namespace、文字列 localName、および 要素 element が与えられたとき、 名前空間とローカル名によって属性を 除去するには:
要素は、関連付けられた 一意識別子(ID)を持つことができる。
歴史的には、要素は、たとえば HTML の id
属性と DTD
を使用することで複数の識別子を持つことができた。
この仕様は IDを
DOM の概念とし、id 属性によって与えられる
要素ごとに 1 つだけを許可する。
-
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-
DOMTokenListオブジェクトを通じて、element のclass内容属性を空白区切りの トークン集合として操作できる。 element . slot [ = value ]-
element の
slot内容属性の値を返す。これを変更するよう設定できる。
文字列 name を反映するよう定義された IDL 属性は、次の取得手順と 設定手順を持たなければならない:
id 属性は "id" を
反映しなければならない。
className 属性は
"class" を反映しなければならない。
classList の取得手順は、関連付けられた
要素がthis
であり、関連付けられた
属性のローカル名が class である DOMTokenList
オブジェクトを返すことである。この特定の DOMTokenList
オブジェクトのトークン集合は、要素の
クラスとも呼ばれる。
slot 属性は "slot" を
反映しなければならない。
id、class、および slot は、
要素の名前空間に関係なく任意の要素に現れることができるため、実質的に超大域属性である。
element . hasAttributes()-
element が属性を持つ場合は true を返し、それ以外の場合は false を返す。
element . getAttributeNames()element . getAttribute(qualifiedName)-
element の、修飾名が qualifiedName である最初の属性を返し、そのような属性がない場合は null を返す。
element . getAttributeNS(namespace, localName)-
element の、名前空間が namespace であり、ローカル名が localName である 属性を返し、そのような 属性がない場合は null を返す。
element . setAttribute(qualifiedName, value)element . setAttributeNS(namespace, localName, value)-
element の、名前空間が namespace であり、 ローカル名が localName である属性の 値を value に設定する。
element . removeAttribute(qualifiedName)element . removeAttributeNS(namespace, localName)element . toggleAttribute(qualifiedName [, force])-
force が指定されていない場合は qualifiedName を「切り替え」、 存在する場合は除去し、存在しない場合は追加する。force が true の場合は qualifiedName を追加する。force が false の場合は qualifiedName を除去する。
qualifiedName が現在存在する場合は true を返し、それ以外の場合は false を返す。
element . hasAttribute(qualifiedName)-
element が、修飾名が qualifiedName である 属性を持つ場合は true を返し、それ以外の場合は false を返す。
element . hasAttributeNS(namespace, localName)-
element が、名前空間が namespace であり、ローカル名が localName である 属性を持つ場合は true を返す。
attributes の取得手順は、関連付けられた
NamedNodeMap
を返すことである。
getAttributeNames() メソッドの手順は、
this の
属性リスト内の属性の
修飾名を順番に返し、それ以外の場合は新しい
リストを返すことである。
これらが一意であることは保証されない。
getAttribute(qualifiedName) メソッドの
手順は次のとおりである:
getAttributeNS(namespace, localName)
メソッドの手順は次のとおりである:
setAttribute(qualifiedName, value)
メソッドの手順は次のとおりである:
-
qualifiedName が有効な属性ローカル名でない場合は、 "
InvalidCharacterError"DOMExceptionをスローする。引数名とは異なり、 qualifiedName は、その修飾名を持つ属性がすでに存在する場合にのみ修飾名として使用される。 それ以外の場合は、新しい属性のローカル 名として使用される。後者の場合についてのみ検証する必要がある。
-
this がHTML 名前空間にあり、そのノード文書が HTML 文書である場合は、 qualifiedName をASCII 小文字に変換した qualifiedName に設定する。
-
verifiedValue を、qualifiedName、null、 this、および value を使用して 信頼済み型に適合する属性値を 取得するを呼び出した結果とする。[TRUSTED-TYPES]
-
attribute を、this の 属性リスト内で、 修飾名が qualifiedName である最初の属性とし、 それ以外の場合は null とする。
-
attribute が null でない場合は、attribute を verifiedValue に変更し、返る。
-
attribute を、this の ノード文書、qualifiedName、null、 null、および verifiedValue を指定して 属性を作成した結果に設定する。
setAttributeNS(namespace, qualifiedName, value)
メソッドの手順は次のとおりである:
-
(namespace, prefix, localName) を、 "
attribute" を指定して namespace と qualifiedName を検証して抽出した結果とする。 -
verifiedValue を、localName、namespace、 this、および value を使用して 信頼済み型に適合する属性値を 取得するを呼び出した結果とする。[TRUSTED-TYPES]
-
localName、verifiedValue、prefix、および namespace を使用して、this の属性値を設定する。
removeAttributeNS(namespace, localName)
メソッドの手順は、namespace、localName、および
this
を指定して属性を除去し、その後
undefined を返すことである。
hasAttribute(qualifiedName) メソッドの
手順は次のとおりである:
toggleAttribute(qualifiedName, force)
メソッドの手順は次のとおりである:
-
qualifiedName が有効な属性ローカル名でない場合は、 "
InvalidCharacterError"DOMExceptionをスローする。修飾名ではなくローカル名として検証する理由については、 上記の説明を参照。
-
this がHTML 名前空間にあり、その ノード文書が HTML 文書である場合は、 qualifiedName をASCII 小文字に変換した qualifiedName に設定する。
-
attribute を、this の 属性リスト内で、 修飾名が qualifiedName である最初の属性とし、 それ以外の場合は null とする。
-
attribute が null の場合:
-
force が指定されていないか false である場合は、 qualifiedName と this を指定して属性を除去し、その後 false を 返す。
-
true を返す。
hasAttributeNS(namespace, localName)
メソッドの手順は次のとおりである:
getAttributeNodeNS(namespace, localName)
メソッドの手順は、namespace、localName、および
this を指定して
属性を取得した結果を返すことである。
removeAttributeNode(attr)
メソッドの手順は次のとおりである:
-
this の属性リストが attr を含まない場合は、 "
NotFoundError"DOMExceptionをスローする。 -
attr を除去する。
-
attr を返す。
shadow = element .attachShadow(init)-
element のシャドウルートを作成して返す。
shadow = element .shadowRoot-
element のシャドウルートが存在し、かつその シャドウルートのモードが "
open" である場合はそれを返し、それ以外の場合は null を返す。
有効なシャドウホスト名は次のいずれかである:
- 有効なカスタム要素名
- "
article"、 "aside"、 "blockquote"、 "body"、 "div"、 "footer"、 "h1"、 "h2"、 "h3"、 "h4"、 "h5"、 "h6"、 "header"、 "main"、 "nav"、 "p"、 "section"、または "span"
このリストは、組み込み要素が必要に応じて時間の経過とともに内部 シャドウツリーを持てるよう、意図的に制限されている。
The attachShadow(init) メソッドの手順は次のとおりである。
-
registry を this の node document の custom element registry とする。
-
init["
customElementRegistry"] exists する場合、registry をそれに設定する。 -
registry が null ではなく、registry の is scoped が false であり、かつ registry が this の node document の custom element registry ではない場合、 throw a "
NotSupportedError"DOMExceptionをスローする。 -
attach a shadow root を、 this、 init["
mode"]、 init["delegatesFocus"]、 init["serializable"]、 init["slotAssignment"]、 init["clonable"]、 および registry を指定して実行する。 -
this の shadow root を返す。
attach a
shadow root とは、element
element、文字列 mode、boolean delegatesFocus、boolean
serializable、文字列 slotAssignment、boolean clonable、および null
または CustomElementRegistry
オブジェクト registry が与えられた場合、次の手順を実行することである。
-
element の namespace が HTML namespace ではない場合、 throw a "
NotSupportedError"DOMExceptionをスローする。 -
element の local name が valid shadow host name ではない場合、 throw a "
NotSupportedError"DOMExceptionをスローする。 -
element の local name が valid custom element name である場合、または element の
isvalue が null ではない場合:-
definition を、element の custom element registry、 その namespace、その local name、およびその
isvalue を指定して looking up a custom element definition した結果とする。 -
definition が null ではなく、definition の disable shadow が true の場合、 throw a "
NotSupportedError"DOMExceptionをスローする。
-
-
element が shadow host である場合:
-
currentShadowRoot を element の shadow root とする。
-
以下のいずれかが true の場合:
-
currentShadowRoot の declarative が false である、または
-
currentShadowRoot の mode が mode ではない場合、
その場合、 throw a "
NotSupportedError"DOMExceptionをスローする。 -
-
currentShadowRoot のすべての children を、 tree order で Remove する。
-
currentShadowRoot の declarative を false に設定する。
-
Return。
-
-
shadow を、element の node document を指定して、 creating a node した結果であり、
ShadowRootを実装する node とする。 -
shadow の host を element に設定する。
-
shadow の mode を mode に設定する。
-
shadow の delegates focus を delegatesFocus に設定する。
-
element の custom element state が "
precustomized" または "custom" の場合、shadow の available to element internals を true に設定する。 -
shadow の declarative を false に設定する。
-
shadow の serializable を serializable に設定する。
-
shadow の slot assignment を slotAssignment に設定する。
-
shadow の clonable を clonable に設定する。
-
shadow の custom element registry を registry に設定する。
-
element の shadow root を shadow に設定する。
shadowRoot の取得手順は次のとおりである:
registry = element .customElementRegistry-
element の
CustomElementRegistryオブジェクトがあればそれを返し、それ以外の場合は null を返す。
customElementRegistry の取得手順は、
this のカスタム要素レジストリを返すことである。
element .closest(selectors)- selectors に一致する最初の 包括的祖先を (element から開始して)返し、それ以外の場合は null を返す。
element .matches(selectors)- selectors を element のルートに対して照合した結果が element である場合は true を返し、それ以外の場合は false を返す。
closest(selectors) メソッドの手順は次の
とおりである:
-
selector を、selectors からセレクターを構文解析した結果とする。 [SELECTORS4]
-
selector が失敗である場合は、 "
SyntaxError"DOMExceptionをスローする。 -
elements の各 element について、selector、 element、およびスコープルート this を使用して 要素に対してセレクターを照合するが 成功を返す場合は、element を返す。[SELECTORS4]
-
null を返す。
matches(selectors) および
webkitMatchesSelector(selectors)
メソッドの手順は次のとおりである:
-
selector を、selectors からセレクターを構文解析した結果とする。 [SELECTORS4]
-
selector が失敗である場合は、 "
SyntaxError"DOMExceptionをスローする。 -
selector、this、およびスコープルート this を使用して 要素に対してセレクターを照合するの 結果が成功である場合は true を返し、それ以外の場合は false を返す。 [SELECTORS4]
getElementsByTagName(qualifiedName)
メソッドの手順は、this
について
修飾名
qualifiedName を持つ要素の
リストを返すことである。
getElementsByTagNameNS(namespace, localName)
メソッドの手順は、this
について
名前空間 namespace とローカル名
localName を持つ要素のリストを返すことである。
getElementsByClassName(classNames)
メソッドの手順は、this
について
クラス名 classNames を持つ要素のリストを
返すことである。
要素 element、文字列 where、およびノード node が与えられたとき、隣接挿入するには、 where とASCII 大文字・小文字を区別せず最初に一致する項目に 関連付けられた手順を実行する:
- "
beforebegin" -
element の親が null である場合は、null を返す。
- "
afterbegin" - "
beforeend" -
node を element 内の null の前に 事前挿入した結果を返す。
- "
afterend" -
element の親が null である場合は、null を返す。
- それ以外
insertAdjacentElement(where, element)
メソッドの手順は、this、
where、および element を指定して
隣接挿入するを実行した結果を返すことである。
insertAdjacentText(where, data)
メソッドの手順は次のとおりである:
-
text を、this のノード文書と 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
には、関連付けられた
要素(
要素)がある。
NamedNodeMap
オブジェクトの
属性リストは、その
要素の
属性
リストである。
NamedNodeMap
オブジェクトのサポートされるプロパティインデックスは、0 から
その属性リストのサイズ − 1 までの範囲の
数値である。ただし、属性リストが空である場合は、
サポートされるプロパティインデックスは存在しない。
length の取得手順は、
属性リストのサイズを返すことである。
item(index) メソッドの手順は次のとおりである:
NamedNodeMap
オブジェクトのサポートされるプロパティ名は、次の
手順を実行した返値である:
-
names を、この
NamedNodeMapオブジェクトの属性リスト内の属性の 修飾名から、重複を省いて順番に並べた ものとする。 -
この
NamedNodeMapオブジェクトの要素が HTML 名前空間にあり、そのノード文書がHTML 文書である 場合は、names の各 name について反復する:-
lowercaseName を、name をASCII 小文字に変換したものとする。
-
lowercaseName が name と等しくない場合は、 names から name を除去する。
-
-
names を返す。
getNamedItem(qualifiedName)
メソッドの手順は、qualifiedName と要素を指定して属性を取得した結果を返すことである。
getNamedItemNS(namespace, localName)
メソッドの手順は、namespace、localName、および要素を指定して
属性を取得した結果を返すことである。
setNamedItem(attr) および
setNamedItemNS(attr) メソッドの
手順は、attr と
要素を指定して属性を設定した結果を返すことである。
removeNamedItem(qualifiedName)
メソッドの手順は次のとおりである:
-
attr が null の場合は、"
NotFoundError"DOMExceptionをスローする。 -
attr を返す。
removeNamedItemNS(namespace, localName)
メソッドの手順は次のとおりである:
-
attr が null の場合は、"
NotFoundError"DOMExceptionをスローする。 -
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 ; // historical; always returns true };
Attr ノードは、単に
属性と呼ばれる。IDL 属性との混同を避けるため、
内容属性と呼ばれることもある。
属性には、 名前空間(null または空でない文字列)、 名前空間接頭辞(null または空でない文字列)、 ローカル名(空でない文字列)、 値(文字列)、および 要素(null または 要素)がある。
今日設計されるのであれば、名前と値だけを持つものになっていただろう。☹
属性の
修飾名は、その名前空間
接頭辞が null である場合は、その
ローカル名であり、それ以外の場合は、その
名前空間接頭辞、それに続く ":"、
さらにそれに続く
ローカル名である。
ユーザーエージェントは、最適化のため、これを内部スロットとして 持つことができる。
文書 document、文字列 localName、および省略可能な文字列または null の namespace(既定値は null)、文字列または null の prefix(既定値は null)、および文字列 value(既定値は空文字列)が与えられたとき、属性を作成するには:
A 属性とは、その
ローカル名が
A であり、その
名前空間および
名前空間接頭辞が
null である属性である。
namespaceURI の取得手順は、
this の名前空間を返すことである。
prefix の取得手順は、this の
名前空間接頭辞を返すことである。
localName の取得手順は、
this のローカル名を返すことである。
name の取得手順は、this の
修飾名を返すことである。
value の取得手順は、this の
値を
返すことである。
属性 attribute と文字列 value が与えられたとき、既存の属性値を設定するには、次の手順を実行する:
-
element を attribute の要素とする。
-
verifiedValue を、attribute の ローカル名、attribute の名前空間、element、および value を使用して 信頼済み型に適合する属性値を 取得するを呼び出した結果とする。[TRUSTED-TYPES]
-
attribute の要素が null である場合は、 attribute の 値を verifiedValue に設定し、返る。
-
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
インターフェイスを継承する各ノードには、
データと呼ばれる変更可能な文字列が関連付けられている。
ノード node のデータを置換するには、整数 offset、整数 count、文字列 data、および省略可能なブール値 piAttributesAlreadyUpdated(既定値は false)を使用して、次を行う:
-
length を node の長さとする。
-
offset が length より大きい場合は、 "
IndexSizeError"DOMExceptionをスローする。 -
offset + count が length より大きい場合は、 count を length − offset に設定する。
-
node について、null、null、node のデータ、« »、« »、null、および null を使用して、 "
characterData" の変更レコードをキューに入れる。 -
deleteOffset を offset + data の 長さとする。
-
開始ノードが node であり、 開始オフセットが offset より 大きく、かつ offset + count 以下である各ライブ範囲について、その 開始オフセットを offset に設定する。
-
終了ノードが node であり、 終了オフセットが offset より 大きく、かつ offset + count 以下である各ライブ範囲について、その 終了オフセットを offset に設定する。
-
開始ノードが node であり、 開始オフセットが offset + count より大きい各ライブ範囲について、その 開始オフセットを data の長さだけ増加させ、 count だけ減少させる。
-
終了ノードが node であり、 終了オフセットが offset + count より大きい各ライブ範囲について、その 終了オフセットを data の長さだけ増加させ、 count だけ減少させる。
-
node が
ProcessingInstructionノードであり、 piAttributesAlreadyUpdated が false である場合は、node を指定して データから属性を更新する。
ノード node の部分文字列データを取得するには、 整数 offset と整数 count を使用して、次を行う:
substringData(offset, count)
メソッドの手順は、this の部分文字列データを取得した結果を返すことであり、
offset と count を使用する。
4.11. インターフェイス Text
[Exposed =Window ]interface :Text CharacterData {constructor (optional DOMString = ""); [data NewObject ]Text splitText (unsigned long );offset readonly attribute DOMString wholeText ; };
text = new Text([data = ""])- データが
data である、新しい
Textノードを返す。 text .splitText(offset)- 指定された
offset でデータを分割し、残りを
Textノードとして返す。 text .wholeText- 直接のすべての
Textノード 兄弟の、 結合されたデータを返す。
排他的 Text
ノードとは、
CDATASection
ノードではない
Text ノードである。
ノード nodeの
連続する Text ノードは、
node、存在する場合は node の直前の兄弟である Text ノードと
その連続する
Text ノード、および存在する場合は node の直後の兄弟である
Text ノードと、その連続する
Text ノードであり、重複は除外する。
ノード nodeの
連続する排他的
Text
ノードは、
node、存在する場合は node の直前の兄弟である
排他的
Text ノードと、その
連続する排他的 Text ノード、および
存在する場合は node の
直後の
兄弟である排他的
Text ノードと、その
連続する排他的 Text ノードであり、
重複は除外する。
文書 document と文字列 data が与えられたとき、テキストノードを作成するには:
new Text(data)
コンストラクターの手順は、this のデータを data に設定し、
this のノード
文書を現在のグローバルオブジェクトの
関連付けられた Documentに設定することである。
整数 offset を使用して、Text
ノード node を
分割するには:
-
length を node の長さとする。
-
offset が length より大きい場合は、 "
IndexSizeError"DOMExceptionを スローする。 -
count を length − offset とする。
-
newData を、offset と count を使用して node の部分文字列データを取得した結果とする。
-
newNode を、node の ノード 文書と newData を指定してテキストノードを作成した結果とする。
-
parent を node の親とする。
-
parent が null でない場合:
-
開始 ノードが node であり、 開始オフセットが offset より大きい各ライブ範囲について、その 開始ノードを newNode に 設定し、その開始オフセットを offset だけ減少させる。
-
終了ノードが node であり、 終了オフセットが offset より大きい各ライブ範囲について、その 終了ノードを newNode に設定し、その終了 オフセットを offset だけ減少させる。
-
開始 ノードが parent であり、 開始オフセットが node のインデックス + 1 に等しい各ライブ範囲について、その 開始オフセットを 1 増加させる。
-
終了ノードが parent であり、 終了オフセットが node のインデックス + 1 に等しい各ライブ範囲について、その 終了オフセットを 1 増加させる。
-
offset、count、および空文字列を使用して、node の データを置換する。
-
newNode を返す。
wholeText の取得手順は、
this の連続する
Text ノードのデータを、
ツリー順に連結したものを返すことである。
4.12. インターフェイス CDATASection
[Exposed =Window ]interface :CDATASection Text { };
4.13.
インターフェイス ProcessingInstruction
[Exposed =Window ]interface :ProcessingInstruction CharacterData {constructor (DOMString ,target optional DOMString = "");data readonly attribute DOMString target ;boolean hasAttributes ();sequence <DOMString >getAttributeNames ();DOMString ?getAttribute (DOMString );name undefined setAttribute (DOMString ,name DOMString );value undefined removeAttribute (DOMString );name boolean toggleAttribute (DOMString ,name optional boolean );force boolean hasAttribute (DOMString ); };name
pi = new ProcessingInstruction(target [, data = ""])- 対象が
target であり、
データが
data である、新しい
ProcessingInstructionノードを返す。 pi .target- 対象を返す。
pi . hasAttributes()-
pi が属性を持つ場合は true を返し、それ以外の場合は false を返す。
pi . getAttributeNames()-
pi のすべての属性の名前を返す。重複を含むことはできない。
pi . getAttribute(name)-
pi の name という名前の属性の値を返し、そのような属性が ない場合は null を返す。
pi . setAttribute(name, value)-
pi の name という名前の属性を value に設定する。
pi . removeAttribute(name)-
pi の name という名前の属性を除去する。
pi . toggleAttribute(name [, force])-
force が指定されていない場合は name を「切り替え」、 存在する場合は除去し、存在しない場合は追加する。force が true の場合は name を追加する。force が false の場合は name を除去する。
name が現在存在する場合は true を返し、それ以外の場合は false を返す。
pi . hasAttribute(name)-
pi が name という名前の属性を持つ場合は true を返し、それ以外の場合は false を返す。
ProcessingInstruction
ノードには、関連付けられた
対象がある。
ProcessingInstruction
ノードには、関連付けられた
属性マップがある。これは
マップであり、
初期状態では空である。
文書 document、文字列 target、および文字列 data が与えられたとき、 処理命令ノードを作成するには:
-
pi を、document を指定して
ProcessingInstructionを実装するノードを作成した結果とする。 -
target と data を使用して pi を初期化する。
-
pi を返す。
ProcessingInstruction
ノード pi を、
target と data を使用して初期化するには:
-
target が
Name生成規則に一致しない場合は、 "InvalidCharacterError"DOMExceptionをスローする。 -
data が文字列 "
?>" を含む場合は、 "InvalidCharacterError"DOMExceptionをスローする。 -
pi の対象を target に設定する。
-
pi のデータを data に設定する。
-
pi を指定してデータから属性を更新する。
ProcessingInstruction
ノード
pi が与えられたとき、データから属性を更新するには:
ProcessingInstruction
ノード
pi が与えられたとき、属性からデータを更新するには:
-
data を空文字列とする。
-
pi の 属性マップの各 name → value について反復する:
-
data が空文字列でない場合は、U+0020 SPACE を data に付加する。
-
name を data に付加する。
-
U+003D (=) を data に付加する。
-
U+0022 (") を data に付加する。
-
value 内のすべての U+0026 (&) を "
&" で置換する。 -
value 内のすべての U+003C (<) を "
<" で置換する。 -
value 内のすべての U+003D (>) を "
>" で置換する。 -
value 内のすべての U+0022 (") を "
"" で置換する。 -
value を data に付加する。
-
U+0022 (") を data に付加する。
-
ProcessingInstruction
ノード pi と
文字列 name が与えられたとき、処理命令属性を取得するには、
pi の
属性マップ[name] を、null を
既定値として返す。
new ProcessingInstruction(target, data)
コンストラクターの手順は次のとおりである:
-
this のノード文書を、現在のグローバルオブジェクトの 関連付けられた
Documentに設定する。
getAttribute(name) メソッドの
手順は、this と
name を指定して
処理命令属性を取得した結果を返すことである。
setAttribute(name, value)
メソッドの手順は次のとおりである:
-
name が有効な属性ローカル名でない場合は、 "
InvalidCharacterError"DOMExceptionをスローする。 -
this を指定して属性からデータを更新する。
removeAttribute(name)
メソッドの手順は次のとおりである:
-
this を指定して属性からデータを更新する。
toggleAttribute(name, force)
メソッドの手順は次のとおりである:
-
name が有効な属性ローカル名でない場合は、 "
InvalidCharacterError"DOMExceptionをスローする。 -
attributes[name] が存在しない場合:
-
force が指定されていないか true である場合は、 attributes[name] を空文字列に設定し、 this を指定して属性からデータを更新し、 その後 true を返す。
-
false を返す。
-
-
force が指定されていないか false である場合は、 attributes[name] を除去し、 this を指定して 属性からデータを更新し、その後 false を返す。
-
true を返す。
4.14. インターフェイス Comment
[Exposed =Window ]interface :Comment CharacterData {constructor (optional DOMString = ""); };data
comment = new Comment([data = ""])- データが
data である、新しい
Commentノードを返す。
コメント ノードを作成するには、文書 document と 文字列 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 ) // 先頭の空白を忘れないこと
range. setEnd( secondText, 4 )
// range は、文字列化すると前述の引用になる
上記の
ノードツリー内の
src や alt のような属性は、範囲によって表現することはできない。範囲が有用なのは、
ノードに対してのみである。
Range オブジェクトは、
StaticRange
オブジェクトとは異なり、
ノードツリーへの
変更の影響を受ける。そのため、ライブ範囲とも呼ばれる。このような変更によって
無効になることはなく、引き続き同じ内容部分を表すように維持される。
必然的に、たとえば表している内容の一部が変更される場合、ライブ範囲自体も、
ノードツリーへの
変更の一環として変更されることがある。
詳細については、挿入および除去アルゴリズム、
normalize()
メソッド、ならびにデータを置換するおよび分割する
アルゴリズムを参照。
ノード
ツリーの変更に応じてライブ範囲を更新する処理は、高コストになる可能性がある。
ノードツリーが
変更されるたびに、影響を受けるすべての Range
オブジェクトを更新する必要がある。アプリケーションが一部のライブ範囲に関心がなくても、
変更が発生した際には、それらを最新の状態に保つためのコストを負担しなければならない。
StaticRange
オブジェクトは、ノードツリーが変更されても更新されない、軽量な
範囲である。そのため、
ライブ範囲と同じ保守コストは発生しない。
5.2. 境界点
境界点は、 ノード(ノード)と オフセット(非負整数)からなる タプルである。
正しい境界点のオフセットは、 0 以上、その境界点のノードの 長さ以下である。
境界点 (nodeB、offsetB)に対する 境界点 (nodeA、offsetA)の 位置は、次の手順によって返される 前、 等しい、または 後である:
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ノードである場合は、"InvalidNodeTypeError"DOMExceptionをスローする。 -
this の開始を (init["
startContainer"], init["startOffset"]) に設定し、終了を (init["endContainer"], init["endOffset"]) に設定する。
StaticRange
は、次のすべてが true である場合に妥当である:
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 は、 node のルートが range のルートであり、かつ(node, 0)が range の開始より 後であり、 かつ(node, node の長さ)が range の終了より前である場合、 ライブ範囲 range に包含されている。
ノードは、それが ライブ範囲の 開始ノードの 包括的祖先であるが、その 終了 ノードの包括的祖先ではない場合、またはその逆の場合、ライブ範囲に 部分的に包含されている。
これらの定義をより理解するためのいくつかの事実:
-
ライブ範囲内にあると 考えられる内容は、すべての包含されているノードに加え、 開始ノードおよび終了ノードが
CharacterDataノードである場合には、 それらの内容の一部から構成されることもある。 -
ライブ範囲に包含されるノードは、 一般には連続しない。これは、包含されている ノードの 親が常に包含されているとは限らないためである。
-
ただし、包含されている ノードの 子孫は包含されており、また、 2 つの兄弟が 包含されている場合、 それらの間にあるすべての兄弟も包含されている。
-
最初の包含されている ノード(存在する 場合)は常に開始ノードより後にあり、最後の包含されている ノードは常に、 終了ノードの最後の 子孫と等しいか、それより前にある。
-
部分的に包含されているノードが存在するのは、 開始ノードと終了ノードが 異なる場合に限り、かつその場合に限る。
-
commonAncestorContainer属性値は、包含されているものでも、部分的に 包含されているものでもない。 -
開始ノードが 終了 ノードの祖先である場合、 共通の包括的祖先は 開始ノードになる。その 子のうち正確に 1 つが 部分的に 包含されていることになり、ある子が 包含されるのは、その子が 部分的に 包含されている子より 前にある場合に限り、かつその場合に限る。 終了 ノードが開始ノードの祖先である場合は、 その逆が成立する。
-
開始ノードが 終了 ノードの包括的祖先ではなく、その逆でもない場合、 共通の包括的祖先は、それらの両方と異なるものに なる。その子のうち正確に 2 つが 部分的に 包含されていることになり、ある子が包含されるのは、それら 2 つの間にある 場合に限り、かつその場合に限る。
ノード node が与えられたときの、ライブ 範囲の除去前手順は次のとおりである:
-
parent を node の親とする。
-
表明:parent は null ではない。
-
index を node のインデックスとする。
-
開始ノードが node の 包括的子孫である各 ライブ範囲について、その 開始を (parent, index)に設定する。
-
終了ノードが node の 包括的子孫である各 ライブ範囲について、その 終了を(parent, index)に設定する。
-
開始ノードが parent であり、 開始オフセットが index より 大きい各ライブ範囲について、その 開始オフセットを 1 減少させる。
-
終了ノードが parent であり、 終了オフセットが index より 大きい各ライブ範囲について、その 終了オフセットを 1 減少させる。
range = new Range()- 新しいライブ 範囲を返す。
new Range() コンストラクターの
手順は、this
の開始および終了を、
(現在のグローバルオブジェクトの関連付けられた Document, 0)に設定することである。
- container = range .
commonAncestorContainer - range の開始ノードおよび 終了 ノードの両方の祖先であるノードのうち、 文書から最も離れたものを返す。
ライブ範囲 range の共通 祖先を取得するには:
range の開始または終了を設定するには、 それを境界点(node, offset)に設定する:
-
node が文書型である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。 -
offset が node の長さより大きい場合は、 "
IndexSizeError"DOMExceptionを スローする。 -
boundaryPoint を境界点 (node, offset)とする。
-
- これらの手順が「開始を設定する」として呼び出された場合
- これらの手順が「終了を設定する」として呼び出された場合
setStartBefore(node) メソッドの手順は
次のとおりである:
-
parent を node の親とする。
-
parent が null である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。
setStartAfter(node) メソッドの手順は
次のとおりである:
-
parent を node の親とする。
-
parent が null である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。
setEndBefore(node) メソッドの手順は
次のとおりである:
-
parent を node の親とする。
-
parent が null である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。
setEndAfter(node) メソッドの手順は
次のとおりである:
-
parent を node の親とする。
-
parent が null である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。
-
parent を node の親とする。
-
parent が null である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。 -
index を node のインデックスとする。
selectNodeContents(node) メソッドの
手順は次のとおりである:
-
node が文書型である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。 -
length を node の長さとする。
compareBoundaryPoints(how, sourceRange)
メソッドの手順は次のとおりである:
-
how が次のいずれでもない場合
-
this のルートが sourceRange の ルート ではない場合は、"
WrongDocumentError"DOMExceptionをスローする。 -
thisPoint および sourcePoint を null とする。
-
how に応じて切り替える:
START_TO_START:-
thisPoint をthis の開始に設定し、 sourcePoint を sourceRange の開始に設定する。
START_TO_END:END_TO_END:END_TO_START:-
thisPoint をthis の開始に設定し、 sourcePoint を sourceRange の終了に設定する。
-
sourcePoint に対する thisPoint の位置に応じて切り替える:
deleteContents() メソッドの手順は次のとおりである:
-
originalStartNode、originalStartOffset、 originalEndNode、および originalEndOffset を、それぞれ this の 開始ノード、開始 オフセット、終了ノード、および 終了オフセットとする。
-
originalStartNode が originalEndNode であり、それが
CharacterDataノードである場合:-
originalStartOffset、 originalEndOffset − originalStartOffset、および空文字列を使用して、 originalStartNode のデータを置換する。
-
返る。
-
-
nodesToRemove を、this に包含されているすべてのノードをツリー順に並べたリストとする。ただし、その 親も this に包含されている ノードは除外する。
-
newNode および newOffset を null とする。
-
originalStartNode が originalEndNode の包括的祖先である場合は、 newNode を originalStartNode に設定し、 newOffset を originalStartOffset に設定する。
-
それ以外の場合:
-
referenceNode を originalStartNode とする。
-
referenceNode の親が null ではなく、かつ originalEndNode の包括的祖先でない間、 referenceNode をその親に設定する。
-
newNode を referenceNode の親に設定し、 newOffset を referenceNode のインデックス + 1 に設定する。
referenceNode の親が null であるなら、 それはthis の ルートになる。そしてその場合、それは originalEndNode の 包括的祖先になるため、この地点には 到達できない。
-
-
originalStartNode が
CharacterDataノードである場合、 originalStartOffset、 originalStartNode の長さ − originalStartOffset、および 空文字列を使用して、originalStartNode のデータを置換する。 -
originalEndNode が
CharacterDataノードである場合、 0、originalEndOffset、および空文字列を使用して、 originalEndNode のデータを置換する。
ライブ範囲 range を抽出するには:
-
fragment を、range の開始ノードのノード文書を指定して 文書断片を 作成した結果とする。
-
range が折りたたまれている場合は、fragment を返す。
-
originalStartNode、originalStartOffset、 originalEndNode、および originalEndOffset を、それぞれ range の 開始ノード、開始 オフセット、終了ノード、および 終了オフセットとする。
-
originalStartNode が originalEndNode であり、それが
CharacterDataノードである場合:-
clone を originalStartNode の複製とする。
-
clone のデータを、 originalStartOffset および originalEndOffset − originalStartOffset を使用して originalStartNode の部分文字列データを取得した結果に設定する。
-
clone を fragment に付加する。
-
originalStartOffset、 originalEndOffset − originalStartOffset、および空文字列を使用して、 originalStartNode のデータを置換する。
- fragment を返す。
-
-
commonAncestor を range の共通 祖先を取得した結果とする。
-
firstPartiallyContainedChild を null とする。
- originalStartNode が originalEndNode の包括的 祖先でない場合、firstPartiallyContainedChild を commonAncestor の子のうち、range に 部分的に 包含されている最初のものに設定する。
-
lastPartiallyContainedChild を null とする。
-
originalEndNode が originalStartNode の包括的祖先でない場合、 lastPartiallyContainedChild を commonAncestor の 子 のうち、range に 部分的に 包含されている最後のものに設定する。
これらの変数への代入は、実際には常に意味を成す。たとえば、 originalStartNode が originalEndNode の包括的祖先でない場合、 originalStartNode 自体が range に 部分的に 包含されており、さらに commonAncestor の 子に至るまでのすべての 祖先も同様である。 commonAncestor は originalStartNode ではあり得ない。なぜなら、 originalEndNode の 包括的祖先でなければならないからである。 もう一方の場合も同様である。また、両方が定義されている場合、2 つの 子が等しくなることはない。
-
containedChildren を、commonAncestor の 子のうち、 range に包含されているすべてのものを ツリー 順に並べたリストとする。
-
containedChildren のいずれかのメンバーが文書型である場合は、 "
HierarchyRequestError"DOMExceptionをスローする。最初または最後の部分的に包含されているノードについて心配する必要はない。 文書型が部分的に包含されることは決してないためである。 文書型は範囲の境界点になることができず、また何かの祖先になることもできない。
-
newNode および newOffset を null とする。
-
originalStartNode が originalEndNode の包括的祖先である場合、 newNode を originalStartNode に設定し、 newOffset を originalStartOffset に設定する。
-
それ以外の場合:
-
referenceNode を originalStartNode とする。
-
referenceNode の親が null ではなく、かつ originalEndNode の包括的祖先でない間、 referenceNode をその親に設定する。
-
newNode を referenceNode の親に設定し、 newOffset を referenceNode のインデックス + 1 に設定する。
referenceNode の親が null であるなら、 それは range の ルートになる。そしてその場合、それは originalEndNode の 包括的祖先になるため、この地点には 到達できない。
-
-
firstPartiallyContainedChild が
CharacterDataノードである場合:この場合、firstPartiallyContainedChild は originalStartNode である。
-
それ以外で、firstPartiallyContainedChild が null でない場合:
-
containedChildren の各 contained child について、 contained child を fragment に付加する。
-
lastPartiallyContainedChild が
CharacterDataノードである場合:この場合、lastPartiallyContainedChild は originalEndNode である。
-
clone を originalEndNode の複製とする。
-
clone のデータを、0 および originalEndOffset を使用して originalEndNode の部分文字列データを取得した結果に設定する。
-
clone を fragment に付加する。
-
0、originalEndOffset、および空文字列を使用して、 originalEndNode のデータを置換する。
-
-
それ以外で、lastPartiallyContainedChild が null でない場合:
-
fragment を返す。
ライブ範囲 range の内容を複製するには:
-
fragment を、range の開始ノードのノード文書を指定して 文書断片を 作成した結果とする。
-
range が折りたたまれている場合は、fragment を返す。
-
originalStartNode、originalStartOffset、 originalEndNode、および originalEndOffset を、それぞれ range の 開始ノード、開始 オフセット、終了ノード、および 終了オフセットとする。
-
originalStartNode が originalEndNode であり、それが
CharacterDataノードである場合:-
clone を originalStartNode の複製とする。
-
clone のデータを、 originalStartOffset および originalEndOffset − originalStartOffset を使用して originalStartNode の部分文字列データを取得した結果に設定する。
-
clone を fragment に付加する。
-
fragment を返す。
-
-
commonAncestor を range の共通 祖先を取得した結果とする。
-
firstPartiallyContainedChild を null とする。
-
originalStartNode が originalEndNode の包括的祖先でない場合、 firstPartiallyContainedChild を commonAncestor の 子 のうち、range に 部分的に 包含されている最初のものに設定する。
-
lastPartiallyContainedChild を null とする。
-
originalEndNode が originalStartNode の包括的祖先でない場合、 lastPartiallyContainedChild を commonAncestor の 子 のうち、range に 部分的に 包含されている最後のものに設定する。
これらの変数への代入は、実際には常に意味を成す。たとえば、 originalStartNode が originalEndNode の包括的祖先でない場合、 originalStartNode 自体が range に 部分的に 包含されており、さらに commonAncestor の 子に至るまでのすべての 祖先も同様である。 commonAncestor は originalStartNode ではあり得ない。なぜなら、 originalEndNode の 包括的祖先でなければならないからである。 もう一方の場合も同様である。また、両方が定義されている場合、2 つの 子が等しくなることはない。
-
containedChildren を、commonAncestor の 子のうち、 range に包含されているすべてのものを ツリー 順に並べたリストとする。
-
containedChildren のいずれかのメンバーが文書型である場合は、 "
HierarchyRequestError"DOMExceptionをスローする。最初または最後の部分的に包含されているノードについて心配する必要はない。 文書型が部分的に包含されることは決してないためである。 文書型は範囲の境界点になることができず、また何かの祖先になることもできない。
-
firstPartiallyContainedChild が
CharacterDataノードである場合:この場合、firstPartiallyContainedChild は originalStartNode である。
-
clone を originalStartNode の複製とする。
-
clone のデータを、 originalStartOffset および originalStartNode の長さ − originalStartOffset を使用して originalStartNode の部分文字列データを取得した結果に設定する。
-
clone を fragment に付加する。
-
-
それ以外で、firstPartiallyContainedChild が null でない場合:
-
containedChildren の各 contained child について:
-
lastPartiallyContainedChild が
CharacterDataノードである場合:この場合、lastPartiallyContainedChild は originalEndNode である。
-
clone を originalEndNode の複製とする。
-
clone のデータを、0 および originalEndOffset を使用して originalEndNode の部分文字列データを取得した結果に設定する。
-
clone を fragment に付加する。
-
-
それ以外で、lastPartiallyContainedChild が null でない場合:
-
fragment を返す。
ライブ範囲 range にノード node を挿入するには:
-
range の開始ノードが
ProcessingInstructionまたはCommentノードであるか、 その親が null であるTextノードであるか、 または node である場合は、"HierarchyRequestError"DOMExceptionをスローする。 -
referenceNode を null とする。
-
range の開始ノードが
Textノードである場合、 referenceNode をそのTextノードに設定する。 -
それ以外の場合、そのような子が存在するなら、referenceNode を range の開始ノードの子のうち、そのインデックスが range の開始オフセットであるものに設定し、 それ以外の場合は null に設定する。
-
referenceNode が null である場合は parent を range の開始ノードとし、 それ以外の場合は referenceNode の親とする。
-
node、parent、 referenceNode、および « » を指定して挿入前の妥当性を確保する。
-
range の開始ノードが
Textノードである場合、 referenceNode を、そのノードを range の開始オフセットで分割した結果に設定する。 -
node が referenceNode である場合、referenceNode をその 直後の兄弟に設定する。
-
referenceNode が null である場合は newOffset を parent の長さとし、 それ以外の場合は referenceNode のインデックスとする。
-
node が
DocumentFragmentノードである場合は、 newOffset を node の長さだけ増加させ、 それ以外の場合は 1 増加させる。 -
node を parent 内の referenceNode の前に 事前挿入する。
surroundContents(newParent) メソッドの
手順は次のとおりである:
-
Textではない ノードが this に部分的に包含されている場合は、 "InvalidStateError"DOMExceptionをスローする。 -
newParent が
Document、DocumentType、 またはDocumentFragmentノードである場合は、 "InvalidNodeTypeError"DOMExceptionをスローする。歴史的な理由により、
CharacterDataノードはここでは 検査されず、副作用として後でスローすることになる。 -
fragment を newParent に付加する。
detach() メソッドの手順は何もしないことである。
その機能(Range オブジェクトを
無効化すること)は削除されたが、メソッド自体は互換性のために
保持されている。
- position = range .
comparePoint(node, offset) - 点が範囲より前にある場合は −1、点が範囲内にある場合は 0、 点が範囲より後にある場合は 1 を返す。
- intersects = range .
intersectsNode(node) - range が node と交差するかどうかを返す。
isPointInRange(node, offset)
メソッドの手順は次のとおりである:
-
node が文書型である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。 -
offset が node の長さより大きい場合は、 "
IndexSizeError"DOMExceptionを スローする。 -
true を返す。
comparePoint(node, offset)
メソッドの手順は次のとおりである:
-
node のルートがthis のルート ではない場合は、"
WrongDocumentError"DOMExceptionをスローする。 -
node が文書型である場合は、"
InvalidNodeTypeError"DOMExceptionをスローする。 -
offset が node の長さより大きい場合は、 "
IndexSizeError"DOMExceptionを スローする。 -
0 を返す。
intersectsNode(node) メソッドの手順は
次のとおりである:
文字列化の動作は、次の手順を 実行しなければならない:
-
string を空文字列とする。
-
this の開始ノードがthis の終了ノードであり、 それが
Textノードである場合、 そのTextノードの データのうち、 this の開始オフセットから始まり、 this の終了オフセットで終わる部分文字列を返す。 -
this の開始ノードが
Textノードである場合、 そのノードのデータのうち、this の 開始オフセットから末尾までの部分文字列を string に付加する。 -
this に包含されているすべての
Textノードの データを ツリー 順に連結したものを、string に付加する。 -
this の終了ノードが
Textノードである場合、 そのノードのデータの先頭から this の終了オフセットまでの部分文字列を string に付加する。 -
string を返す。
createContextualFragment()、
getClientRects()、
および getBoundingClientRect()
メソッドは、他の仕様で定義されている。
[DOM-Parsing]
[CSSOM-VIEW]
6. 走査
NodeIterator
および TreeWalker
オブジェクトは、ノード
ツリーをフィルター処理し、
走査するために使用できる。
各 NodeIterator
および TreeWalker
オブジェクトには、再帰的な呼び出しを避けるため、関連付けられたブール値
アクティブであるがある。これは
初期状態では false である。
各 NodeIterator
および TreeWalker
オブジェクトには、関連付けられた
ルート(ノード)、
whatToShow(ビットマスク)、および
フィルター(コールバック)もある。
NodeIterator
または TreeWalker
オブジェクト traverser 内のノード node を
フィルター処理するには:
-
traverser のアクティブであるが true である場合は、 "
InvalidStateError"DOMExceptionをスローする。 -
n を node の
nodeType属性値 − 1 とする。 -
traverser のwhatToShow の n番目のビット(0 を最下位ビットとする)が設定されていない場合は、
FILTER_SKIPを返す。 -
traverser のフィルターが null である場合は、
FILTER_ACCEPTを返す。 -
traverser のアクティブであるを true に設定する。
-
result を、traverser のフィルター、"
acceptNode"、および « node » を使用してユーザーオブジェクトの演算を呼び出した 返値とする。これが例外をスローした場合は、traverser の アクティブであるを false に設定し、その例外を 再スローする。 -
traverser のアクティブであるを 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
オブジェクトには、関連付けられた
イテレーターコレクションがあり、これは
NodeIterator
オブジェクトのルートを根とし、その
フィルターが任意のノードに一致する
コレクションである。
ノードポインターは、 ノード(ノード)と 前方ポインター(ブール値)から構成される タプルである。
各 NodeIterator
オブジェクトには、関連付けられた参照(
ノードポインター)と候補参照(null または
ノードポインターであり、初期状態では
null)もある。
前述したように、NodeIterator
オブジェクトには、関連付けられた
アクティブ
である、ルート、whatToShow、および
フィルターもある。
NodeIterator
オブジェクト nodeIterator とノード
toBeRemovedNode が与えられたときの、NodeIterator の除去前手順は、
次のとおりである:
-
nodeIterator の参照を、nodeIterator の 参照、nodeIterator、および toBeRemovedNode を指定して ノードポインターを調整した結果に設定する。
-
nodeIterator の候補参照が null でない場合、 nodeIterator の候補参照を、nodeIterator の 候補参照、 nodeIterator、および toBeRemovedNode を指定して ノードポインターを調整した結果に設定する。
ノードポインター
nodePointer、NodeIterator
オブジェクト nodeIterator、およびノード
toBeRemovedNode が与えられたとき、ノードポインターを調整するには、次の手順を実行する。
これらはノードポインターを返す。
whatToShow の取得手順は、
this のwhatToShowを返すことである。
NodeIterator
オブジェクト iterator と、"next" または "previous" の
type が与えられたとき、走査するには:
-
result を null とする。
-
true の間:
-
type が "
next" である場合: -
それ以外の場合:
-
filterResult を、iterator 内の node をフィルター処理した結果とする。 これが例外をスローした場合は、iterator の 候補参照を null に設定し、 その例外を再スローする。
-
filterResult が
FILTER_ACCEPTである場合:
-
-
iterator の候補参照を null に設定する。
-
result を返す。
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
オブジェクトには、関連付けられた現在のノード(
ノード)がある。
前述したように、TreeWalker
オブジェクトには、関連付けられた
ルート、whatToShow、およびフィルターもある。
whatToShow の取得手順は、
this のwhatToShowを返すことである。
currentNode
の設定手順は、this
の
現在のノードを
与えられた値に設定することである。
parentNode() メソッドの手順は次のとおりである:
TreeWalker
オブジェクト walker と、"first" または "last" の
type が与えられたとき、子を走査するには:
-
node を walker の現在のノードとする。
-
type が "
first" である場合は node を node の最初の子に設定し、それ以外の場合は node の最後の子に設定する。 -
node が null でない間:
-
result を、walker 内の node をフィルター処理した 結果とする。
-
result が
FILTER_ACCEPTである場合、walker の 現在のノードを node に設定し、 node を返す。 -
result が
FILTER_SKIPである場合: -
node が null でない間:
-
-
null を返す。
TreeWalker
オブジェクト walker と、"next" または "previous" の
type が与えられたとき、兄弟を走査するには:
-
node を walker の現在のノードとする。
-
node がルートである場合は、null を返す。
-
true の間:
-
type が "
next" である場合は sibling を node の直後の 兄弟とし、それ以外の場合は node の 直前の兄弟とする。 -
sibling が null でない間:
-
node を sibling に設定する。
-
result を、walker 内の node をフィルター処理した 結果とする。
-
result が
FILTER_ACCEPTである場合、walker の 現在のノードを node に設定し、 node を返す。 -
type が "
next" である場合は sibling を node の最初の子に設定し、 それ以外の場合は node の 最後の子に設定する。 -
result が
FILTER_REJECTであるか、sibling が null である場合、 type が "next" であれば sibling を node の直後の兄弟に設定し、それ以外の場合は node の直前の兄弟に設定する。
-
-
node を node の親に設定する。
-
node が null または walker のルートである場合、 null を返す。
-
walker 内の node をフィルター処理した返値が
FILTER_ACCEPTである場合は、null を返す。
-
previousNode() メソッドの手順は次のとおりである:
nextNode() メソッドの手順は次のとおりである:
-
result を
FILTER_ACCEPTとする。 -
true の間:
-
result が
FILTER_REJECTではなく、かつ node が 子を持つ間: -
sibling を null とする。
-
temporary を node とする。
-
temporary が null でない間:
-
sibling が null である場合は、null を返す。
-
node を sibling に設定する。
-
result が
FILTER_ACCEPTである場合、this の 現在のノードを 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
オブジェクトには、関連付けられた
トークン集合(集合)があり、これは
初期状態では空である。
DOMTokenList
オブジェクトには、関連付けられた要素
(要素)および属性名(属性の
ローカル名)もある。
仕様は、DOMTokenListの
要素および属性名について、
サポートされるトークンを定義できる。
DOMTokenList
オブジェクト set の、指定された
token に対する
検証手順は次のとおりである:
-
set の要素および 属性名にサポートされるトークンが定義されていない場合は、
TypeErrorをスローする。 -
lowercaseToken を、token をASCII 小文字にしたものとする。
-
lowercaseToken が、 set の要素および属性 名のサポートされるトークン に存在する場合は、true を返す。
-
false を返す。
DOMTokenList
オブジェクト set の
更新手順は次のとおりである:
-
null、set の 属性名、および set の要素を指定して名前空間およびローカル名により 属性を取得した結果が null であり、かつ set のトークン集合が空である場合は、返る。
-
set の要素、 set の属性名、および set の トークン 集合に対して順序付き集合シリアライザーを実行した結果を指定して、 属性値を設定する。
DOMTokenList
オブジェクト set の
シリアル化手順は、set の
要素および
set の属性名を指定して
属性値を取得するを実行した結果を返すことである。
DOMTokenList
オブジェクト set には、set の要素について、次の属性変更手順がある:
DOMTokenList
オブジェクト set が作成されたとき:
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()と同じ)。force が false の場合は token を除去する (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 までの 0 以上の数である。ただし、トークン集合が 空 である場合は、 サポートされるプロパティインデックスは存在しない。
add(tokens…)
メソッドの手順は次のとおりである:
-
tokens の各 token について反復する:
-
token が空文字列である場合は、"
SyntaxError"DOMExceptionをスローする。 -
token にASCII 空白が含まれる場合は、"
InvalidCharacterError"DOMExceptionをスローする。
-
-
更新 手順を実行する。
remove(tokens…)
メソッドの手順は次のとおりである:
-
tokens の各 token について反復する:
-
token が空文字列である場合は、"
SyntaxError"DOMExceptionをスローする。 -
token にASCII 空白が含まれる場合は、"
InvalidCharacterError"DOMExceptionをスローする。
-
-
更新手順を実行する。
toggle(token, force)
メソッドの手順は次のとおりである:
-
token が空文字列である場合は、"
SyntaxError"DOMExceptionをスローする。 -
token にASCII 空白が含まれる場合は、"
InvalidCharacterError"DOMExceptionをスローする。 -
それ以外で、force が指定されていないか true である場合、 token をthis のトークン集合に付加し、更新手順を実行して true を返す。
-
false を返す。
ウェブ互換性のため、toggle()
では、更新手順が常に実行されるとは限らない。
replace(token, newToken)
メソッドの手順は次のとおりである:
-
token または newToken のいずれかが空文字列である場合は、"
SyntaxError"DOMExceptionをスローする。 -
token または newToken のいずれかにASCII 空白が含まれる場合は、"
InvalidCharacterError"DOMExceptionを スローする。 -
更新手順を実行する。
-
true を返す。
ウェブ互換性のため、replace()
では、更新手順が常に実行されるとは限らない。
supports(token)
メソッドの手順は次のとおりである:
-
result を、token を指定して呼び出した検証手順の返値とする。
-
result を返す。
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
ブラウザーではクライアント側 XSLT を使用しないでください。ブラウザーの XSLT 実装は メモリ安全性の脆弱性が非常に生じやすく、ウェブプラットフォームは安全な代替手段として JavaScript を使用する方向へ進化してきました。これらの理由により、この機能はウェブプラットフォームから 削除される過程にあります。(これは何年もかかる長いプロセスです。)
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、 Armen Michaeli、 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、 Steven Obiajulu、 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 をご覧ください。