선택 API

문서마다 브라우징 컨텍스트가 있으면 고유한 selection(선택)이 연결됩니다.

이 selection은 문서의 모든 콘텐츠(중첩된 문서는 제외)에 공유되어야 하며, 편집 호스트도 포함됩니다.

각 selection은 하나의 range와 연관될 수 있습니다. range가 연결되지 않은 경우 selection은 비어 있음(empty) 상태입니다. selection은 처음에 비어 있어야 합니다.

selection이 특정 range와 연결된 이후에는 이 명세에서 달리 요구하지 않는 한 계속 동일한 range와 연관되어야 합니다.

selection의 range가 null이 아니고 collapsed되어 있다면, 캐럿 위치는 해당 range의 경계점에 있어야 합니다. selection이 collapsed되어 있지 않은 경우, 이 명세는 캐럿 위치를 정의하지 않으므로 user agent는 selection의 시작, 끝, 혹은 다른 위치에 캐럿을 둘지 플랫폼 관례를 따라야 합니다.

각 selection은 방향(direction) 값을 갖습니다: forwards(정방향), backwards(역방향), 또는 무방향(directionless). 사용자가 selection을 어떤 경계점에서 시작하여(마우스 클릭) 다른 지점(드래그)으로 지정한 경우, 첫 번째 경계점이 두 번째 이후면 해당 selection은 역방향이어야 합니다. 첫 경계점이 두 번째 이전이면 정방향이고, 그렇지 않으면 무방향이어야 합니다.

selection의 range가 스크립트로 변형될 때(예: selectNode(node)로), 방향은 반드시 유지되어야 합니다.

각 selection은 앵커(anchor)와 포커스(focus)를 가집니다. selection의 range가 null이면 앵커와 포커스 모두 null입니다. selection의 range가 null이 아니고, 방향이 정방향이면 앵커는 range의 start이고, 포커스는 end입니다. 그렇지 않으면 포커스는 start이고, 앵커는 end입니다.

각 문서, input 요소, textarea 요소에는 부울값 has scheduled selectionchange event가 있으며, 최초에는 false입니다.

Selection 인터페이스는 각 문서와 연관된 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

이 속성은 앵커 노드를 this에서 반환해야 하며, 앵커가 null이거나 앵커가 문서 트리에 없으면 null을 반환해야 합니다.

anchorOffset

이 속성은 앵커의 오프셋을 this에서 반환해야 하며, 앵커가 null이거나 앵커가 문서 트리에 없으면 0을 반환해야 합니다.

focusNode

이 속성은 포커스 노드를 this에서 반환해야 하며, 포커스가 null이거나 포커스가 문서 트리에 없으면 null을 반환해야 합니다.

focusOffset

이 속성은 포커스의 오프셋을 this에서 반환해야 하며, 0을 반환해야 합니다. 만약 포커스가 null이거나 포커스가 문서 트리에 없을 경우에는 0을 반환해야 합니다.

isCollapsed

이 속성은 앵커와 포커스가 동일할 경우에만 true를 반환해야 합니다(둘 다 null인 경우 포함). 그렇지 않으면 false를 반환해야 합니다.

rangeCount

이 속성은 this가 비어 있음이거나 포커스 또는 앵커가 문서 트리에 없으면 0을 반환하고, 그렇지 않으면 1을 반환해야 합니다.

type

이 속성은 this가 비어 있음이거나 포커스 또는 앵커가 문서 트리에 없으면 "None"을 반환해야 하며, this의 range가 collapsed이면 "Caret"를 반환하고, 그렇지 않으면 "Range"를 반환해야 합니다.

direction

이 속성은 this가 비어 있음이거나 이 선택이 무방향이면 "none"을 반환해야 합니다. 이 선택의 방향이 정방향이면 "forward"를, 역방향이면 "backward"를 반환해야 합니다.

getRangeAt() method

이 메서드는 index가 0가 아니거나, this가 비어 있음이거나 포커스 또는 앵커가 문서 트리에 없으면 IndexSizeError 예외를 던져야 합니다. 그렇지 않으면, this의 range에 대한 참조(복사본이 아님)를 반환해야 합니다.

Note

따라서 이 메서드를 연속해서 호출하면(그 사이에 이의 range가 제거되지 않았다면) 동일한 range 객체를 반환합니다. 특히, getSelection().getRangeAt(0) === getSelection().getRangeAt(0)는 selection이 비어 있지 않은 경우 true로 평가됩니다.

addRange() method

이 메서드는 다음 단계를 따라야 합니다:

1. 만약 루트가 range의 경계점들이 속한 루트가 this와 연관된 문서가 아니라면, 이 단계를 중단합니다.
2. 만약 rangeCount가 0이 아니면, 이 단계를 중단합니다.
3. this의 range를 강한 참조로(복사본을 만들지 않고) range로 설정합니다.

Note

range가 참조로 추가되므로, 이후의 getRangeAt(0) 호출은 동일한 객체를 반환하며, 스크립트가 range를 추가한 이후에 range에 대해 수행하는 모든 변경은 selection에 반영되어야 합니다. 예를 들어 다음 코드를 실행한 후에는 selection이 a가 아니라 b를 포함하게 됩니다: 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의 비어 있음 상태를 만들기 위해, 만약 this의 range가 range이면 그 연관을 해제해야 합니다. 그렇지 않으면 NotFoundError를 던져야 합니다.

removeAllRanges() method

이 메서드는 this에 연관된 range이 있으면, 그 연관을 해제하여 비어 있음 상태로 만들어야 합니다.

empty() method

이 메서드는 removeAllRanges()의 별칭이며 동일하게 동작해야 합니다.

getComposedRanges() method

1. 만약 this가 비어 있음이면, 빈 배열을 반환합니다.
2. 그렇지 않으면, startNode를 연관된 range의 시작 노드로 정하고, startOffset을 시작 오프셋으로 정합니다.
3. startNode가 노드이고, 그 startNode의 루트가 섀도우 루트이며, 그 루트가 options["shadowRoots"]의 어떤 항목의 shadow-including 포괄적 조상이 아니면, 다음 단계를 반복합니다:
   1. startOffset를 startNode의 루트의 인덱스로 설정합니다.
   2. startNode를 그 루트의 호스트의 부모로 설정합니다.
4. endNode를 연관된 range의 끝 노드로 정하고, endOffset를 끝 오프셋으로 정합니다.
5. endNode가 노드이고, 그 endNode의 루트가 섀도우 루트이며, 그 루트가 options["shadowRoots"]의 어떤 항목의 shadow-including 포괄적 조상이 아니면, 다음 단계를 반복합니다:
   1. endOffset를 그 루트의 호스트의 인덱스에 1을 더한 값으로 설정합니다.
   2. endNode를 그 루트의 호스트의 부모로 설정합니다.
6. 시작 노드가 startNode, 시작 오프셋이 startOffset, 끝 노드가 endNode, 끝 오프셋이 endOffset인 새 StaticRange들의 배열을 반환합니다.

collapse() method

이 메서드는 다음 단계를 따라야 합니다:

1. 만약 node가 null이면, 이 메서드는 removeAllRanges()와 동일하게 동작하고 이 단계들을 중단해야 합니다.
2. 만약 node가 DocumentType이면, InvalidNodeTypeError 예외를 던지고 이 단계들을 중단해야 합니다.
3. 만약 offset가 node의 길이보다 크면, IndexSizeError 예외를 던지고 이 단계들을 중단해야 합니다.
4. 만약 this와 연관된 문서가 node의 shadow-including 포괄적 조상이 아니면, 이 단계들을 중단해야 합니다.
5. 그렇지 않으면, newRange라는 새 range를 만들야 합니다.
6. 시작점을 설정하여 newRange의 start와 end를 (node, offset)로 설정해야 합니다.
7. this의 range를 newRange로 설정해야 합니다.

setPosition() method

이 메서드는 collapse()의 별칭이며 동일하게 동작해야 합니다.

collapseToStart() method

이 메서드는 InvalidStateError 예외를, 만약 this가 비어 있음이면 던져야 합니다. 그렇지 않으면 새 range를 생성하고, 그 range의 시작점을 설정하여 그 range의 start와 end를 this의 range의 start로 설정한 다음, this의 range를 새로 생성한 range로 설정해야 합니다.

Note

collapseToStart/End의 경우, IE9는 기존 range를 변경(mutates)하고, Firefox 9.0a2와 Chrome 15 개발 버전은 새 것으로 교체합니다. 명세는 다수의 구현을 따라 새 것으로 교체하여 이전 Range 객체는 변경되지 않도록 합니다.

collapseToEnd() method

이 메서드는 InvalidStateError 예외를, 만약 this가 비어 있음이면 던져야 합니다. 그렇지 않으면 새 range를 생성하고, 그 range의 시작점을 설정하여 그 range의 start와 end를 this의 range의 end로 설정한 다음, this의 range를 새로 생성한 range로 설정해야 합니다.

extend() method

이 메서드는 다음 단계를 따라야 합니다:

1. 만약 this와 연관된 문서가 node의 shadow-including 포괄적 조상이 아니면, 이 단계들을 중단해야 합니다.
2. 만약 this가 비어 있음이면, InvalidStateError 예외를 던지고 이 단계들을 중단해야 합니다.
3. oldAnchor와 oldFocus를 this의 앵커와 포커스로 두고, newFocus를 (node, offset)인 새로운 경계점으로 정합니다.
4. newRange라는 새 range를 만듭니다.
5. 만약 node의 루트가 this의 연관된 range의 루트와 다르면, newRange의 start와 end를 newFocus로 설정해야 합니다.
6. 그렇지 않으면, 만약 oldAnchor가 before 또는 newFocus와 동일하면, newRange의 start를 oldAnchor로 설정한 다음, 그 end를 newFocus로 설정해야 합니다.
7. 그렇지 않으면, newRange의 start를 newFocus로 설정하고 그 end를 oldAnchor로 설정해야 합니다.
8. this의 range를 newRange로 설정해야 합니다.
9. 만약 newFocus가 before oldAnchor이면, this의 direction을 backwards로 설정해야 합니다. 그렇지 않으면 forwards로 설정해야 합니다.

Note

2011년 1월경 역공학된 내용입니다. IE는 이를 지원하지 않으므로 Firefox(extend()를 2000년 이전에 구현)와 WebKit(2007년에 구현)에 의존하고 있습니다. Opera는 구현이 호환되지 않는 것으로 간주하여 대부분 무시하고 있습니다. Firefox 12.0a1은 기존 range를 변경하는 것으로 보입니다. IE9는 extend()를 지원하지 않으며, Chrome 17 개발 버전이나 Opera Next 12.00 알파가 변경하는지 교체하는지 판단하기 어렵습니다(어차피 getRangeAt()가 복사본을 반환하기 때문). 그럼에도 불구하고 collapse()와 일관되도록 Gecko와는 다른 방식을 따릅니다.

setBaseAndExtent() method

이 메서드는 다음 단계를 따라야 합니다:

1. 만약 anchorOffset가 anchorNode의 길이보다 크거나, focusOffset가 focusNode의 길이보다 크면, IndexSizeError 예외를 던지고 이 단계들을 중단해야 합니다.
2. 만약 this와 연관된 문서가 anchorNode나 focusNode의 shadow-including 포괄적 조상이 아니면, 이 단계들을 중단해야 합니다.
3. anchor을 (anchorNode, anchorOffset)인 경계점으로, focus을 (focusNode, focusOffset)인 경계점으로 정합니다.
4. newRange라는 새 range를 만듭니다.
5. 만약 anchor가 before focus이면, newRange의 start를 anchor로, end를 focus로 설정합니다. 그렇지 않으면 start를 focus로, end를 anchor로 설정합니다.
6. this의 range를 newRange로 설정해야 합니다.
7. 만약 focus가 before anchor이면, this의 direction을 backwards로 설정합니다. 그렇지 않으면 forwards로 설정합니다.

selectAllChildren() method

이 메서드는 다음 단계를 따라야 합니다:

1. 만약 node가 DocumentType이면, InvalidNodeTypeError 예외를 던지고 이 단계들을 중단해야 합니다.
2. 만약 node의 루트가 this와 연관된 문서가 아니면, 이 단계들을 중단해야 합니다.
3. newRange라는 새 range를 만들고, childCount를 node의 자식 수로 정합니다.
4. newRange의 start를 (node, 0)으로 설정합니다.
5. newRange의 end를 (node, childCount)으로 설정합니다.
6. this의 range를 newRange로 설정합니다.
7. this의 direction을 forwards로 설정해야 합니다.

Note

주로 Firefox 9.0a2를 기반으로 한 내용입니다. 재현하지 못한 버그가 있는데, 예를 들어 Document를 인자로 전달하면 end offset이 자식 수가 아닌 1이 되는 문제가 있습니다. 또한 구현이 DOMException과 합쳐지기 이전의 것이어서 RangeException을 던집니다.

IE9는 유사하게 동작하지만 결함이 있습니다. 노드가 분리되었거나 display:none인 경우 "Unspecified error."를 던지고, 일부 다른 무작위한 경우에도 에러를 던집니다. 분리된 코멘트에 대해서는 "Invalid argument."를 던집니다(오직 그 경우에만). 마지막으로 코멘트를 전달하면 텍스트 노드와 달리 코멘트 전체를 선택하는 것처럼 보입니다.

Chrome 16 개발 버전은 Selection 구현에 따라 예상대로 동작합니다. 보이지 않는 것을 선택하기를 거부하므로 거의 항상 잘못된 동작을 합니다. Opera 11.50은 모든 테스트에서 아무 작업도 하지 않습니다.

새 range는 기존의 것을 대체하며, 변경(mutates)하지 않습니다. 이는 IE9와 Firefox 12.0a1과 일치합니다. (Chrome 17 개발 버전과 Opera Next 12.00 알파는 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 selection이 비어 있으면, 이 단계를 중단합니다.
5. effectiveDirection을 backwards로 정합니다.
6. 만약 direction가 "forward"와 ASCII 대소문자 구분 없이 일치하면, effectiveDirection을 forwards로 설정합니다.
7. 만약 direction가 "right"와 ASCII 대소문자 구분 없이 일치하고, inline base direction이 this selection의 focus에 대해 ltr이면, effectiveDirection을 forwards로 설정합니다.
8. 만약 direction가 "left"와 ASCII 대소문자 구분 없이 일치하고, inline base direction이 this selection의 focus에 대해 rtl이면, effectiveDirection을 forwards로 설정합니다.
9. this selection의 direction을 effectiveDirection으로 설정합니다.
10. 만약 alter가 "extend"와 ASCII 대소문자 구분 없이 일치하면, this selection의 focus를 사용자가 granularity로 선택을 확장하라고 요청한 것과 같은 위치로 설정합니다.
11. 그렇지 않으면, this의 selection의 focus와 anchor를 사용자가 granularity로 선택을 이동하라고 요청한 것과 같은 위치로 설정합니다.

Note

각 granularity별로 선택을 확장하거나 이동한다는 것이 정확히 무엇을 의미하는지 더 정확히 정의할 필요가 있습니다.

deleteFromDocument() method

이 메서드는 deleteContents()를 this의 range에 대해 호출해야 합니다. 단, this가 비어 있음이 아니고, 포커스와 앵커가 문서 트리에 있을 때만입니다. 그렇지 않으면 이 메서드는 아무 작업도 하지 않아야 합니다.

Note

이것은 실제로 range를 교체하지 않고 변경(mutates)하는 유일한 메서드입니다. 이는 IE9와 Firefox 12.0a1과 일치합니다. (Chrome 17 개발 버전과 Opera Next 12.00 알파는 getRangeAt()가 복사본을 반환하므로 테스트할 수 없습니다.)

containsNode() method

만약 this가 비어 있음이거나, node의 루트가 this와 연관된 문서가 아니면, 이 메서드는 false를 반환해야 합니다.

그렇지 않으면, 만약 allowPartialContainment이 false이면, 이 메서드는 다음 조건이 모두 성립할 때에만 true를 반환해야 합니다: 자신의 range의 start가 node 안의 첫 번째 경계점보다 앞서거나 시각적으로 동등하고, 그 range의 end가 node 안의 마지막 경계점보다 뒤이거나 시각적으로 동등해야 합니다.

만약 allowPartialContainment이 true이면, 이 메서드는 다음 조건이 모두 성립할 때에만 true를 반환해야 합니다: 자신의 range의 시작이 node 안의 마지막 경계점보다 앞서거나 시각적으로 동등하고, 자신의 range의 끝이 node 안의 첫 번째 경계점보다 뒤이거나 시각적으로 동등해야 합니다.

stringifier

문자열화는 range가 this에 연관되어 있을 경우 렌더된 텍스트들을 연결한 문자열을 반환해야 합니다.

만약 선택이 textarea 또는 input 요소 내에 있으면, 해당 요소의 value에서 선택된 부분 문자열을 반환해야 합니다.

Selection 인터페이스의 모든 멤버는 이 객체가 나타내는(있는 경우) range 객체에 대한 연산을 기준으로 정의됩니다. 이러한 연산은 Range 인터페이스에 대해 정의된 대로 예외를 일으킬 수 있으며, 이로 인해 Selection 인터페이스의 멤버들도 위에 명시된 것 이외에 예외를 일으킬 수 있습니다.

본 명세는 여기서 정의된 인터페이스에 진입점(entry point)을 제공하기 위해 여러 인터페이스를 확장합니다.

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

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

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

사용자 에이전트가 데이터를 대체하거나 부분 문자열을 CharacterData에 대해 처리할 때, 사용자 에이전트는 range를 해당 selection의 node document에서 CharacterData와 연관된 live range처럼 갱신해야 합니다.

사용자 에이전트가 Text 노드를 분할할 때, 사용자 에이전트는 range를 해당 selection의 node document에서 Text와 연관된 live range처럼 갱신해야 합니다.

사용자 에이전트가 normalize() 메서드의 단계를 실행할 때, 사용자 에이전트는 range를 해당 selection의 node document에서 this와 연관된 live range처럼 갱신해야 합니다.

사용자 에이전트가 노드 제거 또는 노드 삽입을 수행할 때, 사용자 에이전트는 range를 해당 selection의 node document에서 노드와 연관된 live range처럼 갱신해야 합니다.

사용자 에이전트는 사용자가 선택을 활성 문서와 연관된 것을 변경할 수 있도록 허용해야 합니다. 사용자가 선택을 수정하면, 사용자 에이전트는 적절한 범위의 시작과 끝을 가지는 새로운 범위를 생성하고 이 새로운 선택을 해당 새로운 범위와 연관시켜야 하며(기존 범위를 수정하지 않습니다), 선택의 방향을 정방향으로 설정해야 합니다. 단, 시작이 이전에 있거나 끝과 같으면 정방향으로, 역방향으로 설정해야 합니다. 만약 끝이 시작보다 이전이면 역방향으로, 플랫폼 관례로 인해 시작과 끝의 순서를 정할 수 없으면 무방향으로 설정해야 합니다.

사용자 에이전트는 어떤 사용자 동작(예: 편집 불가능한 영역 클릭)에 대해서도 이미 비어 있음이 아닌 selection을 비어 있음으로 만들면 안 됩니다.

규범적이지 않은 섹션과 마찬가지로, 이 명세의 모든 작성 가이드라인, 도표, 예제, 참고사항 또한 규범적이지 않습니다. 이 명세의 그 외 모든 사항은 규범적입니다.

이 명세는 다음 한 가지 제품에 적용되는 적합성 기준을 정의합니다: 이 명세가 담고 있는 인터페이스를 구현하는 user agent.

이 표준에는 알려진 보안 고려사항이 없습니다.

사용자의 보조 기술 사용 노출로 인한 잠재적 프라이버시 위험을 완화하기 위해, 예를 들어 user agent는 사용자가 문서의 selection을 수정하도록 선택할 때, selectstart 또는 selectionchange 이벤트와 일반적으로 연관되는 마우스 및 키보드 이벤트를 에뮬레이션하도록 선택할 수 있습니다.