JavaTM 2 Platform
Standard Ed. 5.0

org.w3c.dom
接口 Element

所有超级接口:
Node
所有已知实现类:
IIOMetadataNode

public interface Element
extends Node

Element 接口表示 HTML 或 XML 文档中的一个元素。元素可能有与它们相关的属性;由于 Element 接口继承自 Node,所以可以使用一般 Node 接口属性 attributes 来获得元素所有属性的集合。Element 接口上有通过名称获得 Attr 对象或通过名称获得属性值的方法。在 XML 中(其中的属性值可能包含实体引用),应该获得 Attr 对象来检查表示属性值的可能相当复杂的子树。另一方面,在 HTML 中(其中的所有属性都有简单的字符串值),可以使用直接访问属性值的方法,这既安全又便捷。

注:在 DOM Level 2 中,方法 normalize 是从转移到的 Node 接口继承的。

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


字段摘要
 
从接口 org.w3c.dom.Node 继承的字段
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
 
方法摘要
 String getAttribute(String name)
          通过名称获得属性值。
 Attr getAttributeNode(String name)
          通过名称获得属性节点。
 Attr getAttributeNodeNS(String namespaceURI, String localName)
          通过本地名称和名称空间 URI 获得 Attr 节点。
 String getAttributeNS(String namespaceURI, String localName)
          通过本地名称和名称空间 URI 获得属性值。
 NodeList getElementsByTagName(String name)
          以文档顺序返回具有给定标记名称的所有后代 ElementsNodeList
 NodeList getElementsByTagNameNS(String namespaceURI, String localName)
          以文档顺序返回具有给定本地名称和名称空间 URI 的所有后代 ElementsNodeList
 TypeInfo getSchemaTypeInfo()
          与此元素相关的类型信息。
 String getTagName()
          元素的名称。
 boolean hasAttribute(String name)
          当具有给定名称的属性在此元素上被指定一个值或具有默认值时,返回 true;否则返回 false
 boolean hasAttributeNS(String namespaceURI, String localName)
          当具有给定本地名称和名称空间 URI 的属性在此元素上被指定一个值或具有默认值时,返回 true;否则返回 false
 void removeAttribute(String name)
          通过名称移除一个属性。
 Attr removeAttributeNode(Attr oldAttr)
          移除指定的属性节点。
 void removeAttributeNS(String namespaceURI, String localName)
          通过本地名称和名称空间 URI 移除属性值。
 void setAttribute(String name, String value)
          添加一个新属性。
 Attr setAttributeNode(Attr newAttr)
          添加新的属性节点。
 Attr setAttributeNodeNS(Attr newAttr)
          添加新属性。
 void setAttributeNS(String namespaceURI, String qualifiedName, String value)
          添加新属性。
 void setIdAttribute(String name, boolean isId)
          如果参数 isIdtrue,则此方法将指定的属性声明为用于确定用户的 ID 属性。
 void setIdAttributeNode(Attr idAttr, boolean isId)
          如果参数 isIdtrue,则此方法将指定的属性声明为用户确定的 ID 属性。
 void setIdAttributeNS(String namespaceURI, String localName, boolean isId)
          如果参数 isIdtrue,则此方法将指定的属性声明为用户确定的 ID 属性。
 
从接口 org.w3c.dom.Node 继承的方法
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData
 

方法详细信息

getTagName

String getTagName()
元素的名称。如果 Node.localNamenull 不同,则此属性为一个限定名称。例如,在以下示例中:
 <elementExample id="demo"> ... 
 </elementExample> , 
tagName 具有值 "elementExample"。注意,这在 XML 中是保留大小写的,DOM 中的所有操作也是这样。HTML DOM 以规范的大写形式返回 HTML 元素的 tagName,而不考虑源 HTML 文档中的大小写形式。


getAttribute

String getAttribute(String name)
通过名称获得属性值。

参数:
name - 要获得的属性名称。
返回:
字符串形式的 Attr 值;如果该属性没有指定值或默认值,则返回空字符串。

setAttribute

void setAttribute(String name,
                  String value)
                  throws DOMException
添加一个新属性。如果具有该名称的属性已经出现在元素中,则将其值更改为值参数的值。此值为简单的字符串;在设置它时没有对它进行解析。因此,将任何标记(如作为实体引用而被识别的语法)视为字面值文本,并且需要在写出时由实现适当转义。为了分配包含实体引用的属性值,用户必须创建一个 Attr 节点,加上所有 TextEntityReference 节点,构建适当的子树,并将它作为属性值,通过 setAttributeNode 方法来分配。
要设置具有限定名称和名称空间 URI 的属性,使用 setAttributeNS 方法。

参数:
name - 要创建或更改的属性名称。
value - 以字符串形式设置的值。
抛出:
DOMException - INVALID_CHARACTER_ERR: 根据在 Document.xmlVersion 属性中指定的正在使用的 XML 版本,如果指定名称不是 XML 名称,则引发此异常。
NO_MODIFICATION_ALLOWED_ERR: 如果此节点为只读的,则引发此异常。

removeAttribute

void removeAttribute(String name)
                     throws DOMException
通过名称移除一个属性。如果被移除属性的默认值在 DTD 中定义,则新的属性值将在可用时随该默认值以及相应名称空间 URI、本地名称和前缀立即出现。类似地,实现可以处理其他模式的默认值,但应用程序应该使用 Document.normalizeDocument() 来保证此信息最新。
如果找不到具有此名称的属性,则此方法无效。
要通过本地名称和名称空间 URI 移除属性,使用 removeAttributeNS 方法。

参数:
name - 要移除的属性的名称。
抛出:
DOMException - NO_MODIFICATION_ALLOWED_ERR: 如果此节点为只读的,则引发此异常。

getAttributeNode

Attr getAttributeNode(String name)
通过名称获得属性节点。
要通过限定名称和名称空间 URI 获得属性节点,使用 getAttributeNodeNS 方法。

参数:
name - 要获得的属性名称 (nodeName)。
返回:
返回具有指定名称 (nodeName) 的 Attr 节点;如果没有这样的属性,则返回 null

setAttributeNode

Attr setAttributeNode(Attr newAttr)
                      throws DOMException
添加新的属性节点。如果具有该名称 (nodeName) 的属性已经出现在元素中,则用新属性替换它。用自身替换属性节点无效。
要添加具有限定名称和名称空间 URI 的新属性节点,使用 setAttributeNodeNS 方法。

参数:
newAttr - 要添加到属性列表的 Attr 节点。
返回:
如果用 newAttr 属性替换现有属性,则返回被替换的 Attr 节点;否则返回 null
抛出:
DOMException - WRONG_DOCUMENT_ERR: 如果 newAttr 是从不同的文档创建的,不是从创建该元素的文档创建的,则引发此异常。
NO_MODIFICATION_ALLOWED_ERR: 如果此节点为只读的,则引发此异常。
INUSE_ATTRIBUTE_ERR: 如果 newAttr 已经是另一个 Element 对象的属性,则引发此异常。DOM 用户必须显式地克隆 Attr 节点,以便在其他元素中重新使用它们。

removeAttributeNode

Attr removeAttributeNode(Attr oldAttr)
                         throws DOMException
移除指定的属性节点。如果在 DTD 中定义了被移除 Attr 节点的默认值,则新的节点将在可用时随该默认值以及相应名称空间 URI、本地名称和前缀一起立即出现。类似地,实现可以处理其他模式的默认值,但应用程序应该使用 Document.normalizeDocument() 来保证此信息最新。

参数:
oldAttr - 从属性列表中移除的 Attr 节点。
返回:
被移除的 Attr 节点。
抛出:
DOMException - NO_MODIFICATION_ALLOWED_ERR: 如果此节点为只读的,则引发此异常。
NOT_FOUND_ERR: 如果 oldAttr 不是该元素的属性,则引发此异常。

getElementsByTagName

NodeList getElementsByTagName(String name)
以文档顺序返回具有给定标记名称的所有后代 ElementsNodeList

参数:
name - 要匹配的标记的名称。特殊值 "*" 匹配所有标记。
返回:
匹配的 Element 节点列表。

getAttributeNS

String getAttributeNS(String namespaceURI,
                      String localName)
                      throws DOMException
通过本地名称和名称空间 URI 获得属性值。
按照 [XML Namespaces],如果应用程序希望没有名称空间,则它们必须将值 null 用作方法的 namespaceURI 参数。

参数:
namespaceURI - 要获得的属性的名称空间 URI。
localName - 要获得的属性的本地名称。
返回:
字符串形式的 Attr 值;如果该属性没有指定值或默认值,则返回空字符串。
抛出:
DOMException - NOT_SUPPORTED_ERR: 如果实现不支持功能 "XML" 且文档中公开的语言不支持 XML 名称空间(例如 [HTML 4.01]),则可能引发此异常。
从以下版本开始:
DOM Level 2

setAttributeNS

void setAttributeNS(String namespaceURI,
                    String qualifiedName,
                    String value)
                    throws DOMException
添加新属性。如果具有相同本地名称和名称空间 URI 的属性已经出现在元素上,则将其前缀更改为 qualifiedName 的前缀部分,并将其值更改为 value 参数。此值为简单的字符串;在设置它时没有对它进行解析。因此,将任何标记(如作为实体引用识别的语法)视为字面值文本,并且需要在写出时由实现适当转义。为了分配包含实体引用的属性值,用户必须创建一个 Attr 节点,加上所有 TextEntityReference 节点,构建适当的子树,并使用 setAttributeNodeNSsetAttributeNode 作为属性的值分配它。
按照 [XML Namespaces],如果应用程序希望没有名称空间,则它们必须将值 null 用作方法的 namespaceURI 参数。

参数:
namespaceURI - 要创建或更改的属性的名称空间 URI。
qualifiedName - 要创建或更改的属性的限定名称。
value - 以字符串形式设置的值。
抛出:
DOMException - INVALID_CHARACTER_ERR: 根据在 Document.xmlVersion 属性中指定的正在使用的 XML 版本,如果指定名称不是 XML 名称,则引发此异常。
NO_MODIFICATION_ALLOWED_ERR:如果此节点为只读的,则引发此异常。
NAMESPACE_ERR: 在以下情况下引发此异常:如果根据 XML 规范中的名称空间,qualifiedName 是错误格式的;如果 qualifiedName 有前缀且 namespaceURInull;如果 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 名称空间(例如 [HTML 4.01]),则可能引发此异常。
从以下版本开始:
DOM Level 2

removeAttributeNS

void removeAttributeNS(String namespaceURI,
                       String localName)
                       throws DOMException
通过本地名称和名称空间 URI 移除属性值。如果被移除属性的默认值在 DTD 中定义,则新的属性值将在可用时随该默认值以及相应名称空间 URI、本地名称和前缀立即出现。类似地,实现可以处理其他模式的默认值,但应用程序应该使用 Document.normalizeDocument() 来保证此信息最新。
如果找不到具有此本地名称和名称空间 URI 的属性,则此方法无效。
按照 [XML Namespaces],如果应用程序希望没有名称空间,则它们必须将值 null 用作方法的 namespaceURI 参数。

参数:
namespaceURI - 要移除的属性的名称空间 URI。
localName - 要移除的属性的本地名称。
抛出:
DOMException - NO_MODIFICATION_ALLOWED_ERR: 如果此节点为只读的,则引发此异常。
NOT_SUPPORTED_ERR: 如果实现不支持功能 "XML" 且文档中公开的语言不支持 XML 名称空间(例如 [HTML 4.01]),则可能引发此异常。
从以下版本开始:
DOM Level 2

getAttributeNodeNS

Attr getAttributeNodeNS(String namespaceURI,
                        String localName)
                        throws DOMException
通过本地名称和名称空间 URI 获得 Attr 节点。
按照 [XML Namespaces],如果应用程序希望没有名称空间,则它们必须将值 null 用作方法的 namespaceURI 参数。

参数:
namespaceURI - 要获得的属性的名称空间 URI。
localName - 要获得的属性的本地名称。
返回:
具有特定属性名称和名称空间 URI 的 Attr 节点;如果没有这样的属性,则返回 null
抛出:
DOMException - NOT_SUPPORTED_ERR: 如果实现不支持功能 "XML" 且文档中公开的语言不支持 XML 名称空间(例如 [HTML 4.01]),则可能引发此异常。
从以下版本开始:
DOM Level 2

setAttributeNodeNS

Attr setAttributeNodeNS(Attr newAttr)
                        throws DOMException
添加新属性。如果具有该本地名称和该名称空间 URI 的属性已经出现在元素中,则用新的属性替换它。用自身替换属性节点无效。
按照 [XML Namespaces],如果应用程序希望没有名称空间,则它们必须将值 null 用作方法的 namespaceURI 参数。

参数:
newAttr - 要添加到属性列表的 Attr 节点。
返回:
如果用 newAttr 属性替换具有相同本地名称和名称空间 URI 的现有属性,则返回被替换的 Attr 节点;否则返回 null
抛出:
DOMException - WRONG_DOCUMENT_ERR: 如果 newAttr 是从不同的文档创建的,不是从创建该元素的文档创建的,则引发此异常。
NO_MODIFICATION_ALLOWED_ERR:如果此节点为只读的,则引发此异常。
INUSE_ATTRIBUTE_ERR: 如果 newAttr 已经是另一个 Element 对象的属性,则引发此异常。DOM 用户必须显式地克隆 Attr 节点,以便在其他元素中重新使用它们。
NOT_SUPPORTED_ERR: 如果实现不支持功能 "XML" 且文档中公开的语言不支持 XML 名称空间(例如 [HTML 4.01]),则可能引发此异常。
从以下版本开始:
DOM Level 2

getElementsByTagNameNS

NodeList getElementsByTagNameNS(String namespaceURI,
                                String localName)
                                throws DOMException
以文档顺序返回具有给定本地名称和名称空间 URI 的所有后代 ElementsNodeList

参数:
namespaceURI - 要匹配的元素的名称空间 URI。特殊值 "*" 匹配所有名称空间。
localName - 要匹配的元素的本地名称。特殊值 "*" 匹配所有本地名称。
返回:
包含所有匹配的 Elements 的新 NodeList 对象。
抛出:
DOMException - NOT_SUPPORTED_ERR: 如果实现不支持功能 "XML" 且文档中公开的语言不支持 XML 名称空间(例如 [HTML 4.01]),则可能引发此异常。
从以下版本开始:
DOM Level 2

hasAttribute

boolean hasAttribute(String name)
当具有给定名称的属性在此元素上被指定一个值或具有默认值时,返回 true;否则返回 false

参数:
name - 要查找的属性名称。
返回:
如果具有给定名称的属性在此元素上被指定一个值或具有默认值,则返回 true;否则返回 false
从以下版本开始:
DOM Level 2

hasAttributeNS

boolean hasAttributeNS(String namespaceURI,
                       String localName)
                       throws DOMException
当具有给定本地名称和名称空间 URI 的属性在此元素上被指定一个值或具有默认值时,返回 true;否则返回 false
按照 [XML Namespaces],如果应用程序希望没有名称空间,则它们必须将值 null 用作方法的 namespaceURI 参数。

参数:
namespaceURI - 要查找的属性的名称空间 URI。
localName - 要查找的属性的本地名称。
返回:
如果具有给定本地名称和名称空间 URI 的属性在此元素上被指定一个值或具有默认值,则返回 true;否则返回 false
抛出:
DOMException - NOT_SUPPORTED_ERR:如果实现不支持功能 "XML" 且文档中公开的语言不支持 XML 名称空间(例如 [HTML 4.01]),则可能引发此异常。
从以下版本开始:
DOM Level 2

getSchemaTypeInfo

TypeInfo getSchemaTypeInfo()
与此元素相关的类型信息。

从以下版本开始:
DOM Level 3

setIdAttribute

void setIdAttribute(String name,
                    boolean isId)
                    throws DOMException
如果参数 isIdtrue,则此方法将指定的属性声明为用于确定用户的 ID 属性。此方法影响 Attr.isId 的值和 Document.getElementById 的行为,但不更改可能正在使用的任何模式;需要特别指出的是,此方法不影响指定 Attr 节点的 Attr.schemaTypeInfo。使用参数 isId 的值 false 来取消将属性声明为用户确定的 ID 属性。
要通过本地名称和名称空间 URI 指定属性,使用 setIdAttributeNS 方法。

参数:
name - 属性名称。
isId - 属性是否是 ID 类型。
抛出:
DOMException - NO_MODIFICATION_ALLOWED_ERR:如果此节点为只读的,则引发此异常。
NOT_FOUND_ERR:如果指定的节点不是此元素的属性,则引发此异常。
从以下版本开始:
DOM Level 3

setIdAttributeNS

void setIdAttributeNS(String namespaceURI,
                      String localName,
                      boolean isId)
                      throws DOMException
如果参数 isIdtrue,则此方法将指定的属性声明为用户确定的 ID 属性。此方法影响 Attr.isId 的值和 Document.getElementById 的行为,但不更改可能正在使用的任何模式;需要特别指出的是,此方法不影响指定 Attr 节点的 Attr.schemaTypeInfo。使用参数 isId 的值 false 来取消将属性声明为用户确定的 ID 属性。

参数:
namespaceURI - 属性的名称空间 URI。
name - 属性的本地名称。
isId - 属性是否是 ID 类型。
抛出:
DOMException - NO_MODIFICATION_ALLOWED_ERR:如果此节点为只读的,则引发此异常。
NOT_FOUND_ERR: 如果指定的节点不是此元素的属性,则引发此异常。
从以下版本开始:
DOM Level 3

setIdAttributeNode

void setIdAttributeNode(Attr idAttr,
                        boolean isId)
                        throws DOMException
如果参数 isIdtrue,则此方法将指定的属性声明为用户确定的 ID 属性。此方法影响 Attr.isId 的值和 Document.getElementById 的行为,但不更改可能正在使用的任何模式;需要特别指出的是,此方法不影响指定 Attr 节点的 Attr.schemaTypeInfo。使用参数 isId 的值 false 来取消将属性声明为用户确定的 ID 属性。

参数:
idAttr - 属性节点。
isId - 属性是否是 ID 类型。
抛出:
DOMException - NO_MODIFICATION_ALLOWED_ERR: 如果此节点为只读的,则引发此异常。
NOT_FOUND_ERR: 如果指定的节点不是此元素的属性,则引发此异常。
从以下版本开始:
DOM Level 3

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

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