2. 文書オブジェクトモデル範囲

2.1. 概要

Range(範囲)は，Document，DocumentFragment又はAttrの内容の範囲を識別する。これは，境界点の対の間のすべての内容を選択するものとして特徴付け可能という意味で，連続的といえる。

備考　テキストエディタ又はワードプロセサでは，利用者は，文書の中のある点でマウスを押し下げ，他の点まで移動し，マウスを放すことによって，選択が可能となる。その結果得られた選択は，連続的であって，その2点間の内容から構成される。

'選択(する)'という用語は，すべてのRangeが，GUI利用者が行う選択に相当するということ意味しているのではない。しかし，このような選択をRangeとしてDOM利用者に返すことはできる。

備考　アラビア語，ヘブライ語などの双方向書きでは，範囲は，表示の際に必ずしも連続しない論理的な選択に相当する場合もある。視覚的に連続する選択が使用される場合もあるが，これは，単一の論理的な選択に相当しなくてもよく，したがって，一つより多くの範囲によって表現されなければならない場合があってもよい。

Rangeインタフェースは，Nodeインタフェースの類似のメソッドよりも高水準で，文書木にアクセスし，操作するメソッドを提供する。内容の挿入，削除及びコピーについてRangeインタフェースが提供する各メソッドは，DOMコアが可能にする一連のNode編集操作に直接に対応付けできることが期待される。この意味で，Rangeの操作は，実装が共通的な編集パタンを最適化できるようにする便利なメソッドとしてもとらえることができる。

2.では，Rangeの生成及び移動のためのメソッド，並びにRangeを用いて内容を操作するメソッドを含んだ，Rangeインタフェースを示す。

2.で示すインタフェースは，必須とはしない。DOMアプリケーションは，このモジュールが実装によってサポートされているかどかを決定するために，パラメタ値"Range"及び"2.0"をそれぞれ用いてDOMImplementationインタフェースのhasFeature(feature, version)メソッドを使用してもよい。このモジュールを完全にサポートするためには，実装は，DOM水準2 コア規定[DOM Level 2 Core]で定義されている"コア"機能もサポートしなければならない。DOM 水準2 コア規定[DOM Level 2 Core]の適合性に関する追加情報を参照すること。

2.2 定義及び記法

2.2.1 位置

2.では，文書の異なる二つの表現に言及する。それらは，すなわち，文書マーク付けを含むテキスト又はソースの形式，及びDOM水準2 コア[DOM Level 2 Core]の導入で示されたものと類似する木表現とする。

Rangeは，その開始及び終了に対応する二つの境界点から構成される。Document又はDocumentFragmentの木の中の境界点の位置は，一つのノード及び一つのオフセットによって特徴付け可能とする。ノードは，境界点及びその位置のコンテナと呼ばれる。そのコンテナ及びその先祖は，境界点及びその位置の先祖コンテナとする。ノード内のオフセットは，境界点及びその位置のオフセットと呼ばれる。コンテナが，Attrノード，Documentノード，DocumentFragmentノード，Elementノード又はEntityReferenceノードである場合, オフセットは，その子ノードの間とする。コンテナが，CharacterDataノード，Commentノード又はProcessingInstructionノードである場合は，オフセットは，それが含むUTF-16符号化文字列の16ビット単位の間とする。

Rangeの境界点は，Documentノード，DocumentFragmentノード又はAttrノードのいずれかである共通の先祖コンテナをもたなければならない。すなわち，Rangeの内容は，単一のDocumentノード，DocumentFragmentノード又はAttrノードがルートになる部分木の内部に完全に存在しなければならない。この共通の先祖コンテナを，範囲のルートコンテナという。ルートコンテナをルートとする木を，Rangeの文脈木という。

Rangeの境界点のコンテナは，Elementノード，Commentノード，ProcessingInstructionノード，EntityReferenceノード，CDATASectionノード，Documentノード，DocumentFragmentノード，Attrノード又はTextノードでなければならない。Rangeの境界点の先祖コンテナは，DocumentTypeノード，Entityノード又はNotationノードになることはできない。

文書のテキスト表現に関しては，Rangeの境界点を，トークン境界上に限ることができる。すなわち，テキスト範囲の境界点が，要素の開始タグ又は終了タグの途中に存在したり，実体参照又は文字参照の名前の内部に存在することはできない。Rangeは，構造モデルの内容の連続部分を位置決めする。

文書のテキスト表現における位置とDOMのNode木インタフェースの位置との間の関係を，次の図で示す。

Range(範囲)の例

この図では，異なる四つのRangeが示されている。各Rangeの境界点は，s#(Rangeの開始)及びe#(Rangeの終了)を用いてラベル付けされている。ここで，#はRangeの番号とする。Range 2については，開始はBODY要素の中であって，H1要素の直後及びP要素の直前にある。そこで，その位置は，BODYのH1子どもとP子どもとの間になる。コンテナがCharacterDataノードではない開始点のオフセットは，それが最初の子の前に存在する場合は0，それが最初の子と二番目の子との間に存在する場合は1，などとなる。そのために，Range 2の開始については，コンテナはBODYであって，オフセットは1となる。コンテナがCharacterDataノードである境界点のオフセットも同様に得られるが，代わりに16ビット単位の位置を使用する。例えば，Range 1のs1とラベル付けされた境界点は，そのコンテナとしてTextノード("Title"を含むもの)をもち，それが二番目及び三番目の16ビット単位の間に存在するために，2のオフセットをもつ。

Range 3及びRange 4の境界点は，テキスト表現における同じ位置に対応していることに注意すること。Rangeの境界点が，文書木内のすべての位置をあいまい性なく表現できるということは，Rangeの重要な機能になっている。

次の読取り専用のRange属性を通じて，境界点のコンテナ及びオフセットを取得できる。

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

Rangeの複数の境界点が同じコンテナ及びオフセットをもつ場合，その範囲を，縮退範囲という。これは，利用者エージェントでは，挿入点として参照されることが多い。

2.2.2 選択及び部分選択

ノード又は16ビット単位の構成単位は，それがRangeの二つの境界点の間にある場合，すなわち，ノード又は16ビット単位の直前の位置がRangeの終了前であって，ノード又は16ビット単位の直後の位置がRangeの開始後になる場合，Rangeによって選択されるという。例えば，文書のテキスト表現に関して，要素は，対応する開始タグがRangeの開始後に位置し，その終了タグがRangeの終了前に位置する場合，Rangeによって選択される。先の図の例では，Range 2は，Pノードを選択し，Range 3は，テキスト"Blah xyz."を含むテキストノードを選択する。

ノードがRangeの正確に一つの境界点の先祖コンテナになる場合，そのノードは，Rangeによって部分選択されているという。例えば，先の図のRange 1を検討してみる。H1要素は，Rangeの開始がその要素の子どもの一つの内部にあるので，そのRangeによって部分選択されている。

2.2.3 記法

2.における例の多くは，文書のテキスト表現を使用して，例示される。Rangeの境界点は，二つの境界点間にある文字(マーク付け又はデータ文字)を太字で表示することによって，示される。その例を次に示す。

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

境界点が両方とも同じ位置にある場合，それらは，太字の脱字記号(caret，'^')で示される。その例を次に示す。

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

2.3 範囲の生成

Rangeは，DocumentRangeインタフェース上のcreateRange()メソッドを呼び出すことによって，生成される。このインタフェースは，Documentインタフェースを実装するオブジェクトから束縛固有のキャスト化メソッドを使用して取得できる。

  interface DocumentRange {
    Range createRange();
  }

このメソッドから返されるRangeの初期状態は，その境界点が両方とも，対応するDocumentの最初であってすべての内容の前に配置されている。言い換えれば，各境界点のコンテナがDocumentノードであって，そのノード内のオフセットが0になっている。

Documentインタフェースの中でメソッドを使用して生成される(Node及びDocumentFragmentといった)幾つかのオブジェクトと同様に，特定の文書インスタンスを介して生成されるRangeは，そのDocument，又はそのDocumentがownerDocumentであるDocumentFragment及びAttrと関連付けられる内容だけを選択できる。したがって，これらのRangeを，他のDocumentインスタンスとともに使用することはできない。

2.4 範囲の位置の変更

setStartメソッド及びsetEndメソッドを用いて，各境界点のコンテナ及びオフセットを設定することによって，Rangeの位置を指定することができる。

  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は，その位置まで縮退される。

木のノードに対して相対的に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);

パラメタtoStartとしてTRUEを渡すことによって，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の二つの境界点を比較することによって，それらRangeを比較することができる。

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

このCompareHowは，START_TO_START，START_TO_END，END_TO_END及びEND_TO_STARTの四つの値のうちの一つとする。返却値は，-1, 0又は1であって，Rangeの対応する境界点がsourceRangeの対応する境界点の前にあるか，等しいか，又は後にあるかに依存する。二つのRangeが異なるルートコンテナをもつ場合には，例外が投げられる。

二つの境界点(又は位置)を比較した結果を次に規定する。一つの境界点が，あるテキスト表現において，他方の対応位置の前，等しい又は後の位置に対応する場合に，前者の境界点が，他の境界点の前にあるか，等しいか又は後にあるというのは，非形式的であって必ずしも正しくない規定である。

A及びBを二つの境界点又は位置とする。その場合，次のうちの一つが成立する。AはBの前にある，AはBと等しい，又はAはBの後にある。どれが成立するかは，四つの場合を調査することによって，次で規定される。

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

二番目の場合は，Aのコンテナの子ノードCがBの先祖コンテナである場合とする。この場合，Aのオフセットが子ノードCのインデクスよりも小さいか又は等しい場合，AはBの前にある。それ以外の場合は，AはBの後にある。

三番目の場合は，Bのコンテナの子ノードCがAの先祖コンテナである場合とする。この場合，子ノードCのインデクスがBのオフセットより小さい場合は，AはBの前にある。それ以外の場合は，AはBの後にある。

四番目の場合は，他の三つのいずれも成立しない場合とする。すなわち，A及びBのコンテナが，兄弟又は兄弟ノードの子孫である場合とする。この場合，Aのコンテナが，Rangeの文脈木の前順たどりで，Bのコンテナの前にある場合，AはBの前にある。それ以外の場合は，AはBの後にある。

文書のテキスト表現における同じ位置がDOM木では二つの異なる位置に対応可能なので，二つの境界点が，たとえテキスト表現では等しかったとしても，それらが等しいと比較されないことも可能な点に注意すること。このために，この非形式的な定義は，正しくない場合もある。

2.6 範囲を用いた内容の削除

次を用いて，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の開始の先祖コンテナであって，そのノードの先祖がこれら二つの条件を満たさない場合，Rangeは，(2)及び(4)の例のとおり，ノードの直後の位置まで縮退される。Rangeがノードを部分選択し，そのノードがRangeの終了の先祖コンテナであって，そのノードの先祖がこれら二つの条件を満たさない場合，Rangeは，(3)及び(4)の例のとおり，ノードの直前の位置まで縮退される。

Rangeの削除が隣接するTextノードを残す場合は，それらノードは自動的に併合(merge)されず，空のTextノードは自動的に削除されない点に注意すること。二つのTextノードは，それぞれが，内容が削除されたRangeの境界点の一つのコンテナになる場合に限り，併合されるのが望ましい。隣接するTextノードを併合するか，又は空のTextノードを削除するためには，Nodeインタフェースにおけるnormalize()メソッドを使用するのが望ましい。

2.7 内容の抽出

Rangeの内容が削除ではなく抽出される必要がある場合には，次のメソッドを使用してよい。

  DocumentFragment extractContents();

extractContents()メソッドは，deleteContents()メソッドと同様に，ノードをRangeの文脈木から取り除く。さらに，このメソッドは，新しい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

(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が部分選択したノードはクローン化されるという点に注意することは重要である。このようなノードの内容の一部は，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は，それが既に親をもつ場合，その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の文脈木上でのこのメソッドの影響を記述する別の方法は，他の操作によってそれを分解することである。

extractContents()への呼出しを用いて，Rangeが選択した内容を取り除く。
抽出後にRangeがinsertNode()を用いて縮退された場所にノードnewParentを挿入する。
抽出されたDocumentFragmentの内容全体をnewParentに挿入する。特に，newParent上でappendChild()を呼び出して，extractContents()への呼出しの結果として返されたDocumentFragmentを受け渡す。
selectNode()を用いて，newParent及びその内容のすべてを選択する。

Rangeが非Textノードを部分選択する場合，surroundContents()メソッドは，例外を挙げる。surroundContents()が例外を挙げるRangeの例を次に示す。

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

ノードnewParentが子どもをもつ場合，それらの子どもは，挿入前に取り除かれる。同様に，ノードnewParentが既に親をもつ場合，それは，元の親の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は，何らかの方法で修正されない場合には，無効になる。2.12では，Rangeが有効な状態を保つためには，文書変異においてRangeがどのように修正されるかを示す。

文書変異においてRangeに適用される一般的な原理は二つある。一つは，文書の中のすべてのRangeがいかなる変更操作の後でも有効な状態を保つこととし，もう一つは，すべてのRangeが，いかなる文書変異後も可能な限り文書の同じ部分を選択することとする。

Rangeに影響を与える文書木のあらゆる変異は，基本的な削除操作及び挿入操作の組合せと考えることができる。実際，これらの操作は，deleteContents()及びinsertNode()のRangeメソッドを使用して，Text変異の場合は，splitText()及びnormalize()のメソッドを使用して，実行されると考えるのが便利といえる。

2.12.1 挿入

挿入は，文書の中の単一の点である挿入点で出現する。文書木の中のあらゆるRangeについて，各境界点を考える。境界点が挿入後に変更されるのは，境界点及び挿入点が同じコンテナをもち，挿入点のオフセットがRangeの境界点のオフセットよりも厳密に小さい場合に限られる。その場合，Rangeの境界点のオフセットは，挿入前と同じノード又は文字の間にあるように，増加される。

内容が境界点で挿入される場合，その相対位置が維持されるのが望ましいときには，境界点が再配置されることが望ましい場所に関しては，あいまいになる。これには，新たに挿入された内容の開始又は終了という二つの可能性がある。この場合，境界点のコンテナもオフセットも変更されないことを(今まで)選択してきた。その結果として，境界点は，新たに挿入された内容の開始に配置されることになる。

例

Rangeが次を選択したとする。

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

次の位置でのテキスト"inserted text"の挿入を考える。

1. 'X'の前の場合

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

2. 'X'の後の場合

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

3. 'Y'の後の場合

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

4. "Y blah"の中の'h'の後の場合

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

2.12.2 削除

文書木からのあらゆる削除は，分離したRangeの最小集合に適用されるdeleteContents()操作の列として考えることができる。削除においてRangeがどのように変更されるかを規定するためには，あるRangeに対して，それとは別のRangeの単一のdeleteContents()操作の下で，何が起こるかだけを考える必要がある。実際には，両境界点は同じアルゴリズムを使用して修正されるので，Rangeの一つの境界点に何が起こるかだけを考えれる必要がある。

元のRangeの境界点が削除される内容の中にある場合，削除後，その境界点は，内容の削除に使用された(縮退された)Rangeの結果として得られる境界点の位置に存在する。

境界点が削除される内容の後にある場合，そのコンテナが削除されるRangeの一方の境界点のコンテナにもなることがないときには，削除による影響はない。このような共通のコンテナが存在する場合，境界点のインデクスは，コンテナの内容に対して相対的な位置を維持するように変更される。

境界点が削除される内容の前にある場合，削除による影響を全く受けない。

例

次の例では，deleteContents()が呼び出されるRangeを下線によって示す。

例1

操作前

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

操作後

  <P>Abcd Range ijkl</P>

例2

操作前

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

操作後

  <p>Abcd ^kl</p>

例3

操作前

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

操作後

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

この例では，削除後，開始境界点のコンテナは，文字列"ange"を保持するTextノードになる。

例4

操作前

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

操作後

  <P>Abcd he Range ijkl</P>

例5

操作前

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

操作後

  <P>Abcd ^kl</P>

2.13 Rangeインタフェースの形式記述

Rangeインタフェースの完全な形式記述を，まとめて次に示す。

インタフェース Range (DOM水準2で導入)

IDL 定義

// 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);
};

定義グループ CompareHow

パラメタとしてcompareBoundaryPointsメソッドに渡される。

定義済み定数

END_TO_END: sourceRangeの終了境界点をcompareBoundaryPointsが呼び出されるRangeの終了境界点と比較する。
END_TO_START: sourceRangeの終了境界点をcompareBoundaryPointsが呼び出されるRangeの開始境界点と比較する。
START_TO_END: sourceRangeの開始境界点をcompareBoundaryPointsが呼び出されるRangeの終了境界点と比較する。
START_TO_START: sourceRangeの開始境界点をcompareBoundaryPointsが呼び出されるRangeの開始境界点と比較する。

属性

型booleanのcollapsed，読取り専用

Rangeが縮退される場合はTRUE。

取得に関する例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

型NodeのcommonAncestorContainer，読取り専用

Rangeの二つの境界点の最も深い共通の先祖コンテナ。

取得に関する例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

型NodeのendContainer，読取り専用

その内部でRangeが終了するノード。

取得に関する例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

型longのendOffset，読取り専用

Rangeの終了ノード内でのオフセット。

取得に関する例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

型NodeのstartContainer，読取り専用

その内部でRangeが始まるノード。

取得に関する例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

型longのstartOffset，読取り専用

Rangeの開始ノード内でのオフセット。

取得に関する例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

メソッド

cloneContents

Rangeの内容を複製する。

返却値

DocumentFragment

このRangeに等価な内容を含むDocumentFragmentcontent。

例外

DOMException

HIERARCHY_REQUEST_ERR: DocumentTypeノードが新しいDocumentFragmentに抽出される場合に，挙げられる。

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

パラメタなし

cloneRange

境界点がRangeの境界点と等しい新しいRangeを作成する。

返却値

Range

複製されたRange。

例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

パラメタなし

collapse

Rangeをその境界点の一方まで縮退する。

パラメタ

型booleanのtoStart: TRUEの場合, Rangeをその開始まで縮退する。FALSEの場合，Rangeをその終了まで縮退する。

例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

返却値なし

compareBoundaryPoints

文書の中の二つのRangeの境界点を比較する。

パラメタ

型unsigned shortのhow: "定義済み定数"において定義したとおりの，比較の型を表現する符号。
型RangeのsourceRange: この現在のRangeが比較されるRange。

返却値

short

Rangeの対応する境界点がsourceRangeの対応境界点の前にある場合は-1，等しい場合は0，又は後にある場合は1とする。

例外

DOMException

WRONG_DOCUMENT_ERR: 二つのRangeが同じDocument又はDocumentFragmentの中にない場合に，挙げられる。

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

deleteContents

取り除かれる内容への参照を返すことなく，包含する文書又は文書素片から，Rangeの内容を取り除く。

例外

DOMException

NO_MODIFICATION_ALLOWED_ERR: Rangeの内容のあらゆる部分が読取り専用になっている場合，又は何らかのRangeの内容を含むあらゆるノードが読取り専用になっている場合に，挙げられる。

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

パラメタなし

返却値なし

detach

Rangeがもはや使用状態にないこと，及び実装がこのRangeに関連するあらゆる資源を解放してもよいことを示すために呼び出される。このRangeにおけるあらゆるメソッド又は属性取得子(属性を取得する専用メソッド)をその後に呼び出した場合には，INVALID_STATE_ERRのエラーコードをもつDOMExceptionが投げられる。

例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

パラメタなし

返却値なし

extractContents

Rangeの内容を，包含する文書又は文書素片から新しいDocumentFragmentへと移動する。

返却値

DocumentFragment

抽出された内容を含むDocumentFragment。

例外

DOMException

HIERARCHY_REQUEST_ERR: DocumentTypeノードが新しいDocumentFragmentに抽出される場合に，挙げられる。

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

パラメタなし

insertNode

Rangeの開始で，ノードをDocument又はDocumentFragmentに挿入する。コンテナがTextノードの場合，これは，TextノードのsplitTextメソッドが挿入点で実行されたものとして，Rangeの開始で分割され，挿入は，その結果として得られた二つのTextノード間で発生する。隣接するTextノードが，自動的に併合されることはない。挿入されるノードがDocumentFragmentノードの場合，DocumentFragmentノードそれ自体ではなく，その子どもが挿入される。

パラメタ

型NodeのnewNode: Rangeの開始で挿入するノード。

例外

DOMException

NO_MODIFICATION_ALLOWED_ERR: Rangeの開始の先祖コンテナが読取り専用の場合に，挙げられる。

WRONG_DOCUMENT_ERR: newNode，及びRangeの開始のコンテナが，同じ文書から生成されなかった場合に，挙げられる。

HIERARCHY_REQUEST_ERR: Rangeの開始のコンテナが型newNodeの子どもを許容しない型の場合，又はnewNodeがコンテナの先祖の場合に，挙げられる。

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

RangeException

INVALID_NODE_TYPE_ERR: newNodeが，Attrノード，Entityノード，Notationノード又はDocumentノードの場合に，挙げられる。

返却値なし

selectNode

ノード及びその内容を選択する。

パラメタ

型NodeのrefNode: 選択するノード。

例外

`RangeException`	INVALID_NODE_TYPE_ERR: `refNode`の先祖が，Entityノード，Notationノード若しくはDocumentTypeノードの場合，又は`refNode`が，Documentノード，DocumentFragmentノード，Attrノード，Entityノード若しくはNotationノードの場合に，挙げられる。
`DOMException`	INVALID_STATE_ERR: このオブジェクトで`detach()`が既に呼び出されている場合に，挙げられる。

返却値なし

selectNodeContents

ノード内の内容を選択する。

パラメタ

型NodeのrefNode: (内容を)それから選択するノード。

例外

`RangeException`	INVALID_NODE_TYPE_ERR: `refNode`又は`refNode`の先祖が，Entityノード，Notationノード又はDocumentTypeノードの場合に，挙げられる。
`DOMException`	INVALID_STATE_ERR: このオブジェクトで`detach()`が既に呼び出されている場合に，挙げられる。

返却値なし

setEnd

Rangeの終了を記述する属性を設定する。

パラメタ

型NodeのrefNode: refNode値。このパラメタは，nullとは異なっていなければならない。
型longのoffset: endOffset値。

例外

RangeException

INVALID_NODE_TYPE_ERR: refNode又はrefNodeの先祖が，Entityノード，Notationノード又はDocumentTypeノードの場合に，挙げられる。

DOMException

INDEX_SIZE_ERR: offsetが負か，又はrefNodeにおける子単位の数よりも大きい場合に，挙げられる。ここで，子単位とは，refNodeが(Textノード，Commentノードなどの)CharacterDataノード又はProccessingInstructionノードの型である場合には，16ビット単位とする。その他のすべての場合には，子単位は，ノードとする。

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

返却値なし

setEndAfter

Rangeの終了をノードの後とするように設定する。

パラメタ

型NodeのrefNode: Rangeは，refNode後で終了する。

例外

`RangeException`	INVALID_NODE_TYPE_ERR: `refNode`のルートコンテナが，Attrノード，Documentノード若しくはDocumentFragmentノードではない場合，又は`refNode`が，Documentノード，DocumentFragmentノード，Attrノード，Entityノード若しくはNotationノードの場合に，挙げられる。
`DOMException`	INVALID_STATE_ERR: このオブジェクトで`detach()`が既に呼び出されている場合に，挙げられる。

返却値なし

setEndBefore

終了位置をノードの前とするように設定する。

パラメタ

型NodeのrefNode: Rangeは，refNodeの前で終了する。

例外

`RangeException`	INVALID_NODE_TYPE_ERR: `refNode`のルートコンテナが，Attrノード，Documentノード若しくはDocumentFragmentノードではない場合，又は`refNode`が，Documentノード，DocumentFragmentノード，Attrノード，Entityノード若しくはNotationノードの場合に，挙げられる。
`DOMException`	INVALID_STATE_ERR: このオブジェクトで`detach()`が既に呼び出されている場合に，挙げられる。

返却値なし

setStart

範囲の開始を記述する属性を設定する。

パラメタ

型NodeのrefNode: refNode値。このパラメタは，nullとは異なっていなければならない。
型longのoffset: startOffset値。

例外

RangeException

INVALID_NODE_TYPE_ERR: refNode又はrefNodeの先祖が，Entityノード，Notationノード又はDocumentTypeノードの場合に，挙げられる。

DOMException

INDEX_SIZE_ERR: offsetが負か，又はrefNodeにおける子単位の数よりも大きい場合に，挙げられる。ここで，子単位とは，refNodeが(Textノード，Commentノードなどの)CharacterDataノード又はProcessingInstructionノードの型の場合には，16ビット単位とする。その他のすべての場合には，子単位は，Nodeとする。

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

返却値

setStartAfter

開始位置をノードの後とするように設定する。

パラメタ

Node型のrefNode: Rangeは，refNodeの後から開始する。

例外

`RangeException`	INVALID_NODE_TYPE_ERR: `refNode`のルートコンテナが，Attrノード，Documentノード若しくはDocumentFragmentノードではない場合，又は`refNode`が，Documentノード，DocumentFragmentノード，Attrノード，Entityノード若しくはNotationノードの場合に，挙げられる。
`DOMException`	INVALID_STATE_ERR: このオブジェクトで`detach()`が既に呼び出されている場合に，挙げられる。

返却値

setStartBefore

開始位置をノードの前とするように設定する。

パラメタ

型NodeのrefNode: Rangeは，refNodeの前で開始する。

例外

`RangeException`	INVALID_NODE_TYPE_ERR: `refNode`のルートコンテナが，Attrノード，Documentノード若しくはDocumentFragmentノードではない場合，又は`refNode`が，Documentノード，DocumentFragmentノード，Attrノード，Entityノード若しくはNotationノードの場合に，挙げられる。
`DOMException`	INVALID_STATE_ERR: このオブジェクトで`detach()`が既に呼び出されている場合に，挙げられる。

返却値なし

surroundContents

与えられたノードにRange内容を親として再度指定し，Rangeの開始位置でそのノードを挿入する。

パラメタ

型NodeのnewParent: 内容を囲むノード。

例外

DOMException

NO_MODIFICATION_ALLOWED_ERR: Rangeのいずれかの境界点の先祖コンテナが読取り専用の場合に，挙げられる。

WRONG_DOCUMENT_ERR: newParent，及びRangeの開始のコンテナが同じ文書から生成されていなかった場合に，挙げられる。

HIERARCHY_REQUEST_ERR: Rangeの開始のコンテナがnewParentの型の子どもを許容しない型の場合，newParentがコンテナの先祖になる場合，又はnodeがnodeの型が許容しない型の子ノードで終了する場合に，挙げられる。

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

RangeException

BAD_BOUNDARYPOINTS_ERR: Rangeが非テキストノードを部分選択する場合に，挙げられる。

INVALID_NODE_TYPE_ERR: nodeが，Attrノード，Entityノード，DocumentTypeノード，Notationノード，Documentノード又はDocumentFragmentノードの場合に，挙げられる。

返却値なし

toString

Rangeの内容を文字列として返す。この文字列は，データ文字だけを含み，マーク付けは含まない。

返却値

DOMString

Rangeの内容。

例外

DOMException

INVALID_STATE_ERR: このオブジェクトでdetach()が既に呼び出されている場合に，挙げられる。

パラメタなし

インタフェース DocumentRange (DOM水準2で導入)

IDL定義

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

メソッド

createRange

このインタフェースは，束縛固有のキャスト化メソッドを使用して，Documentインタフェースを実装するオブジェクトから取得できる。

返却値

Range

このメソッドから返されるRangeの初期状態は，その境界点の両方が対応するDocumentの最初であってあらゆる内容の前に配置されるものとする。返されるRangeは，このDocument，又はこのDocumentがownerDocumentになるDocument及びAttrsと関連付けられた内容を選択することだけに使用できる。

パラメタなし

例外なし

例外RangeException (DOM水準2で導入)

Range操作は，そのメソッド記述で指定されるとおりのRangeExceptionを投げてもよい。

IDL定義

// 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;

定義グループRangeExceptionCode

生成されるエラーの型を示す整数。

定義済み定数

BAD_BOUNDARYPOINTS_ERR: Rangeの境界点が，特定の要件を満たさない場合。
INVALID_NODE_TYPE_ERR: Rangeの境界点のコンテナが，無効な型のノード，又は無効な型の先祖をもつノードのいずれかに設定されている場合。

2. 文書オブジェクトモデル 範囲

2.1. 概要

2.2 定義及び記法

2.2.1 位置

2.2.2 選択及び部分選択

2.2.3 記法

2.3 範囲の生成

2.4 範囲の位置の変更

2.5 範囲の境界点の比較

2.6 範囲を用いた内容の削除

2.7 内容の抽出

2.8 内容のクローン化

2.9 内容の挿入

2.10 内容の周辺

2.11 その他のメンバ

2.12 文書変異における範囲の修正

2.12.1 挿入

2.12.2 削除

2.13 Rangeインタフェースの形式記述

2. 文書オブジェクトモデル範囲