Интерфейс Node

Интерфейс Node является основным типом данных для всего Document Object Model. Он представляет собой отдельный узел в дереве документа. Хотя все объекты, реализующие интерфейс Node, предоставляют методы для работы с дочерними элементами, не все объекты, реализующие интерфейс Node, могут иметь дочерние элементы. Например, узлы Text могут не иметь дочерних элементов, и добавление дочерних элементов к таким узлам приводит к возникновению исключения DOMException.

Атрибуты nodeName, nodeValue и attributes включены для доступа к информации узла без приведения к конкретному производному интерфейсу. В тех случаях, когда для определенного nodeType нет очевидной связи этих атрибутов (например, nodeValue для Element или attributes для Comment), возвращается значение null. Обратите внимание, что специализированные интерфейсы могут содержать дополнительные и более удобные механизмы для получения и установки соответствующей информации.

Значения nodeName, nodeValue, и attributes изменяются в зависимости от типа узла следующим образом:

См. также Спецификацию Document Object Model (DOM) Level 3 Core.

Поля

ELEMENT_NODE

static final short ELEMENT_NODE

Узел является Element.

См. также:

Значения константных полей

ATTRIBUTE_NODE

static final short ATTRIBUTE_NODE

Узел является Attr.

См. также:

Значения константных полей

TEXT_NODE

static final short TEXT_NODE

Узел является узлом Text.

См. также:

Значения константных полей

CDATA_SECTION_NODE

static final short CDATA_SECTION_NODE

Узел является CDATASection.

См. также:

Значения константных полей

ENTITY_REFERENCE_NODE

static final short ENTITY_REFERENCE_NODE

Узел является EntityReference.

См. также:

Значения константных полей

ENTITY_NODE

static final short ENTITY_NODE

Узел является Entity.

См. также:

Значения константных полей

PROCESSING_INSTRUCTION_NODE

static final short PROCESSING_INSTRUCTION_NODE

Узел является ProcessingInstruction.

См. также:

Значения константных полей

COMMENT_NODE

static final short COMMENT_NODE

Узел является Comment.

См. также:

Значения константных полей

DOCUMENT_NODE

static final short DOCUMENT_NODE

Узел является Document.

См. также:

Значения константных полей

DOCUMENT_TYPE_NODE

static final short DOCUMENT_TYPE_NODE

Узел является DocumentType.

См. также:

Значения константных полей

DOCUMENT_FRAGMENT_NODE

static final short DOCUMENT_FRAGMENT_NODE

Узел является DocumentFragment.

См. также:

Значения константных полей

NOTATION_NODE

static final short NOTATION_NODE

Узел является Notation.

См. также:

Значения константных полей

DOCUMENT_POSITION_DISCONNECTED

static final short DOCUMENT_POSITION_DISCONNECTED

Два узла отключены. Порядок между отключёнными узлами всегда зависит от реализации.

См. также:

Значения константных полей

DOCUMENT_POSITION_PRECEDING

static final short DOCUMENT_POSITION_PRECEDING

Второй узел предшествует узлу-ссылке.

См. также:

Значения константных полей

DOCUMENT_POSITION_FOLLOWING

static final short DOCUMENT_POSITION_FOLLOWING

Узел следует за узлом-ссылкой.

См. также:

Значения константных полей

DOCUMENT_POSITION_CONTAINS

static final short DOCUMENT_POSITION_CONTAINS

Узел содержит узел-ссылку. Узел, содержащий другой, всегда предшествует ему.

См. также:

Значения константных полей

DOCUMENT_POSITION_CONTAINED_BY

static final short DOCUMENT_POSITION_CONTAINED_BY

Узел содержится внутри узла-ссылки. Узел, содержащийся в другом, всегда следует за ним.

См. также:

Значения константных полей

DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC

static final short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC

Определение предшествующего или последующего узла зависит от реализации.

См. также:

Значения константных полей

Методы

getNodeName

String getNodeName()

Имя этого узла, зависящее от его типа; см. таблицу выше.

getNodeValue

String getNodeValue()
             throws DOMException

Значение этого узла, зависящее от его типа; см. таблицу выше. Если оно определено как null, установка значения не имеет эффекта, включая случай, если узел является только для чтения.

Исключения:

DOMException - DOMSTRING_SIZE_ERR: Возникает, если возвращается больше символов, чем может поместиться в переменной типа DOMString на платформе реализации.

setNodeValue

void setNodeValue(String nodeValue)
           throws DOMException

Значение этого узла, зависящее от его типа; см. таблицу выше. Если оно определено как null, установка значения не имеет эффекта, включая случай, если узел является только для чтения.

Исключения:

DOMException - NO_MODIFICATION_ALLOWED_ERR: Возникает, если узел только для чтения и если его значение не определено как null.

getNodeType

short getNodeType()

Код, представляющий тип базового объекта, как определено выше.

getParentNode

Node getParentNode()

Родительский узел. Все узлы, кроме Attr, Document, DocumentFragment, Entity, и Notation могут иметь родителя. Однако, если узел только что был создан и ещё не добавлен в дерево, или если он был удален из дерева, это null.

getChildNodes

NodeList getChildNodes()

Объект NodeList, содержащий всех потомков этого узла. Если потомков нет, это NodeList без узлов.

getFirstChild

Node getFirstChild()

Первый потомок этого узла. Если такого узла нет, возвращает null.

getLastChild

Node getLastChild()

Последний потомок этого узла. Если такого узла нет, возвращает null.

getPreviousSibling

Node getPreviousSibling()

Узел, непосредственно предшествующий этому узлу. Если такого узла нет, возвращает null.

getNextSibling

Node getNextSibling()

Узел, непосредственно следующий за этим узлом. Если такого узла нет, возвращает null.

getAttributes

NamedNodeMap getAttributes()

Объект NamedNodeMap, содержащий атрибуты этого узла (если это Element) или null в противном случае.

getOwnerDocument

Document getOwnerDocument()

Объект Document , связанный с этим узлом. Это также объект Document , используемый для создания новых узлов. Когда этот узел является Document или DocumentType , который ещё не используется ни с каким Document , это null.

С момента:

DOM Level 2

insertBefore

Node insertBefore(Node newChild,
                  Node refChild)
           throws DOMException

Параметры:

newChild - Узел для вставки.

refChild - Узел-ссылка, т.е., узел перед которым должен быть вставлен новый узел.

Возвращает:

Вставляемый узел.

Исключения:

DOMException - HIERARCHY_REQUEST_ERR: Возникает, если этот узел имеет тип, не допускающий потомков указанного типа узла newChild, или если вставляемый узел является одним из предков этого узла или самим этим узлом, или если этот узел имеет тип Document и приложение DOM пытается вставить второй узел типа DocumentType или Element .
WRONG_DOCUMENT_ERR: Возникает, если newChild был создан в другом документе, чем тот, который создал этот узел.
NO_MODIFICATION_ALLOWED_ERR: Возникает, если этот узел только для чтения или если родитель вставляемого узла также только для чтения.
NOT_FOUND_ERR: Возникает, если refChild не является потомком этого узла.
NOT_SUPPORTED_ERR: если этот узел имеет тип Document, это исключение может быть вызвано, если реализация DOM не поддерживает вставку узла типа DocumentType или Element.

С момента:

DOM Level 3

replaceChild

Node replaceChild(Node newChild,
                  Node oldChild)
           throws DOMException

Параметры:

newChild - Новый узел для добавления в список дочерних узлов.

oldChild - Узел, который заменяется в списке.

Возвращает:

Замененный узел.

Выбрасывает:

DOMException - HIERARCHY_REQUEST_ERR: Выбрасывается, если тип этого узла не допускает дочерние узлы указанного типа newChild, или если добавляемый узел является предком или самим этим узлом, или если этот узел имеет тип Document, и операция замены добавит второй DocumentType или Element на узел Document.
WRONG_DOCUMENT_ERR: Выбрасывается, если newChild был создан в другом документе, нежели тот, который создал этот узел.
NO_MODIFICATION_ALLOWED_ERR: Выбрасывается, если этот узел или родительский узел нового узла является только для чтения.
NOT_FOUND_ERR: Выбрасывается, если oldChild не является дочерним узлом этого узла.
NOT_SUPPORTED_ERR: если этот узел имеет тип Document, это исключение может быть выброшено, если реализация DOM не поддерживает замену дочернего узла DocumentType или Element.

С:

DOM Level 3

removeChild

Node removeChild(Node oldChild)
          throws DOMException

Удаляет дочерний узел, указанный в oldChild, из списка дочерних узлов и возвращает его.

Параметры:

oldChild - Узел, который удаляется.

Возвращает:

Удаленный узел.

Выбрасывает:

DOMException - NO_MODIFICATION_ALLOWED_ERR: Выбрасывается, если этот узел является только для чтения.
NOT_FOUND_ERR: Выбрасывается, если oldChild не является дочерним узлом этого узла.
NOT_SUPPORTED_ERR: если этот узел имеет тип Document, это исключение может быть выброшено, если реализация DOM не поддерживает удаление дочернего узла DocumentType или Element.

С:

DOM Level 3

appendChild

Node appendChild(Node newChild)
          throws DOMException

Добавляет узел newChild в конец списка дочерних узлов этого узла. Если newChild уже находится в дереве, он сначала удаляется.

Параметры:

newChild - Узел для добавления. Если это объект DocumentFragment, все содержимое фрагмента документа перемещается в список дочерних узлов этого узла.

Возвращает:

Добавленный узел.

Выбрасывает:

DOMException - HIERARCHY_REQUEST_ERR: Выбрасывается, если тип этого узла не допускает дочерние узлы указанного типа newChild, или если добавляемый узел является предком или самим этим узлом, или если этот узел имеет тип Document, и приложение DOM пытается добавить второй DocumentType или Element узел.
WRONG_DOCUMENT_ERR: Выбрасывается, если newChild был создан в другом документе, нежели тот, который создал этот узел.
NO_MODIFICATION_ALLOWED_ERR: Выбрасывается, если этот узел или предыдущий родитель вставляемого узла является только для чтения.
NOT_SUPPORTED_ERR: если узел newChild является дочерним узлом узла Document, это исключение может быть выброшено, если реализация DOM не поддерживает удаление дочерних узлов DocumentType или Element.

С:

DOM Level 3

hasChildNodes

boolean hasChildNodes()

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

Возвращает:

Возвращает true, если у этого узла есть дочерние узлы, false в противном случае.

cloneNode

Node cloneNode(boolean deep)

Возвращает дубликат этого узла, т.е. служит универсальным конструктором копирования для узлов. Дублированный узел не имеет родителя (parentNode является null) и данных пользователя. Данные пользователя, связанные с импортированным узлом, не переносятся. Однако, если указаны обработчики UserDataHandlers вместе с ассоциированными данными, эти обработчики будут вызваны с соответствующими параметрами перед возвратом этого метода.
Клонирование Element копирует все атрибуты и их значения, включая те, которые сгенерированы обработчиком XML для представления атрибутов по умолчанию, но этот метод не копирует никакие дочерние узлы, если это не глубокая копия. Это включает текст, содержащийся в Element, так как текст содержится в дочернем узле Text. Клонирование Attr непосредственно, а не как часть операции клонирования Element, возвращает указанный атрибут (specified является true). Клонирование Attr всегда клонирует его дочерние узлы, так как они представляют его значение, независимо от того, является ли это глубокой копией или нет. Клонирование EntityReference автоматически строит его поддерево, если соответствующий Entity доступен, независимо от того, является ли это глубокой копией или нет. Клонирование любого другого типа узла просто возвращает копию этого узла.
Обратите внимание, что клонирование неизменяемого поддерева приводит к изменяемой копии, но дочерние узлы узла EntityReference при клонировании являются только для чтения. Кроме того, клонированные узлы Attr указываются, а клонирование Document, DocumentType, Entity и Notation узлов зависит от реализации.

Параметры:

deep - Если true, рекурсивно клонирует поддерево под указанным узлом; если false, клонирует только сам узел (и его атрибуты, если это Element).

Возвращает:

Дублированный узел.

normalize

void normalize()

С:

DOM Level 3

isSupported

boolean isSupported(String feature,
                    String version)

Проверяет, реализует ли реализация DOM определённый функциональный параметр и поддерживается ли этот функциональный параметр этим узлом, как указано в .

Параметры:

feature - Название функционального параметра для проверки.

version - Это номер версии функционального параметра для проверки.

Возвращает:

Возвращает true, если указанный функциональный параметр поддерживается этим узлом, false в противном случае.

С:

DOM Level 2

getNamespaceURI

String getNamespaceURI()

С:

DOM Level 2

getPrefix

String getPrefix()

Префикс пространства имён этого узла, или null, если он не указан. Когда он определён как null, его установка не оказывает никакого влияния, включая случай, если узел является только для чтения.
Обратите внимание, что установка этого атрибута, когда это разрешено, изменяет атрибут nodeName, который содержит полное имя, а также атрибуты tagName и name интерфейсов Element и Attr, когда это применимо.
Установка префикса в null делает его неопределённым, установка его в пустую строку зависит от реализации.
Обратите также внимание, что изменение префикса атрибута, для которого известно значение по умолчанию, не создаёт новый атрибут со значением по умолчанию и исходным префиксом, так как namespaceURI и localName не изменяются.
Для узлов любого типа, кроме ELEMENT_NODE и ATTRIBUTE_NODE, и узлов, созданных с помощью метода DOM Level 1, такого как createElement из интерфейса Document, это всегда null.

С:

DOM Level 2

setPrefix

void setPrefix(String prefix)
        throws DOMException

Префикс пространства имён этого узла, или null, если он не указан. Когда он определён как null, его установка не оказывает никакого влияния, включая случай, если узел является только для чтения.
Обратите внимание, что установка этого атрибута, когда это разрешено, изменяет атрибут nodeName, который содержит полное имя, а также атрибуты tagName и name интерфейсов Element и Attr, когда это применимо.
Установка префикса в null делает его неопределённым, установка его в пустую строку зависит от реализации.
Обратите также внимание, что изменение префикса атрибута, для которого известно значение по умолчанию, не создаёт новый атрибут со значением по умолчанию и исходным префиксом, так как namespaceURI и localName не изменяются.
Для узлов любого типа, кроме ELEMENT_NODE и ATTRIBUTE_NODE, и узлов, созданных с помощью метода DOM Level 1, такого как createElement из интерфейса Document, это всегда null.

Исключения:

DOMException - INVALID_CHARACTER_ERR: Выбрасывается, если указанный префикс содержит недопустимый символ в соответствии с используемой версией XML, указанной в атрибуте Document.xmlVersion.
NO_MODIFICATION_ALLOWED_ERR: Выбрасывается, если этот узел является только для чтения.
NAMESPACE_ERR: Выбрасывается, если указанный prefix имеет неправильный формат в соответствии со спецификацией XML Namespaces, если namespaceURI этого узла имеет значение null, если указанный префикс равен "xml", а namespaceURI этого узла отличается от " http://www.w3.org/XML/1998/namespace", если этот узел является атрибутом и указанный префикс равен "xmlns", а namespaceURI этого узла отличается от "http://www.w3.org/2000/xmlns/", или если этот узел является атрибутом и qualifiedName этого узла равно "xmlns" [XML Namespaces] .

С:

DOM Level 2

getLocalName

String getLocalName()

Возвращает локальную часть квалифицированного имени этого узла.
Для узлов любого типа, кроме ELEMENT_NODE и ATTRIBUTE_NODE, и узлов, созданных с помощью метода DOM Level 1, например Document.createElement(), это всегда null.

С:

DOM Level 2

hasAttributes

boolean hasAttributes()

Возвращает, имеет ли этот узел (если это элемент) какие-либо атрибуты.

Возвращает:

Возвращает true, если этот узел имеет какие-либо атрибуты, false в противном случае.

С:

DOM Level 2

getBaseURI

String getBaseURI()

Абсолютный базовый URI этого узла или null, если реализация не смогла получить абсолютный URI. Это значение вычисляется, как описано в . Однако, когда Document поддерживает функцию "HTML" [DOM Level 2 HTML] , базовый URI вычисляется с использованием сначала значения атрибута href элемента HTML BASE, если он есть, и значения атрибута documentURI из интерфейса Document в противном случае.

С:

DOM Level 3

compareDocumentPosition

short compareDocumentPosition(Node other)
                       throws DOMException

Сравнивает узел-ссылку, т.е. узел, на котором вызывается этот метод, с узлом, т.е. переданным в качестве параметра, относительно их позиции в документе и в соответствии с порядком документа.

Параметры:

other - Узел для сравнения с узлом-ссылкой.

Возвращает:

Возвращает, как узел расположен относительно узла-ссылки.

Исключения:

DOMException - NOT_SUPPORTED_ERR: когда сравниваемые узлы происходят из разных реализаций DOM, которые не координируются для возвращения согласованных результатов, специфичных для реализации.

С:

DOM Level 3

getTextContent

String getTextContent()
               throws DOMException

Этот атрибут возвращает текстовое содержимое этого узла и его потомков. Если он определён как null, установка не имеет эффекта. При установке, любые возможные дочерние элементы этого узла удаляются и, если новая строка не пустая или null, заменяются одним узлом Text, содержащим строку, к которой установлен данный атрибут.
При получении не выполняется сериализация, возвращаемая строка не содержит разметки. Не выполняется нормализация пробелов, и возвращаемая строка не содержит пробелов в содержимом элемента (см. атрибут Text.isElementContentWhitespace). Аналогично, при установке не выполняется разбор, входная строка рассматривается как чистое текстовое содержимое.
Возвращаемая строка состоит из текстового содержимого этого узла в зависимости от его типа, как определено ниже:

Исключения:

DOMException - DOMSTRING_SIZE_ERR: Выбрасывается, когда возвращаются больше символов, чем помещается в переменную DOMString на платформе реализации.

С:

DOM Level 3

setTextContent

void setTextContent(String textContent)
             throws DOMException

Этот атрибут возвращает текстовое содержимое этого узла и его потомков. Если он определён как null, установка не имеет эффекта. При установке, любые возможные дочерние элементы этого узла удаляются и, если новая строка не пустая или null, заменяются одним узлом Text, содержащим строку, к которой установлен данный атрибут.
При получении не выполняется сериализация, возвращаемая строка не содержит разметки. Не выполняется нормализация пробелов, и возвращаемая строка не содержит пробелов в содержимом элемента (см. атрибут Text.isElementContentWhitespace). Аналогично, при установке не выполняется разбор, входная строка рассматривается как чистое текстовое содержимое.
Возвращаемая строка состоит из текстового содержимого этого узла в зависимости от его типа, как определено ниже:

Исключения:

DOMException - NO_MODIFICATION_ALLOWED_ERR: Выбрасывается, когда узел является только для чтения.

С:

DOM Level 3

isSameNode

boolean isSameNode(Node other)

Возвращает, является ли этот узел тем же узлом, что и данный.
Этот метод предоставляет способ определить, ссылаются ли две ссылки Node от реализации на один и тот же объект. Когда две ссылки Node являются ссылками на один и тот же объект, даже если через прокси, ссылки могут использоваться полностью взаимозаменяемо, так что все атрибуты имеют одинаковые значения, и вызов одного и того же метода DOM на любой ссылке всегда имеет точно такой же эффект.

Параметры:

other - Узел для проверки.

Возвращает:

Возвращает true если узлы одинаковые, false в противном случае.

С:

DOM Level 3

lookupPrefix

String lookupPrefix(String namespaceURI)

Ищет префикс, связанный с заданным URI пространства имён, начиная с этого узла. Объявления пространства имён по умолчанию игнорируются этим методом.
См. для получения подробностей об алгоритме, используемом этим методом.

Параметры:

namespaceURI - URI пространства имён для поиска.

Возвращает:

Возвращает связанный префикс пространства имён, если он найден, или null если не найден. Если более одного префикса связаны с префиксом пространства имён, возвращаемый префикс пространства имён зависит от реализации.

С:

DOM Level 3

isDefaultNamespace

boolean isDefaultNamespace(String namespaceURI)

Этот метод проверяет, является ли указанный namespaceURI пространством имён по умолчанию или нет.

Параметры:

namespaceURI - URI пространства имён для поиска.

Возвращает:

Возвращает true если указанный namespaceURI является пространством имён по умолчанию, false в противном случае.

С:

DOM Level 3

lookupNamespaceURI

String lookupNamespaceURI(String prefix)

Ищет URI пространства имён, связанный с данным префиксом, начиная с этого узла.
См. для получения подробностей об алгоритме, используемом этим методом.

Параметры:

prefix - Префикс для поиска. Если этот параметр null, метод вернёт URI пространства имён по умолчанию, если таковой имеется.

Возвращает:

Возвращает связанный URI пространства имён или null если не найден.

С:

DOM Level 3

isEqualNode

boolean isEqualNode(Node arg)

Параметры:

arg - Узел для сравнения на равенство.

Возвращает:

Возвращает true если узлы равны, false в противном случае.

С:

DOM Level 3

getFeature

Object getFeature(String feature,
                  String version)

Этот метод возвращает специализированный объект, который реализует специализированные API указанной функции и версии, как указано в . Специализированный объект также может быть получен с помощью методов преобразования, специфичных для связывания, но это не обязательно, как обсуждалось в . Этот метод также позволяет реализации предоставлять специализированные объекты, которые не поддерживают интерфейс Node.

Параметры:

feature - Имя запрашиваемой функции. Обратите внимание, что любой знак «плюс» «+», предшествующий имени функции, будет проигнорирован, так как он не имеет значения в контексте этого метода.

version - Номер версии функции для проверки.

Возвращает:

Возвращает объект, который реализует специализированные API указанной функции и версии, если таковой существует, или null если нет объекта, реализующего интерфейсы, связанные с данной функцией. Если DOMObject возвращаемый этим методом, реализует интерфейс Node, он должен делегировать основному ядру Node и не возвращать результаты, несовместимые с основным ядром Node, такие как атрибуты, childNodes и т.д.

С:

DOM Level 3

setUserData

Object setUserData(String key,
                   Object data,
                   UserDataHandler handler)

Ассоциирует объект с ключом в этом узле. Объект можно позже извлечь из этого узла, вызвав getUserData с тем же ключом.

Параметры:

key - Ключ для ассоциации объекта.

data - Объект для ассоциации с заданным ключом, или null для удаления любой существующей ассоциации с этим ключом.

handler - Обработчик для ассоциации с этим ключом, или null.

Возвращает:

Возвращает DOMUserData ранее ассоциированный с данным ключом в этом узле, или null если его не было.

С:

DOM Level 3

getUserData

Object getUserData(String key)

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

Параметры:

key - Ключ, к которому привязан объект.

Возвращает:

Возвращает DOMUserData связанный с данным ключом в этом узле, или null если его не было.

С:

DOM Level 3