テキスト・フィールド選択 API
4.10.20 テキスト・フィールド選択 API
input と textarea 要素は、その選択状態を扱う DOM インタフェースにおいて、次のメンバーを定義します:
void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; attribute DOMString selectionDirection; void setSelectionRange(in unsigned long start, in unsigned long end, in optional DOMString direction);
これらのメソッドと属性から、input と textarea のテキスト・フィールドの選択状態にアクセスしたり制御することができます。
- element .
select() -
テキスト・フィールドのすべてを選択状態にします。
- element .
selectionStart[ = value ] -
選択開始位置のオフセットを返します。
値をセットすれば、選択開始位置を変更することができます。
- element .
selectionEnd[ = value ] -
選択終了位置のオフセットを返します。
値をセットすれば、選択終了位置を変更することができます。
- element .
selectionDirection[ = value ] -
現在の選択方向を返します。
値をセットすれば、選択方向を変更することができます。
指定可能な値は、"
forward", "backward", "none" です。 - element .
setSelectionRange(start, end [, direction] ) -
指定の部分文字列を指定方向に選択した状態にします。選択方向が省略されたら、プラットフォームのデフォルト(none または forward)にリセットされます。
これらのメソッドと属性が input 要素で使われたにも関わらず適用されなかったときは INVALID_STATE_ERR 例外を発出しなければいけません。そうでなければ、後述の通りに動作しなければいけません。
input 要素では、これらのメソッドと属性は、その要素の値に作用しなければいけません。textarea 要素では、これらのメソッドと属性は、その要素の生データ値に作用しなければいけません。
可能な場合は、input と textarea 要素におけるテキスト選択の変更に関するユーザー・インタフェース機能は、本セクションで説明されている DOM API の観点で実装されなければいけません。例えば、すべて同じイベントが発出されるなどです。
input と textarea 要素の選択状態は direction を持ちます。これは forward, backward, none のいずれかになります。この方向は、ユーザーが選択状態を操作したときにセットされます。選択方向の正確な意味は、プラットフォームに依存します。
Windows では、この方向は、選択範囲から見たキャレットの位置を指します。前方選択(forward)は、選択範囲の最後尾にキャレットを持ち、後方選択(backward)は選択範囲の開始位置にキャレットを持ちます。Windows には none という方向はありません。Mac では、この方向は、ユーザーが Shift 修飾キーと一緒に矢印キーを使って選択範囲のサイズを調整したときに、選択範囲のどちらの端が影響を受けたかを指します。前方選択(forward)は選択範囲の最後尾が変更されたことを意味し、後方選択(backward)は選択範囲の開始位置が変更されたことを意味します。Mac では、none という方向がデフォルトです。これは、特に方向がまだ選択されていないことを表します。ユーザーが選択範囲を初めて調整するときに暗黙的に方向がセットされるわけですが、それは、どの方向の矢印キーが使われたかに基づきます。
select() メソッドは、テキスト・フィールのコンテンツが完全に選択されるようにしなければいけません。そのプラットフォームが方向 none の選択をサポートしているなら選択方向は none です。そうでなければ forward です。ユーザーエージェントは、タスク・ソースとしてユーザー・インタラクション・タスク・ソースを使って、その要素で、select という名前の、バブリングするシンプルなイベントを発出するタスクをキューイングしなければいけません。
selectionStart 属性は、取得時においては、選択範囲の開始位置の直後の文字へのオフセット(論理順)を返さなければいけません。選択範囲がなければ、テキスト入力カーソルの直後の文字へのオフセット(論理順)を返さなければいけません。
セット時においては、setSelectionRange() メソッドを呼び出したかのように作用しなければいけません。第一引数には新たな値が与えられたものとします。第二引数には selectionEnd の現在値が与えられたものとします。ただし、selectionEnd 属性の現在値が新しい値より小さくない場合に限ります。そうでなければ、その第二引数も新しい値にしなければいけません。そして、第三に引数には、selectionDirection の現在値が与えられたものとします。
selectionEnd 属性は、取得時においては、選択範囲の最後尾の直後の文字へのオフセット(論理順)を返さなければいけません。選択範囲がなければ、テキスト入力カーソルの直後の文字へのオフセット(論理順)を返さなければいけません。
セット時においては、setSelectionRange() メソッドを呼び出したかのように作用しなければいけません。第一引数には selectionStart 属性の現在値が、第二引数には新しい値が、第三引数には selectionDirection の現在値が与えられたものとします。
selectionDirection 属性は、現在の選択範囲の方向に対応する文字列を返さなければいけません。その方向が forward なら "forward"、backward なら "backward"、そうでなければ "none" です。
セット時においては、setSelectionRange() メソッドを呼び出したかのように作用しなければいけません。第一引数には selectionStart 属性の現在値を、第二引数には selectionEnd 属性の値が、第三引数には新しい値が与えられたものとします。
setSelectionRange(start, end, direction) メソッドは、テキスト・フィールドの選択範囲を、start 番目の位置(論理順)の文字で始まり、(end-1) 番目の位置の文字で終わる範囲にセットしなければいけません。テキスト・フィールドの値の長さより大きい引数は、そのテキスト・フィールドの最後尾が指定されたとして扱われなければいけません。もし、選択範囲の end が start より小さいか等しいなら、その選択範囲の開始位置と終了位置は、いずれも、オフセット end となる文字の直前に置かれなければいけません。選択範囲が空という概念がないユーザーエージェントにおいては、オフセット end の文字の直前にカーソルをセットしなければいけません。選択範囲の方向は、direction が文字列 "backward" に大文字・小文字を区別して一致するなら backward にセットされなければいけません。direction が文字列 "forward" に大文字・小文字を区別して一致するなら、または、プラットフォームが方向 none の選択をサポートしていないなら、forward にセットされなければいけません。そうでなければ none にセットされなければいけません(この引数が省略された場合も含む)。ユーザーエージェントは、タスク・ソースとしてユーザー・インタラクション・タスク・ソースを使って、その要素で、select という名前の、バブリングするシンプルなイベントを発出するタスクをキューイングしなければいけません。
この API が適用されるすべての要素は、常に選択範囲もしくはテキスト入力カーソル位置を持ちます(たとえ、レンダリングされていない要素だとしてもです)。ユーザーエージェントは、初期状態を決定するために、プラットフォームの関連に従うべきです。
U+200D ZERO WIDTH JOINER といったレンダリングされずに表示されない文字は、文字としてカウントされます。ゆえに、例えば、選択状態は、表示されない文字のみを含むことがあります。そして、そのテキスト挿入カーソルは、そういった文字の前後どちらかに置かれます。
現在の選択テキストを取得するには、次の JavaScript で事足ります:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
テキストの選択状態を維持したまま、テキスト・コントロールの最初にテキストを追加するには、3 つの属性を維持しなければいけません:
var oldStart = control.selectionStart; var oldEnd = control.selectionEnd; var oldDirection = control.selectionDirection; var prefix = "http://"; control.value = prefix + control.value; control.setSelectionRange(oldStart + prefix.length, oldEnd + prefix.length, oldDirection);