XML DOM - объект Range

объект Range представляет собой последовательный диапазон в документе.

объект Range

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

если реализация поддерживает модуль Range, то объект Documentопределяет метод createRange()для создания нового объекта Range.

Примечание:IE определил несовместимый метод Document.createRange(), который возвращает объект, подобный интерфейсу Range, но несовместимый.

интерфейс Range определяет множество методов для определения области "выбранного" документа, а также несколько методов для выполнения операций вырезания и вставки в выбранной области.

свойства интерфейса Range предоставляют методы для получения границ диапазона и смещений. Его методы предоставляют методы для установки границ диапазона. Обратите внимание, что границы диапазона могут быть установлены Document или объект DocumentFragmentв узле. После того как определены крайние точки диапазона, можно использовать методы deleteContents(), extractContents(), cloneContents() и insertNode() для выполнения операций вырезания, копирования и вставки.

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

термин: диапазон, крайняя точка и смещение

диапазон имеет два крайних точки, то есть точку начала и точку окончания. Каждая крайняя точка определяется узлом и смещением этого узла. Этот узел обычно является узел Elementиузел Documentили узел TextДля узлов Element и Document, смещение указывает на подузел этого узла. Смещение 0 означает, что граница находится перед первым подузлом узла. Смещение 1 означает, что граница находится после первого подузла узла, перед вторым подузлом. Но если границей является узел Text, смещение указывает на положение между двумя символами в тексте.

Константы объекта Range

Эти константы определяют способ сравнения границ объектов Range

Они являются параметрами метода compareBoundaryPoints() how Допустимые значения параметра:

Константы Описание
START_TO_START Сравнивает начало заданного диапазона с концом текущего диапазона
START_TO_END Сравнивает конец заданного диапазона с концом текущего диапазона
END_TO_END Сравнивает конец заданного диапазона с концом текущего диапазона
END_TO_START Сравнивает конец заданного диапазона с началом текущего диапазона

Атрибуты объекта Range

Примечание:Все атрибуты являются только для чтения, изменять начало и конец диапазона через эти атрибуты нельзя, для этого необходимо вызывать методы setEnd() и setStart()

Примечание:Любое чтение этих атрибутов после вызова метода detach() вызовет исключение INVALID_STATE_ERR DOMException исключение.

Атрибуты Описание
collapsed Если начало и конец диапазона находятся в одном месте документа, то true, то есть диапазон пуст или сложен
commonAncestorContainer Начальная и конечная точки диапазона (то есть их предшественники), наиболее глубокий документальный узел, вложенный в них
endContainer Документальный узел, содержащий конец точки диапазона
endOffset Позиция конца точки в endContainer
startContainer Документальный узел, содержащий начало точки диапазона
startOffset Позиция начала точки в startContainer

Методы объекта Range

Примечание:Если был вызван метод detach() диапазона, то следующий вызов любого метода объекта Range вызовет исключение INVALID_STATE_ERR DOMException исключение.

Метод Описание
cloneContents() Возвращает новый объект DocumentFragment, содержащий копию документальной области, представляемой этим диапазоном.
cloneRange() Создать новый объект Range, представляющий документальную область, такую же, как и текущий объект Range.
collapse() Свернуть диапазон, чтобы его граница точилась.
compareBoundaryPoints() Сравнить границу диапазона с границей текущего диапазона и вернуть -1, 0 или 1 в зависимости от их порядка. Сравнивать哪个 границу определяет первый параметр, его значение должно быть одним из заранее определённых констант.
deleteContents() Удалить документную область, представленную текущим объектом Range.
detach() Уведомить реализацию о том, что текущий диапазон больше не используется, и можно прекратить отслеживание. Если был вызван этот метод диапазона, то следующий вызов любого метода этого диапазона вызовет исключение INVALID_STATE_ERR. DOMException исключение.
extractContents() Удалить документную область, представленную текущим диапазоном, и вернуть содержимое этой области в виде объекта DocumentFragment. Этот метод очень похож на комбинацию методов deleteContents() и cloneContents().
insertNode() Вставить указанный узел в начало диапазона документа.
selectNode() Установить границу этого диапазона так, чтобы он содержал указанный узел и все его дети.
selectNodeContents() Установить границу этого диапазона так, чтобы он содержал все дети указанного узла, но не включал сам узел.
setEnd() Установить конец этого диапазона в указанном узле и смещении.
setEndAfter() Установить конец этого диапазона вплотную после указанного узла.
setEndBefore() Установить конец этого диапазона вплотную перед указанным узлом.
setStart() Установить начало этого диапазона в указанном узле и смещении.
setStartAfter() Установить начало этого диапазона вплотную после указанного узла.
setStartBefore() Установить начало этого диапазона вплотную перед указанным узлом.
surroundContents() Вставить指定的 узел в начало диапазона документа, затем перенастроить родительские узлы всех узлов в диапазоне, чтобы они стали детьми нового вставленного узла.
toString() Вернуть текстовый контент области документа, представленной этим диапазоном.