RangeNN 6 IE なし DOM 2

W3C DOM の Range オブジェクトは、ドキュメント内に表示されている 0 個以上のテキスト文字を表すオブジェクトであり、その概念は Internet Explorer の TextRange オブジェクトに似ています。0 文字のテキスト範囲は、2 文字の間 (つまり開始点の文字の前または終了点の文字の後) にある挿入ポイントを表します。Range オブジェクトは、範囲の開始点と終了点を含むノードへの参照と、そのノード内でのオフセットを自動的に決定します。そのため、このオブジェクトのメソッドを使用すれば、ドキュメントツリーの整合性を保ちながら、既存のコンテンツをコピーしたり、範囲のコンテンツを削除したり、新しいコンテンツを (ノードの形式で) 既存の範囲に挿入したりできます。Range オブジェクトではノード階層が重要ですが、ノード階層を扱う処理のほとんどはこのオブジェクトが自動的に行います。

 

Range オブジェクトは、document.createTextRange() メソッドを使って作成するか、または window.getSelection().getRangeAt(0) を使ってユーザーによる選択部分を範囲に変換することによって作成します。テキスト範囲を作成したら、document.createTextRange() メソッドによって開始点と終了点を調整して、目的のテキストセグメントが範囲に含まれるようにします。その後、その他の一連のメソッドから必要なものを選択し、範囲に対して処理を行います。Range オブジェクトの詳細と使用例、および Range オブジェクトと Internet Explorer の TextRange オブジェクトとの構文の違いについては、第 5 章を参照してください。

 
オブジェクト参照
 
document.createRange()
 
オブジェクト固有のプロパティ
 
collapsedcommonAncestorContainerendContainer
endOffsetstartContainerstartOffset
 
オブジェクト固有のメソッド
 
cloneContents()cloneRange()collapse()
compareBoundaryPoints()compareNode()comparePoint()
createContextualFragment()deleteContents()detach()
extractContents()insertNode()intersectsNode()
isPointInRange()selectNode()selectNodeContents()
setEnd()setEndAfter()setEndBefore()
setStart()setStartAfter()setStartBefore()
surroundContents()toString()
 
オブジェクト固有のイベントハンドラープロパティ

なし

 
collapsedNN 6 IE なし DOM 2

読み取り専用

範囲の開始点と終了点が同じで、範囲内に文字が含まれていない場合に、ブール値 true を返します。このような縮退された範囲はドキュメント内の任意の場所に配置される可能性があります。

 
 
if (rng.collapsed) {
    // act on collapsed text range
}
 

true または false のブール値

 
既定値

なし

 
commonAncestorContainerNN 6 IE なし DOM 2

読み取り専用

ドキュメントツリー内で現在の範囲の開始点と終了点を含むノードのすぐ外側にあるノードへの参照を返します。開始点と終了点が同じノード (テキストノードなど) 内にある場合、commonAncestorContainer プロパティはそのノードの親ノードへの参照を返します。Internet Explorer でこの機能を提供するのは TextRangeparentElement() です。

 
 
var containingElem = rng.commonAncestorContainer;
 

ノードオブジェクト (通常は要素ノードタイプ) への参照

 
既定値

なし

 
endContainerNN 6 IE なし DOM 2

読み取り専用

現在の範囲の終了点を含むドキュメントツリーノードへの参照を返します。

 
 
var containingElemRight = rng.endContainer;
 

ノードオブジェクトへの参照

 
既定値

なし

 
endOffsetNN 6 IE なし DOM 2

読み取り専用

endContainer プロパティから取得したノード内での終了点の文字数またはノード数を表す整数値を返します。endContainer がテキストノードの場合、endOffset プロパティはそのテキストノードの先頭文字の右側にある文字数を返します。endContainer が要素ノードの場合、endOffset プロパティは、コンテナとなるそのノードのコンテンツの先頭と終了点との間にあるノードの数を返します。

 

次の例に示したドキュメントセグメントでは、テキスト範囲を太字で示し、開始点と終了点をパイプ記号で示しています。

<>One paragraph with |pa<span> nested</spa>| element inside.</p>n
 
<p>One paragraph with |a <span>nested</span>| element inside.</p>
 

開始点はテキストノード内にありますが、終了点は span 要素の終了タグの外側にあります。この場合、Range オブジェクトのプロパティは次の表に示す値を返します。

 
プロパティ説明
commonAncestorContainer[object HTMLParagraphElement]開始点と終了点の両方が p 要素内にある。
startContainer[object Text]開始点がテキストノード内にある。
startOffset19開始点はそのコンテナであるテキストノードの先頭から 20 文字目 (0 から始まるインデックスの 19) にある。
endContainer[object HTMLParagraphElement]終了点は、span 要素の末尾として指定されているため、すぐ外側の p 要素内にある。
endOffset2終了点は endContainerp のコンテキストで 3 番目 (0 から始まるインデックスの 2) のノードにある (最初のノードはテキストノード、2 番目のノードは span 要素、3 番目のノードは p 要素であり、終了点はこの 3 番目のノードの先頭にある)。
 
 
var rngEndOff = rng.endOffset;
 

整数

 
既定値

なし

 
startContainerNN 6 IE なし DOM 2

読み取り専用

ドキュメントツリー内で現在の範囲の開始点を含むノードへの参照を返します。

 
 
var containingElemLeft = rng.startContainer;
 

ノードオブジェクトへの参照

 
既定値

なし

 
startOffsetNN 6 IE なし DOM 2

読み取り専用

startContainer プロパティから取得したノード内での開始点の文字数またはノード数を表す整数値を返します。startContainer がテキストノードの場合、startOffset プロパティはそのテキストノードの先頭文字の右側にある文字数をカウントします。startContainer が要素ノードの場合、startOffset プロパティは、コンテナとなるノードのコンテンツの先頭と開始点との間にあるノードの数を返します。詳細については、endOffset を参照してください。

 
 
var rngStartOff = rng.startOffset;
 

整数

 
既定値

なし

 
cloneContents()NN 7 IE なし DOM 2

現在の範囲のコンテンツのコピーを含む DocumentFragment ノードへの参照を返します。ぶら下がりノードはクローン作成プロセスの中で解決されます。

 
戻り値

ドキュメントフラグメントタイプのノードへの参照

 
パラメータ

なし

 
cloneRange()NN 6 IE なし DOM 2

現在の範囲のコピーとなっている Range オブジェクトを、関連するコンテナへの参照と共に返します。このメソッドにより、現在の Range オブジェクトの仕様のコピーを保持しながら、新しい Range オブジェクトを作成できます。このメソッドは Internet Explorer の TextRange オブジェクトの duplicate() メソッドに似ています。

 
戻り値

Range オブジェクトへの参照

 
パラメータ

なし

 
collapse()NN 6 IE なし DOM 2

collapse(toStartFlag)

現在の範囲を挿入ポイントまで縮退します。これにより、開始点と終了点が同じノード内に同じオフセットで存在することになります。範囲をどの位置まで縮退するかはブール値のパラメータで制御します。現在の範囲を開始点まで縮退する場合は true を、終了点まで縮退する場合は false を指定します。スクリプトによるドキュメントの処理、たとえば String.indexOf() メソッドによる文字列の次のインスタンスの検索では、範囲を終了点まで縮退し、終了点が body 要素の最後になったら、String.indexOf() による次の検索を行います。

 
戻り値

なし

 
パラメータ
 
  • toStartFlag
      範囲をどの位置まで縮退するかを制御するブール値。開始点まで縮退する場合は true を、終了点まで縮退する場合は false を指定します。
 
compareBoundaryPoints()NN 6 IE なし DOM 2

compareBoundaryPoints(compareType, sourceRangeRef)

現在の範囲の境界点を別のテキスト範囲の境界点に対する相対位置で示す整数コードを返します。最も単純なのは、それぞれの範囲の 2 つの終了点の先祖コンテナが同じ場合です。この場合、2 つの範囲の終了点のどちらを比較するかを最初のパラメータに指定します。次の表に示すように、Range オブジェクトに用意された定数を使用します。

 
比較のタイプ説明
rng.START_TO_START現在の範囲の開始点をソースの範囲の開始点と比較
rng.START_TO_END現在の範囲の開始点をソースの範囲の終了点と比較
rng.END_TO_END現在の範囲の終了点をソースの範囲の終了点と比較
rng.END_TO_START現在の範囲の終了点をソースの範囲の開始点と比較
 

このような境界点の比較では、第 1 の境界点がドキュメント内で第 2 の境界点より先に出現する場合、戻り値は -1 です。第 1 の境界点が第 2 の境界点より後に出現する場合、戻り値は 1 です。2 つの境界点が同じ位置にある場合、戻り値は 0 です。このメソッドは Internet Explorer の TextRange オブジェクトの compareEndPoints() メソッドに似ています。

 

しかし、比較する境界点の先祖コンテナノードが異なっている場合には、状況がより複雑になります。そのコンテナノード内でのオフセット値によって比較結果に違いが生じます。比較する終了点の間に多数の関係が存在すると比較結果が異なってくるため、スクリプトでは、比較によって目的の結果が得られるように、境界点について複雑な分析を行う必要があります。これに対し、境界点の一致を調べるだけの場合ははるかに単純な処理で済みます。境界点の比較で二社択一の判断になる可能性を高くするには、戻り値が 0 (またはその他なんらかの値) のみになるように、比較の対象を限定することをお勧めします。

 
戻り値

-101 のいずれかの整数

 
パラメータ
 
  • compareType
      比較タイプに対応する 03 のいずれかの整数。Netscape 6 および 7 では、整数値は W3C DOM 規格に準拠していません。ただし、標準テキストの定数 (上の表に示した rng.START_TO_START など) では正しい比較が行えます。
  • sourceRangeRef
      既に定義されている 2 番目の Range オブジェクトへの参照。通常、このオブジェクトは cloneRange() メソッドを使って保持されています。
 
compareNode()NN 6 IE なし DOM なし

compareNode(nodeReference)

Netscape 独自のメソッドです。いくつかの別のノードを現在の範囲に対する相対位置で示す整数コードを返します。Netscape の Range オブジェクトには 4 つの標準テキスト定数が用意されており、compareNode() メソッドが返す値との比較で使用できます。ただしこの戻り値は、現在の範囲からではなく、パラメータとして渡されたノードから見た値です。

 

戻り値と定数を次に示します。

 
]
定数説明
rng.NODE_BEFORE0ノード全体が範囲の前にある。
rng.NODE_AFTER1ノード全体が範囲の後ろにある。
rng.NODE_BEFORE_AND_AFTER 2ノードの先頭が現在の範囲の前にあり、ノードの末尾が現在の範囲の後ろにある。
rng.NODE_INSIDE3ノード全体が範囲の中にある。
 

 
if (rng.compareNode(document.getElementById("myElem")) == rng.NODE_INSIDE) {
    // process for myElem node being contained by the range
}
 
戻り値

0123 のいずれかの整数

 
パラメータ
 
  • nodeReference
      ドキュメントツリー内の任意のノードへの参照
 
comparePoint()NN 6 IE なし DOM なし

compareNode(nodeReference, offset)

Netscape 独自のメソッドです。いくつかの別のノードの位置とそのノード内でのオフセットを、現在の範囲に対する相対位置で示す整数コードを返します。ただしこの戻り値は、現在の範囲からではなく、パラメータとして渡されたノード (より厳密にはノード内のオフセットで指示されているポイント) から見た値です。

 

戻り値を次に示します。

 
説明
-1ポイントが範囲の開始点より前にある。
0ポイントが範囲の中にある。
1ポイントが範囲の終了点より後ろにある。
 

 
if (rng.comparePoint(document.getElementById("myElem"), 2) == 0) {
    // process for offset of 2 within myElem node being contained by the range
}
 
戻り値

-101 のいずれかの整数

 
パラメータ
 
  • nodeReference
      ドキュメントツリー内の任意のノードへの参照
  • offset
      要素内にネストされているノードの数、またはテキストノード内の文字の数を示す整数のオフセット
 
createContextualFragment()NN 6 IE なし DOM なし

createContextualFragment(contentString)

createContextualFragment() メソッドは元々、便宜的な innerHTML プロパティに代わるメソッドとして考案されました。これは、W3C DOM ではタグを含むコンテンツ文字列のサポートについてほとんど定義されていないためです。このメソッドは、タグ付きコンテンツを含め、あらゆる文字列をパラメータとして許容しており、DocumentFragment タイプのノードを返します。そのため簡単にドキュメントツリーにノードを追加および挿入できます。その後、Mozilla ブラウザで innerHTML プロパティが採用されたため、このメソッドは冗長的なメソッドとなりました。ただし、W3C DOM の全体的なノード階層との整合性は、createContextualFragment() メソッドの方が優れています。

 
戻り値

ドキュメントツリー外にあるドキュメントフラグメントタイプのノードへの参照。ドキュメントフラグメントタイプのノードをドキュメントツリーに適用できます。

 
パラメータ
 
  • contentString
      文字列形式のドキュメントコンテンツ (タグと属性を含む)
 
deleteContents()NN 6 IE なし DOM 2

ドキュメントツリーから現在のテキスト範囲のコンテンツを削除します。範囲が要素ノードである場合 (selectNode() メソッドで設定された境界点が要素ノード内にある場合など) は、範囲に対して deleteContents() を呼び出すことにより、ドキュメントツリーからノードを削除し、範囲を縮退することができます。Range オブジェクトはメモリ内に残りますが、コンテンツは残りません。削除する前にコンテンツを保持しておく場合は、cloneRange()cloneContents() を組み合わせて使用するなど、Range オブジェクトの他のメソッドを使用してください。

 
戻り値

なし

 
パラメータ

なし

 
detach()NN 6 IE なし DOM 2

現在の Range オブジェクトを破棄します。以降、このオブジェクトのメソッドを呼び出したり、このオブジェクトのプロパティにアクセスすると、INVALID_STATE_ERR タイプの RangeException が発生します。

 
戻り値

なし

 
パラメータ

なし

 
extractContents()NN 6 IE なし DOM 2

ドキュメントツリーから現在の範囲のコンテンツを削除した後、そのコンテンツを DocumentFragment ノードに移動し、そのノードへの参照を返します。selectNodeContents() メソッドで範囲の境界点を設定した場合を除き、Netscape 6.2 では機能しません。

 
戻り値

ドキュメントフラグメントタイプのノードへの参照

 
パラメータ

なし

 
insertNode()NN 6 IE なし DOM 2

insertNode(nodeReference)

現在のテキスト範囲の開始点にノードを挿入します。範囲がテキスト挿入ポイントとして縮退されている場合に便利です。挿入するノードは、document.createElement() で新たに作成するか、ドキュメントツリーの別の場所から取得します。別の場所から取得したノードは元の位置からは削除されて、現在の範囲に挿入されます。テキストノードの挿入先の隣が既存のテキストノードである場合は、この隣接する 2 つのテキストノードを連結できます。テキストノードを連結するには、親の normalize() メソッドを呼び出します。

 
戻り値

なし

 
パラメータ
 
  • nodeReference
      範囲に挿入するテキスト、要素、またはドキュメントフラグメントタイプのノードへの参照
 
intersectsNode()NN 6 IE なし DOM なし

intersectsNode(nodeReference)

現在の範囲のいずれかの部分が、パラメータとして渡されたテキストまたは要素ノードと重なっている場合に、ブール値 true を返します。スクリプトで、このような重なった部分が検出された場合に compareNode() メソッドを使用して、その部分に関する詳細な情報を取得できます。

 
戻り値

true または false のブール値

 
パラメータ
 
  • nodeReference
      ドキュメントツリー内のテキストまたは要素への参照
 
isPointInRange()NN 6 IE なし DOM なし

isPointInRange(nodeReference, offset)

パラメータ値 (ドキュメントツリー内のノードとそのノード内でのオフセット) で示された位置が現在の範囲の中にある場合、ブール値 true を返します。

 
戻り値

true または false のブール値

 
パラメータ
 
  • nodeReference
      ドキュメントツリー内のテキストまたは要素への参照
  • offset
      要素内にネストされているノードの数、またはテキストノード内の文字の数を示す整数のオフセット
 
selectNode()、selectNodeContents()NN 6 IE なし DOM 2

selectNode(nodeReference) selectNodeContents(nodeReference)

ノードまたはノードのコンテンツのみを含むように範囲の境界点を設定します。メソッドの名前に select が付いていますが、表示されるドキュメント内の body 要素のテキストはハイライト表示されません。

 

どのメソッドを選択するかによって、範囲の startContainer および endContainer プロパティの設定方法が異なります。この後の一連の例で、これらメソッドへのパラメータが要素ノードである場合とテキストノードである場合とで、範囲とそのプロパティにどのように変化があるかを確認してください。最初の HTML セグメントが次のようになっているとします。

 
<p>One paragraph with a <span id="myspan">nested</span> element inside.</p>
 

rng.selectNode(document.getElementById("myspan") メソッドで span 要素を選択し、範囲を次のように設定します。

 
<p>One paragraph with a |<span id="myspan">nested</span>| element inside.</p>
 

この場合、Range オブジェクトのプロパティは次の表に示す値を返します。

 
プロパティ説明
startContainer[object HTMLParagraphElement]開始点は span 要素の直前にある。
startOffset1開始点は p 要素内の 2 番目 (0 から始まるインデックスの 1) のノードにある。
endContainer[object HTMLParagraphElement]終了点は span 要素の直後にある。
endOffset2終了点は endContainerp 要素のコンテキストで 3 番目 (0 から始まるインデックスの 2) のノードにある。
 

rng.selectNodeContents(document.getElementById("myspan") メソッドで span 要素のコンテンツを選択し、範囲を次のように設定します。

 
<p>One paragraph with a <span id="myspan">|nested|</span> element inside.</p>
 

この場合、Range オブジェクトのプロパティは次の表に示す値を返します。

 
プロパティ説明
startContainer[object HTMLSpanElement]開始点は span 要素のすぐ内側にある。
startOffset0開始位置は span 要素内の 1 番目 (0 から始まるインデックスの 0) のノードにある。
endContainer[object HTMLSpanElement]終了点は span 要素のコンテンツの直後にある。
endOffset1終了点は endContainerspan 要素のコンテキストで 2 番目 (0 から始まるインデックスの 1) のノードにある。
 

rng.selectNode(document.getElementById("myspan").firstChild) メソッドで span 要素内のテキストノードを選択し、範囲を次のように設定します。

 
<p>One paragraph with a <span id="myspan">|nested|</span> element inside.</p>
 

パラメータとして渡されるノード (およびノードタイプ) が異なっている場合も、新しい選択された範囲は前の例と同じように表示されます。実際にはノードツリーの構造により、Range オブジェクトのプロパティは次のように同じ値を返します。

 
プロパティ説明
startContainer[object HTMLSpanElement]開始点は span 要素のすぐ内側にある。
startOffset0開始点は span 要素内の 1 番目 (0 から始まるインデックスの 0) のノードにある。
endContainer[object HTMLSpanElement]終了点は span 要素のコンテンツの直後にある。
endOffset1終了点は endContainerspan 要素のコンテキストで 2 番目 (0 から始まるインデックスの 1) のノードにある。
 

rng.selectNodeContents(document.getElementById("myspan") メソッドで span 要素内のテキストノードを選択し、範囲を次のように設定します。

 
<p>One paragraph with a <span id="myspan">||nested</span> element inside.</p>
 

つまり次に示すプロパティのように、範囲はテキストノードの開始点にある挿入ポイントまで縮退され (これは Netscape 6 のバグの可能性あり)、テキストノードはコンテナになります。

 
プロパティ説明
startContainer[object Text]開始点はテキストノードの先頭にある。
startOffset0開始点はテキストノードの 1 番目 (0 から始まるインデックスの 0) の位置にある。
endContainer[object Text]終了点が縮退されている。
endOffset0終了点が縮退されている。
 

多くの場合、いずれのメソッドでも要素ノードが最も実用的なパラメータ値となります。

 
戻り値

なし

 
パラメータ
 
  • nodeReference
      ドキュメントツリー内のテキストまたは要素への参照
 
setEnd()、setStart()NN 6 IE なし DOM 2

setEnd(nodeReference, offset) setStart(nodeReference, offset)

ドキュメントツリー内での既存の Range オブジェクトの個々の境界点の位置を設定します。このメソッドは Internet Explorer の TextRange オブジェクトの setEndPoint() メソッドに似ています。位置の指定には、ノードへの参照、および該当タイプのノード内での開始点に対するオフセット値を使用します。nodeReference が要素ノードである場合、オフセット値には子ノードがカウントされます。nodeReference がテキストノードである場合は、文字数がカウントされます。ノードの先頭と末尾に境界点を設定するには、関連するメソッド (setEndAfter() とその他 3 つのメソッド) を使用する方が便利です。

 
戻り値

なし

 
パラメータ
 
  • nodeReference
      ドキュメントツリー内の要素またはテキストノードへの参照
  • offset
      要素内にネストされているノードの数、またはテキストノード内の文字の数を示す整数のオフセット
 
setEndAfter()、setEndBefore()、setStartAfter()、setStartBefore()NN 6 IE なし DOM 2

setEndAfter(nodeReference) setEndBefore(nodeReference) setStartAfter(nodeReference) setStartBefore(nodeReference)

ドキュメントツリー内での既存の Range オブジェクトの個々の境界点の位置をノードの先頭と末尾に対する位置で設定します。これらのメソッドでは、範囲の境界を既存のノードの直前または直後に設定することが前提となっており、他の種類のオフセットは無関係です。範囲の境界点の位置は左右対称である必要はありません。ドキュメント内で、開始点をあるノードに対して指定し、終了点を後続のまったく別のノードに対して指定できます。

 
戻り値

なし

 
パラメータ
 
  • nodeReference
      ドキュメントツリー内の要素またはテキストノードへの参照
 
surroundContents()NN 7 IE なし DOM 2

surroundContents(parentNodeReference)

現在の範囲を新しいコンテナで囲みます。コンテナは通常、document.createElement() メソッドで新たに作成された要素ノードです。このメソッドを適用する前に、現在の範囲の終了点が同じ親コンテナ内にある必要があります。

 
戻り値

なし

 
パラメータ
 
  • parentNodeReference
      範囲の新しい親コンテナとなるノードへの参照
 
toString()NN 6 IE なし DOM 2

body 要素内で範囲内にあるコンテンツを文字列として返します。戻り値にタグと属性は含まれません。

 
戻り値

文字列

 
パラメータ

なし