public interface Document extends Node
Document
接口表示整个 HTML 或 XML 文档。从概念上讲,它是文档树的根,并提供对文档数据的基本访问。
因为元素、文本节点、注释、处理指令等不能存在于 Document
的上下文之外,所以 Document
接口还包含所需的创建这些对象的工厂方法。所创建的 Node
对象具有 ownerDocument
属性,该属性将 Node
对象与创建这些对象时的上下文所属的 Document
关联起来。
另请参见 Document Object Model (DOM) Level 3 Core Specification。
字段摘要 |
---|
方法摘要 | |
---|---|
Node | adoptNode(Node source) 试图把另一文档中的节点采用到此文档。 |
Attr | createAttribute(String name) 创建给定名称的 Attr 。 |
Attr | createAttributeNS(String namespaceURI, String qualifiedName) 创建给定的限定名称和名称空间 URI 的属性。 |
CDATASection | createCDATASection(String data) 创建其值为指定字符串的 CDATASection 节点。 |
Comment | createComment(String data) 创建给定指定字符串的 Comment 节点。 |
DocumentFragment | createDocumentFragment() 创建空 DocumentFragment 对象。 |
Element | createElement(String tagName) 创建指定类型的元素。 |
Element | createElementNS(String namespaceURI, String qualifiedName) 创建给定的限定名称和名称空间 URI 的元素。 |
EntityReference | createEntityReference(String name) 创建 EntityReference 对象。 |
ProcessingInstruction | createProcessingInstruction(String target, String data) 创建给定指定名称和数据字符串的 ProcessingInstruction 节点。 |
Text | createTextNode(String data) 创建给定指定字符串的 Text 节点。 |
DocumentType | getDoctype() 与此文档相关的文档类型声明(参见 DocumentType )。 |
Element | getDocumentElement() 这是一种便捷属性,该属性允许直接访问文档的文档元素的子节点。 |
String | getDocumentURI() 文档的位置,如果未定义或 Document 是使用 DOMImplementation.createDocument 创建的,则为 null 。 |
DOMConfiguration | getDomConfig() 调用 Document.normalizeDocument() 时使用的配置。 |
Element | getElementById(String elementId) 返回具有带给定值的 ID 属性的 Element 。 |
NodeList | getElementsByTagName(String tagname) 按文档顺序返回包含在文档中且具有给定标记名称的所有 Element 的 NodeList 。 |
NodeList | getElementsByTagNameNS(String namespaceURI, String localName) 以文档顺序返回具有给定本地名称和名称空间 URI 的所有 Elements 的 NodeList 。 |
DOMImplementation | getImplementation() 处理此文档的 DOMImplementation 对象。 |
String | getInputEncoding() 指定解析时此文档使用的编码的属性。 |
boolean | getStrictErrorChecking() 指定是否强制执行错误检查的属性。 |
String | getXmlEncoding() 作为 XML 声明的一部分,指定此文档编码的属性。 |
boolean | getXmlStandalone() 作为 XML 声明的一部分,指定此文档是否为独立文档的属性。 |
String | getXmlVersion() 作为 XML 声明 的一部分指定此文档版本号的属性。 |
Node | importNode(Node importedNode, boolean deep) 从另一文档向此文档导入节点,而不改变或移除原始文档中的源节点;此方法创建源节点的一个新副本。 |
void | normalizeDocument() 此方法的行为如同使文档通过一个保存和加载的过程,而将其置为 "normal(标准)" 形式。 |
Node | renameNode(Node n, String namespaceURI, String qualifiedName) 重命名 ELEMENT_NODE 或 ATTRIBUTE_NODE 类型的现有节点。 |
void | setDocumentURI(String documentURI) 文档的位置,如果未定义或 Document 是使用 DOMImplementation.createDocument 创建的,则为 null 。 |
void | setStrictErrorChecking(boolean strictErrorChecking) 指定是否强制执行错误检查的属性。 |
void | setXmlStandalone(boolean xmlStandalone) 作为 XML 声明 的一部分指定此文档是否是单独的的属性。 |
void | setXmlVersion(String xmlVersion) 作为 XML 声明 的一部分指定此文档版本号的属性。 |
方法详细信息 |
---|
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
-