选择 API

每个具有 浏览上下文 的 文档 都关联着一个唯一的 选区 (selection)。

此单一的 选区 必须被 文档 的所有内容共享（嵌套的 文档 除外），包括 文档 中的任何 编辑宿主 (editing hosts)。

每个 选区 可关联一个单一的 范围 (range)。当没有 范围 关联到 选区 时，该选区是 空的 (empty)。选区必须初始为 空的。

一旦 选区 与给定的 范围 关联，除非本规范另有要求，否则它必须继续与该相同的 范围 保持关联。

如果 选区 的 范围 不为 null 且已 折叠 (collapsed)，则插入符位置必须位于该 范围 的 边界点。当 选区 未 折叠 时，本规范不定义插入符位置；用户代理应遵循平台惯例，决定插入符位于 选区 的开头、结尾还是其他位置。

每个 选区 都有一个 方向 (direction)：向前 (forwards)、向后 (backwards) 或 无方向 (directionless)。如果用户通过首先指示 范围 的一个 边界点，然后再指示另一个（例如点击一点并拖动到另一点）来创建 选区，且第一个指示的 边界点 在第二个 之后，则相应的 选区 最初必须是 向后 的。如果第一个指示的 边界点 在第二个 之前，则相应的 选区 最初必须是 向前 的。否则，它必须是 无方向 的。

当 选区 的 范围 被脚本变更时（例如通过 selectNode(node)），必须保留 选区 的 方向。

每个 选区 都有一个 锚点 (anchor) 和一个 焦点 (focus)。如果 选区 的 范围 为 null，则其 锚点 和 焦点 均为 null。如果 选区 的 范围 不为 null 且其 方向 为 向前，则其 锚点 为 范围 的 开始，其 焦点 为 结束。否则，其 焦点 为 开始，其 锚点 为 结束。

每个 文档、input 元素和 textarea 元素都有一个布尔值 has scheduled selectionchange event (已调度 selectionchange 事件)，初始为 false。

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

该属性必须返回 此对象 的 锚点 节点；如果 锚点 为 null，或者 锚点 不在 文档树 中，则返回 null。

anchorOffset

该属性必须返回 此对象 的 锚点 偏移量；如果 锚点 为 null，或者 锚点 不在 文档树 中，则返回 0。

focusNode

该属性必须返回 此对象 的 焦点 节点；如果 焦点 为 null，或者 焦点 不在 文档树 中，则返回 null。

focusOffset

该属性必须返回 此对象 的 焦点 偏移量；如果 焦点 为 null，或者 焦点 不在 文档树 中，则返回 0。

isCollapsed

当且仅当 锚点 和 焦点 相同（包括两者均为 null 的情况）时，该属性必须返回 true。否则必须返回 false。

rangeCount

如果 此对象 为 空，或者 焦点 或 锚点 不在 文档树 中，该属性必须返回 0，否则必须返回 1。

type

如果 此对象 为 空，或者 焦点 或 锚点 不在 文档树 中，该属性必须返回 "None"；如果 此对象 的 范围 已 折叠，则返回 "Caret"；否则返回 "Range"。

direction

如果 此对象 为 空 或此选区为 无方向，该属性必须返回 "none"；如果此选区的方向为 向前，则返回 "forward"；如果方向为 向后，则返回 "backward"。

getRangeAt() 方法

如果 index 不为 0，或者 此对象 为 空，或者 焦点 或 锚点 不在 文档树 中，该方法必须抛出 IndexSizeError 异常。否则，它必须返回对 此对象 的 范围 的引用（而非副本）。

注

因此，如果在此期间没有移除 此对象 的范围，该方法的后续调用将返回相同的 范围 对象。特别地，如果 选区 不为 空，则 getSelection().getRangeAt(0) === getSelection().getRangeAt(0) 的求值结果为 true。

addRange() 方法

The method must follow these steps

1. 如果 range 的边界点的 根节点 不是与 此对象 关联的 文档，则中止这些步骤。
2. 如果 rangeCount 不为 0，则中止这些步骤。
3. 通过强引用（而非通过制作副本）将 此对象 的范围设置为 range。

注

由于 范围 是通过引用添加的，因此对 getRangeAt(0) 的后续调用将返回相同的对象，并且脚本在添加 范围 后对其所做的任何更改都必须反映在 选区 中，直到其他操作移除或替换 此对象 的 范围。特别地，在运行以下代码后，选区 将包含 b 而不是 a：var r = document.createRange(); r.selectNode(a); getSelection().addRange(r); r.selectNode(b);

注

在第 2 步，Chrome 58 和 Edge 25 不执行任何操作。Firefox 51 会产生一个多范围选区。至少它们保留了现有的 范围。

在第 3 步，Chrome 58 和 Firefox 51 存储一个引用，如本文所述。Edge 25 存储一个副本。如果修改了 范围，Firefox 51 会更改其选区。

removeRange() 方法

如果 此对象 的 范围 是 range，该方法必须通过解除其 范围 的关联来使 此对象 变为 空。否则，它必须抛出 NotFoundError。

removeAllRanges() 方法

如果 此对象 有关联的 范围，该方法必须通过解除其 范围 的关联来使 此对象 变为 空。

empty() 方法

该方法必须是 removeAllRanges() 的别名，并表现一致。

getComposedRanges() 方法

1. 如果 此对象 为 空，则返回一个空数组。
2. 否则，设 startNode 为与 此对象 关联的 范围 的 开始节点，设 startOffset 为该 范围 的 开始偏移量。
3. 当 startNode 为 节点，startNode 的 根节点 是 阴影根节点 (shadow root)，且 startNode 的 根节点 不是 options["shadowRoots"] 中任一节点的 包含阴影的包含祖先 时，重复以下步骤：
   1. 设置 startOffset 为 startNode 的 根节点 的 宿主 (host) 的索引。
   2. 设置 startNode 为 startNode 的 根节点 的 宿主 的 父节点。
4. 设 endNode 为与 此对象 关联的 范围 的 结束节点，设 endOffset 为该 范围 的 结束偏移量。
5. 当 endNode 为 节点，endNode 的 根节点 是 阴影根节点，且 endNode 的 根节点 不是 options["shadowRoots"] 中任一节点的 包含阴影的包含祖先 时，重复以下步骤：
   1. 设置 endOffset 为 endNode 的 根节点 的 宿主 的索引加 1。
   2. 设置 endNode 为 endNode 的 根节点 的 宿主 的 父节点。
6. 返回一个包含新的 StaticRange 的数组，其 开始节点 为 startNode，开始偏移量 为 startOffset，结束节点 为 endNode，结束偏移量 为 endOffset。

collapse() 方法

The method must follow these steps

1. 如果 node 为 null，此方法必须表现得与 removeAllRanges() 一致并中止这些步骤。
2. 如果 node 是 DocumentType，抛出 InvalidNodeTypeError 异常并中止这些步骤。
3. 如果 offset 长度超过 node 的 长度，该方法必须抛出 IndexSizeError 异常并中止这些步骤。
4. 如果与 此对象 关联的 文档 不是 node 的 包含阴影的包含祖先，则中止这些步骤。
5. 否则，设 newRange 为一个新的 范围。
6. 设置 newRange 的 开始 和 结束 为 (node, offset)。
7. 设置 此对象 的 范围 为 newRange。

setPosition() 方法

该方法必须是 collapse() 的别名，并表现一致。

collapseToStart() 方法

如果 此对象 为 空，该方法必须抛出 InvalidStateError 异常。否则，它必须创建一个新的 范围，设置 其 开始 和 结束 均为 此对象 的 范围 的 开始，然后将 此对象 的 范围 设置为该新创建的 范围。

注

对于 collapseToStart/End，IE9 会变更现有范围，而 Firefox 9.0a2 和 Chrome 15 开发版则将其替换为一个新范围。本规范遵循多数派，将其替换为新范围，使旧 Range 对象保持不变。

collapseToEnd() 方法

如果 此对象 为 空，该方法必须抛出 InvalidStateError 异常。否则，它必须创建一个新的 范围，设置 其 开始 和 结束 均为 此对象 的 范围 的 结束，然后将 此对象 的 范围 设置为该新创建的 范围。

extend() 方法

The method must follow these steps

1. 如果与 此对象 关联的 文档 不是 node 的 包含阴影的包含祖先，则中止这些步骤。
2. 如果 此对象 为 空，抛出 InvalidStateError 异常并中止这些步骤。
3. 设 oldAnchor 和 oldFocus 为 此对象 的 锚点 和 焦点，设 newFocus 为 边界点 (node, offset)。
4. 设 newRange 为一个新的 范围。
5. 如果 node 的 根节点 与 此对象 的 范围 的 根节点 不相同，则将 newRange 的 开始 和 结束 设置 为 newFocus。
6. 否则，如果 oldAnchor 在 newFocus 之前 或相等，则 设置 newRange 的 开始 为 oldAnchor，然后将 结束 设置为 newFocus。
7. 否则，设置 newRange 的 开始 为 newFocus，然后将 结束 设置为 oldAnchor。
8. 设置 此对象 的 范围 为 newRange。
9. 如果 newFocus 在 oldAnchor 之前，将 此对象 的 方向 设置为 向后。否则，将其设置为 向前。

注

约 2011 年 1 月逆向工程的结果。IE 不支持该方法，因此我依赖于 Firefox（2000 年前就实现了 extend()）和 WebKit（2007 年实现）。我基本忽略了 Opera，因为 gsnedders 告诉我它的实现不兼容。Firefox 12.0a1 似乎会变更现有范围。IE9 不支持 extend()，且无法判断 Chrome 17 开发版或 Opera Next 12.00 alpha 是变更还是替换范围，因为 getRangeAt() 本身返回的就是副本。尽管如此，为了与 collapse() 保持一致，我在此违背了 Gecko 的做法。

setBaseAndExtent() 方法

The method must follow these steps

1. 如果 anchorOffset 长度超过 anchorNode 的 长度，或者 focusOffset 长度超过 focusNode 的 长度，抛出 IndexSizeError 异常并中止这些步骤。
2. 如果与 此对象 关联的 文档 不是 anchorNode 或 focusNode 的 包含阴影的包含祖先，则中止这些步骤。
3. 设 anchor 为 边界点 (anchorNode, anchorOffset)，设 focus 为 边界点 (focusNode, focusOffset)。
4. 设 newRange 为一个新的 范围。
5. 如果 anchor 在 focus 之前，设置 newRange 的 开始 为 anchor，其 结束 为 focus。否则，设置 它们分别为 focus 和 anchor。
6. 设置 此对象 的 范围 为 newRange。
7. 如果 focus 在 anchor 之前，将 此对象 的 方向 设置为 向后。否则，将其设置为 向前。

selectAllChildren() 方法

The method must follow these steps

1. 如果 node 是 DocumentType，抛出 InvalidNodeTypeError 异常并中止这些步骤。
2. 如果 node 的 根节点 不是与 此对象 关联的 文档，则中止这些步骤。
3. 设 newRange 为一个新的 范围，childCount 为 node 的 子节点 数量。
4. 设置 newRange 的 开始 为 (node, 0)。
5. 设置 newRange 的 结束 为 (node, childCount)。
6. 设置 此对象 的 范围 为 newRange。
7. 设置 此对象 的 方向 为 向前。

注

主要基于 Firefox 9.0a2。它有一个我没有重现的 bug，即如果将 Document 作为参数传递，结束偏移量会变成 1 而不是其子节点数量。它还会抛出 RangeException 而不是 DOMException，因为其实现早于两者的合并。

IE9 的表现类似，但有缺陷。如果节点是分离的或 display:none，它会抛出“未指定的错误”，显然在其他一些随机情况下也会这样。对于分离的注释（仅限注释！），它会抛出“无效参数”。最后，如果你传递给它一个注释，它似乎会选择整个注释，而不像对待文本节点那样。

Chrome 16 开发版的表现符合其 Selection 实现的预期。它拒绝选择任何不可见的内容，所以它几乎总是错误的。Opera 11.50 在我的所有测试中都什么也不做，一如既往。

新范围替换任何现有范围，而不变更它。这与 IE9 和 Firefox 12.0a1 一致。（Chrome 17 开发版和 Opera Next 12.00 alpha 无法测试，因为 getRangeAt() 返回的是副本。）

modify() 方法

The method must follow these steps

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. 如果 此对象 的 选区 为空，则中止这些步骤。
5. 设 effectiveDirection 为 向后。
6. 如果 direction 与 "forward" 符合 ASCII 大小写不敏感 匹配，设置 effectiveDirection 为 向前。
7. 如果 direction 与 "right" 符合 ASCII 大小写不敏感 匹配，且 此对象 的 选区 的 焦点 的 内联基准方向 为 ltr，设置 effectiveDirection 为 向前。
8. 如果 direction 与 "left" 符合 ASCII 大小写不敏感 匹配，且 此对象 的 选区 的 焦点 的 内联基准方向 为 rtl，设置 effectiveDirection 为 向前。
9. 设置 此对象 的 选区 的 方向 为 effectiveDirection。
10. 如果 alter 与 "extend" 符合 ASCII 大小写不敏感 匹配，则将 此对象 的 选区 的 焦点 设置为用户请求按 granularity 扩展选区时的位置。
11. 否则，将 此对象 的 选区 的 焦点 和 锚点 设置为用户请求按 granularity 移动选区时的位置。

注

我们需要更精确地定义按每种颗粒度扩展或移动选区的含义。

deleteFromDocument() 方法

如果 此对象 不为 空，且 焦点 和 锚点 均在 文档树 中，该方法必须在 此对象 的 范围 上调用 deleteContents()。否则该方法必须不执行任何操作。

注

这是唯一一个实际变更范围而不是替换它的方法。这与 IE9 和 Firefox 12.0a1 一致。（Chrome 17 开发版和 Opera Next 12.00 alpha 无法测试，因为 getRangeAt() 返回的是副本。）

containsNode() 方法

如果 此对象 为 空，或者 node 的 根节点 不是与 此对象 关联的文档，该方法必须返回 false。

否则，如果 allowPartialContainment 为 false，当且仅当其 范围 的 开始 在 node 内的第一个 边界点 之前或在视觉上等效，且其 范围 的 结束 在 node 内的最后一个 边界点 之后或在视觉上等效时，该方法必须返回 true。

如果 allowPartialContainment 为 true，当且仅当其 范围 的 开始 在 node 内的最后一个 边界点 之前或在视觉上等效，且其 范围 的 结束 在 node 内的第一个 边界点 之后或在视觉上等效时，该方法必须返回 true。

stringifier

字符串化必须返回字符串，如果 此对象 关联有 范围，该字符串是渲染文本的拼接。

如果选区位于 textarea 或 input 元素内，它必须返回其值中选定的子字符串。

Selection 接口的所有成员都是根据对对象表示的 范围 对象（如果有）的操作来定义的。这些操作可能会像 Range 接口定义的那样抛出异常；因此，这可能导致 Selection 接口的成员除了上面明确指出的异常外，也会抛出异常。

本规范扩展了几个接口，为本规范定义的接口提供了入口点。

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

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

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

当用户代理要对 CharacterData 替换数据 或 截取子字符串 时，用户代理必须就像其为 动态范围 (live range) 一样，更新与该 CharacterData 的 节点文档 的 选区 关联的 范围。

当用户代理要拆分 Text 节点 时，用户代理必须就像其为 动态范围 一样，更新与该 Text 的 节点文档 的 选区 关联的 范围。

当用户代理要运行 normalize() 方法的步骤时，用户代理必须就像其为 动态范围 一样，更新与 此对象 的 节点文档 的 选区 关联的 范围。

当用户代理要 移除 或 插入 节点 时，用户代理必须就像其为 动态范围 一样，更新与该 节点 的 节点文档 的 选区 关联的 范围。

用户代理应允许用户更改与 活动文档 关联的 选区。如果用户对 选区 进行任何修改，用户代理必须创建一个具有合适 开始 和 结束 的新 范围，并使 选区 与此新 范围 关联（而非修改现有 范围），且如果 开始 在 结束 之前或相等，则将 选区 的 方向 更新为 向前；如果 结束 在 开始 之前，则更新为 向后；或者如果由于平台惯例无法对 开始 和 结束 进行排序，则更新为 无方向。

用户代理在响应任何用户操作（例如点击非可编辑区域）时，不得使之前非 空 的 选区 变 空。

除了标记为非规范性的章节外，本规范中的所有创作指南、图表、示例和注释均为非规范性内容。本规范中的其他所有内容均为规范性内容。

本规范定义了适用于单一产品的符合性准则：实现本规范所含接口的 用户代理 (user agent)。

目前没有针对本标准的已知安全考量。

为了减轻暴露用户使用辅助技术带来的潜在隐私风险，例如，当用户选择修改文档的 选区 时，用户代理 可以选择模拟通常与 selectstart 或 selectionchange 事件相关的鼠标和键盘事件。