DOM | Интерфейс Document

IDL

[Exposed=Window]
interface Document : Node {
   constructor();

   [SameObject] readonly attribute DOMImplementation implementation;
   readonly attribute USVString URL;
   readonly attribute USVString documentURI;
   readonly attribute DOMString compatMode;
   readonly attribute DOMString characterSet;
   readonly attribute DOMString charset; // исторический псевдоним .characterSet
   readonly attribute DOMString inputEncoding; // исторический псевдоним .characterSet
   readonly attribute DOMString contentType;

   readonly attribute DocumentType? doctype;
   readonly attribute Element? documentElement;
   HTMLCollection getElementsByTagName(DOMString qualifiedName);
   HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
   HTMLCollection getElementsByClassName(DOMString classNames);

   [CEReactions, NewObject] Element createElement(DOMString localName, optional (DOMString or ElementCreationOptions) options = {});
   [CEReactions, NewObject] Element createElementNS(DOMString? namespace, DOMString qualifiedName, optional (DOMString or ElementCreationOptions) options = {});
   [NewObject] DocumentFragment createDocumentFragment();
   [NewObject] Text createTextNode(DOMString data);
   [NewObject] CDATASection createCDATASection(DOMString data);
   [NewObject] Comment createComment(DOMString data);
   [NewObject] ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);

   [CEReactions, NewObject] Node importNode(Node node, optional boolean deep = false);
   [CEReactions] Node adoptNode(Node node);

   [NewObject] Attr createAttribute(DOMString localName);
   [NewObject] Attr createAttributeNS(DOMString? namespace, DOMString qualifiedName);

   [NewObject] Event createEvent(DOMString interface); // исторический

   [NewObject] Range createRange();

   // NodeFilter.SHOW_ALL = 0xFFFFFFFF
   [NewObject] NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
   [NewObject] TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
};

[Exposed=Window]
interface XMLDocument : Document {};

dictionary ElementCreationOptions {
   DOMString is;
};

 

Узлы Document просто известны как «документы» (documents).

Каждый документ имеет связанную «кодировку» (encoding), «тип содержимого» (content type — строка), «URL» (URL), «источник» (origin), «тип» (type — «xml» или «html») и «режим» (mode — «no-quirks«, «quirks«, or «limited-quirks» («без причуд», «причуды» или «ограниченные причуды»)). [ENCODING] [URL] [HTML]

Если не указано иное, кодировка документа — это кодировка utf-8, тип контента — «application/xml», URL — «about: blank», источникнепрозрачный источник, тип — «xml», а его режим — «no-quirks«.

Документ называется «XML-документом» (XML document), если его тип — «xml», и «HTML-документом» (HTML document) в противном случае. Независимо от того, является ли документ HTML-документом или XML-документом, влияет на поведение определенных API.

Считается, что документ находится в «режиме без причуд» (no-quirks mode), если его режим «no-quirks«, в «режиме причуд» (quirks mode), если его режим «quirks«, и в «режиме с ограниченными причудами» (limited-quirks mode), если его режим «limited-quirks«.

 

Примечание!

Режим по умолчанию изменяется только для документов, созданных синтаксическим анализатором HTML на основе наличия, отсутствия или значения строки DOCTYPE, а также с помощью нового контекста просмотра (начальное «about:blank»). [HTML]

Режим без причуд изначально был известен как «стандартный режим», а режим с ограниченными причудами когда-то был известен как «почти стандартный режим». Они были переименованы, потому что их детали теперь определены стандартами. (И потому, что Ян Хиксон наложил вето на их оригинальные имена на том основании, что они бессмысленны.)

При заданном событии event алгоритм получения родителя документа возвращает null, если значение атрибута типа type события event равно «load» или документ не имеет контекста просмотра, а в противном случае — соответствующий глобальный объект документа.

 

Для веб-разработчиков (не нормативно)

document = new Document()

Возвращает новый документ.

document . implementation

Возвращает объект DOMImplementation документа document.

document . URL

document . documentURI

Возвращает URL документа document.

document . compatMode

Возвращает строку «BackCompat», если режим документа document — «quirks», и «CSS1Compat» в противном случае.

document . characterSet

Возвращает кодировку документа document.

document . contentType

Возвращает тип содержимого документа document.

Конструктор Document() при вызове должен возвращать новый документ, источником которого является источник документа Document, связанного с текущим глобальным объектом. [HTML]

Примечание!

В отличие от createDocument(), этот конструктор возвращает не объект XMLDocument, а документ (объект Document).

Получатель атрибута implementation (реализация) должен возвращать объект DOMImplementation, связанный с документом.

Получатель атрибута URL и получатель атрибута documentURI должны возвращать сериализованный URL.

Получатель атрибута compatMode должен возвращать «BackCompat«, если режим этого this «quirks«, и «CSS1Compat» в противном случае.

Получатель атрибута characterSet, получатель атрибута charset и получатель атрибута inputEncoding должны возвращать имя кодировки этого this.

Получатель атрибута contentType должен возвращать тип контента.

 

Для веб-разработчиков (не нормативно)

document . doctype

Возвращает doctype или null, если его нет.

document . documentElement

Возвращает элемент документа.

collection = document . getElementsByTagName(qualifiedName)

Если qualifiedName — «*», возвращает HTMLCollection всех элементов потомков.

В противном случае возвращает HTMLCollection всех элементовпотомков, чье полное имяqualifiedName. (Сопоставляет без учета регистра элементов в пространстве имен HTML в документе HTML.)

collection = document . getElementsByTagNameNS(namespace, localName)

Если namespace и localName равны «*», возвращает HTMLCollection всех элементовпотомков.

Если только namespace равно «*», возвращает HTMLCollection всех элементовпотомков, локальное имя которых — localName.

Если только localName имеет значение «*», возвращает HTMLCollection всех элементовпотомков, пространство имен которых является namespace.

В противном случае возвращает HTMLCollection всех элементовпотомков, пространство имен которых является namespace, а локальное имяlocalName.

collection = document . getElementsByClassName(classNames)

collection = element . getElementsByClassName(classNames)

Возвращает HTMLCollection элементов в объекте, для которого был вызван метод (документ или элемент), у которых есть все классы, заданные classNames. Аргумент classNames интерпретируется как список классов, разделенных пробелами.

 

Получатель атрибута doctype должен возвращать ребёнка документа, который является типом документа, в противном случае — null.

Получатель атрибута documentElement должен возвращать элемент документа.

Метод getElementsByTagName(qualifiedName) при вызове должен возвращать список элементов с полным именем qualifiedName для этого this.

 

Примечание!

Таким образом, в HTML-документе запись document.getElementsByTagName(«FOO») будет соответствовать элементам <FOO>, которые не находятся в пространстве имен HTML, и элементам <foo>, которые находятся в пространстве имен HTML, но не элементам <FOO>, которые находятся в пространство имен HTML.

 

Метод getElementsByTagNameNS(namespace, localName) при вызове должен возвращать список элементов с пространством имен namespace и локальным именем localName для этого this.

Метод getElementsByClassName(classNames) при вызове должен возвращать список элементов с именами классов classNames для этого this.

 

Пример

Учитывая следующий фрагмент XHTML:

<div id="example">
   <p id="p1" class="aaa bbb"/>
   <p id="p2" class="aaa ccc"/>
   <p id="p3" class="bbb ccc"/>
</div>

Вызов document.getElementById(«example»).getElementsByClassName(«aaa») вернет HTMLCollection с двумя параграфами p1 и p2 в нем.

Однако вызов getElementsByClassName(«ccc bbb») вернет только один узел, а именно p3. Вызов document.getElementById(«example»).getElementsByClassName(«bbb ccc «) вернет то же самое.

Вызов getElementsByClassName(«aaa,bbb») не вернет узлов; ни один из вышеперечисленных элементов не входит в класс aaa, bbb.

 

Для веб-разработчиков (не нормативно)

element = document . createElement(localName [, options])

Возвращает элемент с localName в качестве локального имени (если document является HTML-документом, localName переводится в нижний регистр). Пространство имен элемента — это пространство имен HTML, если document является документом HTML или тип содержимого документа document — «application/xhtml+xml», в противном случае — null.

Если localName не соответствует продукту Name, будет выброшено исключение DOMException «InvalidCharacterError».

При поставке параметры options is можно использовать для создания настраиваемого встроенного элемента.

element = document . createElementNS(namespace, qualifiedName [, options])

Возвращает элемент с пространством имен namespace. Его префиксом пространства имен будет все, что находится перед «:» (U+003E) в qualifiedName или null. Его локальным именем будет все, что находится после «:» (U+003E) в qualifiedName или qualifiedName.

Если localName не соответствует продукту Name, будет выброшено исключение DOMException «InvalidCharacterError».

Если выполняется одно из следующих условий, будет выброшено исключение DOMException «NamespaceError«:

localName не соответствует продукту QName.

Префикс пространства имен не равен null, а namespace — это пустая строка.

Префикс пространства имен — «xml», а namespace не является пространством имен XML.

qualifiedName или префикс пространства имен — «xmlns», а namespace не является пространством имен XMLNS.

namespace — это пространство имен XMLNS, и ни qualifiedName, ни префикс пространства имен не являются «xmlns».

При наличии опции options «is» можно использовать для создания настраиваемого встроенного элемента.

documentFragment = document . createDocumentFragment()

Возвращает узел DocumentFragment.

text = document . createTextNode(data)

Возвращает узел Text, данные которого являются data.

text = document . createCDATASection(data)

Возвращает узел CDATASection, данные которого являются data.

comment = document . createComment(data)

Возвращает узел комментария Comment, данные которого являются data.

processingInstruction = document . createProcessingInstruction(target, data)

Возвращает узел ProcessingInstruction, цель которого — target, а данныеdata. Если target не соответствует продукту Name, будет выброшено исключение DOMException «InvalidCharacterError». Если data содержат «?>», Будет выброшено исключение DOMException «InvalidCharacterError».

 

«Интерфейс элемента» (element interface) для любого имени name и пространства имен namespace является Element, если не указано иное.

 

Примечание!

Стандарт HTML будет, например, определите, что для html и пространства имен HTML используется интерфейс HTMLHtmlElement. [HTML]

Метод createElement(localName, options) при вызове должен выполнить следующие шаги:

1. Если localName не совпадает с производством Name, генерируется исключение DOMException «InvalidCharacterError».
2. Если этот this является документом HTML, установите для localName значение localName в нижнем регистре ASCII.
3. Пусть is будет null.
4. Если options - это словарь и is options присутствует, то установите is на него.
5. Пусть пространство имен namespace будет пространством имен HTML, если этот this является документом HTML или тип содержимого этого this - «application/xhtml+xml», и null в противном случае.
6. Вернуть результат создания элемента с учетом this, localName, namespace, null, is и с установленным флагом синхронных настраиваемых элементов (synchronous custom elements).

«Внутренние шаги createElementNS» (internal createElementNS steps) для данного документа document, пространства имен namespace, квалифицированного имени qualifiedName и параметров options следующие:

1. Пусть namespace, prefix и localName будут результатом передачи namespace и qualifiedName для проверки и извлечения.
2. Пусть is будет null.
3. Если options - это словарь и is options присутствует, то установите is на него.
4. Вернуть результат создания элемента с заданным document, localName, namespace, prefix, is и с установленным флагом синхронных настраиваемых элементов (synchronous custom elements).

 

Метод createElementNS(namespace, qualifiedName, options) при вызове должен возвращать результат выполнения внутренних шагов createElementNS с учетом этого this, пространства имен namespace, квалифицированного имени qualifiedName и параметров options.

Примечание!

Параметры parameter createElement() и createElementNS() может быть строкой для веб-совместимости.

Метод createDocumentFragment() при вызове должен возвращать новый узел DocumentFragment с его документом узла, установленным на this.

Метод createTextNode(data) при вызове должен возвращать новый узел Text с его набором данных для data и документом узла, установленным для этого this.

Примечание!

Не выполняется проверка того, что данные data состоят из символов, соответствующих продукту Char.

Метод createCDATASection(data) при вызове должен выполнить следующие шаги:

1. Если этот this является HTML-документом, выбросить исключение DOMException "NotSupportedError".
2. Если данные data содержат строку "]]>", выбросить исключение DOMException "InvalidCharacterError".
3. Вернуть новый узел CDATASection с его набором данных в data и документ узла, установленный для этого this.

Метод createComment(data) при вызове должен возвращать новый узел Comment с его набором данных для данных в data и документ узла, установленный для этого this..

Примечание!

Не выполняется проверка того, состоят ли данные data из символов, соответствующих продукту Char, или содержат ли они два смежных дефиса или заканчиваются дефисом.

При вызове метода createProcessingInstruction(target, data) необходимо выполнить следующие шаги:

1. Если цель target не совпадает с производством Name, то генерирует исключение DOMException «InvalidCharacterError».
2. Если данные data содержат строку «?>», то генерировать исключение DOMException «InvalidCharacterError».
3. Верните новый узел ProcessingInstruction с целью, установленной на target, набором данных для data и документом узла, установленным на this.

Примечание!

Не выполняется проверка того, содержит ли цель target «xml» или «:», или что данные содержат символы, соответствующие продукту Char.

 

Для веб-разработчиков (не нормативно)

clone = document . importNode(node [, deep = false])

Возвращает копию узла node. Если deeptrue, копия также включает потомков узла node.

Если узел node является документом или теневым корнем, выдает исключение DOMException «NotSupportedError«.

node = document . adoptNode(node)

Перемещает узел node из другого документа и возвращает его.

Если узел node является документом, генерирует исключение DOMException «NotSupportedError» или, если узел node является теневым корнем, генерирует исключение DOMException «HierarchyRequestError».

 

При вызове метода importNode(node, deep) необходимо выполнить следующие шаги:

1. Если узел node является документом или теневым корнем, выбросить исключение DOMException "NotSupportedError".
2. Вернуть клон узла node с this и установленным флагом clone children flag, если deep равен true.

Спецификации могут определять «шаги внедрения» (adopting steps) для всех или некоторых узлов. Алгоритм передается node и oldDocument, как указано в  алгоритме внедрения.

Чтобы «внедрить» (adopt) узел node в документ document, выполните следующие действия:

1. Пусть oldDocument будет документом узла node.
2. Если родитель узла node не равен null, удалите узел node.
3. Если document не oldDocument, то:
   1. Для каждого инклюзивного потомка inclusiveDescendant в инклюзивных потомков включающих тень узла node:
      1. Установите документ узла inclusiveDescendant на document.
      2. Если inclusiveDescendant является элементом, то установите документ узла каждого атрибута в списке атрибутов inclusiveDescendant на document.
   2. Для каждого объекта inclusiveDescendant в инклюзивных потомках включающих тень узла node, который является настраиваемым, поставьте в очередь реакцию обратного вызова настраиваемого элемента с помощью inclusiveDescendant, имени обратного вызова «adoptedCallback» и списка аргументов, содержащих oldDocument и document.
   3. Для каждого inclusiveDescendant в инклюзивных потомках включающих тень узла node в древовидном порядке, включающем тень, выполните шаги внедрения с inclusiveDescendant и oldDocument.

 

При вызове метода adoptNode(node) необходимо выполнить следующие шаги:

1. Если узел node является документом, выбросить исключение DOMException "NotSupportedError".
2. Если узел node является теневым корнем, выбросить исключение DOMException «HierarchyRequestError».
3. Если node является узлом DocumentFragment, хост которого не равен null, верните.
4. Внедрите узел node в этот this.
5. Вернуть узел node.

 

Метод createAttribute(localName) при вызове должен выполнить следующие шаги:

1. Если localName не совпадает с производством Name в XML, выбросить исключение DOMException «InvalidCharacterError».
2. Если этот this является документом HTML, установите для localName значение localName в нижнем регистре ASCII.
3. Вернуть новый атрибут, локальное имя которого - localName, а документ узла - this.

 

При вызове метода createAttributeNS(namespace, qualifiedName) необходимо выполнить следующие действия:

1. Пусть namespace, prefix и localName будут результатом передачи пространства имен namespace и квалифицированного имени qualifiedName для проверки и извлечения.

2. Возвращает новый атрибут, пространство имен которого — namespace, префикс пространства именprefix, локальное имяlocalName, а документ узла — этот this.

 

Метод createEvent(interface) при вызове должен выполнить следующие шаги:

1. Пусть конструктор constructor будет null.
2. Если interface является соответствием ASCII без учета регистра для любой из строк в первом столбце в следующей таблице, тогда установите constructor для интерфейса во втором столбце в той же строке, что и соответствующая строка:
String (Строка) Interface (Интерфейс) Notes (Заметки)
«beforeunloadevent» BeforeUnloadEvent [HTML]
«compositionevent» CompositionEvent [UIEVENTS]
«customevent» CustomEvent
«devicemotionevent» DeviceMotionEvent [DEVICE-ORIENTATION]
«deviceorientationevent» DeviceOrientationEvent [DEVICE-ORIENTATION]
«dragevent» DragEvent [HTML]
«event» Event
«events» Event
«focusevent» FocusEvent [UIEVENTS]
«hashchangeevent» HashChangeEvent [HTML]
«htmlevents» Event
«keyboardevent» KeyboardEvent [UIEVENTS]
«messageevent» MessageEvent [HTML]
«mouseevent» MouseEvent [UIEVENTS]
«mouseevents» MouseEvent [UIEVENTS]
«storageevent» StorageEvent [HTML]
«svgevents» Event
«textevent» CompositionEvent [UIEVENTS]
«touchevent» TouchEvent [TOUCH-EVENTS]
«uievent» UIEvent [UIEVENTS]
«uievents» UIEvent [UIEVENTS]
3. Если constructor имеет значение NULL, выбросить исключение DOMException "NotSupportedError".
4. Если интерфейс, указанный конструктором constructor, не отображается в соответствующем глобальном объекте этого this, то генерирует исключение DOMException "NotSupportedError".

Примечание!

Обычно пользовательские агенты отключают поддержку сенсорных событий в некоторых конфигурациях, и в этом случае это предложение будет активировано для интерфейса TouchEvent.

5. Пусть событие event будет результатом создания события при помощи конструктора constructor.
6. Инициализировать атрибут type события event пустой строкой.
7. Инициализируйте атрибут timeStamp события event как DOMHighResTimeStamp, представляющий время с высоким разрешением от начала отсчета времени до настоящего момента.
8. Установите для атрибута isTrusted события event значение false.
9. Флаг инициализации события event не установлен.
10. Вернуть event

Примечание!

Вместо этого следует использовать конструкторы событий.

 

Метод createRange() при вызове должен возвращать новый активный диапазон с (this, 0) в качестве начала и конца.

Примечание!

Вместо этого можно использовать конструктор Range().

 

При вызове метода createNodeIterator(root, whatToShow, filter) необходимо выполнить следующие шаги:

1. Пусть итератор iterator будет новым объектом NodeIterator.
2. Установите корень итератора iterator и ссылку итератора iterator на root.
3. Установите указатель перед ссылкой итератора iterator на true.
4. Установите для итератора iterator whatToShow значение whatToShow.
5. Установите фильтр итератора iterator на filter.
6. Верните iterator

 

При вызове метода createTreeWalker(root, whatToShow, filter) необходимо выполнить следующие шаги:

1. Пусть пешеход walker будет новым объектом TreeWalker.
2. Установите корень walker и ток walker на root.
3. Установите для walker whatToShow значение whatToShow.
4. Установите фильтр пешехода walker на filter.
5. Верните walker

 

Ссылки

DOM стандарт — https://efim360.ru/dom/

Читайте перевод полной версии стандарта «объектной модели документа», чтобы ознакомиться со всеми концепциями и интерфейсами.

DOMLiving Standardhttps://dom.spec.whatwg.org

Читайте официальную документацию живого стандарта «объектной модели документа», чтобы быть в курсе последних изменений.

Поделись записью