Интерфейс DOMConfiguration

public interface DOMConfiguration

Интерфейс DOMConfiguration представляет конфигурацию документа и поддерживает таблицу распознаваемых параметров. С помощью конфигурации можно изменять поведение Document.normalizeDocument(), например заменять узлы CDATASection узлами Text или указывать тип схемы, которую необходимо использовать при запросе проверки Document. Объекты DOMConfiguration также используются в [DOM Level 3 Load and Save] в интерфейсах DOMParser и DOMSerializer.

Имена параметров, используемые объектом DOMConfiguration, определены в спецификациях DOM Level 3. Имена не учитывают регистр. Во избежание возможных конфликтов рекомендуется, чтобы имена параметров, определённых за пределами спецификации DOM, были уникальными. Поскольку параметры представлены как свойства, рекомендуется, чтобы их имена соответствовали разделу 5.16 «Идентификаторы» [Unicode], с добавлением символа «-» (ДЕФИС-МИНУС), однако реализация DOM не обязана это обеспечивать. Реализации DOM Level 3 Core обязаны распознавать все параметры, определённые в этой спецификации. Для реализации также может быть обязательна поддержка некоторых значений параметров. Чтобы узнать, обязательно ли поддерживать то или иное значение, обратитесь к описанию параметра.

Примечание: Параметры похожи на возможности и свойства, используемые в SAX2 [SAX].

Ниже приведён список параметров, определённых в DOM:

"canonical-form"

true

[необязательно] Канонизировать документ согласно правилам, заданным в [Canonical XML], например удалив узел DocumentType (если он есть) из дерева или удалив избыточные объявления пространств имён из каждого элемента. Следует учитывать, что это ограничено тем, что может быть представлено в DOM; в частности, в DOM невозможно задать порядок атрибутов. Кроме того, установка этого параметра в значение true также изменит состояние перечисленных ниже параметров. Последующее изменение состояния одного из этих параметров вернёт значение "canonical-form" к false. В значение false устанавливаются параметры: "entities", " normalize-characters", "cdata-sections". В значение true устанавливаются параметры: "namespaces", "namespace-declarations", "well-formed", "element-content-whitespace". Другие параметры не изменяются, если только это явно не указано в их описании.

false

[обязательно] (по умолчанию) Не канонизировать документ.

"cdata-sections"

true

[обязательно] (по умолчанию) Сохранять узлы CDATASection в документе.

false

[обязательно] Преобразовывать узлы CDATASection в документе в узлы Text. Затем новый узел Text объединяется с любым соседним узлом Text.

"check-character-normalization"

true

[необязательно] Проверять, являются ли символы в документе полностью нормализованными согласно определению в приложении B [XML 1.1]. При обнаружении последовательности символов, не прошедшей проверку нормализации, выдаётся ошибка, у которой DOMError.type равно "check-character-normalization-failure".

false

[обязательно] (по умолчанию) Не проверять, нормализованы ли символы.

"comments"

true

[обязательно] (по умолчанию) Сохранять узлы Comment в документе.

false

[обязательно] Удалять узлы Comment из документа.

"datatype-normalization"

true

[необязательно] Представлять в дереве нормализованные схемой значения, например нормализованные значения XML Schema в случае XML Schema. Поскольку для этого параметра необходима информация о схеме, параметр "validate" также будет установлен в true. Если этот параметр включён, а "validate" имеет значение false, это не оказывает эффекта и нормализация схемой не выполняется.

Примечание: Поскольку документ содержит результат обработки XML 1.0, этот параметр не применяется к нормализации значений атрибутов, определённой в разделе 3.3.3 [XML 1.0], и предназначен только для языков схем, отличных от определения типа документа (DTD).

false

[обязательно] (по умолчанию) Не выполнять нормализацию схемой для дерева.

"element-content-whitespace"

true

[обязательно] (по умолчанию) Сохранять все пробельные символы в документе.

false

[необязательно] Отбрасывать все узлы Text, содержащие пробельные символы в содержимом элемента, как описано в [пробельные символы в содержимом элемента]. Предполагается, что реализация будет использовать атрибут Text.isElementContentWhitespace, чтобы определить, следует ли отбрасывать узел Text.

"entities"

true

[обязательно] (по умолчанию) Сохранять узлы EntityReference в документе.

false

[обязательно] Удалять из документа все узлы EntityReference, помещая вместо них непосредственно развёрнутые сущности. Узлы Text нормализуются согласно определению в Node.normalize. В документе сохраняются только неразвёрнутые ссылки на сущности.

Примечание: Этот параметр не влияет на узлы Entity.

"error-handler"

[обязательно] Содержит объект DOMErrorHandler. Если в документе обнаружена ошибка, реализация вызовет обработчик DOMErrorHandler, зарегистрированный с помощью этого параметра. Реализация может предоставить объект DOMErrorHandler по умолчанию. При вызове DOMError.relatedData будет содержать ближайший узел к месту возникновения ошибки. Если реализация не может определить узел, в котором произошла ошибка, DOMError.relatedData будет содержать узел Document. Изменение документа из обработчика ошибок приведёт к поведению, зависящему от реализации.

"infoset"

true

[обязательно] Сохранять в документе информацию, определённую в наборе сведений XML [XML Information Set]. Это принудительно устанавливает следующие параметры в значение false: " validate-if-schema", "entities", "datatype-normalization", "cdata-sections ". Это принудительно устанавливает следующие параметры в значение true: " namespace-declarations", "well-formed", "element-content-whitespace", " comments", "namespaces". Другие параметры не изменяются, если только это явно не указано в их описании. Обратите внимание: запрос этого параметра со значением getParameter возвращает true только в том случае, если отдельные параметры, указанные выше, установлены соответствующим образом.

false

Установка infoset в значение false не оказывает эффекта.

"namespaces"

true

[обязательно] (по умолчанию) Выполнять обработку пространств имён, как определено в .

false

[необязательно] Не выполнять обработку пространств имён.

"namespace-declarations"

Этот параметр не оказывает эффекта, если параметр "namespaces" установлен в значение false.

true

[обязательно] (по умолчанию) Включать в документ атрибуты объявлений пространств имён, указанные в схеме или заданные в ней по умолчанию. См. также разделы «Объявление пространств имён» в [XML Namespaces] и [XML Namespaces 1.1].

false

[обязательно] Удалять все атрибуты объявлений пространств имён. Префиксы пространств имён (Node.prefix) сохраняются, даже если этот параметр установлен в значение false.

"normalize-characters"

true

[необязательно] Полностью нормализовать символы в документе согласно определению в приложении B [XML 1.1].

false

[обязательно] (по умолчанию) Не выполнять нормализацию символов.

"schema-location"

[необязательно] Представляет объект DOMString, содержащий список URI, разделённых пробельными символами (символами, соответствующими нетерминалу S, определённому в разделе 2.3 [XML 1.0]), которые обозначают схемы для проверки, то есть текущую схему. Типы схем, указанных в этом списке, должны совпадать с типом, заданным с помощью schema-type, в противном случае поведение реализации не определено. Схемы, указанные с помощью этого свойства, имеют приоритет над информацией о схеме, указанной непосредственно в документе. Для схем с поддержкой пространств имён, если схема, заданная с помощью этого свойства, и схема, указанная в экземпляре документа (то есть с помощью атрибута schemaLocation) в документе схемы (то есть с помощью механизмов схемы import), имеют одинаковое targetNamespace, будет использоваться схема, заданная пользователем с помощью этого свойства. Если две схемы, указанные с помощью этого свойства, имеют одинаковое targetNamespace или не имеют пространства имён, поведение зависит от реализации. Если расположение не задано, значение этого параметра — null.

Примечание: Параметр "schema-location" игнорируется, если не задано значение параметра "schema-type". Настоятельно рекомендуется задать Document.documentURI, чтобы реализация могла успешно разрешать ссылки на внешние сущности.

"schema-type"

[необязательно] Представляет объект DOMString, содержащий абсолютный URI, который обозначает тип языка схем, используемого для проверки документа. Обратите внимание, что лексическая проверка абсолютного URI не выполняется. Если этот параметр не задан, реализация может предоставить значение по умолчанию на основе поддерживаемых языков схем и языка схем, использовавшегося во время загрузки. Если значение не предоставлено, значение этого параметра — null.

Примечание: Для XML Schema [XML Schema Part 1] приложения должны использовать значение "http://www.w3.org/2001/XMLSchema". Для XML DTD [XML 1.0] приложения должны использовать значение "http://www.w3.org/TR/REC-xml". Другие языки схем не входят в область компетенции W3C, поэтому для использования этого метода в их спецификациях следует рекомендовать абсолютный URI.

"split-cdata-sections"

true

[обязательно] (по умолчанию) Разбивать секции CDATA, содержащие маркер завершения секции CDATA ']]>'. При разбиении секции CDATA выдаётся предупреждение, у которого DOMError.type равно "cdata-sections-splitted", а DOMError.relatedData равно первому узлу CDATASection в порядке документа, полученному в результате разбиения.

false

[обязательно] Выдавать ошибку, если CDATASection содержит непредставимый символ.

"validate"

true

[необязательно] Требовать проверки документа по схеме (то есть XML Schema, DTD или схеме любого другого типа либо представления) во время его нормализации, определённой в [XML 1.0]. Если обнаружены ошибки проверки или схема не найдена, обработчик ошибок получает уведомление. Нормализованные схемой значения не будут представлены согласно используемой схеме, если только параметр "datatype-normalization" не установлен в значение true. При этом параметре будут повторно вычислены:

• узлы атрибутов со значением Attr.specified, равным false, как указано в описании интерфейса Attr;
• значение атрибута Text.isElementContentWhitespace для всех узлов Text;
• значение атрибута Attr.isId для всех узлов Attr;
• атрибуты Element.schemaTypeInfo и Attr.schemaTypeInfo.

Примечание: Параметры "validate-if-schema" и "validate" взаимоисключающие: установка одного из них в значение true устанавливает другой в значение false. При проверке документа приложениям также следует рассмотреть возможность установки параметра "well-formed" в значение true, которое используется для этого параметра по умолчанию.

false

[обязательно] (по умолчанию) Не выполнять обработку схем, включая обработку внутреннего подмножества. Сведения о значениях атрибутов по умолчанию сохраняются. Обратите внимание, что проверка всё ещё может выполняться, если параметр "validate-if-schema" имеет значение true.

"validate-if-schema"

true

[необязательно] Включать проверку только в том случае, если в схеме можно найти объявление элемента документа (независимо от того, где оно найдено: в XML Schema, DTD или схеме любого другого типа либо представления). Если проверка включена, этот параметр действует так же, как параметр "validate", установленный в значение true.

Примечание: Параметры "validate-if-schema" и "validate" взаимоисключающие: установка одного из них в значение true устанавливает другой в значение false.

false

[обязательно] (по умолчанию) Не выполнять обработку схемы, включая обработку внутреннего подмножества, даже если документ содержит схему. Сведения о значениях атрибутов по умолчанию сохраняются. Обратите внимание, что проверка всё равно должна выполняться, если параметр "validate" имеет значение true.

"well-formed"

true

[обязательно] (по умолчанию) Проверять, что все узлы правильно сформированы в соответствии с версией XML, используемой в Document.xmlVersion:

• проверять, содержит ли атрибут Node.nodeName недопустимые символы с учётом типа узла, и при необходимости создавать DOMError типа "wf-invalid-character-in-node-name" с уровнем важности DOMError.SEVERITY_ERROR;
• проверять текстовое содержимое узлов Attr, Element, Comment, Text, CDATASection на наличие недопустимых символов и при необходимости создавать DOMError типа "wf-invalid-character" с уровнем важности DOMError.SEVERITY_ERROR;
• проверять данные в узлах ProcessingInstruction на наличие недопустимых символов и при необходимости создавать DOMError типа "wf-invalid-character" с уровнем важности DOMError.SEVERITY_ERROR;

false

[необязательно] Не проверять правильность формирования XML.

Разрешение системных идентификаторов, связанных с сущностями, выполняется с помощью Document.documentURI. Однако если реализация DOM поддерживает возможность "LS", определённую в [DOM Level 3 Load and Save], параметр "resource-resolver" также можно использовать для объектов DOMConfiguration, связанных с узлами Document. Если этот параметр задан, Document.normalizeDocument() вызовет обработчик разрешения ресурсов вместо использования Document.documentURI.

См. также спецификацию ядра объектной модели документа (DOM) уровня 3.