TextRangeNN なし IE 4(Win) DOM なし

TextRange オブジェクトは、ドキュメントにある 0 個以上のテキスト文字を表すオブジェクトであり、その概念は Netscape 6 および W3C DOM のRange オブジェクトに類似しています。0 文字のテキスト範囲は、文字の間、最初の文字の前、または最後の文字の後にある挿入ポイントを表します。

 

TextRange オブジェクトは bodybuttontext、または textarea オブジェクトに関連付けられている createTextRange() メソッドによって作成されます。selection オブジェクトの createRange() (メソッド名が少し違う点に注意) を使ってユーザーの選択部分を範囲に変換することもできます。テキスト範囲を作成したら、そのメソッドを使って開始点と終了点を調整し、たとえば検索文字列に一致するテキストなどの特定のテキスト部分を範囲に指定します。適切な範囲を設定したら、範囲の htmlText プロパティと text プロパティに値を設定して、テキストの変更、削除、挿入を行います。テキストの各種編集を直接行うコマンドのライブラリを呼び出して、テキスト範囲を操作することもできます。TextRange オブジェクトの詳細と使用例については、第 5 章を参照してください。

 

{章の冒頭のリストに示している共通のプロパティとメソッドは次のとおりです。offsetLeftoffsetTopgetBoundingClientRect()getClientRects()、および scrollIntoView() がオブジェクト間で共用されます。TextRange オブジェクトとそのすべての関連機能は、Win32 版 IE のみで使用できます。

 
オブジェクト参照
 
objectRef.createTextRange()
selectionObjectRef.createRange()
 
オブジェクト固有のプロパティ
 
 
boundingHeightboundingLeftboundingTopboundingWidth
htmlTexttext
 
オブジェクト固有のメソッド
 
collapse()compareEndPoints()duplicate()
execCommand()expand()findText()
getBookmark()inRange()isEqual()
move()moveEnd()moveStart()
moveToBookmark()moveToElementText()moveToPoint()
parentElement()pasteHTML()queryCommandEnabled()
queryCommandIndeterm()queryCommandState()queryCommandSupported()
queryCommandText()queryCommandValue()select()
setEndPoint()
 
boundingHeight、boundingWidthNN なし IE 4(Win) DOM なし

読み取り専用

TextRange オブジェクトが占める仮定領域のサイズをピクセル数で返します。スクリプトがこのオブジェクトを選択しなければドキュメントには TextRange オブジェクトが表示されませんが、TextRange オブジェクトの領域は選択部分のハイライトが占める領域と同じです。これらの値は、テキスト範囲の幅の一番広い部分と高さの一番高い部分に合わせて適宜調整されます。getBoundingClientRect() メソッドから返された値に対して計算を行うと、これと同じ値が得られます。

 
 
var rangeWidth = document.forms[0].myTextArea.createTextRange().boundingWidth;
 

整数

 
既定値

なし

 
boundingLeft、boundingTopNN なし IE 4(Win) DOM なし

読み取り専用

ブラウザウィンドウやフレームの左端または上端から TextRange オブジェクトが占める仮定領域の左端または上端までの距離をピクセル数で返します。スクリプトがこのオブジェクトを選択しなければドキュメントには TextRange オブジェクトが表示されませんが、TextRange オブジェクトの領域は選択部分のハイライトが占める領域と同じです。これらのプロパティの値は、ドキュメントの上端や左端ではなく、固定されたウィンドウまたはフレームの端から計測されます。これは、ドキュメントの端はスクロールによって表示されなくなる可能性があり、その場合にはプロパティ値が変わってしまうためです。

 
 
var rangeOffH = document.forms[0].myTextArea.createTextRange().boundingLeft;
 

整数

 
既定値

なし

 
htmlTextNN なし IE 4(Win) DOM なし

読み取り専用

TextRange オブジェクトのベースとして使用される特定の要素に関して、そのドキュメントにあるすべての HTML を示します。たとえば body 要素に TextRange を作成 (document.body.createTextRange() を使用) した場合、htmlText プロパティには body 要素タグの間にあるすべての HTML コンテンツ (タグ自体は除きます) が設定されます。

 
 
var rangeHTML = document.body.createTextRange().htmlText;
 

文字列

 
既定値

なし

 
textNN なし IE 4(Win) DOM なし

読み書き

テキスト範囲に含まれているテキストを示します。body 要素の TextRange オブジェクトの場合、このプロパティには表示されるテキストのみが設定され、その中に HTML タグは含まれません。

 
 
var rangeText = document.body.createTextRange().text;
 

文字列

 
既定値

なし

 
collapse()NN なし IE 4(Win) DOM なし

collapse([start])

TextRange オブジェクトの長さを 0 に戻し、元のテキスト範囲の開始点または終了点に挿入ポイントを作成します。

 
戻り値

なし

 
パラメータ
 
  • start
      挿入ポイントを元の範囲の開始点に作成する (true) か、終了点に作成する (false) かを制御するブール値。この値は省略可能です。既定値は true です。
 
compareEndPoints()NN なし IE 4(Win) DOM なし

compareEndPoints("type", comparisonRange)

現在のテキスト範囲と既に変数に保存されているテキスト範囲の、開始点と終了点の相対的な位置を比較します。最初のパラメータは各範囲に対して開始点と終了点のどちらを比較するかを指定します。テキスト範囲で最初の比較点の方が先にある場合、-1 が返されます。2 つの比較点が同じ位置にある場合、0 が返されます。最初の比較点の方が後にある場合、1 が返されます。たとえば、まず最初のテキスト範囲を r1 という変数に保存し、その後 r2 という新しい範囲を作成した場合、r2 の終了点と r1 の開始点との相対位置関係を調べるには、次のようなステートメントを使用します。

 
r1.compareEndPoints("EndToStart", r2)
 

r1r2 の開始点で終了している (2 文字の間に挿入ポイントがある) 場合、戻り値は 0 になります。

 
戻り値

-101 のいずれか

 
パラメータ
 
  • type
      StartToEndStartToStartEndToStartEndToEnd のいずれかの定数を示す文字列
  • comparisonRange
      以前に作成され、既に変数に保存されている TextRange オブジェクト
 
duplicate()NN なし IE 4(Win) DOM なし

現在の範囲と同じ値を持つ新しい TextRange オブジェクトを作成します。新しいオブジェクトは元のオブジェクトに依存しません (2 つのオブジェクトは等しくありません) が、これらのオブジェクトに変更を加えるまでは、まったく同じ値を持ちます。

 
戻り値

TextRange オブジェクト

 
パラメータ

なし

 
execCommand()NN なし IE 4(Win) DOM なし

execCommand("commandName"[, UIFlag[, value]])

指定されたコマンドを現在の TextRange オブジェクトに対して実行します。多くのコマンドは、TextRange オブジェクトが挿入ポイントである場合に最良の結果が得られます。コマンドのリストについては、付録 D を参照してください。

 
戻り値

ブール値。コマンドが成功した場合は true、失敗した場合は false が返されます。

 
パラメータ
 
  • commandName
      コマンド名を示す文字列。大文字と小文字は区別されません。付録 D を参照してください。
  • UIFlag
      省略可能なブール値。コマンドで生成されたユーザーインターフェイスを表示する場合は true、表示しない場合は false を指定します。
  • value
      コマンドのパラメータ値
 
expand()NN なし IE 4(Win) DOM なし

expand("unit")

現在のテキスト範囲 (縮退された範囲を含む) にパラメータで指定されたテキスト単位が収まるように範囲を拡張します。たとえば、ドキュメントで一部の文字が選択された場合、次のように範囲を作成し、これを選択された文字のある文全体に拡張することができます。

 
var rng = document.selection.createRange();
rng.expand("sentence");
 

元のテキスト範囲が複数のユニットをカバーしている場合、expand() メソッドは次の一番近い単位まで範囲を拡張します。

 
戻り値

ブール値。メソッドが成功した場合は true、失敗した場合は false が返されます。

 
パラメータ
 
  • unit
      拡張する単位を示す characterwordsentencetextedit のいずれかの文字列。大文字と小文字は区別されません。textedit を指定すると、元の範囲全体に拡張されます。
 
findText()NN なし IE 4(Win) DOM なし

findText("string"[, searchScope][, flags])

現在の TextRange オブジェクトで、1 番目の必{のパラメータで指定された文字列を検索します。デフォルトでは、検索時に大文字と小文字は区別されません。文字列が見つかった場合、TextRange オブジェクトにそのテキストが収まるようにオブジェクトの開始点と終了点が調整されます。ドキュメント内で検索を続けるには、collapse() を使ってテキスト範囲の開始点を検索された文字列の終了点に変更する必要があります。

 

省略可能なパラメータを指定することにより、開始点以降の文字数を指定して検索の対象範囲を絞り込んだり、一部の単語またはすべての単語などのように、一致条件を追加することができます。

 
戻り値

ブール値。一致する文字列が見つかった場合は true、見つからない場合は false が返されます。

 
パラメータ
 
  • string
      検索条件となる文字列。大文字と小文字は区別されません。
  • searchScope
      検索する文字数を範囲の開始点からの相対位置で示す整数。正の数を指定すると、下方を検索します。負の数を指定すると、上方 (ドキュメントのテキスト範囲の開始点より前) を検索します。
  • flags
      0 (部分一致)、1 (後方一致)、2 (単語一致)、4 (大小文字一致) のいずれかの詳細な検索条件を示す整数
 
getBookmark()、moveToBookmark()NN なし IE 4(Win) DOM なし

getBookmark() moveToBookmark(bookmarkString)

この 2 つのメソッドは、テキスト範囲を一時的に保存し、後で必要に応じて取得するために一緒に使用します。getBookmark() メソッドは、人間には解読できないバイナリデータを含んだマシン用の文字列を返します。この値が変数に保存されたら、必要に応じてテキスト範囲を変更できます。その後でブックマークに保存したテキスト範囲を取得するには、次のように moveToBookmark() メソッドを使用します。

 
var rangeMark = myRange.getBookmark();
...
myRange.moveToBookmark(rangeMark);
 
戻り値

ブール値。操作が成功した場合は true、失敗した場合は false が返されます。

 
パラメータ
 
  • bookmarkString
      getBookmark() メソッドによって返されたマシン用の文字列
 
inRange()NN なし IE 4(Win) DOM なし

inRange(comparisonRange)

パラメータで指定した範囲が現在のテキスト範囲内と物理的に等しいか、またはそれより小さいかを調べます。

 
戻り値

ブール値。比較範囲が現在の範囲と等しいかそれ以下の場合は true、現在の範囲を越えている場合は false が返されます。

 
パラメータ
 
  • comparisonRange
      以前に作成され、既に変数に保存されている TextRange オブジェクト
 
isEqual()NN なし IE 4(Win) DOM なし

isEqual(comparisonRange)

パラメータで指定した範囲が現在のテキスト範囲と等しいかどうかを調べます。

 
戻り値

ブール値。指定範囲が現在の範囲と等しい場合は true、等しくない場合は false が返されます。

 
パラメータ
 
  • comparisonRange
      以前に作成され、既に変数に保存されている TextRange オブジェクト
 
move()NN なし IE 4(Win) DOM なし

move("unit"[, count])

現在のテキスト範囲の長さを 0 にして、その終了点に挿入ポイントを作成し、作成した挿入ポイントを現在の位置から指定の単位だけ前または後に移動します。

 
戻り値

移動した単位数を示す整数

 
パラメータ
 
  • unit
      移動に使用する単位を示す characterwordsentencetextedit のいずれかの文字列。大文字と小文字は区別されません。textedit を指定した場合、挿入ポイントを元の範囲全体の開始点または終了点に移動します。
  • count
      挿入ポイントを移動する単位数を整数値で指定します。このパラメータは省略可能です。正の値を指定すると挿入ポイントが先に進み、負の値を指定すると後に戻ります。既定値は 1 です。
 
moveEnd()、moveStart()NN なし IE 4(Win) DOM なし

moveEnd("unit"[, count]) moveStart("unit"[, count])

現在のテキスト範囲の終了点または開始点のみを、特定の単位数だけ移動します。省略可能なパラメータで移動する単位数と方向を指定できます。テキスト範囲の開始点を元の範囲の開始点の方向に移動するには、負の値を指定してください。単語 (word) を単位として終了点を右へ移動する場合、単語の終わりは空白スペース (ピリオドも含む) である点に注意してください。したがって、findText() メソッドで検索された文字列に範囲を設定する場合、その文字列が空白スペースで終わっていないと、最初に呼び出された moveEnd("word") メソッドは終了点をその単語のすぐ後ではなく、単語の後のスペースの後に移動します。

 
戻り値

移動した単位数を示す整数

 
パラメータ
 
  • unit
      移動に使用する単位を示す characterwordsentencetextedit のいずれかの文字列。大文字と小文字は区別されません。textedit を指定した場合、挿入ポイントを元の範囲全体の開始点または終了点に移動します。
  • count
      挿入ポイントを移動する単位数を整数値で指定します。このパラメータは省略可能です。正の値を指定すると挿入ポイントが先に進み、負の値を指定すると後に戻ります。既定値は 1 です。
 
moveToBookmark()

getBookmark() を参照してください。

 
moveToElementText()NN なし IE 4(Win) DOM なし

moveToElementText(elementObject)

現在の TextRange オブジェクトの開始点と終了点を、指定された HTML 要素オブジェクトが収まる位置に移動します。この結果のテキスト範囲には、その要素の HTML も含まれます。

 
戻り値

なし

 
パラメータ
 
  • elementObject
      オブジェクトへのスクリプトによる参照これには、(document.getElementById("elementID") のような直接の参照か、同様の参照を含む変数を指定できます。
 
moveToPoint()NN なし IE 4(Win) DOM なし

moveToPoint(xy)

テキスト範囲を挿入ポイントにして、ブラウザウィンドウやフレーム内の、指定された X 座標と Y 座標の位置に移動します。これは、ユーザーがウィンドウ内をクリックして挿入ポイントを定義するのと同じ効果があります。expand() などのメソッドを使ってテキスト範囲を拡大し、文字、単語、文、またはテキスト範囲全体を含めることができます。

 
戻り値

なし

 
パラメータ
 
  • x
      挿入ポイントの横方向の位置を、ウィンドウまたはフレームの左端からのピクセル数で指定します。
  • y
      挿入ポイントの縦方向の位置を、ウィンドウまたはフレームの上端からのピクセル数で指定します。
 
parentElement()NN なし IE 4(Win) DOM なし

TextRange オブジェクトを完全に含んでいる、すぐ外にある要素オブジェクトへの参照を返します。

 
戻り値

要素オブジェクトへの参照

 
パラメータ

なし

 
pasteHTML()NN なし IE 4(Win) DOM なし

pasteHTML("HTMLText")

現在のテキスト範囲を、パラメータ文字列で指定された HTML コンテンツで置換します。通常、このメソッドは、挿入ポイントとして機能している長さが 0 のテキスト範囲オブジェクトに対して使用します。タグはすべて、元のソースコードの一部であったかのように表示されます。

 
戻り値

なし

 
パラメータ
 
  • HTMLText
      ドキュメントに挿入するドキュメントソースコード
 
queryCommandEnabled()NN なし IE 4(Win) DOM なし

queryCommandEnabled("commandName")

ドキュメントや選択部分の現在のステートに対してコマンドが呼び出し可能かどうかを示します。

 
戻り値

ブール値。呼び出し可能な場合は true、不可能な場合は false です。

 
パラメータ
 
  • commandName
      コマンド名を示す文字列。大文字と小文字は区別されません。付録 D を参照してください。
 
queryCommandIndeterm()NN なし IE 4(Win) DOM なし

queryCommandIndeterm("commandName")

コマンドが indeterminate ステートかどうかを示します。

 
戻り値

true または false のブール値

 
パラメータ
 
  • commandName
      コマンド名を示す文字列。大文字と小文字は区別されません。付録 D を参照してください。
 
queryCommandState()NN なし IE 4(Win) DOM なし

queryCommandState("commandName")

指定されたコマンドの現在のステートを調べます。

 
戻り値

コマンドが完了している場合は true、完了していない場合は false、ステートが不明の場合は null です。

 
パラメータ
 
  • commandName
      コマンド名を示す文字列。大文字と小文字は区別されません。付録 D を参照してください。
 
queryCommandSupported()NN なし IE 4(Win) DOM なし

queryCommandSupported("commandName")

指定のコマンドがこのドキュメントオブジェクトによってサポートされるかどうかを調べます。

 
戻り値

true または false のブール値

 
パラメータ
 
  • commandName
      コマンド名を示す文字列。大文字と小文字は区別されません。付録 D を参照してください。
 
queryCommandText()NN なし IE 4(Win) DOM なし

queryCommandText("commandName")

コマンドに関連付けられているテキストを返します。

 
戻り値

文字列

 
パラメータ
 
  • commandName
      コマンド名を示す文字列。大文字と小文字は区別されません。付録 D を参照してください。
 
queryCommandValue()NN なし IE 4(Win) DOM なし

queryCommandValue("commandName")

選択部分のフォントなど、コマンドに関連付けられている値を返します。

 
戻り値

コマンドによって異なります。

 
パラメータ
 
  • commandName
      コマンド名を示す文字列。大文字と小文字は区別されません。付録 D を参照してください。
 
select()NN なし IE 4(Win) DOM なし

現在の TextRange オブジェクトに含まれているすべてのテキストを選択します。このメソッドによって、スクリプトが特定のテキストブロックを認識したことをユーザーが確認できます。たとえば、findText() メソッドを使用して検索スクリプトを作成する場合、scrollIntoView() メソッドと select() メソッドをその範囲に対して実行し、一致したテキストの場所をユーザーに通知することができます。

 
戻り値

なし

 
パラメータ

なし

 
setEndPoint()NN なし IE 4(Win) DOM なし

setEndPoint("type", comparisonRange)

現在の TextRange オブジェクトの終了点を、既に変数参照として保存されている別の範囲の終了点に設定します。

 
戻り値

なし

 
パラメータ
 
  • type
      StartToEndStartToStartEndToStartEndToEnd のいずれかの定数を示す文字列
  • comparisonRange
      以前に作成され、既に変数に保存されている TextRange オブジェクト