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

void setXmlVersion(String xmlVersion)
                   throws DOMException

作为 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 异常。

抛出：

DOMException - NOT_SUPPORTED_ERR:如果将该版本设置为此 Document 不支持的值，或此文档不支持 "XML" 特性，则引发此异常。

从以下版本开始：

DOM Level 3

getStrictErrorChecking

boolean getStrictErrorChecking()

指定是否强制执行错误检查的属性。设置为 false 时，该实现可以不测试通常在 DOM 操作上定义的每个可能的错误情形，可以不在 DOM 操作上引发任何 DOMException，也可以不在使用 Document.normalizeDocument() 时报告错误。如果发生错误，则该行为将会不确定。此属性默认为 true。

从以下版本开始：

DOM Level 3

setStrictErrorChecking

void setStrictErrorChecking(boolean strictErrorChecking)

指定是否强制执行错误检查的属性。设置为 false 时，该实现不会随意测试通常在 DOM 操作上定义的每个可能的错误情形，不会在 DOM 操作上引发任何 DOMException，也不会在使用 Document.normalizeDocument() 时报告错误。如果发生错误，则该行为不确定。此属性默认为 true。

从以下版本开始：

DOM Level 3

getDocumentURI

String getDocumentURI()

文档的位置，如果未定义或 Document 是使用 DOMImplementation.createDocument 创建的，则为 null。设置此属性时不执行任何词汇检查；这可能导致在使用 Node.baseURI 时返回 null 值。
请注意，如果 Document 支持 "HTML" [DOM Level 2 HTML] 特性，则计算 Node.baseURI 时 HTML BASE 元素的 href 属性优先于此属性。

从以下版本开始：

DOM Level 3

setDocumentURI

void setDocumentURI(String documentURI)

文档的位置，如果未定义或 Document 是使用 DOMImplementation.createDocument 创建的，则为 null。设置此属性时不执行任何词汇检查；这可能导致在使用 Node.baseURI 时返回 null 值。
请注意，如果 Document 支持 "HTML" [DOM Level 2 HTML] 特性，则计算 Node.baseURI 时 HTML BASE 元素的 href 属性优先于此属性。

从以下版本开始：

DOM Level 3

adoptNode

Node adoptNode(Node source)
               throws DOMException

试图把另一文档中的节点采用到此文档。如果受支持，则它将更改源节点的 ownerDocument、它的子节点以及连接的属性节点（如果有）。如果源节点有父节点，则首先从其父节点的子节点列表中移除它。此方法允许将子树从一个文档移动到另一个文档（与 importNode() 不同，后者创建源节点副本，而不是移动子树）。失败时，应用程序应该改为使用 Document.importNode()。注意，如果采用的节点已经是此文档的一部分（即源文档和目标文档相同），此方法仍可有效地从其父节点（如果有）的子列表移除源节点。下表描述了每种类型节点的细节。

ATTRIBUTE_NODE

在采用的 Attr 上，将 ownerElement 属性设置为 null 并将 specified 标志设置为 true。递归地采用源 Attr 的后代。

DOCUMENT_FRAGMENT_NODE

递归地采用源节点的后代。

DOCUMENT_NODE

不能采用 Document 节点。

DOCUMENT_TYPE_NODE

不能采用 DocumentType 节点。

ELEMENT_NODE

采用源元素的 Specified 属性节点。丢弃默认属性，不过，如果被采用的文档定义了此元素名称的默认属性，则分配这些属性。递归地采用源元素的后代。

ENTITY_NODE

不能采用 Entity 节点。

ENTITY_REFERENCE_NODE

只采用 EntityReference 节点本身并丢弃其后代，因为源文档和目标文档可能以不同方式定义实体。如果要导入的文档提供了对此实体名称的定义，则分配其值。

NOTATION_NODE

不能采用 Notation 节点。

PROCESSING_INSTRUCTION_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE

这些节点均可以采用。无特殊说明。

注： 由于它与 Document.importNode() 方法不同，不创建新的节点，因此此方法不引发 INVALID_CHARACTER_ERR 异常，并且应用程序应该使用 Document.normalizeDocument() 方法来检查导入的名称是否是遵循正在使用的 XML 版本的 XML 名称。

参数：

source - 要移入此文档的节点。

返回：

采用的节点，如果此操作失败（例如源节点来自不同实现时），则返回 null。

抛出：

DOMException - NOT_SUPPORTED_ERR:如果源节点属于 DOCUMENT、DOCUMENT_TYPE 类型，则引发此异常。
NO_MODIFICATION_ALLOWED_ERR:源节点为只读的时引发此异常。

从以下版本开始：

DOM Level 3

getDomConfig

DOMConfiguration getDomConfig()

调用 Document.normalizeDocument() 时使用的配置。

从以下版本开始：

DOM Level 3

normalizeDocument

void normalizeDocument()

此方法的行为如同使文档通过一个保存和加载的过程，而将其置为 "normal（标准）" 形式。因此，此方法更新 EntityReference 节点的替换树并规范化 Text 节点，如在方法 Node.normalize() 中定义的那样。
否则，实际结果取决于在 Document.domConfig 对象上设置的、控制哪个操作实际发生的特性。值得注意的是，此方法还可以按照其中描述的算法使文档名称空间格式良好、检查字符规范化、移除 CDATASection 节点，等等。有关详细信息请参见 DOMConfiguration。

// Keep in the document 
 the information defined // in the XML Information Set (Java example) 
 DOMConfiguration docConfig = myDocument.getDomConfig(); 
 docConfig.setParameter("infoset", Boolean.TRUE); 
 myDocument.normalizeDocument();

生成改变事件（当被支持时）来反映在该文档上发生的更改。
如果在调用此方法期间发生错误（如试图更新只读节点）或按照正在使用的 XML 版本 Node.nodeName 包含无效字符，则将使用与 "error-handler" 参数相关联的 DOMErrorHandler 对象报告错误或警告（DOMError.SEVERITY_ERROR 或 DOMError.SEVERITY_WARNING）。注意，如果实现无法从错误中恢复，则此方法还可能报告严重错误（DOMError.SEVERITY_FATAL_ERROR）。

从以下版本开始：

DOM Level 3

renameNode

Node renameNode(Node n,
                String namespaceURI,
                String qualifiedName)
                throws DOMException

重命名 ELEMENT_NODE 或 ATTRIBUTE_NODE 类型的现有节点。
如有可能，此方法只更改给定节点的名称；否则此方法将创建一个具有指定名称的新节点，并将现有节点替换为新节点，如下所述。
如果只更改给定节点的名称是不可能的，则执行以下操作：创建新节点；在新节点上注册任何已注册的事件侦听器；从旧节点移除连接到该节点的任何用户数据；从旧节点的父节点（如果有）将其移除；将子节点移到新节点；如果重命名的节点为 Element，则其属性移动到新节点；将新节点插入旧节点原来在其父（如果有）的子节点列表中的位置；将连接到旧节点的用户数据连接到新节点。
当正被重命名的节点为 Element 时，只移动指定的属性，源于 DTD 的默认属性按照新的元素名称更新。此外，实现还可以更新源自其他模式的默认属性。应用程序应该使用 Document.normalizeDocument() 来保证这些属性是最新的。
当正被重命名的节点是连接到 Element 的 Attr 时，则首先从 Element 属性映射中移除该节点。然后，一旦通过修改现有节点或创建新节点（如上所述）重命名，则将它放回原处。
此外，

• 可触发用户数据事件 NODE_RENAMED,
• 当实现支持 "MutationNameEvents" 特性时，此方法中包含的每个改变操作都将触发相应的事件，最后将触发事件 { http://www.w3.org/2001/xml-events DOMElementNameChanged} 或 { http://www.w3.org/2001/xml-events DOMAttributeNameChanged}。

参数：

n - 要重命名的节点。

namespaceURI - 新的名称空间 URI。

qualifiedName - 新的限定名称。

返回：

重命名的节点。这可以是指定的节点，也可以是用来替换指定节点而创建的新节点。

抛出：

DOMException - NOT_SUPPORTED_ERR:当指定节点的类型不是 ELEMENT_NODE，也不是 ATTRIBUTE_NODE 时，或者如果实现不支持重命名文档元素，则引发此异常。
INVALID_CHARACTER_ERR:如果新的限定名称不是遵循正在使用的在 Document.xmlVersion 属性中指定的 XML 版本的 XML 名称，则引发此异常。
WRONG_DOCUMENT_ERR:当从与此文档不同的另一个文档创建指定节点时，引发此异常。
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/"，也引发此异常。

从以下版本开始：

DOM Level 3

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。