DOM Level 2 リファレンス (Traversal + Range)

NodeIterator

文書ツリー内にあるノードを、ノードの開始順に並べた一覧を示す。一覧のノードの間・両端をイテレータが移動する。

例えば<p><span>ABC</span><q>DE<span>F</span>G</q>HI</p>という文書は、 p要素をルートノードとしたとき、 [p要素][span要素][テキストABC][q要素][テキストDE][span要素][テキストF][テキストG][テキストHI]という一覧になり、 最初イテレータはp要素の前に置かれる。nextNodeメソッドが呼ばれるとイテレータはp要素とspan要素の間に移動し、p要素を返す。

NodeIteratorのサンプル

メソッド・属性名 解説 RO,X
root Node NodeIteratorのルートノード。イテレータは最初このノードの前に位置付けられる。 whatToShow, filter属性はイテレータの位置の設定時には考慮されない。 RO
whatToShow unsigned long ノード型がイテレータで可視かどうかを判定する。使用可能な定数の集合はNodeFilterインターフェイスで定義される。この値の設定はNodeFilterでFILTER_SKIPを設定するのと同じである。ただし、スキップしたノードの子は依然として論理一覧には考慮される。これらの定数名はorで結合できる。 RO
filter NodeFilter 一覧を作成するのに使用されるフィルタ。フィルタを使用しないならばnull RO
expandEntityReferences boolean EntityReferenceノードの子がイテレータから可視であるかどうかを決定する。falseならば、EntityReferenceノードとその子孫は一覧に含まれない(フィルタのFILTER_REJECTと同様の効果がある)。 RO
nextNode() Node 集合内の次のノードを返し、集合内でのイテレータの位置を進める。NodeIteratorが生成された後、最初のnextNodeメソッド呼出しは集合内の最初のノードを返す。集合内にこれ以上メンバが存在しない場合はnull X
previousNode() Node 集合内の前のノードを返し、集合内でのイテレータの位置を前に戻す。集合内にこれ以上メンバが存在しない場合はnull X
detach() void NodeIteratorがもう使用されず、実装がこのNodeIteratorに関連するリソースを開放してもよいことを示す。 -

NodeFilter

NodeIteratorTreeWalkerを作成するとき、各ノードを検査し論理一覧に出現するか否かを決定するフィルタ。ECMAScriptではacceptNodeをメソッドとして持つオブジェクトを作成するだけでいい(NodeIteratorのサンプルも参照)。また、(どこにそんな仕様があるのか不明だが)acceptNodeの働きをする関数オブジェクトだけでも同じ動きをする様子。(特にSafari 3では関数でないとうまく動かない。)

NodeIterator,TreeWalkerインタフェースのwhatToShow属性で用いられる定数の定義
定数名 解説
SHOW_ALL 0xFFFFFFFF 全ノードを表示する。
SHOW_ELEMENT 0x00000001 Elementノードを表示する。
SHOW_ATTRIBUTE 0x00000002 Attrノードを表示する。ルートとしてAttrノードを持つNodeIterator, TreeWalkerを生成するときのみ意味を持つ。この場合、Attrノードが走査の最初の位置に出現することを意味する。Attrノードは他のノードの子にはならないため、文書ツリーの走査時には出現しない。
SHOW_TEXT 0x00000004 Textノードを表示する。
SHOW_CDATA_SECTION 0x00000008 CDATASectionノードを表示する。
SHOW_ENTITY_REFERENCE 0x00000010 EntityReferenceノードを表示する。
SHOW_ENTITY 0x00000020 Entityノードを表示する。ルートとしてEntityノードを持つNodeIterator, TreeWalkerを生成するときのみ意味を持つ。この場合、Entityノードが走査の最初の位置に出現することを意味する。Entityノードは文書ツリーの一部ではないため、文書ツリーの走査時には出現しない。
SHOW_PROCESSING_INSTRUCTION 0x00000040 ProcessingInstructionノードを表示する。
SHOW_COMMENT 0x00000080 Commentノードを表示する。
SHOW_DOCUMENT 0x00000100 Documentノードを表示する。
SHOW_DOCUMENT_TYPE 0x00000200 DocumentTypeノードを表示する。
SHOW_DOCUMENT_FRAGMENT 0x00000400 DocumentFragmentノードを表示する。
SHOW_NOTATION 0x00000800 Notationノードを表示する。ルートとしてNotationノードを持つNodeIterator, TreeWalkerを生成するときのみ意味を持つ。この場合、Notationノードが走査の最初の位置に出現することを意味する。Notationノードは文書ツリーの一部ではないため、文書ツリーの走査時には出現しない。
メソッド名 解説 引数の型
acceptNode(n) short nがTreeWalkerまたはNodeIteratorの論理一覧内で可視であるかどうかを検査する。返値は、ノードを受け付けるときFILTER_ACCEPT = 1、ノードを拒否するときFILTER_REJECT = 2、この単一のノードをスキップするときFILTER_SKIP = 3FILTER_REJECTFILTER_SKIPの違いはTreeWalkerの時のみ現れて、子ノードもまとめて無視するのがFILTER_REJECT、子ノードを走査するのがFILTER_SKIP Node

TreeWalker

ルートノードの下位ツリー内についてのツリー指向のビューを提供する。 普通にノードのツリーとして処理するのとほとんど同じであるが、 大きな違いはNodeFilterを使ってあらかじめ関係ないノードをスキップ、拒否して処理できる点、 NodeIteratorのようなアクセスを提供できる点である。

メソッド・属性名 解説 RO,X
root Node TreeWalkerのルートノード。 RO
whatToShow unsigned long ノード型がTreeWalkerで可視かどうかを判定する。使用可能な定数の集合はNodeFilterインターフェイスで定義される。この値の設定はNodeFilterでFILTER_SKIPを設定するのと同じである。ただし、スキップしたノードの子は依然としてTreeWalkerの論理ツリーには考慮される。これらの定数名はorで結合できる。 RO
filter NodeFilter TreeWalkerの論理ツリーを作成するのに使用されるフィルタ。フィルタを使用しないならばnull RO
expandEntityReferences boolean EntityReferenceノードの子がTreeWalkerから可視であるかどうかを決定する。falseならば、EntityReferenceノードとその子孫は一覧に含まれない(フィルタのFILTER_REJECTと同様の効果がある)。 RO
currentNode Node TreeWalkerが現在位置しているノード。 XS
parentNode() Node 現在のノードに最も近い可視の祖先ノードまで移動し、その祖先ノードを返す。TreeWalkerのルートノードから上に上がろうとする場合や、祖先ノードの検索に失敗した場合は、このメソッドは現在の位置を維持しnullを返す。 -
firstChild() Node 現在のノードの可視である最初の子ノードまでTreeWalkerを移動し、新しいノードを返す。現在のノードが可視な子を持たなければ、nullを返し、現在のノードを維持する。 -
lastChild() Node 現在のノードの可視である最後の子ノードまでTreeWalkerを移動し、新しいノードを返す。現在のノードが可視な子を持たなければ、nullを返し、現在のノードを維持する。 -
previousSibling() Node 現在のノードの前の兄弟ノードまでTreeWalkerを移動し、新しいノードを返す。現在のノードが可視な前の兄弟ノードを持たない場合は、nullを返し、現在のノードを維持する。 -
nextSibling() Node 現在のノードの後ろの兄弟ノードまでTreeWalkerを移動し、新しいノードを返す。現在のノードが可視な後ろの兄弟ノードを持たない場合は、nullを返し、現在のノードを維持する。 -
previousNode() Node 文書の登場順で前の可視なノードまでTreeWalkerを移動し、新しいノードを返す。可視な前のノードがない場合、またはルートノードから上に上がろうとする場合にはnullを返し、現在のノードを維持する。 -
nextNode() Node 文書の登場順で次の可視なノードまでTreeWalkerを移動し、新しいノードを返す。可視な次のノードがない場合、またはルートノードから上に上がろうとする場合にはnullを返し、現在のノードを維持する。 -

なんでdetachメソッドはないんだろう。よくわからん。

Range

文書のソースにおいてのある範囲。開始点と終了点の2つの境界点に挟まれた部分のテキスト。 境界点はコンテナ、オフセットの2値により指定され、その数え方は以下の通りである。 例えば、<body><h1>Title</h1><p>Blah xyz.</p></body>という文書があったとき、 body要素をコンテナと見ると、その内容は<body>[h1要素ノード][p要素ノード]</body>となっており、 [h1要素ノード]の前がオフセット0、[h1要素ノード]の後[p要素ノード]の前がオフセット1、[p要素ノード]の後がオフセット2である。 h1要素をコンテナと見ると、その内容は<h1>[テキストノード]</h1>となっており、 [テキストノード]の前がオフセット0、[テキストノード]の後がオフセット1である。 テキストノードTitleをコンテナと見ると、その内容はTitleであり、 Tの前がオフセット0、Tiの間がオフセット1、itの間がオフセット2、…eの後がオフセット5である。

Rangeのサンプル

メソッド・属性名 解説 RO,X 第1引数の型 第2引数の型
startContainer Node Range開始点のコンテナであるノード。 RO,XR - -
startOffset long Range開始点のコンテナに対するオフセット。 RO,XR - -
endContainer Node Range終了点のコンテナであるノード。 RO,XR - -
endOffset long Range終了点のコンテナに対するオフセット。 RO,XR - -
collapsed boolean Rangeが折りたたまれているかどうか。折りたたまれているとは、2つの境界点がともに同じコンテナ、オフセットであることを指す。 RO,XR - -
commonAncestorContainer Node 2つの境界点に共通する祖先のノードであり、Document, DocumentFragment, Attrのいずれかである。 RO,XR - -
setStart(refNode, offset) void 開始点を定める。 X Node long
setEnd(refNode, offset) void 終了点を定める。 X Node long
setStartBefore(refNode) void 開始点をrefNodeの前に定める。つまりrefNodeの親ノードがコンテナとなる。 X Node -
setStartAfter(refNode) void 開始点をrefNodeの後に定める。つまりrefNodeの親ノードがコンテナとなる。 X Node -
setEndBefore(refNode) void 終了点をrefNodeの前に定める。つまりrefNodeの親ノードがコンテナとなる。 X Node -
setEndAfter(refNode) void 終了点をrefNodeの後に定める。つまりrefNodeの親ノードがコンテナとなる。 X Node -
collapse(toStart) void toStarttrueならば終了点を開始点に合わせる、falseならば開始点を終了点に合わせる。Rangeは折りたたまれた状態になる。 X boolean -
selectNode(refNode) void ノードとその内容を選択する。つまりrefNodeの親ノードがコンテナとなる。 X Node -
selectNodeContents(refNode) void ノードの内容を選択する。つまりrefNodeがコンテナとなり、開始点のオフセットは0となる。 X Node -
compareBoundaryPoints(how, sourceRange) short
このRangeの境界点とsourceRangeの境界点の場所を比較する。AがBより前なら-1、同じ位置なら0、後ろなら1を返す。
howAB
0START_TO_START開始点sourceRangeの開始点
1START_TO_END終了点sourceRangeの開始点
2END_TO_END終了点sourceRangeの終了点
3END_TO_START開始点sourceRangeの終了点
X unsigned short Range
deleteContents() void Rangeの内容を文書(片)から削除する。通常Range内のテキストのみを削除するが、Range内に存在するテキスト以外のノードが完全に含まれている場合はそのノードも削除する。 削除後、境界点は削除された場所に折りたたまれて設定される。Rangeがテキスト以外のノードを一部だけ含んでいた場合には、境界点はそのノードの外に移動する。
例:<FOO>A[START]<MOO>BC</MOO>D[END]E</FOO><FOO>A[START][END]E</FOO>
<FOO>A<MOO>B[START]C</MOO>D[END]E</FOO><FOO>A<MOO>B</MOO>[START][END]E</FOO>
X - -
extractContents() DocumentFragment Rangeの内容を文書(片)から削除し、削除された内容を新規DocumentFragment内に配置して返す。詳細はdeleteContentsメソッド参照。 X - -
cloneContents() DocumentFragment Rangeの内容を新規DocumentFragment内に配置して返す。詳細はdeleteContentsメソッド参照。 X - -
insertNode(newNode) void 開始点の場所にnewNodeを挿入する。ノードがDocumentFragmentの場合はDocumentFragmentの内容が挿入される。 newNodeがツリーのルートになっている場合、下位ツリー全体が挿入される。 newNodeは、それが既に親を持っている場合、存在している位置から除去される。 X Node -
surroundContents(newParent) void
Rangeの内容をnewParentノードで囲う。この動作は以下の操作をまとめたものと同じである。
df = range.extractContents();
range.insertNode(newParent);
newParent.appendChild(df);
range.selectNode(newParent);
newParentはAttr, Entity, DocumentType, Notation, Document, DocumentFragmentであってはならない。 newParentが任意の子を持つ場合、それの子は挿入前に除去される。また、newParentが既に親を持つ場合、それは元の親の childNodes リストから取り除かれる。
X Node -
cloneRange() Range 新規Rangeに複製を作成する。 X - -
toString() DOMString 全文字データのコピーを取得する。 X - -
detach() void Rangeがもう使用されず、実装がこのRangeに関連するリソースを開放してもよいことを示す。 X - -