XML DOM - Range オブジェクト

Range オブジェクトは、ドキュメント内の連続する範囲を表します。

Range オブジェクト

Range オブジェクトは、ユーザーがブラウザのウィンドウでマウスをドラッグして選択した範囲を表す、ドキュメントの連続する範囲区域です。

Range モジュールをサポートする実装がある場合、 Document オブジェクトは以下のように定義されています createRange()メソッドを呼び出すことで、新しいRange オブジェクトを作成できます。

注意：IEは非互換のDocument.createRange()メソッドを定義しており、そのオブジェクトはRange インターフェースに似ていますが、互換性がありません。

Range インターフェースは、指定されたドキュメントの「選択」範囲に多くの方法を定義しており、選択範囲内で切り取りや貼り付けなどの操作を行うためのいくつかのメソッドもあります。

Range インターフェースの属性は、範囲の境界ノードおよびオフセットを取得する方法を提供します。そのメソッドは、範囲の境界を設定する方法を提供します。注意していただきたいのは、範囲の境界は Document または DocumentFragment オブジェクト内のノード。範囲の境界点が定義されると、deleteContents()、extractContents()、cloneContents()、insertNode() メソッドを使用して切り取り、コピー、貼り付けの操作を実行できます。

ドキュメントを変更する挿入や削除操作が行われた場合、ドキュメントの一部を表すすべてのRange オブジェクトは変更されます（必要に応じて）、境界点が有効であり、それらが（可能な限り）同じドキュメント内容を表すようにします。

用語：範囲、境界点およびオフセット

範囲は二つの境界点を持っています。一つの開始点と一つの終了点です。各境界点はノードとそのノードのオフセットで指定されます。このノードは通常 Element ノード、Document ノードまたは Text ノードElement ノードおよびDocument ノードに対して、オフセットはその子ノードを指します。オフセットが0の場合は、境界点はそのノードの最初の子ノードの前に位置しています。オフセットが1の場合は、境界点はそのノードの最初の子ノードの後、二番目の子ノードの前に位置しています。しかし、境界ノードがText ノードの場合は、オフセットはテキスト内の二つの文字間の位置を指します。

Range オブジェクトの定数

これらの定数は、Range オブジェクトの境界ポイントをどのように比較するかを指定します。

これらは compareBoundaryPoints() メソッドの how パラメータの有効値：

定数 説明
START_TO_START 指定された範囲の開始ポイントと現在の範囲の開始ポイントを比較します。
START_TO_END 指定された範囲の開始ポイントと現在の範囲の終了ポイントを比較します。
END_TO_END 指定された範囲の終了ポイントと現在の範囲の終了ポイントを比較します。
END_TO_START 指定された範囲の終了ポイントと現在の範囲の開始ポイントを比較します。

Range オブジェクトの属性

注意：すべての属性は読み取り専用であり、これらの属性を設定することで範囲の開始ポイントと終了ポイントを変更することはできません。この点を達成するには、setEnd() メソッドと setStart() メソッドを呼び出す必要があります。

注意：detach() メソッドが呼び出された後、これらの属性に対する読み取り操作は INVALID_STATE_ERR コードが返されます。 DOMException エラー。

属性 説明
collapsed 範囲の開始ポイントと終了ポイントがドキュメントの同一位置にある場合、true になります。つまり、範囲が空であるか、折りたたまれている場合です。
commonAncestorContainer 範囲の開始ポイントと終了ポイント（それらの祖先ノード）が最も深く内側に配置されている Document ノード
endContainer 範囲の終了ポイントを含む Document ノード
endOffset endContainer 内の終了ポイントの位置
startContainer 範囲の開始ポイントを含む Document ノード
startOffset startContainer 内の開始ポイントの位置

Range オブジェクトのメソッド

注意：範囲の detach() メソッドが呼び出された場合、その後 Range オブジェクトのメソッドを呼び出すと INVALID_STATE_ERR コードが返されます。 DOMException エラー。

メソッド 説明
cloneContents() 新しい DocumentFragment オブジェクトを返します。それは、指定された範囲を表すドキュメント範囲のコピーを含んでいます。
cloneRange() 新しい Range オブジェクトを生成し、現在の Range オブジェクトと同じドキュメント範囲を表します。
collapse() この範囲を折りたたんで、境界点を重ね合わせます。
compareBoundaryPoints() 指定された範囲の境界点と現在の範囲の境界点を比較し、その順序に基づいて -1、0、または 1 を返します。比較する境界点は最初の引数で指定され、その値は前に定義された常量のいずれかである必要があります。
deleteContents() 現在の Range オブジェクトが示すドキュメント領域を削除します。
detach() 実装が現在の範囲を使用しないことを通知し、トレースを停止することができます。この範囲のこのメソッドが呼び出された場合、次に呼び出される範囲のメソッドは INVALID_STATE_ERR コードを持つエラーをスローします。 DOMException エラー。
extractContents() 現在の範囲が示すドキュメント領域を削除し、その内容を DocumentFragment オブジェクトの形式で返します。このメソッドと cloneContents() メソッドと deleteContents() メソッドの組み合わせは非常に似ています。
insertNode() 指定されたノードをドキュメント範囲の開始点に挿入します。
selectNode() この範囲の境界点を設定して、指定されたノードとそのすべての子孫ノードを含みます。
selectNodeContents() この範囲の境界点を設定して、指定されたノードのすべての子孫ノードを含みますが、指定されたノード自体を含みません。
setEnd() この範囲の終了点を指定されたノードとオフセットに設定します。
setEndAfter() この範囲の終了点を指定されたノードの直後に設定します。
setEndBefore() この範囲の終了点を指定されたノードの直前に設定します。
setStart() この範囲の開始点を指定されたノード内の指定されたオフセットに設定します。
setStartAfter() この範囲の開始点を指定されたノードの直後に設定します。
setStartBefore() この範囲の開始点を指定されたノードの直前に設定します。
surroundContents() 指定されたノードをドキュメント範囲の開始点に挿入し、範囲内のすべてのノードの親ノードを再定義して、それらを新しい挿入されたノードの子孫ノードにします。
toString() この範囲が示すドキュメント領域のテキスト内容を返します。