2. ドキュメントオブジェクトモデルレンジ

編集者: Peter Sharpe, SoftQuad Software Inc.; Vidur Apparao, Netscape Communications Corp.; Lauren Wood, SoftQuad Software Inc.

2.1. イントロダクション

RangeはDocument, DocumentFragment, Attr の内容の範囲を識別する。ある意味これは、一対の境界点の間にある全ての内容の選択として特徴づけられる連続、といえる。

備考: テキストエディタあるいはワードプロセッサでは、ユーザーはドキュメント中の1点からマウスを押して、他の点までマウスを移動して、マウスを放すことによって選択を行うことができる。その結果となる選択は2点の間の内容の連続であり、かつそれが構成しているものである。

「選択している」という用語は、RangeがGUIユーザーによってなされた選択と常に一致するということを意味しない。しかしながら、そのような選択をDOMユーザーにRangeとして返すことはできる。

備考: 双方向の文書（アラビア語、ヘブライ語）では、範囲は、必ずしも表示されたときに連続的ではない、論理上の選択となるかもしれない。いくつかのケースで用いられる、視覚的に連続的な選択も用いられる場合があろうが、それらは単一の論理上の選択には一致しない可能性があり、従って複数の範囲によって表現されなければならないかもしれない。

このRangeインターフェースは、Nodeインターフェースの類似メソッドよりも高次元の、ドキュメントツリーに対するアクセスおよび複製のメソッドを提供する。 Rangeインターフェースで提供されている、内容の追加・削除・複製のための各メソッドは、DOMコアが可能にしている一連のNode編集操作に直接対応できることが期待されている。この観点では、Range操作は、実装が一般的な編集パターンを最適化することも可能にするような便利メソッドとして捉えることもできる。

この章では、Rangeインターフェースについて、Rangeを生成あるいは移動するメソッドや、Rangeと一緒に内容を操作するメソッドも含めて説明する。

このセクションに見られるインターフェースは必須ではない。DOMアプリケーションはDOMImplementation のhasFeature(feature, version) メソッドを、パラメータ値"Range" と "2.0"を（それぞれ）指定することによって、この実装がこのモジュールをサポートするかしないかを決定してよい。。このモジュールを完全にサポートするためには、実装はDOM レベル 2 コア仕様 [DOM Level 2 Core] で定義されている"Core" feature もサポートしなければならない。 適合性 に関するさらなる情報を、DOM レベル 2 コア仕様 [DOM Level 2 Core]で参照して頂きたい。

2.2. 定義および表記法

2.2.1. 位置

この章は2つの異なった表現でドキュメントについて言及する: ドキュメントマークアップを含むテキストあるいはソースと、DOM レベル 2 コア [DOM Level 2 Core] のイントロダクションのセクションで説明されているものと同様のツリー表現である。

Rangeはその開始と終端に該当する、2つの境界点 から構成される。ドキュメントあるいはドキュメントフラグメントのツリーにおける境界点の位置は、1つのノードと1つのオフセットによって表され(characterized)る。このノードは境界点およびその位置のコンテナ と呼ばれる。このコンテナおよびその祖先は、その境界点およびその位置の祖先コンテナである。このノードの中にあるオフセットは、境界点およびその位置のオフセット である。もしこのコンテナがAttr, Document, DocumentFragment, Element あるいは EntityReference nodeであった場合、このオフセットはその子ノードの間にある。もしこのコンテナがCharacterData, Comment あるいは ProcessingInstructionであった場合、このオフセットは、その中に含まれるUTF-16エンコードされた文字列の間に16ビット単位 で存在する。

あるRangeの境界点 は、それぞれDocument, DocumentFragment, Attrのノードのいずれかとなるような共通の祖先コンテナ を持たなければならない。すなわち、Rangeの内容は単一のDocument, DocumentFragment あるいは Attrノードをルートとする完全サブツリー中に存在しなければならない。この共通の祖先コンテナ は、Rangeのルートコンテナ とも言われる。 ルートコンテナ をルートとするツリーはRangeの 内容ツリーとも言われる。

Rangeの境界点のコンテナ はElement, Comment, ProcessingInstruction, EntityReference, CDATASection, Document, DocumentFragment, Attr, あるいは Text ノードでなければならない。 Rangeの境界点 の 祖先コンテナ のいずれもDocumentType, Entity あるいは Notation ノードであってはならない。

ドキュメントのテキスト表現に関して、Rangeの境界点 はトークン境界上にのみ存在しうる。すなわち、テキスト範囲の境界点 はエレメントの開始タグあるいは終了タグの内部や、エンティティ名あるいは文字参照の中にあってはならない。 Rangeはある構造モデルの内容の一部の連続の場所を示すのである。

ドキュメント中のテキスト表現における場所とDOMのNodeツリーインターフェースにおける場所との関係は、次の図によって表される:

Range の例

この図では、4つの別々のRangeが示されている。それぞれの境界点 はs# (Rangeの開始) と e# (Rangeの終端)で目印してある。#はRangeの番号を表す。 Range 2については、その開始はBODY エレメントの中、H1 エレメントの直後、Pエレメントの直前で始まっている。つまりこの位置はBODYの子であるH1とPの間にある。 コンテナ がCharacterDataノードではない境界点 のオフセット はもしそれが最初の子より前であれば0であり、最初の子と2番目の子の間であれば1であり、以下同様である。すなわち、Range 2の開始について言えば、そのコンテナ はBODY であり、そのオフセット は 1となる。 コンテナ がCharacterDataノードである境界点 のオフセット は同様に求められるが、16ビット単位の位置を用いられる。たとえば、Range 1 で s1と目印された境界点 は、そのコンテナ にText ノード("Title"を含むもの)をもち、またそれが2番目と3番目の16ビット単位 の間にあるため、そのオフセット は2となる。

Range3と4の境界点はテキスト表現においては同じ位置にあることに注意してほしい。 Rangeの重要な機能として、Rangeの境界点 はドキュメントツリー中のあらゆる位置を曖昧さのない表現であらわすことができる。

境界点　のコンテナ およびオフセット は以下のread onlyの Rangeアトリビュートによって取得できる:

  readonly attribute Node startContainer; 
  readonly attribute long startOffset;
  readonly attribute Node endContainer; 
  readonly attribute long endOffset;

もしRangeの2つの境界点 が同じコンテナ とオフセット をもつ場合、そのRange は消失(collapsed)していると言われる。（これは時としてユーザーエージェントにおける挿入位置と表される。）

2.2.2. 選択と部分選択

ノードあるいは16ビット単位 の群は、それがRangeの2つの境界点 の間にある場合、そのRangeによって選択されている という。つまり、もしノードあるいは16ビット単位の直前の位置が、そのRangeの終端より前にあり、かつそのノードあるいは16ビット単位の直後の位置が、そのrangeの開始より後にある場合である。たとえば、ドキュメントのテキスト表現において、エレメントは、もし開始タグがRangeの開始より後に位置し、その終了タグがそのRangeの終端より前に位置している場合、このRangeによって選択されている。先の図の例では、 Range 2 は P ノードを選択しており、Range 3 はテキスト"Blah xyz."を含むテキストノードを選択している。

もしノードが、 Rangeの一方だけの境界点 の祖先コンテナ となる場合、そのノードはRangeによって部分選択 されていると言われる。たとえば、先の図のRange 1について考えると、エレメント H1 は、そのRangeの開始がその子の1つの中にあるので部分選択 されている。

2.2.3. 表記規則

この章で用いられる多くの例では、ドキュメントのテキスト表現を図示している。 Rangeの境界点 は、2つの境界点の間の文字（マークアップあるいはデータ文字）として、bold体で次のように示す。

    <FOO>ABC<BAR>DEF</BAR></FOO>

もし両方の境界点 が同じ位置にあれば、それらはbold体のキャレット('^')を用いて、次のように示される。

    <FOO>A^BC<BAR>DEF</BAR></FOO>

2.3. Rangeの生成

Range はDocumentRange インターフェースのcreateRange() メソッドの呼び出しによって生成される。このインターフェースはDocument インターフェースを実装しているオブジェクトから、バインディング固有のキャストメソッドを用いて取得できる。

  interface DocumentRange {
    Range createRange();
  }

このメソッドで返されるRangeの初期状態としては、両境界点 が、該当するDocumentの最初、全ての内容より前に位置する。言い換えれば、それぞれの境界点 のコンテナ はDocumentノードであり、このノードにおけるオフセットが0となるのである。

Documentインターフェース中でメソッドを用いて生成されるいくつかのオブジェクト（NodeやDocumentFragmentなど）と同様、個別の文書インスタンスを通じて生成された Range はそのDocumentがownerDocument となるようなDocument, DocumentFragment, Attr に関連付けられた内容のみを選択することができる。従って、このようなRangeは他のDocumentインスタンスとともに用いることはできない。

2.4. Rangeの位置変更

Rangeの位置は、そのコンテナ と オフセット を、setStart とsetEnd のメソッドを用いてセットすることで指定できる。

  void setStart(in Node parent, in long offset)
                        raises(RangeException);
  void setEnd(in Node parent, in long offset)
                raises(RangeException);

もしRangeの一方の境界点がもう一方とは異なるルートコンテナ をもつようセットされた場合、そのRangeは新しい位置で消失する。このことは、Rangeの両方の境界点は同一のルートコンテナ をもたなければならないという制限を実現している。

Rangeの開始位置はその終了位置よりも絶対に後に来ないことが保証されている。この制限が実現されるために、もし開始位置が終了位置よりも後にセットされた場合、そのRangeはその位置で消失する。同様に、もし終了位置が開始位置よりも前にセットされた場合、そのRangeはその位置で消失する。

Rangeの位置をツリーのノードからの相対でセットすることも可能である:

  void setStartBefore(in Node node);
                              raises(RangeException);
  void setStartAfter(in Node node);
                       raises(RangeException);
  void setEndBefore(in Node node);
                      raises(RangeException);
  void setEndAfter(in Node node);
                     raises(RangeException);

ノードの親はその境界点 のコンテナ となり、このRangeは先のsetStart() と setEnd() の説明で提示されたものと同じ制限に従う。

Range はどちらの境界点で消失してもよい:

  void collapse(in boolean toStart);

TRUE をパラメータ toStart に渡すとそのRangeの開始で、FALSE を渡すと終端で、それぞれ消失する。

Range が消失しているかどうかのテストは、collapsed アトリビュートを確認することで可能である:

  readonly attribute boolean collapsed;

以下のメソッドは、Rangeがあるノードの内容あるいはそのノード自身を選択するようにできる。

  void selectNode(in Node n);
  void selectNodeContents(in Node n);

以下の例はメソッド selectNode と selectNodeContentsの操作のデモンストレーションである:

実行前:
  ^<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>
Range.selectNodeContents(FOO) 実行後:
  <BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>
（この場合、FOOは両境界点の親）
Range.selectNode(FOO) 実行後:

<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>

2.5. Rangeの境界点の比較

2つのRangeの比較は、その境界点の比較によって可能となる:

  short compareBoundaryPoints(in CompareHow how, in Range sourceRange) raises(RangeException);

CompareHow は次の4つの値のうちの1つとなる: START_TO_START, START_TO_END, END_TO_END, END_TO_START である。戻り値はそのRangeの該当する境界点がsourceRange の境界点より前にあるか、等しいか、後にあるかによって、-1, 0, 1 のいずれかになる。もし2つのRangeが異なるルートコンテナ をもっていたら例外が投げられる。

2つの境界点（あるいは位置）の比較の結果は以下で示すとおり。形式的ではなく、常に正しくない言い方(specification)としては、もし1つの位置(location)がテキスト表現でもう一方の該当する位置よりも前にあるか、等しいか、あるいは後にあるか、であれば、その境界点が他方よりも前にある、等しい、あるいは後にある、ということである。（境界点の比較＝テキスト表現における場所の比較）

A と B に2つの境界点あるいは位置を与えたとき、以下のどれかが成り立つ: AはBより前であるか、, AはBに等しい か、AはBより後である。このどれが成り立つかは、次の4つの条件を判断して決定される:

最初のケースは、境界点が同一のコンテナをもつ場合である。もしAのオフセット がBの オフセット よりも小さい場合、 AはBの前にあり、もしAのオフセット がBの オフセット と等しい場合、 AはBと等しい ものであり、もしAのオフセット がBの オフセット より大きい場合、 AはBの後にある。

2番目のケースは、Aのコンテナ である子ノードCが Bの祖先コンテナ である場合である。この場合、もしAの オフセット が子ノードCのインデックス以下であれば、AはBより前にあるし、そうでなければAはBの後にある。

3番目のケースは、Bのコンテナ である子ノードCが Aの祖先コンテナ である場合である。この場合、もし子ノードCのインデックスがBの オフセット より小さければ、AはBより前にあるし、そうでなければAはBの後にある。

4番目のケースは他の3つのどれも成立しない場合である: AとBのコンテナは兄弟あるいは兄弟ノードの子孫である。この場合、もしAのコンテナ がBのコンテナ よりそのRangeの コンテキストツリー の順序付きトラバース(pre-order traversal)で前にあれば、AはBの前となり、そうでなければAはBの後になる。

注意してほしいのは、ドキュメントのテキスト表現において同じ位置にあるものが、DOMツリーでは異なる2つの位置について一致することもあるので、テキスト表現において等しいものであっても、2つの境界点が等しくない場合がありうるということである。このため、上記の非公式な定義は時として正しくないのである。

2.6. Rangeとその内容の削除

以下を用いて、Rangeで選択した内容を削除することができる:

  void deleteContents();

deleteContents() は、そのRangeが選択している全てのノードと文字を削除する。他の全てのノードおよび文字はRangeの コンテキストツリー の中に残る。この削除命令の例をいくつか挙げる:

(1) <FOO>AB<MOO>CD</MOO>CD</FOO>  -->
<FOO>A^CD</FOO>

(2) <FOO>A<MOO>BC</MOO>DE</FOO>  -->
<FOO>A<MOO>B</MOO>^E</FOO>

(3) <FOO>XY<BAR>ZW</BAR>Q</FOO>  -->
<FOO>X^<BAR>W</BAR>Q</FOO>

(4) <FOO><BAR1>AB</BAR1><BAR2/><BAR3>CD</BAR3></FOO>
-->  <FOO><BAR1>A</BAR1>^<BAR3>D</BAR3>

deleteContents() がRangeについて呼び出された後、このRangeは消失する。もしRangeがノードを部分選択 していなかった場合、それは例(1)のように、オリジナルの開始点について消失する。もしノードがそのRangeによって部分選択 されており、それがRangeの開始の祖先コンテナ であり、そのノードのどの祖先もこの2つの条件を満たさない場合、このRangeはそのノードの直後の位置について例(2)および(4)のように消失する。もしノードがRangeによって 部分選択 されており、かつRange の終端の祖先コンテナ であり、かつそのノードのどの祖先もこの2つの条件を満たさない場合、このRangeはそのノードの直前で、例(3)および(4)のように消失する。

もしRangeの削除が隣接するTextノードを残す場合、それらは自動的にはマージされず、空のTextノードも自動的には削除されないことに注意。 2つのTextノードは、そのどちらもが、その内容が削除されたRangeにおける境界点の一方のコンテナであった場合にのみ結合される。隣接したTextノードをマージするためには、あるいは空のテキストノードを削除するためには、Node インターフェースの normalize() メソッドを用いるべきである。

2.7. 内容の展開

もしRangeの内容が削除されるのではなく展開される必要がある場合、次のメソッドを用いることができる:

  DocumentFragment extractContents();

extractContents() メソッドは、Rangeのコンテキストツリー 上からdeleteContents() メソッドと同様にノードを削除する。それに加えて、これは削除された内容を新しいDocumentFragment上に置く。以下の例は返されたDocumentFragmentの内容を表している:

(1) <FOO>AB<MOO>CD</MOO>CD</FOO>  -->
B<MOO>CD</MOO>

(2) <FOO>A<MOO>BC</MOO>DE</FOO>  -->
<MOO>C<MOO>D <MOO>C</MOO>D の誤りか？

(3) <FOO>XY<BAR>ZW</BAR>Q</FOO>  -->
Y<BAR>Z</BAR>

(4)
<FOO><BAR1>AB</BAR1><BAR2/><BAR3>CD</BAR3></FOO> -->
<BAR1>B</BAR1><BAR2/><BAR3>C</BAR3>

このRangeによって部分選択 されたノードは複製(clone)されたものだということが重要である。このようなノードの内容の一部はこのRangeのコンテキストツリー であり続けなければならず、またこの内容の一部は新しいDocumentFragmentに移動しなければならないため、部分選択 されたノードの複製は新しいDocumentFragmentに含まれる。複製は選択されたエレメントに取って代わるものではないことに注意; これらのノードは新しいDocumentFragmentに移動されるのである。

2.8. 内容の複製

Rangeの内容は以下のメソッドを用いて複製することができる:

  DocumentFragment cloneContents();

このメソッドは、メソッドextractContents()によって返されるものと同様のDocumentFragment を返す。しかしこの場合、このRangeに含まれるオリジナルのノードおよび文字データはRangeの内容ツリーから削除されることはない。むしろ返されたDocumentFragment 中の全てのノードおよびテキスト内容は複製されているのである。

2.9. 内容の追加

ノードは次のメソッドを用いてRangeの中に追加されうる:

  void insertNode(in Node n) raises(RangeException);

insertNode() メソッドは指定されたノードをRange の内容ツリー中に追加する。このノードはこのRangeの開始境界点 に、それを変更することなく追加される。

もしRangeの開始境界点がText ノード中にあれば、このinsertNode 命令はその Text ノードを境界点で分割する。もし追加されるノードもText ノードであった場合、結果的に隣接することになるText ノードは、自動的には正規化されない; その処理はアプリケーション依存となる。

このメソッドに渡されたNodeはDocumentFragmentであってよい。この場合、この DocumentFragment の内容はそのRangeの開始境界点 に追加されるが、そのDocumentFragment 自身は追加されない。もしこのNodeがサブツリーのルートを表す場合、全サブツリーが追加されるということに注意。

NodeインターフェースのinsertBefore()メソッドについて当てはまるものと同様のルールが、ここでも当てはまる。特に、渡されたNodeがもし既に親をもっていた場合、その現存する位置から削除されることになる。

2.10. 内容の包含

Rangeが選択した内容を含むサブツリーへの単一ノードの追加は次のものが実行する:

  void surroundContents(in Node newParent);

surroundContents() メソッドは、指定したノードが Rangeが選択する全ての内容のルートなるようにする。このノードはAttr, Entity, DocumentType, Notation, Document, DocumentFragment の各ノードであってはならない。以下の例のElementノードFOOでsurroundContents() を呼び出した結果は次の通り:

     使用前:
       <BAR>AB<MOO>C</MOO>DE</BAR>

     surroundContents(FOO) 使用後:

<BAR>A<FOO>B<MOO>C</MOO>D</FOO>E</BAR>

このRangeの 内容ツリー に与えるこのメソッドの効果を記述する、もうひとつの方法は、これを他の命令を用いて再編することである:

Rangeによって選択されている範囲をextractContents() の呼び出しによって削除する。
ノードnewParent を、そのRange が（展開によって）消失したところに、insertNode()を用いて追加する。
展開されたDocumentFragment の全内容をnewParent の中に追加する。具体的には、newParent で、extractContents() の呼び出しの結果として返されたDocumentFragmentを渡して appendChild() を呼び出す。
newParent とその全内容をselectNode() を用いて選択する。

surroundContents() メソッドは、もしこのRange が非Textノードを部分選択 した場合は例外を投げる。 surroundContents()が例外を投げるようなRangeの例としては:

     <FOO>AB<BAR>CD</BAR>E</FOO>

もしノードnewParent が何らかの子をもっていれば、それらの子はその追加前に削除される。また、もしノード newParent が親をもっていれば、それはその（originalの、源流の）親の childNodes のリストから削除される。

2.11. その他のメンバー

Rangeを複製できるものがある:

  Range cloneRange();

これは、このメソッドcloneRange を呼び出したRangeによって選択されているものと全く同じ内容を選択するような、新しいRangeを生成する。この命令によって影響を受ける内容はない。

Rangeの境界点が必ずしも同一のコンテナをもっているとは限らないので使うのが:

  readonly attribute Node commonAncestorContainer;

Rangeの ルートコンテナ から見て最下層にある、両境界点の 祖先コンテナ を取得する。

Rangeが選択している、あるいは部分選択している文字データの全てのコピーを取得することができる:

  DOMString toString();

これはRangeが選択している全ての文字データを単純に連結する以上の何もしない。これにはText とCDATASection ノードの両方が含まれる。

2.12. ドキュメントの変更に際してのRangeの修正

ドキュメント中のRangeは、そのドキュメントが修正に応じて更新する必要がある。たとえば、もしRangeの一方の境界点があるノードの中にあり、そのノードがそのドキュメントから削除された場合、そのRangeは何らかの方法でそれが固定(fixed)されない限り無効となる。このセクションではRangeがどのようにドキュメントの変更に応じて修正され、有効でいられるかについて説明する。

ドキュメントの変更のもとでRangeに適当される一般原則が2つある: 1つは、ドキュメント中の全てのRangeはどのような変更命令の後でも有効であり続けるということであり、もう一つは、全てのRangeはどのような変更命令の後でも可能な限りそのドキュメントにおける同じ位置を選択するということである。

Rangeに影響を与えるドキュメントツリーの変更は、全て、基本的な削除と追加の命令の組み合わせとして考えることができる。実際、これらの命令は deleteContents() とinsertNode() のRangeメソッドを、あるいはテキスト変更の場合は splitText() と normalize() のメソッドを用いて実現されていると考えた方が便利である。

2.12.1. 追加

追加はドキュメント中の1つの位置すなわち追加位置について発生する。ドキュメントツリー中のいかなるRangeもそれぞれの境界点について考えてみよう。境界点が追加の後に変化する唯一のケースは、境界点と追加位置が同じコンテナ をもち、かつその追加位置の オフセット が、厳密に(strictly)そのRangeの境界点のオフセット よりも小さい場合である。このケースでは、Rangeの境界点のオフセット は、それが追加される以前にあったノードあるいは文字の間に来るように追加される。

参考までに、内容が境界点に追加されたとき、もしその相対位置が維持されるのであれば、境界点が再配置される場所についてはあいまいになる。新しく追加された内容の開始と、その終端という2つの可能性がある。ここまで我々は、境界点のコンテナ も オフセット も変更されないという選択肢をえらんできた。従って結果的に、この境界点は新しく追加された内容の開始に配置されるのである。

例:

たとえばRangeが以下を選択していたとする:

<P>Abcd efgh XY blah ijkl</P>

Consider the insertion of the text "inserted text" at the following positions:

1. Before the 'X':

<P>Abcd efgh inserted textXY blah ijkl</P>

2. After the 'X':

<P>Abcd efgh Xinserted textY blah ijkl</P>

3. After the 'Y':

<P>Abcd efgh XYinserted text blah ijkl</P>

4. After the 'h' in "Y blah":

<P>Abcd efgh XY blahinserted text ijkl</P>

2.12.2. Deletions

Any deletion from the document tree can be considered as a sequence of deleteContents() operations applied to a minimal set of disjoint Ranges. To specify how a Range is modified under deletions we need only consider what happens to a Range under a single deleteContents()operation of another Range. And, in fact, we need only consider what happens to a single boundary-point of the Range since both boundary-points are modified using the same algorithm.

If a boundary-point of the original Range is within the content being deleted, then after the deletion it will be at the same position as the resulting boundary-point of the (now collapsed) Range used to delete the contents.

If a boundary-point is after the content being deleted then it is not affected by the deletion unless its コンテナ is also the コンテナ of one of the boundary-points of the Range being deleted. If there is such a common コンテナ, then the index of the boundary-point is modified so that the boundary-point maintains its position relative to the content of the コンテナ.

If a boundary-point is before the content being deleted then it is not affected by the deletion at all.

Examples:

In these examples, the Range on which deleteContents()is invoked is indicated by the underline.

Example 1.

Before:

<P>Abcd efgh The Range ijkl</P>

After:

<P>Abcd Range ijkl</P>

Example 2.

Before:

<p>Abcd efgh The Range ijkl</p>

After:

<p>Abcd ^kl</p>

Example 3.

Before:

<P>ABCD efgh The <EM>Range</EM> ijkl</P>

After:

<P>ABCD <EM>ange</EM> ijkl</P>

In this example, the container of the start boundary-point after the deletion is the Text node holding the string "ange".

Example 4.

Before:

<P>Abcd efgh The Range ijkl</P>

After:

<P>Abcd he Range ijkl</P>

Example 5.

Before:

<P>Abcd <EM>efgh The Range ij</EM>kl</P>

After:

<P>Abcd ^kl</P>

2.13. Formal Description of the Range Interface

To summarize, the complete, formal description of the Range interface is given below:

Interface Range (introduced in DOM Level 2)

IDL Definition

// Introduced in DOM Level 2:
interface Range {
  readonly attribute Node             startContainer;
                                        // raises(DOMException) on retrieval

  readonly attribute long             startOffset;
                                        // raises(DOMException) on retrieval

  readonly attribute Node             endContainer;
                                        // raises(DOMException) on retrieval

  readonly attribute long             endOffset;
                                        // raises(DOMException) on retrieval

  readonly attribute boolean          collapsed;
                                        // raises(DOMException) on retrieval

  readonly attribute Node             commonAncestorContainer;
                                        // raises(DOMException) on retrieval

  void               setStart(in Node refNode, 
                              in long offset)
                                        raises(RangeException, 
                                               DOMException);
  void               setEnd(in Node refNode, 
                            in long offset)
                                        raises(RangeException, 
                                               DOMException);
  void               setStartBefore(in Node refNode)
                                        raises(RangeException, 
                                               DOMException);
  void               setStartAfter(in Node refNode)
                                        raises(RangeException, 
                                               DOMException);
  void               setEndBefore(in Node refNode)
                                        raises(RangeException, 
                                               DOMException);
  void               setEndAfter(in Node refNode)
                                        raises(RangeException, 
                                               DOMException);
  void               collapse(in boolean toStart)
                                        raises(DOMException);
  void               selectNode(in Node refNode)
                                        raises(RangeException, 
                                               DOMException);
  void               selectNodeContents(in Node refNode)
                                        raises(RangeException, 
                                               DOMException);

  // CompareHow
  const unsigned short      START_TO_START                 = 0;
  const unsigned short      START_TO_END                   = 1;
  const unsigned short      END_TO_END                     = 2;
  const unsigned short      END_TO_START                   = 3;

  short              compareBoundaryPoints(in unsigned short how, 
                                           in Range sourceRange)
                                        raises(DOMException);
  void               deleteContents()
                                        raises(DOMException);
  DocumentFragment   extractContents()
                                        raises(DOMException);
  DocumentFragment   cloneContents()
                                        raises(DOMException);
  void               insertNode(in Node newNode)
                                        raises(DOMException, 
                                               RangeException);
  void               surroundContents(in Node newParent)
                                        raises(DOMException, 
                                               RangeException);
  Range              cloneRange()
                                        raises(DOMException);
  DOMString          toString()
                                        raises(DOMException);
  void               detach()
                                        raises(DOMException);
};

Definition group CompareHow

Passed as a parameter to the compareBoundaryPoints method.

Defined Constants

END_TO_END: Compare end boundary-point of sourceRange to end boundary-point of Range on which compareBoundaryPoints is invoked.
END_TO_START: Compare end boundary-point of sourceRange to start boundary-point of Range on which compareBoundaryPoints is invoked.
START_TO_END: Compare start boundary-point of sourceRange to end boundary-point of Range on which compareBoundaryPoints is invoked.
START_TO_START: Compare start boundary-point of sourceRange to start boundary-point of Range on which compareBoundaryPoints is invoked.

Attributes

collapsed of type boolean, readonly

TRUE if the Range is collapsed

Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

commonAncestorContainer of type Node, readonly

The deepest common ancestor container of the Range's two boundary-points.

Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

endContainer of type Node, readonly

Node within which the Range ends

Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

endOffset of type long, readonly

Offset within the ending node of the Range.

Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

startContainer of type Node, readonly

Node within which the Range begins

Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

startOffset of type long, readonly

Offset within the starting node of the Range.

Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

Methods

cloneContents

Duplicates the contents of a Range

Return Value

DocumentFragment

A DocumentFragment that contains content equivalent to this Range.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be extracted into the new DocumentFragment.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Parameters

cloneRange

Produces a new Range whose boundary-points are equal to the boundary-points of the Range.

Return Value

Range

The duplicated Range.

Exceptions

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Parameters

collapse

Collapse a Range onto one of its boundary-points

Parameters

toStart of type boolean: If TRUE, collapses the Range onto its start; if FALSE, collapses it onto its end.

Exceptions

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Return Value

compareBoundaryPoints

Compare the boundary-points of two Ranges in a document.

Parameters

how of type unsigned short: A code representing the type of comparison, as defined above.
sourceRange of type Range: The Range on which this current Range is compared to.

Return Value

short

-1, 0 or 1 depending on whether the corresponding boundary-point of the Range is respectively before, equal to, or after the corresponding boundary-point of sourceRange.

Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same Document or DocumentFragment.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

deleteContents

Removes the contents of a Range from the containing document or document fragment without returning a reference to the removed content.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the Range is read-only or any of the nodes that contain any of the content of the Range are read-only.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Parameters

No Return Value

detach

Called to indicate that the Range is no longer in use and that the implementation may relinquish any resources associated with this Range. Subsequent calls to any methods or attribute getters on this Range will result in a DOMException being thrown with an error code of INVALID_STATE_ERR.

Exceptions

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Parameters

No Return Value

extractContents

Moves the contents of a Range from the containing document or document fragment to a new DocumentFragment.

Return Value

DocumentFragment

A DocumentFragment containing the extracted contents.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the Range is read-only or any of the nodes which contain any of the content of the Range are read-only.

HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be extracted into the new DocumentFragment.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Parameters

insertNode

Inserts a node into the Document or DocumentFragment at the start of the Range. If the container is a Text node, this will be split at the start of the Range (as if the Text node's splitText method was performed at the insertion point) and the insertion will occur between the two resulting Text nodes. Adjacent Text nodes will not be automatically merged. If the node to be inserted is a DocumentFragment node, the children will be inserted rather than the DocumentFragment node itself.

Parameters

newNode of type Node: The node to insert at the start of the Range

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the start of the Range is read-only.

WRONG_DOCUMENT_ERR: Raised if newNode and the コンテナ of the start of the Range were not created from the same document.

HIERARCHY_REQUEST_ERR: Raised if the コンテナ of the start of the Range is of a type that does not allow children of the type of newNode or if newNode is an ancestor of the コンテナ.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

RangeException

INVALID_NODE_TYPE_ERR: Raised if newNode is an Attr, Entity, Notation, or Document node.

No Return Value

selectNode

Select a node and its contents

Parameters

refNode of type Node: The node to select.

Exceptions

`RangeException`	INVALID_NODE_TYPE_ERR: Raised if an ancestor of `refNode` is an Entity, Notation or DocumentType node or if `refNode` is a Document, DocumentFragment, Attr, Entity, or Notation node.
`DOMException`	INVALID_STATE_ERR: Raised if `detach()` has already been invoked on this object.

No Return Value

selectNodeContents

Select the contents within a node

Parameters

refNode of type Node: Node to select from

Exceptions

`RangeException`	INVALID_NODE_TYPE_ERR: Raised if `refNode` or an ancestor of `refNode` is an Entity, Notation or DocumentType node.
`DOMException`	INVALID_STATE_ERR: Raised if `detach()` has already been invoked on this object.

No Return Value

setEnd

Sets the attributes describing the end of a Range.

Parameters

refNode of type Node: The refNode value. This parameter must be different from null.
offset of type long: The endOffset value.

Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Entity, Notation, or DocumentType node.

DOMException

INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of child units in refNode. Child units are 16-bit units if refNode is a type of CharacterData node (e.g., a Text or Comment node) or a ProcessingInstruction node. Child units are Nodes in all other cases.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Return Value

setEndAfter

Sets the end of a Range to be after a node

Parameters

refNode of type Node: Range ends after refNode.

Exceptions

`RangeException`	INVALID_NODE_TYPE_ERR: Raised if the root container of `refNode` is not an Attr, Document or DocumentFragment node or if `refNode` is a Document, DocumentFragment, Attr, Entity, or Notation node.
`DOMException`	INVALID_STATE_ERR: Raised if `detach()` has already been invoked on this object.

No Return Value

setEndBefore

Sets the end position to be before a node.

Parameters

refNode of type Node: Range ends before refNode

Exceptions

`RangeException`	INVALID_NODE_TYPE_ERR: Raised if the root container of `refNode` is not an Attr, Document, or DocumentFragment node or if `refNode` is a Document, DocumentFragment, Attr, Entity, or Notation node.
`DOMException`	INVALID_STATE_ERR: Raised if `detach()` has already been invoked on this object.

No Return Value

setStart

Sets the attributes describing the start of the Range.

Parameters

refNode of type Node: The refNode value. This parameter must be different from null.
offset of type long: The startOffset value.

Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Entity, Notation, or DocumentType node.

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Return Value

setStartAfter

Sets the start position to be after a node

Parameters

refNode of type Node: Range starts after refNode

Exceptions

`RangeException`	INVALID_NODE_TYPE_ERR: Raised if the root container of `refNode` is not an Attr, Document, or DocumentFragment node or if `refNode` is a Document, DocumentFragment, Attr, Entity, or Notation node.
`DOMException`	INVALID_STATE_ERR: Raised if `detach()` has already been invoked on this object.

No Return Value

setStartBefore

Sets the start position to be before a node

Parameters

refNode of type Node: Range starts before refNode

Exceptions

`RangeException`	INVALID_NODE_TYPE_ERR: Raised if the root container of `refNode` is not an Attr, Document, or DocumentFragment node or if `refNode` is a Document, DocumentFragment, Attr, Entity, or Notation node.
`DOMException`	INVALID_STATE_ERR: Raised if `detach()` has already been invoked on this object.

No Return Value

surroundContents

Reparents the contents of the Range to the given node and inserts the node at the position of the start of the Range.

Parameters

newParent of type Node: The node to surround the contents with.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of either boundary-point of the Range is read-only.

WRONG_DOCUMENT_ERR: Raised if newParent and the コンテナ of the start of the Range were not created from the same document.

HIERARCHY_REQUEST_ERR: Raised if the コンテナ of the start of the Range is of a type that does not allow children of the type of newParent or if newParent is an ancestor of the コンテナ or if node would end up with a child node of a type not allowed by the type of node.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

RangeException

BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a non-text node.

INVALID_NODE_TYPE_ERR: Raised if node is an Attr, Entity, DocumentType, Notation, Document, or DocumentFragment node.

No Return Value

toString

Returns the contents of a Range as a string. This string contains only the data characters, not any markup.

Return Value

DOMString

The contents of the Range.

Exceptions

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

No Parameters

Interface DocumentRange (introduced in DOM Level 2)

IDL Definition

// Introduced in DOM Level 2:
interface DocumentRange {
  Range              createRange();
};

Methods

createRange

This interface can be obtained from the object implementing the Document interface using binding-specific casting methods.

Return Value

Range

The initial state of the Range returned from this method is such that both of its boundary-points are positioned at the beginning of the corresponding Document, before any content. The Range returned can only be used to select content associated with this Document, or with DocumentFragments and Attrs for which this Document is the ownerDocument.

No Parameters

No Exceptions

Exception RangeException introduced in DOM Level 2

Range operations may throw a RangeException as specified in their method descriptions.

IDL Definition

// Introduced in DOM Level 2:
exception RangeException {
  unsigned short   code;
};
// RangeExceptionCode
const unsigned short      BAD_BOUNDARYPOINTS_ERR         = 1;
const unsigned short      INVALID_NODE_TYPE_ERR          = 2;

Definition group RangeExceptionCode

An integer indicating the type of error generated.

Defined Constants

BAD_BOUNDARYPOINTS_ERR: If the boundary-points of a Range do not meet specific requirements.
INVALID_NODE_TYPE_ERR: If the コンテナ of an boundary-point of a Range is being set to either a node of an invalid type or a node with an ancestor of an invalid type.

2. ドキュメントオブジェクトモデル レンジ

目次

2.1. イントロダクション

2.2. 定義および表記法

2.2.1. 位置

2.2.2. 選択と部分選択

2.2.3. 表記規則

2.3. Rangeの生成

2.4. Rangeの位置変更

2.5. Rangeの境界点の比較

2.6. Rangeとその内容の削除

2.7. 内容の展開

2.8. 内容の複製

2.9. 内容の追加

2.10. 内容の包含

2.11. その他のメンバー

2.12. ドキュメントの変更に際してのRangeの修正

2.12.1. 追加

2.12.2. Deletions

2.13. Formal Description of the Range Interface

2. ドキュメントオブジェクトモデルレンジ