Выбор

Объект Selection представляет собой диапазон текста, выбранный пользователем, или текущую позицию курсора. Каждый document связан с уникальным объектом выбора, который можно получить с помощью document.getSelection() или window.getSelection(), а затем исследовать и изменить.

Пользователь может сделать выбор слева направо (в порядке документа) или справа налево (обратный порядок документа). Якорь — это место, где пользователь начал выбор, а фокус — это место, где пользователь завершил выбор. Если вы делаете выбор с помощью мыши на настольном компьютере, якорь устанавливается в месте нажатия кнопки мыши, а фокус — в месте отпускания кнопки мыши.

Selection.anchorNode Только для чтения

Возвращает Node, в котором начинается выбор. Может возвращать null если выбор никогда не существовал в документе (например, в iframe, на который никогда не нажимали).

Selection.anchorOffset Только для чтения

Возвращает число, представляющее смещение якоря выбора внутри anchorNode. Если anchorNode является узлом текста, это число символов внутри anchorNode, предшествующих якорю. Если anchorNode является элементом, это число дочерних узлов anchorNode , предшествующих якорю.

Selection.direction Только для чтения

Строка, описывающая направление текущего выбора.

Selection.focusNode Только для чтения

Возвращает Node, в котором выбор заканчивается. Может возвращать null если выбор никогда не существовал в документе (например, в iframe на который никогда не нажимали).

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.empty()

Удаляет все диапазоны из выбора, оставляя свойства anchorNode и focusNode равными null и ничего не выбранным.

Selection.extend()

Перемещает фокус выбора в указанную точку.

Selection.getComposedRanges() Экспериментально

Возвращает массив объектов StaticRange, каждый из которых представляет собой выбор, который может пересекать границы DOM-теневых элементов.

Selection.getRangeAt()

Возвращает объект Range, представляющий один из диапазонов, которые в данный момент выбраны.

Selection.modify()

Изменяет текущий выбор.

Selection.removeRange()

Удаляет диапазон из выбора.

Selection.removeAllRanges()

Удаляет все диапазоны из выбора.

Selection.selectAllChildren()

Добавляет всех потомков указанного узла в выбор.

Selection.setBaseAndExtent()

Устанавливает выбор так, чтобы он включал все или части двух указанных узлов DOM и любое содержимое, расположенное между ними.

Selection.setPosition()

Сжимает текущий выбор до одной точки.

Selection.toString()

Возвращает строку, в настоящее время представляемую объектом выбора, т. е. текущий выбранный текст.

Вызов метода Selection.toString() возвращает текст, содержащийся в выборе, например:

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

Обратите внимание, что использование объекта выбора в качестве аргумента для window.alert вызовет метод toString объекта.

Объект выбора представляет собой Range, которые пользователь выбрал. Обычно он содержит только один диапазон, к которому можно обратиться следующим образом:

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

• selObj является объектом Selection
• range является объектом Range

Как отмечается в спецификации Selection API, API Selection был первоначально разработан компанией Netscape и позволял работать с несколькими диапазонами (например, для выбора столбца из <table>). Однако браузеры, отличные от Gecko, не реализовали работу с несколькими диапазонами, и спецификация также требует, чтобы выбор всегда содержал один диапазон.

Выбор и фокус ввода (указанный Document.activeElement) имеют сложные взаимоотношения, которые различаются в разных браузерах. В кроссбраузерном коде лучше обрабатывать их отдельно.

Safari и Chrome (в отличие от Firefox) в настоящее время фокусируют элемент, содержащий выбор, при программно изменении выбора; возможно, это может измениться в будущем (см. W3C ошибку 14383 и WebKit ошибку 38696).

API выбора имеет общее поведение (то есть, общее для браузеров), которое управляет тем, как изменяется поведение фокуса для элементов редактирования после вызова определённых методов.

Поведение следующее:

1. Элемент редактирования получает фокус, если предыдущий выбор находился вне него.
2. Вызывается метод API выбора, вызывая создание нового выбора с диапазоном выбора внутри элемента редактирования.
3. Затем фокус перемещается в элемент редактирования.

Вышеуказанное поведение применяется к выборам, сделанным с помощью следующих методов:

• Selection.collapse()
• Selection.collapseToStart()
• Selection.collapseToEnd()
• Selection.extend()
• Selection.selectAllChildren()
• Selection.addRange()
• Selection.setBaseAndExtent()

И когда Range изменяется с помощью следующих методов:

• Range.setStart()
• Range.setEnd()
• Range.setStartBefore()
• Range.setStartAfter()
• Range.setEndBefore()
• Range.setEndAfter()
• Range.collapse()
• Range.selectNode()
• Range.selectNodeContents()

Другие ключевые термины, используемые в этом разделе.

якорь

Якорь выбора — это начальная точка выбора. При выделении с помощью мыши якорь — это место в документе, где нажата кнопка мыши. По мере изменения выбора пользователем с помощью мыши или клавиатуры якорь не перемещается.

элемент редактирования

Редактируемый элемент (например, элемент HTML с contenteditable установленным или дочерний элемент HTML документа, у которого включен designMode).

фокус выбора

Фокус выбора — это конечная точка выбора. При выделении с помощью мыши фокус — это место в документе, где отпускается кнопка мыши. По мере изменения выбора пользователем с помощью мыши или клавиатуры фокус — это конечная точка выбора, которая перемещается.

Примечание: Это не то же самое, что фокусированный элемент документа, возвращаемый document.activeElement.

диапазон

Диапазон — это непрерывная часть документа. Диапазон может содержать целые узлы, а также части узлов (например, часть текстового узла). Пользователь обычно выбирает только один диапазон за раз, но возможно выбрать несколько диапазонов (например, с помощью клавиши Control). Диапазон можно получить из выбора в виде объекта range. Объекты диапазона также могут быть созданы через DOM и программно добавлены или удалены из выбора.

• Window.getSelection, Document.getSelection, Range
• События, связанные с выделением: selectionchange и selectstart
• HTML-входы предоставляют более простые вспомогательные API для работы с выделением (см. HTMLInputElement.setSelectionRange())
• Document.activeElement, HTMLElement.focus и HTMLElement.blur