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«.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Метод 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.

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

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

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

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

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

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

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

При вызове метода 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 для интерфейса во втором столбце в той же строке, что и соответствующая строка:

3. Если constructor имеет значение NULL, выбросить исключение DOMException "NotSupportedError".
4. Если интерфейс, указанный конструктором constructor, не отображается в соответствующем глобальном объекте этого this, то генерирует исключение DOMException "NotSupportedError".

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

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

При вызове метода 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/

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

DOM — Living Standard — https://dom.spec.whatwg.org

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