XPathResult — Schnittstelle · JavaScript-Referenz

Signatur

interface XPathResult

Beschreibung

XPathResult-Objekte entstehen beim Aufruf von document.evaluate() oder XPathExpression.prototype.evaluate(). Je nach angefordertem Ergebnistyp enthält das Objekt einen primitiven Wert (numberValue, stringValue, booleanValue), einen einzelnen Knoten (singleNodeValue) oder eine Knotenmenge, die man über einen Iterator (iterateNext()) oder als Schnappschuss (snapshotItem(), snapshotLength) durchläuft.

Welcher Typ vorliegt, verrät die Eigenschaft resultType. Sie entspricht einer der statischen Konstanten:

ANY_TYPE (0) – der Browser wählt den natürlichen Typ des Ausdrucks
NUMBER_TYPE (1), STRING_TYPE (2), BOOLEAN_TYPE (3)
UNORDERED_NODE_ITERATOR_TYPE (4), ORDERED_NODE_ITERATOR_TYPE (5)
UNORDERED_NODE_SNAPSHOT_TYPE (6), ORDERED_NODE_SNAPSHOT_TYPE (7)
ANY_UNORDERED_NODE_TYPE (8), FIRST_ORDERED_NODE_TYPE (9)

XPath lohnt sich, wenn CSS-Selektoren nicht ausreichen – etwa zur Suche nach Elementen anhand ihres Textinhalts (//button[contains(., "Speichern")]), für Achsen wie ancestor:: oder following-sibling:: oder beim Verarbeiten von XML-Dokumenten aus DOMParser bzw. XMLHttpRequest.responseXML.

Wichtige Eigenschaften und Methoden: resultType, numberValue, stringValue, booleanValue, singleNodeValue, snapshotLength, invalidIteratorState, iterateNext(), snapshotItem(index). Wer auf eine Eigenschaft zugreift, die nicht zum aktuellen Ergebnistyp passt, bekommt einen TypeError.

Parameter

Name	Typ	Default	Beschreibung
$expression Pflicht	string		Der XPath-Ausdruck, der an `document.evaluate()` übergeben wird.
$contextNode Pflicht	Node		Knoten, relativ zu dem der Ausdruck ausgewertet wird, z. B. `document`.
$namespaceResolver	XPathNSResolver\|Function\|null	null	Löst Namensraum-Präfixe auf; bei HTML-Dokumenten ohne Präfixe meist `null`.
$resultType	number	XPathResult.ANY_TYPE	Eine der Konstanten von `XPathResult`, die festlegt, welche Art von Ergebnis zurückkommt.
$result	XPathResult\|null	null	Ein bestehendes `XPathResult` zum Wiederverwenden (in der Praxis meist `null`).

Rückgabewert

Typ

XPathResult

Beschreibung

Das Ergebnisobjekt von document.evaluate(); welche Eigenschaften zugänglich sind, hängt von resultType ab.

Beispiele

Einzelnes Element anhand des Textinhalts finden

// <button>Abbrechen</button><button>Speichern</button>
const result = document.evaluate(
  '//button[normalize-space(.)="Speichern"]',
  document,
  null,
  XPathResult.FIRST_ORDERED_NODE_TYPE,
  null
);

const button = result.singleNodeValue;
console.log(button?.textContent ?? 'nicht gefunden');

Speichern

Alle Treffer als Schnappschuss durchlaufen

const snapshot = document.evaluate(
  '//a[starts-with(@href, "http")]',
  document,
  null,
  XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
  null
);

console.log(`Externe Links: ${snapshot.snapshotLength}`);
for (let i = 0; i < snapshot.snapshotLength; i++) {
  const link = snapshot.snapshotItem(i);
  link.setAttribute('target', '_blank'); // DOM-Änderung ist bei Snapshots erlaubt
}

Externe Links: 3

Iterator und Zahlenwert bei XML-Daten

const xml = new DOMParser().parseFromString(
  '<shop><item preis="10"/><item preis="25"/><item preis="5"/></shop>',
  'application/xml'
);

// Zahl direkt berechnen lassen
const sum = xml.evaluate('sum(//item/@preis)', xml, null, XPathResult.NUMBER_TYPE, null);
console.log('Summe:', sum.numberValue);

// Knoten per Iterator auslesen
const it = xml.evaluate('//item', xml, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE, null);
const preise = [];
let node;
while ((node = it.iterateNext())) {
  preise.push(Number(node.getAttribute('preis')));
}
console.log(preise);

Summe: 40 [10, 25, 5]

Ergebnistyp bei ANY_TYPE prüfen

const r = document.evaluate('count(//p)', document, null, XPathResult.ANY_TYPE, null);

if (r.resultType === XPathResult.NUMBER_TYPE) {
  console.log(`Absätze: ${r.numberValue}`);
}

Absätze: 4

// Wichtig · Fallstricke

Iterator wird ungültig: Ändert sich das Dokument, während ein Ergebnis vom Typ *_NODE_ITERATOR_TYPE durchlaufen wird, wird invalidIteratorState auf true gesetzt und iterateNext() wirft einen InvalidStateError. Wer Knoten ändern will, nimmt besser ORDERED_NODE_SNAPSHOT_TYPE.
Snapshots sind statisch: Sie bilden später hinzugekommene oder entfernte Knoten nicht ab.
Wer auf eine unpassende Eigenschaft zugreift (z. B. snapshotLength bei einem Iterator-Ergebnis), bekommt einen TypeError.
Namensräume: In XHTML- oder SVG-/XML-Dokumenten mit Standard-Namensraum finden Ausdrücke ohne Präfix oft nichts. Dann braucht man einen namespaceResolver und Präfixe im Ausdruck.
Browser unterstützen nur XPath 1.0. Funktionen aus XPath 2.0/3.x (z. B. matches(), lower-case()) gibt es nicht.
Sicherheit: Baue keine XPath-Ausdrücke aus ungeprüften Benutzereingaben per String-Verkettung zusammen, weil sonst XPath-Injection möglich ist. Anführungszeichen müssen korrekt maskiert werden.
Kompatibilität: Wird von allen modernen Browsern unterstützt. In Node.js gibt es die Schnittstelle nicht von Haus aus, nur über Bibliotheken wie jsdom oder xpath.

Siehe auch

Document.evaluate() XPathExpression XPathEvaluator Document.createExpression() DOMParser Document.querySelectorAll() FetchLaterResult