document.evaluate

摘要

根据传入的 XPath 表达式以及其他参数，返回一个 XPathResult 对象。

语法

var xpathResult = document.evaluate(
 xpathExpression, 
 contextNode, 
 namespaceResolver, 
 resultType, 
 result
);

• xpathExpression 是表示Xpath的字符串。
• contextNode 表示本次查询的 context node （参照XPath规范 [https://www.w3.org/TR/xpath]）。通常会使用document。
• namespaceResolver 是函数。传入名空间前缀，返回跟此前缀相关的名空间URI（字符串）。通常用来解析Xpath内的前缀，以便对文档进行匹配。HTML文档或者不使用名空间前缀的文档，通常传入null。
• resultType 是整数。指定所返回的 XPathResult 的类型，常常使用 named constant properties，如 XPathResult.ANY_TYPE，范围 0 到 9，见下表。
• result 为XPathResult型，用以存储查询结果。通常传入null，此时将创建新的XPathResult对象。

Example

var headings = document.evaluate("/html/body//h2", document, null, XPathResult.ANY_TYPE, null); 
/* Search the document for all h2 elements.  
 * The result will likely be an unordered node iterator. */
var thisHeading = headings.iterateNext(); 
var alertText = "Level 2 headings in this document are:\n";
while (thisHeading) {
  alertText += thisHeading.textContent + "\n";
  thisHeading = headings.iterateNext();
}
alert(alertText); // Alerts the text of all h2 elements

Note, in the above example, a more verbose XPath is preferred over common shortcuts such as //h2. Generally, more specific XPath selectors as in the above example usually gives a significant performance improvement, especially on very large documents. This is because the evaluation of the query spends does not waste time visiting unnecessary nodes. Using // is generally slow as it visits every node from the root and all subnodes looking for possible matches.

Further optimization can be achieved by careful use of the context parameter. For example, if you know the content you are looking for is somewhere inside the body tag, you can use this:

document.evaluate(".//h2", document.body, null, XPathResult.ANY_TYPE, null);

Notice in the above document.body has been used as the context instead of document so the XPath starts from the body element. (In this example, the "." is important to indicate that the querying should start from the context node, document.body. If the "." was left out (leaving //h2) the query would start from the root node (html) which would be more wasteful.)

See Introduction to using XPath in JavaScript for more information.

Notes

• XPath expressions can be evaluated on HTML and XML documents.
• While using document.evaluate() works in FF2, in FF3 one must use someXMLDoc.evaluate() if evaluating against something other than the current document.

Result types

(Merge with Template:XPathResultConstants?

These are supported values for the resultType parameter of the evaluate method:

Results of NODE_ITERATOR types contain references to nodes in the document. Modifying a node will invalidate the iterator. After modifying a node, attempting to iterate through the results will result in an error.

Results of NODE_SNAPSHOT types are snapshots, which are essentially lists of matched nodes. You can make changes to the document by altering snapshot nodes. Modifying the document doesn't invalidate the snapshot; however, if the document is changed, the snapshot may not correspond to the current state of the document, since nodes may have moved, been changed, added, or removed.

Browser compatibility

Basic test case, if you want to note coverage for your browser.

Specification

• DOM Level 3 XPath

See also

• DOM:document.createExpression
• XPath Code Snippets