Selection

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.

Selection オブジェクトは、ユーザーが選択したテキストの範囲、またはキャレットの現在の位置を表します。検査や操作のために Selection オブジェクトを取得するには、 window.getSelection() を呼び出してください。

ユーザーは、左から右（文書順）または右から左（文書と逆順）に選択することができます。アンカー (anchor) はユーザーが選択を開始した場所、フォーカス (focus) はユーザーが選択を終了した場所である。デスクトップマウスで選択する場合、アンカーはマウスボタンを押した場所に置かれ、フォーカスはマウスボタンを離した場所に置かれます。

メモ: アンカーとフォーカスは、選択範囲の開始位置と終了位置と混同しないようにしましょう。アンカーはフォーカスの前に置かれることもあればその逆もあり、選択の方向によって異なります。

プロパティ

Selection.anchorNode 読取専用: 選択範囲を開始する Node を返します。選択範囲が文書内に存在しない場合（例：クリックされなかった iframe）には null を返すことがあります。
Selection.anchorOffset 読取専用: 選択部分のアンカーの anchorNode 内でのオフセットを表す値を返します。 anchorNode がテキストノードであった場合、これはアンカーに先行する anchorNode 内の文字数です。 anchorNode が要素であった場合、これはアンカーに先行する anchorNode の子ノードの数です。
Selection.focusNode 読取専用: 選択範囲が終了する Node を返します。選択範囲が文書内に存在しない場合（例えば、クリックされなかった iframe 内の場合）には null を返すことがあります。
Selection.focusOffset 読取専用: 選択部分のアンカーの focusNode 内でのオフセットを表す値を返します。 focusNode がテキストであった場合、これは focusNode 内でフォーカスに先行する文字数です。 focusNode が要素であった場合、フォーカスの前にある focusNode の子ノードの数を表します。
Selection.isCollapsed 読取専用: 選択範囲の始点と終点が同じ位置にあるかどうかを示す論理値を返します。
Selection.rangeCount 読取専用: 選択範囲に含まれる範囲の数を返します。
Selection.type 読取専用: 現在の選択部分の型を記述した文字列を返します。

メソッド

Selection.addRange(): Range オブジェクトを選択範囲に追加します。
Selection.collapse(): 現在の選択範囲をこの点まで折りたたみます。
Selection.collapseToEnd(): 選択範囲を終端まで折りたたみます。
Selection.collapseToStart(): 選択範囲を先頭まで折りたたみます。
Selection.containsNode(): あるノードが選択範囲に含まれるかどうかを示します。
Selection.deleteFromDocument(): 選択部分の内容を文書から削除します。
Selection.extend(): 選択範囲のフォーカスをこの点に移動させる。
Selection.getRangeAt(): 現在選択されている範囲のうちの一つを表す Range オブジェクトを返します。
Selection.modify() Non-standard: 現在の選択範囲を変更します。
Selection.removeRange(): 選択範囲から範囲を削除します。
Selection.removeAllRanges(): 選択範囲からすべての範囲を削除します。
Selection.selectAllChildren(): 指定されたノードのすべての子ノードを選択範囲に追加します。
Selection.setBaseAndExtent(): 指定した 2 つの DOM ノードのすべてまたは一部、およびそれらの間にあるコンテンツを含む範囲を選択範囲に設定します。
Selection.toString(): 選択オブジェクトが現在表現している文字列、すなわち現在選択されている文字列を返します。

メモ

選択範囲の文字列表現

Selection.toString() メソッドを呼び出すと、選択範囲に含まれるテキストなどを返すことができます。

const selObj = window.getSelection();
window.alert(selObj);

なお、選択オブジェクトを window.alert の引数として使用すると、そのオブジェクトの toString メソッドが呼び出されます。

選択範囲に複数の範囲がある場合

選択オブジェクトは、ユーザーが選択したRangeを表します。通常、1つの範囲のみを保持し、以下のようにアクセスします。

const selObj = window.getSelection();
const range = selObj.getRangeAt(0);

selObj は Selection オブジェクト
range は Range オブジェクト

選択 API 仕様書のメモにあるように、選択 API は当初 Netscape 社によって作成され、複数の範囲を許容していました（例えば <table> から列を選択できるようにする）。しかし、 Gecko 以外のブラウザーは複数の範囲を実装しておらず、仕様でも選択範囲は常に一つであることが要求されています。

選択と入力のフォーカス

選択と入力フォーカス（Document.activeElement で示される）には、ブラウザーによって異なる複雑な関係があります。ブラウザー間の互換性のあるコードでは、これらを別個に扱う方がよいでしょう。

Safari と Chrome は（Firefox と異なり）現在、プログラムで選択範囲を変更する場合、選択範囲を含む要素にフォーカスを当てます。将来的には変更される可能性があります（W3C bug 14383 と WebKit bug 38696 を参照して下さい）。

編集ホストのフォーカス変更に関する選択 API の挙動

選択 API には、特定のメソッドが呼ばれた後に編集ホストのフォーカスの動作がどのように変わるかを制御する共通の動作（つまり、ブラウザー間で共有される）があります。

その動作は次のとおりです。

編集中のホストは、直前の選択がその外にあった場合、フォーカスを得ることができます。
選択 API のメソッドが呼び出され、編集ホスト内の選択範囲に新たな選択範囲が発生します。
その後、フォーカスは編集ホストに移ります。

メモ: 選択 API のメソッドは編集ホストにのみフォーカスを移動でき、他のフォーカス可能な要素には移動できません（例: <a>）。

上記の動作は、以下のメソッドを使用して選択された場合にも適用されます。

また、以下のメソッドを使用して Range を変更した場合も同様です。

用語集

この分野で使用されるその他の重要な用語です。

アンカー: 選択範囲のアンカーは、選択範囲の始点です。マウスで選択する場合、アンカーは文書内で最初にマウスボタンが押された位置となります。ユーザーがマウスやキーボードを使用して選択範囲を変更しても、アンカーは移動しません。
編集ホスト: 編集可能な要素（例えば、contenteditableが設定された HTML 要素、または designMode が有効になっている文書の HTML 子要素など）。
選択フォーカス: 選択範囲の フォーカス は、選択範囲の終点です。マウスで選択する場合、フォーカスは文書内でマウスボタンが離された位置にあります。ユーザーがマウスやキーボードを使用して選択範囲を変更すると、フォーカスは移動した選択範囲の終点になります。

メモ: これは、document.activeElementが返すような、文書のフォーカスされた要素と同じものではありません。
範囲: 範囲とは、文書内の連続した部分のことです。範囲には、ノード全体やノードの一部（テキストノードの一部など）を含めることができます。通常、ユーザーは一度に一つの範囲しか選択しませんが、ユーザーが複数の範囲を選択することも可能です (例: Control キーを使用するなど)。範囲は range オブジェクトとして選択範囲から取得することができます。範囲オブジェクトは DOM 経由で作成することもでき、プログラムによって選択範囲に追加したり削除したりすることができます。

仕様書

Specification
Selection API # selection-interface

ブラウザーの互換性

BCD tables only load in the browser