org.w3c.dom
接口 Document

所有超级接口：

Node

所有已知实现类：

SOAPPart

public interface Document
     

      extends 
      Node
     

Document 接口表示整个 HTML 或 XML 文档。从概念上讲，它是文档树的根，并提供对文档数据的基本访问。

因为元素、文本节点、注释、处理指令等不能存在于 Document 的上下文之外，所以 Document 接口还包含所需的创建这些对象的工厂方法。所创建的 Node 对象具有 ownerDocument 属性，该属性将 Node 对象与创建这些对象时的上下文所属的 Document 关联起来。

另请参见 Document Object Model (DOM) Level 3 Core Specification。

getDoctype

DocumentType getDoctype()

与此文档相关的文档类型声明（参见 DocumentType）。对于没有文档类型声明的 XML 文档，此方法返回 null。对于 HTML 文档，可以返回 DocumentType 对象，与 HTML 文档中是否有文档类型声明无关。
这提供对 Document 的子节点 DocumentType 节点的直接访问。此节点可以在文档创建时设置，以后可以通过使用子节点操作方法（如 Node.insertBefore 或 Node.replaceChild）进行更改。不过要注意的是，根据创建时指定的 DocumentType，在有些实现可以实例化不同类型的 Document 对象（支持 "Core" 之外的其他功能，如 "HTML" [ DOM Level 2 HTML]）时，以后对它的更改很可能会导致所支持功能的不可更改。

从以下版本开始：

DOM Level 3

getImplementation

DOMImplementation getImplementation()

处理此文档的 DOMImplementation 对象。DOM 应用程序可以使用多个实现中的对象。

getDocumentElement

Element getDocumentElement()

这是一种便捷属性，该属性允许直接访问文档的文档元素的子节点。

createElement

Element createElement(String tagName)
                      throws DOMException

创建指定类型的元素。注意，返回的实例实现 Element 接口，所以可以直接在返回的对象上指定属性。
此外，如果存在具有默认值的已知属性，则自动创建表示它们的 Attr 节点，并将其连接到该元素。
要创建具有限定名称和名称空间 URI 的元素，使用 createElementNS 方法。

参数：

tagName - 要实例化的元素类型名称。对于 XML，tagName 参数是区分大小写的；而对于其他文档，则取决于所使用标记语言的大小写敏感性。在该情况下，可通过 DOM 实现将该名称映射到该标记的规范形式。

返回：

新的 Element 对象，该对象具有设置为 tagName 的 nodeName 属性以及设置为 null 的 localName、 prefix 和 namespaceURI。

抛出：

DOMException - INVALID_CHARACTER_ERR：如果指定的名称是不遵循所使用的 XML 版本（在 Document.xmlVersion 属性中指定）的 XML 名称，则引发此异常。

createDocumentFragment

DocumentFragment createDocumentFragment()

创建空 DocumentFragment 对象。

返回：

新的 DocumentFragment。

createTextNode

Text createTextNode(String data)

创建给定指定字符串的 Text 节点。

参数：

data - 该节点的数据。

返回：

新 Text 对象。

createComment

Comment createComment(String data)

创建给定指定字符串的 Comment 节点。

参数：

data - 该节点的数据。

返回：

新 Comment 对象。

createCDATASection

CDATASection createCDATASection(String data)
                                throws DOMException

创建其值为指定字符串的 CDATASection 节点。

参数：

data - CDATASection 内容的数据。

返回：

新 CDATASection 对象。

抛出：

DOMException - NOT_SUPPORTED_ERR:如果此文档为 HTML 文档，则引发该异常。

createProcessingInstruction

ProcessingInstruction createProcessingInstruction(String target,
                                                  String data)
                                                  throws DOMException

创建给定指定名称和数据字符串的 ProcessingInstruction 节点。

参数：

target - 处理指令的目标部分。与 Document.createElementNS 或 Document.createAttributeNS 不同，此方法不检查目标名称是否为格式良好的名称空间。为了确保目标名称是格式良好的名称空间，应用程序应该使用设置为 true 的参数 "namespaces" 调用 Document.normalizeDocument()。

data - 该节点的数据。

返回：

新 ProcessingInstruction 对象。

抛出：

DOMException - INVALID_CHARACTER_ERR:如果指定的目标是不遵循在 Document.xmlVersion 属性中指定的使用中的 XML 版本的 XML 名称，则引发此异常。
NOT_SUPPORTED_ERR:如果此文档为 HTML 文档，则引发此异常。

createAttribute

Attr createAttribute(String name)
                     throws DOMException

创建给定名称的 Attr。注意，然后可以使用 setAttributeNode 方法在 Element 上设置 Attr。
要创建具有限定名称和名称空间 URI 的属性，使用 createAttributeNS 方法。

参数：

name - 属性名称。

返回：

新的 Attr 对象，该对象具有设置为 name 的 nodeName 属性以及设置为 null 的 localName、 prefix 和 namespaceURI。该属性的值为空字符串。

抛出：

DOMException - INVALID_CHARACTER_ERR:如果指定的名称是不遵循在 Document.xmlVersion 属性中指定的使用中的 XML 版本的 XML 名称，则引发此异常。

createEntityReference

EntityReference createEntityReference(String name)
                                      throws DOMException

创建 EntityReference 对象。此外，如果引用的实体是已知的，则使 EntityReference 节点的子列表与相应 Entity 节点的子列表相同。

注： 如果任何 Entity 节点的后代具有未绑定的名称空间前缀，则相应的所创建的 EntityReference 节点的后代也未绑定；（其 namespaceURI 为 null）。DOM Level 2 和 3 不支持在此情况下解析名称空间前缀的任何机制。

参数：

name - 要引用的实体的名称。与 Document.createElementNS 或 Document.createAttributeNS 不同，不在实体名称上检查名称空间是否为格式良好的。为了确保实体名称是格式良好的名称空间，应用程序应该使用设置为 true 的参数 "namespaces" 调用 Document.normalizeDocument()。

返回：

新的 EntityReference 对象。

抛出：

DOMException - INVALID_CHARACTER_ERR:如果指定的名称是不遵循在 Document.xmlVersion 属性中指定的使用中的 XML 版本的 XML 名称，则引发此异常。
NOT_SUPPORTED_ERR:如果此文档为 HTML 文档，则引发该异常。

getElementsByTagName

NodeList getElementsByTagName(String tagname)

按文档顺序返回包含在文档中且具有给定标记名称的所有 Element 的 NodeList。

参数：

tagname - 要匹配的标记的名称。特殊值 "*" 匹配所有标记。对于 XML ， tagname 参数是区分大小写的，否则它将依靠正在使用的标记语言的大小写敏感性。

返回：

包含所有匹配的 Elements 的新 NodeList 对象。

importNode

Node importNode(Node importedNode,
                boolean deep)
                throws DOMException

从另一文档向此文档导入节点，而不改变或移除原始文档中的源节点；此方法创建源节点的一个新副本。返回的节点没有父节点；（ parentNode 为 null）。
对于所有节点而言，导入节点创建由导入文档所有的节点对象，属性值等同于源节点的 nodeName 和 nodeType，加上与名称空间相关的属性（ prefix、 localName 和 namespaceURI）。与在 cloneNode 操作中一样，源节点没有改变。与导入的节点相关的用户数据不可继续使用。不过，如果随相关数据一起指定了任何 UserDataHandlers，则将在此方法返回之前用适当的参数调用这些处理程序。
其他信息按相应的 nodeType 复制，在从一个文档向另一文档复制 XML 或 HTML 源的分段时试图镜像所需的行为，并认识到两个方法可以在 XML 实例中具有不同的 DTD。下表描述了每种类型节点的细节。

ATTRIBUTE_NODE

在生成的 Attr 上，将 ownerElement 属性设置为 null 并将 specified 标志设置为 true。递归地导入源 Attr 的后代，并且重新集合得到的节点来构造相应的子树。注意， deep 参数对 Attr 节点无效；它们总是在导入时带着子节点。

DOCUMENT_FRAGMENT_NODE

如果将 deep 选项设置为 true，则递归地导入源 DocumentFragment 的后代，并在导入的 DocumentFragment 下重新集合得到的节点以构造相应的子树。否则，此操作仅生成一个空 DocumentFragment。

DOCUMENT_NODE

不能导入 Document 节点。

DOCUMENT_TYPE_NODE

不能导入 DocumentType 节点。

ELEMENT_NODE

导入源元素的 指定的 属性节点，并将生成的 Attr 节点连接到生成的 Element。默认属性是 不 被复制的，不过，如果被导入的文档定义了此元素名称的默认属性，则分配这些属性。如果将 importNode deep 参数设置为 true，则递归地导入源元素的后代并集合得到的节点，以构造相应的子树。

ENTITY_NODE

可以导入 Entity 节点，但在当前版本的 DOM 中， DocumentType 是只读的。将考虑在以后版本的 DOM 中包含将这些导入的节点添加到 DocumentType 中这一功能。导入时，将复制 publicId、 systemId 和 notationName 属性。如果请求 deep 导入，则递归地导入源 Entity 的后代，并重新集合得到的节点以构造相应的子树。

ENTITY_REFERENCE_NODE

即使请求 deep 导入，也只复制 EntityReference 本身，因为源和目标文档可能以不同方式定义实体。如果正在导入的文档提供对此实体名称的定义，则它的值得以分配。

NOTATION_NODE

可以导入 Notation 节点，但在当前版本的 DOM 中， DocumentType 是只读的。能够将这些导入的节点添加到 DocumentType 将被认为是以后版本的 DOM 的附加功能。导入时，复制 publicId 和 systemId 属性。注意， deep 参数对此类型的节点无效，因为它们不能有任何子节点。

PROCESSING_INSTRUCTION_NODE

导入的节点从源节点中复制其 target 和 data 值。注意，该 deep 参数对此类型的节点无效，因为它们不能有任何子节点。

TEXT_NODE、CDATA_SECTION_NODE、COMMENT_NODE

继承自 CharacterData 的这三种类型的节点从源节点复制其 data 和 length 属性。注意， deep 参数对这三种类型的节点无效，因为它们不能有任何子节点。

参数：

importedNode - 要导入的节点。

deep - 如果为 true，则递归地导入在指定节点下的子树；如果为 false，则仅导入节点本身，如上面的解释。这对不能有任何子节点的节点、对 Attr 和 EntityReference 节点都无效。

返回：

导入的、属于此 Document 的节点。

抛出：

DOMException - NOT_SUPPORTED_ERR:如果不支持正在导入的该类型的节点，则引发此异常。
INVALID_CHARACTER_ERR:如果导入的一个名称是不遵循在 Document.xmlVersion 属性中指定的使用中的 XML 版本的 XML 名称，则引发此异常。例如，将 XML 1.1 [ XML 1.1] 元素导入 XML 1.0 文档时可能引发此异常。

从以下版本开始：

DOM Level 2

createElementNS

Element createElementNS(String namespaceURI,
                        String qualifiedName)
                        throws DOMException

创建给定的限定名称和名称空间 URI 的元素。
依据 [ XML Namespaces]，如果应用程序不希望使用名称空间，则必须将 null 作为方法的 namespaceURI 参数的值。

参数：

namespaceURI - 要创建的元素的名称空间 URI。

qualifiedName - 要实例化的元素类型的限定名称。

返回：

具有以下属性的新 Element 对象：

属性	值
Node.nodeName	qualifiedName
Node.namespaceURI	namespaceURI
Node.prefix	前缀，从 qualifiedName 中提取的；如果没有前缀，则为 null
Node.localName	本地名称，从 qualifiedName 提取的
Element.tagName	qualifiedName

抛出：

DOMException - INVALID_CHARACTER_ERR:如果指定的 qualifiedName 是不遵循在 Document.xmlVersion 属性中指定的使用中的 XML 版本的 XML 名称，则引发此异常。
NAMESPACE_ERR:下列情况引发此异常：如果 qualifiedName 是错误格式的限制名称；如果 qualifiedName 具有前缀且 namespaceURI 为 null；或者如果 qualifiedName 具有前缀 "xml" 且该 namespaceURI 不同于 " http://www.w3.org/XML/1998/namespace" [ XML Namespaces]；或者如果 qualifiedName 或其前缀为 "xmlns" 且该 namespaceURI 不同于 " http://www.w3.org/2000/xmlns/"；或者如果 namespaceURI 为 " http://www.w3.org/2000/xmlns/" 且 qualifiedName 及其前缀都不是 "xmlns"。
NOT_SUPPORTED_ERR:由于 XML 定义了名称空间，如果当前文档不支持 "XML" 特性，则总是抛出此异常。

从以下版本开始：

DOM Level 2

createAttributeNS

Attr createAttributeNS(String namespaceURI,
                       String qualifiedName)
                       throws DOMException

创建给定的限定名称和名称空间 URI 的属性。
对于每个 [ XML Namespaces]，如果应用程序希望没有名称空间，则它们必须将 null 作为方法的 namespaceURI 参数的值。

参数：

namespaceURI - 要创建的属性的名称空间 URI。

qualifiedName - 要实例化的属性的限定名称。

返回：

具有以下属性的新 Attr 对象：

属性	值
Node.nodeName	qualifiedName
Node.namespaceURI	namespaceURI
Node.prefix	前缀，从 qualifiedName 中提取的；如果没有前缀，则为 null
Node.localName	本地名称，从 qualifiedName 提取的
Attr.name	qualifiedName
Node.nodeValue	空字符串

抛出：

DOMException - INVALID_CHARACTER_ERR:如果指定的 qualifiedName 是不遵循在 Document.xmlVersion 属性中指定的使用中的 XML 版本的 XML 名称，则引发此异常。
NAMESPACE_ERR:在以下情况下引发此异常：如果 qualifiedName 为错误格式的限定名称；如果 qualifiedName 有前缀且 namespaceURI 为 null；如果 qualifiedName 有前缀 "xml" 且 namespaceURI 不同于 " http://www.w3.org/XML/1998/namespace"；如果 qualifiedName 或其前缀为 "xmlns" 且 namespaceURI 不同于 " http://www.w3.org/2000/xmlns/"；或者 namespaceURI 为 " http://www.w3.org/2000/xmlns/" 且 qualifiedName 及其前缀都不是 "xmlns"。
NOT_SUPPORTED_ERR:由于 XML 定义了名称空间，如果当前文档不支持 "XML" 特性，则总是抛出此异常。

从以下版本开始：

DOM Level 2

getElementsByTagNameNS

NodeList getElementsByTagNameNS(String namespaceURI,
                                String localName)

以文档顺序返回具有给定本地名称和名称空间 URI 的所有 Elements 的 NodeList。

参数：

namespaceURI - 要匹配的元素的名称空间 URI。特殊值 "*" 匹配所有名称空间。

localName - 要匹配的元素的本地名称。特殊值 "*" 匹配所有本地名称。

返回：

包含所有匹配的 Elements 的新 NodeList 对象。

从以下版本开始：

DOM Level 2

getElementById

Element getElementById(String elementId)

返回具有带给定值的 ID 属性的 Element。如果不存在此类元素，则此方法返回 null。如果一个以上的元素具有带该值的 ID 属性，返回哪一个元素是不确定的。
期望 DOM 实现使用属性 Attr.isId 来确定属性是否属于类型 ID。

注： 具有名称 "ID" 或 "id" 的属性不属于类型 ID，除非这样定义。

参数：

elementId - 元素的唯一 id 值。

返回：

匹配的元素；如果不存在任何匹配元素，则返回 null。

从以下版本开始：

DOM Level 2

getInputEncoding

String getInputEncoding()

指定解析时此文档使用的编码的属性。如果此属性未知（如在内存中创建 Document 时），则为 null。

从以下版本开始：

DOM Level 3

getXmlEncoding

String getXmlEncoding()

作为 XML 声明的一部分，指定此文档编码的属性。在未指定或未知时，如在内存中创建 Document 时，此属性为 null。

从以下版本开始：

DOM Level 3

getXmlStandalone

boolean getXmlStandalone()

作为 XML 声明的一部分，指定此文档是否为独立文档的属性。未指定时，此属性为 false。

注： 设置此属性时不对此值进行任何验证。应用程序应该使用带有 "validate" 参数的 Document.normalizeDocument() 验证该值是否匹配在 [XML 1.0] 中定义的有关独立文档声明的有效性约束（）。

从以下版本开始：

DOM Level 3

setXmlStandalone

void setXmlStandalone(boolean xmlStandalone)
                      throws DOMException

作为 XML 声明 的一部分指定此文档是否是单独的的属性。未指定时，此属性为 false。

注： 设置此属性时不对此值进行任何验证。应用程序应该使用带有 "validate" 参数的 Document.normalizeDocument() 验证该值是否匹配 validity constraint for standalone document declaration（在 [XML 1.0] 中定义）。

抛出：

DOMException - NOT_SUPPORTED_ERR:如果此文档不支持 "XML" 特性，则引发此异常。

从以下版本开始：

DOM Level 3

getXmlVersion

String getXmlVersion()

作为 XML 声明 的一部分指定此文档版本号的属性。如果没有声明，或如果此文档支持 "XML" 特性，则该值为 "1.0"。如果此文档不支持 "XML" 特性，则该值始终为 null。更改此属性将影响在 XML 名称中检查无效字符的方法。应用程序应该调用 Document.normalizeDocument() 来检查在已经是此 Document 一部分的 Node 中的无效字符。
DOM 应用程序可以使用参数值分别为 "XMLVersion" 和 "1.0"的 DOMImplementation.hasFeature(feature, version) 方法来确定实现是否支持 [ XML 1.0]。DOM 应用程序还可以使用参数值分别为 "XMLVersion" 和 "1.1"的同一方法来确定实现是否支持 [ XML 1.1]。在这两种情况下，为了支持 XML，实现还必须支持在此规范中定义的 "XML" 特性。支持某版本的 "XMLVersion" 特性的 Document 对象不能在使用 Document.xmlVersion 时对相同版本号引发 NOT_SUPPORTED_ERR 异常。

从以下版本开始：

DOM Level 3

setXmlVersion