選択 API

document はそれぞれ ブラウジングコンテキスト を持つ場合、 一意な selection が関連付けられます。

この selection は、document 内のすべてのコンテンツ（ネストされた document を除く）や、その 編集ホスト を含めて、共有されなければなりません。

各 selection は、1つの range と関連付けできます。 range が selection に関連付けられていない場合、 選択状態は 空 です。選択状態は初期状態で 空 でなければなりません。

selection が range と関連付けられると、 仕様で別途要求されない限り、そのまま同じ range と紐づき続けなければなりません。

selection の range が null でなく、かつ 折りたたまれている 場合は、キャレットの位置はその range の 境界点 でなければなりません。折りたたまれていない場合、本仕様はキャレットの位置を定義しません。ユーザーエージェントは、キャレットを選択の開始・終了・その他どこに表示するかを、プラットフォームの慣習に則って決定すべきです。

各 selection には direction（forwards・ backwards・directionless）があります。ユーザーが selection を、 境界点 のいずれかをまず指定してから（例：一点をクリックし、他方へドラッグする）、もう一方を指定した場合、最初に指定した 境界点 が二番目より 後 であれば、その selection の初期状態は backwards でなければなりません。最初が 前 であれば forwards。 それ以外の場合は directionless とします。

selection の range がスクリプトで変更された場合（例：selectNode(node) など）、 selection の direction は保持されなければなりません。

各 selection は anchor と focus も持ちます。selection の range が null のときは、 anchor、 focus のいずれも null です。 direction が forwards なら、anchor は range の start、focus は end です。 それ以外は focus が start、anchor が end です。

各 document、input 要素、textarea 要素 には、boolean型の has scheduled selectionchange event があり、 その初期値は false です。

Selection インターフェースは、各 document に関連付けられている selection を操作するための手段を提供します。

WebIDL[Exposed=Window]
interface Selection {
  readonly attribute Node? anchorNode;
  readonly attribute unsigned long anchorOffset;
  readonly attribute Node? focusNode;
  readonly attribute unsigned long focusOffset;
  readonly attribute boolean isCollapsed;
  readonly attribute unsigned long rangeCount;
  readonly attribute DOMString type;
  readonly attribute DOMString direction;
  Range getRangeAt(unsigned long index);
  undefined addRange(Range range);
  undefined removeRange(Range range);
  undefined removeAllRanges();
  undefined empty();
  sequence<StaticRange> getComposedRanges(optional GetComposedRangesOptions options = {});
  undefined collapse(Node? node, optional unsigned long offset = 0);
  undefined setPosition(Node? node, optional unsigned long offset = 0);
  undefined collapseToStart();
  undefined collapseToEnd();
  undefined extend(Node node, optional unsigned long offset = 0);
  undefined setBaseAndExtent(Node anchorNode, unsigned long anchorOffset, Node focusNode, unsigned long focusOffset);
  undefined selectAllChildren(Node node);
  undefined modify(optional DOMString alter, optional DOMString direction, optional DOMString granularity);
  [CEReactions] undefined deleteFromDocument();
  boolean containsNode(Node node, optional boolean allowPartialContainment = false);
  stringifier;
};

dictionary GetComposedRangesOptions {
  sequence<ShadowRoot> shadowRoots = [];
};

anchorNode

この属性は、anchor の node を this から返す必要があります。あるいは、anchor が null であるか、または anchor が document tree に存在しない場合は null を返します。

anchorOffset

この属性は、anchor の offset を this から返す必要があります。あるいは、anchor が null であるか、または anchor が document tree に存在しない場合は 0 を返します。

focusNode

この属性は、focus の node を this から返す必要があります。あるいは、focus が null であるか、または focus が document tree に存在しない場合は null を返します。

focusOffset

この属性は、focus の offset を this から返す必要があります。あるいは、focus が null であるか、または focus が document tree に存在しない場合は 0 を返します。

isCollapsed

この属性は、anchor と focus が同一である場合に限り true を返さなければなりません（両方が null の場合を含む）。それ以外の場合は false を返します。

rangeCount

この属性は、this が empty であるか、または focus または anchor のいずれかが document tree に存在しない場合は 0 を返し、そうでない場合は 1 を返さなければなりません。

type

この属性は、this が empty であるか、または focus または anchor のいずれかが document tree に存在しない場合は "None" を返す必要があります。range が collapsed である場合は "Caret"、それ以外の場合は "Range" を返します。

direction

この属性は、this が empty であるか、またはこの選択が directionless である場合は "none" を返さなければなりません。選択の方向が forwards の場合は "forward"、選択の方向が backwards の場合は "backward" を返します。

getRangeAt() method

IndexSizeError 例外を、index が 0 でない場合、または this が empty である場合、あるいは focus または anchor のいずれかが document tree に存在しない場合に投げなければなりません。そうでなければ、このオブジェクトの range への参照（コピーではなく）を返す必要があります。

Note

したがって、このメソッドを続けて呼び出しても、途中でこのオブジェクトの range が取り除かれていなければ同じ range オブジェクトが返されます。特に、getSelection().getRangeAt(0) === getSelection().getRangeAt(0) は、選択が empty でない場合に true と評価されます。

addRange() method

このメソッドは次の手順に従わなければなりません:

1. もし range の境界点の root が、document （this に関連付けられているもの）でなければ、これらの手順を中止します。
2. もし rangeCount が 0 でない場合、これらの手順を中止します。
3. this の range を、強い参照（コピーを作らない）によって range に設定します。

Note

range を参照で追加するため、後続の getRangeAt(0) 呼び出しは同一のオブジェクトを返し、スクリプトが range に対して行った変更は、それが取り除かれたり置換されたりするまで selection に反映されなければなりません。具体的には、次のコードを実行すると selection は b を含むようになります（a ではなく）: var r = document.createRange(); r.selectNode(a); getSelection().addRange(r); r.selectNode(b);

Note

手順2では、Chrome 58 と Edge 25 は何もしません。Firefox 51 はマルチレンジ選択を返します。少なくとも既存の range は保持します。

手順3では、Chrome 58 と Firefox 51 は参照を保存します（ここで説明されている通り）。Edge 25 はコピーを保存します。Firefox 51 は range が変更されると選択を変更します。

removeRange() method

このメソッドは、もし this の empty にするために、その range が range と等しい場合は関連付けを解除して this を empty にしなければなりません。そうでない場合は NotFoundError を投げます。

removeAllRanges() method

このメソッドは、this が関連付けられた range を持っている場合、その関連付けを解除して this を empty にしなければなりません。

empty() method

このメソッドは removeAllRanges() のエイリアスであり、同一の動作をしなければなりません。

getComposedRanges() method

1. もし this が empty であれば、空の配列を返します。
2. それ以外の場合、startNode を range に関連付けられた開始ノードとし、startOffset をその 開始オフセット とします。
3. もし startNode がノードであり、かつその root が shadow root であり、かつその root が options["shadowRoots"] のいずれかの shadow-including inclusive ancestor でない限り、次の手順を繰り返します:
   1. startOffset を startNode の root の index に設定します。
   2. startNode をその root の host の親に設定します。
4. endNode を range に関連付けられた終了ノードとし、endOffset をその 終了オフセット とします。
5. もし endNode がノードであり、その root が shadow root であり、かつその root が options["shadowRoots"] のいずれかの shadow-including inclusive ancestor でない限り、次の手順を繰り返します:
   1. endOffset を endNode の root の index プラス 1 に設定します。
   2. endNode をその root の host の親に設定します。
6. 開始ノードが startNode、開始オフセットが startOffset、終了ノードが endNode、終了オフセットが endOffset の新しい StaticRange を含む配列を返します。

collapse() method

このメソッドは次の手順に従わなければなりません:

1. もし node が null であれば、このメソッドは removeAllRanges() と同一に振る舞い、これらの手順を中止します。
2. もし node が DocumentType であれば、InvalidNodeTypeError を投げてこれらの手順を中止します。
3. もし offset が node の length より大きければ、IndexSizeError を投げてこれらの手順を中止します。
4. もし document が shadow-including inclusive ancestor でない場合、これらの手順を中止します。
5. それ以外の場合、newRange を新しい range とします。
6. 開始点を設定 し、newRange の開始および終了を (node, offset) に設定します。
7. this の range を newRange に設定します。

setPosition() method

このメソッドは collapse() のエイリアスであり、同一の動作をしなければなりません。

collapseToStart() method

このメソッドは、もし InvalidStateError を投げるべき条件（すなわちこのオブジェクトが empty である場合）でなければ、新しい range を作成し、その開始と終了の両方をこのオブジェクトの range の開始位置に設定し、作成した range を this の range に設定しなければなりません。

Note

collapseToStart/End について、IE9 は既存の range を変更しますが、Firefox 9.0a2 と Chrome 15 dev は新しい range に置き換えます。仕様は多数派に従い、新しい range に置き換えて古い Range オブジェクトを変更しないようにしています。

collapseToEnd() method

このメソッドは、もし InvalidStateError を投げるべき条件（すなわち this が empty である場合）でなければ、新しい range を作成し、その開始と終了の両方をこのオブジェクトの range の終了位置に設定し、作成した range を this の range に設定しなければなりません。

extend() method

このメソッドは次の手順に従わなければなりません:

1. もし document （this に関連付けられているもの）が shadow-including inclusive ancestor でない場合、これらの手順を中止します。
2. もし this が empty であれば、InvalidStateError を投げてこれらの手順を中止します。
3. oldAnchor と oldFocus を this の anchor および focus とし、newFocus を境界点 (node, offset) とします。
4. newRange を新しい range とします。
5. もし node の root が this の range の root と同じでない場合、newRange の開始と終了を newFocus に設定 します。
6. そうでなく、もし oldAnchor が before または newFocus と等しい場合、newRange の開始を oldAnchor に設定 し、その終了を newFocus に設定します。
7. それ以外の場合、newRange の開始を newFocus に設定 し、その終了を oldAnchor に設定します。
8. this の range を newRange に設定します。
9. もし newFocus が oldAnchor より before であれば、this の direction を backwards に設定します。そうでなければ forwards に設定します。

Note

2011年1月頃にリバースエンジニアリングされた実装に基づきます。IE はサポートしておらず、Firefox（2000年以前に実装）と WebKit（2007年に実装）に依拠しています。Opera の実装は互換性がないため主に無視しています。Firefox 12.0a1 は既存の range を変更するようです。IE9 は extend() をサポートしておらず、Chrome 17 dev や Opera Next 12.00 alpha が変更または置換するかは判別できません（getRangeAt() がコピーを返すため）。それでも仕様は collapse() と一貫させるために Gecko の挙動とは異なる決定をしています。

setBaseAndExtent() method

このメソッドは次の手順に従わなければなりません:

1. もし anchorOffset が anchorNode の length より大きい、または focusOffset が focusNode の length より大きい場合、IndexSizeError を投げてこれらの手順を中止します。
2. もし document が shadow-including inclusive ancestor でない場合、これらの手順を中止します。
3. anchor を境界点 (anchorNode, anchorOffset)、focus を境界点 (focusNode, focusOffset) とします。
4. newRange を新しい range とします。
5. もし anchor が before focus であれば、newRange の開始を anchor、終了を focus に設定 します。そうでなければ開始を focus、終了を anchor に設定します。
6. this の range を newRange に設定します。
7. もし focus が anchor より before であれば、this の direction を backwards に設定します。そうでなければ forwards に設定します。

selectAllChildren() method

このメソッドは次の手順に従わなければなりません:

1. もし node が DocumentType であれば、InvalidNodeTypeError を投げてこれらの手順を中止します。
2. もし node の root が、document（this に関連付けられているもの）でない場合、これらの手順を中止します。
3. newRange を新しい range とし、childCount を node の子の数として定義します。
4. newRange の開始を (node, 0) に設定します。
5. newRange の終了を (node, childCount) に設定します。
6. this の range を newRange に設定します。
7. this の direction を forwards に設定します。

Note

主に Firefox 9.0a2 に基づきます。引数に Document を渡すと終了オフセットが子の数ではなく 1 になるバグがありました。また、実装が DOMException と RangeException の統合に先行していたため、RangeException を投げます。

IE9 も類似の振る舞いですが不具合があります。ノードがデタッチされているか display:none の場合に "Unspecified error." を投げたり、デタッチされたコメントに対して "Invalid argument." を投げたりします。コメントを渡すとテキストノードとは異なりコメント全体を選択するようです。

Chrome 16 dev は Selection 実装に従った動作をします。表示されていないものは選択しないため、多くの場合誤っています。Opera 11.50 はテストでは何もしませんでした。

新しい range は既存のものを置換し、変異させません。これは IE9 と Firefox 12.0a1 に一致します。（Chrome 17 dev と Opera Next 12.00 alpha は getRangeAt() がコピーを返すためテスト不可。）

modify() method

このメソッドは次の手順に従わなければなりません:

1. alter が "extend" または "move" とASCII の大小文字を区別しない 一致でない場合、これらの手順を中止する。
2. direction が "forward"、"backward"、"left"、または "right" とASCII の大小文字を区別しない 一致でない場合、これらの 手順を中止する。
3. granularity が "character"、"word"、"sentence"、"line"、"paragraph"、 "lineboundary"、"sentenceboundary"、"paragraphboundary"、 "documentboundary" とASCII の大小文字を区別しない 一致でない場合、これらの手順を中止する。
4. this の選択が空である場合、これらの手順を中止する。
5. effectiveDirection を後方とする。
6. direction が "forward" とASCII の大小文字を区別しない 一致である場合、effectiveDirection を 前方に設定する。
7. direction が "right" とASCII の大小文字を区別しない 一致であり、かつ this の 選択のフォーカスにおける解決済みテキスト方向 が ltr である場合、 effectiveDirection を前方に設定する。
8. direction が "left" とASCII の大小文字を区別しない 一致であり、かつ this の 選択のフォーカスにおける解決済みテキスト方向 が rtl である場合、 effectiveDirection を前方に設定する。
9. this の選択の方向を effectiveDirection に設定する。
10. alter が "extend" とASCII の大小文字を区別しない 一致である場合、this の選択のフォーカスを、ユーザーが granularity によって選択を拡張するよう要求したかのような位置に設定する。
11. そうでない場合、this の選択のフォーカスおよび アンカーを、ユーザーが granularity によって 選択を移動するよう要求したかのような位置に設定する。

境界点における解決済みテキスト方向は、その位置の文字の埋め込み 方向（[UAX9] BD3）が L である場合は ltr、 埋め込み 方向が R である場合は rtl である。

注記

隣接する文字の埋め込み方向が異なる双方向テキスト境界では、ユーザーエージェントは、 どの文字の埋め込み方向を使用するかを決定するために、追加の文脈 （カーソル移動方向に基づくキャレット親和性など）を使用してもよい。

注記

各粒度によって選択を拡張または移動するとは何を意味するのかを、より正確に定義する必要がある。

deleteFromDocument() method

このメソッドは、もし this が empty でなく、かつ focus と anchor の両方が document tree に存在する場合、deleteContents() を this の range に対して呼び出さなければなりません。そうでない場合は何もしません。

Note

これは range を置換するのではなく実際に変異させる唯一のメソッドです。IE9 と Firefox 12.0a1 に一致します。（Chrome 17 dev と Opera Next 12.00 alpha は getRangeAt() がコピーを返すためテスト不可。）

containsNode() method

もし this が empty であるか、または node の root がこの this に関連付けられたドキュメントでない場合、このメソッドは false を返さなければなりません。

そうでない場合、もし allowPartialContainment が false であれば、このメソッドは、(1) 自身の range の start が node 内の最初の境界点と等しいかそれより前であり、かつ (2) 自身の range の end が node 内の最後の境界点と等しいかそれより後である場合に限り true を返さなければなりません（視覚的に等価である場合を含む）。

もし allowPartialContainment が true であれば、このメソッドは、(1) 自身の range の start が node 内の最後の境界点と等しいかそれより前であり、かつ (2) 自身の range の end が node 内の最初の境界点と等しいかそれより後である場合に限り true を返さなければなりません（視覚的に等価である場合を含む）。

stringifier

文字列化は、この this に関連付けられた range のレンダリングされたテキストの連結を返さなければなりません。

選択が textarea または input 要素内にある場合は、その value の選択された部分文字列を返さなければなりません。

Selection インターフェースのすべてのメンバーは、そのオブジェクトによって表される（存在すれば）range オブジェクトに対する操作の観点から定義されています。これらの操作は、Range インターフェースで定義されるように例外を投げることがあります。したがって、Selection インターフェースのメンバーも、上記で明示的に記述された場合に加え、例外をスローする可能性があります。

この仕様は、ここで定義されるインターフェースへのエントリーポイントを提供するために、いくつかのインターフェースを拡張します。

WebIDLpartial interface Document {
  Selection? getSelection();
};

WebIDLpartial interface Window {
  Selection? getSelection();
};

WebIDLpartial interface mixin GlobalEventHandlers {
  attribute EventHandler onselectstart;
  attribute EventHandler onselectionchange;
};

ユーザーエージェントが データを置換 または 部分文字列 を CharacterData に対して行う場合、ユーザーエージェントは、その CharacterData の ノードドキュメント の selection に関連付けられた range を live range として更新しなければなりません。

ユーザーエージェントが Text ノード を分割する場合、ユーザーエージェントは、 Text の ノードドキュメント の selection に関連付けられた range を live range として更新しなければなりません。

ユーザーエージェントが normalize() メソッドの手順を実行する場合、ユーザーエージェントは ノードドキュメント の selection に関連付けられた range を live range として更新しなければなりません。

ユーザーエージェントが ノードを削除 または 挿入 する場合、ユーザーエージェントは、その ノード の ノードドキュメント の selection に関連付けられた range を live range として更新しなければなりません。

ユーザーエージェントは、selection（アクティブドキュメントに関連付けられたもの）を ユーザーが変更できるようにすべきです。ユーザーが selection を何らかの方法で変更した場合、ユーザーエージェントは range の 開始 と 終了 を適切に設定した新しい range を作成し、この selection にこの新しい range を関連付けなければなりません（既存の range を変更しないこと）、また、開始が終了より 前 あるいは等しい場合は selection の direction を forwards に、終了が開始より 前 の場合は backwards に、開始と終了がプラットフォームの慣習により順序付けできない場合は directionless に設定しなければなりません。

ユーザーエージェントは、ユーザーによるいかなる操作（例：編集不可領域のクリック）に対しても、もともと empty でなかった selection を empty にしてはなりません。

非規範的と記載されたセクションだけでなく、本仕様書中のすべての執筆ガイドライン、図、例、および注記は規範的ではありません。それ以外のすべては規範的です。

この仕様書は、含まれるインターフェースを実装する ユーザーエージェント という単一製品に適用される適合基準を定義します。

この標準には既知のセキュリティ上の考慮事項はありません。

支援技術のユーザー利用を開示することによる潜在的なプライバシーリスクを軽減するため、たとえばユーザーエージェント は、ドキュメントの selection をユーザーが変更した場合、通常は selectstart や selectionchange イベントに関連付けられるマウスやキーボードイベントをエミュレートすることを選択することがあります。