テキストフィールド選択 API

4.10.20 テキストフィールド選択 API

inputtextarea 要素は、その選択状態を扱う DOM インタフェースに次のメンバーを定義します:

  void select();
           attribute unsigned long selectionStart;
           attribute unsigned long selectionEnd;
           attribute DOMString selectionDirection;
  void setRangeText(DOMString replacement);
  void setRangeText(DOMString replacement, unsigned long start, unsigned long end, optional SelectionMode selectionMode = "preserve");
  void setSelectionRange(unsigned long start, unsigned long end, optional DOMString direction = "preserve");

setRangeText メソッドは次の列挙を使います:

enum SelectionMode {
  "select",
  "start",
  "end",
  "preserve" // デフォルト
};

これらのメソッドと属性から、inputtextarea のテキストフィールドの選択状態にアクセスしたり制御したりすることができます。

element . select()

テキストフィールドのすべてを選択状態にします。

element . selectionStart [ = value ]

選択開始位置のオフセットを返します。

値をセットすれば、選択開始位置を変更することができます。

element . selectionEnd [ = value ]

選択終了位置のオフセットを返します。

値をセットすれば、選択終了位置を変更することができます。

element . selectionDirection [ = value ]

現在の選択方向を返します。

値をセットすれば、選択方向を変更することができます。

指定可能な値は、"forward", "backward", "none" です。

element . setSelectionRange(start, end [, direction] )

指定の部分文字列を指定方向に選択した状態にします。選択方向が省略されたら、プラットフォームのデフォルト(none または forward)にリセットされます。

element . setRangeText(replacement [, start, end [, selectionMode ] ] )

テキストの範囲を新たなテキストで置き換えます。startend 引数が指定されなければ、その範囲は選択状態のものとみなされます。

最後の引数は、テキストが置き換えられた後に選択状態をどうするべきかを決定します。指定可能な値は次のとおりです:

"select"
新たに挿入されたテキストを選択状態にします。
"start"
挿入されたテキストの直前に選択位置を移動します。
"end"
選択されたテキストの直後に選択位置を移動します。
"preserve"
選択状態の維持を試みます。これがデフォルトです。

input 要素に対して、これらのメソッドが呼ばれたにも関わらず適用されなかったとき、そして、これらの属性の取得またはセットが適用されなかったとき、 InvalidStateError 例外を投げなければいけません。そうでなければ、後述の通りに動作しなければいけません。

input 要素では、これらのメソッドと属性は、その要素のに作用しなければいけません。textarea 要素では、これらのメソッドと属性は、その要素の生データ値に作用しなければいけません。

可能な場合は、inputtextarea 要素におけるテキスト選択の変更に関するユーザーインタフェース機能は、本セクションで説明されている DOM API の観点で実装されなければいけません。例えば、すべて同じイベントが発出されるなどです。

inputtextarea 要素の選択状態は direction を持ちます。これは forward, backward, none のいずれかになります。この方向は、ユーザーが選択状態を操作したときにセットされます。選択方向の正確な意味は、プラットフォームに依存します。

Windows では、この方向は、選択範囲から見たキャレットの位置を指します。前方選択(forward)は、選択範囲の最後尾にキャレットを持ち、後方選択(backward)は選択範囲の開始位置にキャレットを持ちます。Windows には none という方向はありません。Mac では、この方向は、ユーザーが Shift 修飾キーと一緒に矢印キーを使って選択範囲のサイズを調整したときに、選択範囲のどちらの端が影響を受けたかを指します。前方選択(forward)は選択範囲の最後尾が変更されたことを意味し、後方選択(backward)は選択範囲の開始位置が変更されたことを意味します。Mac では、none という方向がデフォルトです。これは、特に方向がまだ選択されていないことを表します。ユーザーが選択範囲を初めて調整するときに暗黙的に方向がセットされるわけですが、それは、どの方向の矢印キーが使われたかに基づきます。

select() メソッドは、テキストフィールドのコンテンツが完全に選択されるようにしなければいけません。そのプラットフォームが方向 none の選択をサポートしているなら、選択方向は none です。そうでなければ forward です。ユーザーエージェントは、タスクソースとしてユーザーインタラクション・タスクソースを使って、その要素で、select という名前の、バブリングするシンプルなイベントを発出するタスクをキューイングしなければいけません。

selectionStart 属性は、取得時においては、選択範囲の開始位置の直後の文字へのオフセット(論理順)を返さなければいけません。選択範囲がなければ、テキスト入力カーソルの直後の文字へのオフセット(論理順)を返さなければいけません。

セット時においては、setSelectionRange() メソッドを呼び出したかのように作用しなければいけません。第 1 引数には新たな値が与えられたものとします。第 2 引数には selectionEnd の現在値が与えられたものとします。ただし、selectionEnd 属性の現在値が新しい値より小さくない場合に限ります。そうでなければ、その第 2 引数も新しい値にしなければいけません。そして、第 3 に引数には、selectionDirection の現在値が与えられたものとします。

selectionEnd 属性は、取得時においては、選択範囲の最後尾の直後の文字へのオフセット(論理順)を返さなければいけません。選択範囲がなければ、テキスト入力カーソルの直後の文字へのオフセット(論理順)を返さなければいけません。

セット時においては、setSelectionRange() メソッドを呼び出したかのように作用しなければいけません。第 1 引数には selectionStart 属性の現在値が、第 2 引数には新しい値が、第 3 引数には selectionDirection の現在値が与えられたものとします。

selectionDirection 属性は、取得時においては、現在の選択範囲の方向に対応する文字列を返さなければいけません。その方向が forward なら "forward"、backward なら "backward"、そうでなければ "none" です。

セット時においては、setSelectionRange() メソッドを呼び出したかのように作用しなければいけません。第 1 引数には selectionStart 属性の現在値が、第 2 引数には selectionEnd の現在値が、第 3 引数には新しい値が与えられたものとします。

setSelectionRange(start, end, direction) メソッドは、テキストフィールドの選択範囲を、start 番目の位置(論理順)の文字で始まり、(end-1) 番目の位置の文字で終わる範囲にセットしなければいけません。テキストフィールドの値の長さより大きい引数は、そのテキストフィールドの最後尾が指定されたとして扱われなければいけません。もし、選択範囲の endstart より小さいか等しいなら、その選択範囲の開始位置と終了位置は、いずれも、オフセット end となる文字の直前に置かれなければいけません。選択範囲が空という概念がないユーザーエージェントにおいては、オフセット end の文字の直前にカーソルをセットしなければいけません。選択範囲の方向は、direction が文字列 "backward" に大文字と小文字を区別して一致するなら backward にセットされなければいけません。direction が文字列 "forward" に大文字と小文字を区別して一致するなら、または、プラットフォームが方向 none の選択をサポートしていないなら、forward にセットされなければいけません。そうでなければ none にセットされなければいけません(この引数が省略された場合も含む)。

ユーザーエージェントは、タスクソースとしてユーザーインタラクション・タスクソースを使って、その要素で、select という名前の、バブリングするシンプルなイベントを発出するタスクをキューイングしなければいけません。

setRangeText(replacement, start, end, selectMode) メソッドは、次の手順を実行しなければいけません:

  1. このメソッドが 1 つしか引数を持たないなら、startend は、それぞれ、selectionStart 属性と selectionEnd 属性の値とします。

    そうでなければ、startend は、それぞれ、第 2 と第 3 引数の値とします。

  2. startend より大きければ、IndexSizeError 例外を投げて、これらの手順を中止します。

  3. start がテキストフィールドの値の長さより大きければ、それを、そのテキストフィールドの値の長さにセットします。

  4. end がテキストフィールドの長さより大きければ、それを、そのテキストフィールドの値の長さにセットします。

  5. selection start を、selectionStart 属性の現在値とします。

  6. selection end を、selectionEnd 属性の現在値とします。

  7. startend より小さいなら、start 番目の位置(論理順)の文字で始まり、(end-1) 番目の位置の文字で終わる文字列を削除します。

  8. テキストフィールドの値のテキストに第 1 引数の値を挿入します。挿入位置は start 番目の文字の直前です。

  9. new length を、第 1 引数の値の長さとします。

  10. new end を、startnew length の和とします。

  11. 次のリストの副手順のうち適切な組を実行します:

    第 4 引数の値が "select" の場合

    selection start を、start とします。

    selection end を、new end とします。

    第 4 引数の値が "start" の場合

    selection startselection end を、start とします。

    第 4 引数の値が "end" の場合

    selection startselection end を、new end とします。

    第 4 引数の値が "preserve" (デフォルト) の場合
    1. old lengthend - start とします。

    2. deltanew length - old length とします。

    3. selection startend より大きければ、それを delta でインクリメントします。(delta が負なら、つまり、新たなテキストが古いテキストより短いなら、これは selection start の値を減らすことになります。)

      そうでない場合:selection startstart より大きければ、それを start にセットします。(This snaps the start of the selection to the start of the new text if it was in the middle of the text that it replaced.)

    4. selection endend より大きければ、同じようにそれを delta でインクリメントします。

      そうでない場合:selection endstart より大きければ、それを new end にセットします。 (This snaps the end of the selection to the end of the new text if it was in the middle of the text that it replaced.)

  12. テキストフィールドの選択範囲を、selection start 番目の位置(論理順)の文字で始まり、(selection end-1) 番目の位置の文字で終わる文字列にセットします。空の選択範囲という概念を持たない UA においては、これは、オフセット end の文字の直前にカーソルをセットしなければいけません。選択範囲の方向は、プラットフォームが方向 none となる選択をサポートしていないなら、forward にセットされなければいけません。そうでなければ none です。

  13. タスクソースとしてユーザーインタラクション・タスクソースを使って、該当の要素で select という名前のバブリングするシンプルなイベントを発出するタスクをキューイングします。

この API が適用されるすべての要素は、常に選択範囲もしくはテキスト入力カーソル位置を持ちます(たとえ、レンダリングされていない要素だとしてもです)。ユーザーエージェントは、初期状態を決定するために、プラットフォームの関連に従うべきです。

U+200D ZERO WIDTH JOINER といったレンダリングされずに表示されない文字も、文字としてカウントされます。ゆえに、選択状態には表示されない文字しか含まれないこともあります。そして、そのテキスト挿入カーソルは、そういった文字の前後どちらかに置かれます。

現在の選択テキストを取得するには、次の JavaScript で事足ります:

var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);

controlinput または textarea 要素を指します。

テキストの選択状態を維持したまま、テキストコントロールの最初にテキストを追加するには、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);

controlinput または textarea 要素を指します。


※ 原文:http://www.w3.org/TR/2014/REC-html5-20141028/forms.html#textFieldSelection