XPathResult.singleNodeValue — Eigenschaft · JavaScript-Referenz

Signatur

XPathResult.singleNodeValue

Beschreibung

Die schreibgeschützte Eigenschaft singleNodeValue eines XPathResult-Objekts enthält den einen Knoten, den ein XPath-Ausdruck über document.evaluate() gefunden hat. Passt kein Knoten auf den Ausdruck, ist der Wert null.

Sie ist nur nutzbar, wenn das Ergebnis mit einem der Typen XPathResult.FIRST_ORDERED_NODE_TYPE (erster Treffer in Dokumentreihenfolge) oder XPathResult.ANY_UNORDERED_NODE_TYPE (irgendein Treffer, oft etwas schneller) angefordert wurde. Bei jedem anderen resultType wirft der Zugriff eine TypeError-Ausnahme.

Typische Einsatzfälle sind Abfragen, die mit CSS-Selektoren nicht oder nur umständlich möglich sind, etwa die Suche nach einem Element über seinen Textinhalt (//button[text()="Speichern"]), Navigation zu Eltern- oder Vorgängerknoten (ancestor::, preceding-sibling::) oder die Auswertung von XML-Dokumenten aus DOMParser bzw. fetch.

Rückgabewert

Typ

Node | null

Beschreibung

Der gefundene Knoten (z. B. Element, Attr oder Text) oder null, wenn der Ausdruck keinen Treffer liefert.

Beispiele

Button über seinen Text finden

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

const saveButton = result.singleNodeValue;
if (saveButton) {
  saveButton.addEventListener('click', () => console.log('Gespeichert!'));
  console.log(saveButton.outerHTML);
} else {
  console.log('Kein Speichern-Button gefunden');
}

<button>Speichern</button>

Wiederverwendbare Hilfsfunktion $x()

const xpathOne = (expr, context = document) =>
  document.evaluate(
    expr,
    context,
    null,
    XPathResult.FIRST_ORDERED_NODE_TYPE,
    null
  ).singleNodeValue;

// Nächste Tabelle oberhalb einer Zelle ermitteln
const cell = document.querySelector('td');
const table = cell ? xpathOne('ancestor::table[1]', cell) : null;
console.log(table?.tagName ?? 'keine Tabelle');

TABLE

Wert aus einem XML-Dokument lesen

const xml = `<config><db host="localhost" port="5432"/></config>`;
const doc = new DOMParser().parseFromString(xml, 'application/xml');

const portAttr = doc.evaluate(
  '/config/db/@port',
  doc,
  null,
  XPathResult.ANY_UNORDERED_NODE_TYPE,
  null
).singleNodeValue;

console.log(portAttr?.value); // Attr-Knoten
console.log(Number(portAttr?.value) + 1);

5432 5433

Fehler bei falschem resultType

const res = document.evaluate(
  '//p',
  document,
  null,
  XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
  null
);

try {
  console.log(res.singleNodeValue);
} catch (err) {
  console.log(err.name); // Zugriff ist bei diesem Typ nicht erlaubt
  console.log(res.snapshotItem(0)?.tagName);
}

TypeError P

// Wichtig · Fallstricke

Nur bei passendem Typ: Wird das Ergebnis z. B. mit ORDERED_NODE_SNAPSHOT_TYPE oder STRING_TYPE erzeugt, wirft der Zugriff auf singleNodeValue einen TypeError. Bei ANY_TYPE entscheidet der Browser selbst über den Typ – nie einen Einzelknoten-Typ; fordern Sie daher explizit FIRST_ORDERED_NODE_TYPE an.
ANY_UNORDERED_NODE_TYPE garantiert nicht den ersten Treffer in Dokumentreihenfolge. Wenn die Reihenfolge wichtig ist, FIRST_ORDERED_NODE_TYPE verwenden.
Der Rückgabewert kann auch ein Attr- oder Text-Knoten sein – vor Aufruf von Element-Methoden ggf. nodeType oder instanceof Element prüfen.
Namensräume: In XHTML/SVG oder XML mit Default-Namespace liefert ein Ausdruck ohne namespaceResolver oft null.
Anders als bei Iteratoren ist das Ergebnis ein fester Verweis; es wird nicht ungültig, wenn sich das DOM ändert.
Kompatibilität: in allen modernen Browsern verfügbar (nicht im Internet Explorer). In Node.js nur über DOM-Implementierungen wie jsdom.

Siehe auch

XPathResult Document.evaluate() XPathResult.resultType XPathResult.snapshotItem() XPathResult.iterateNext() Document.querySelector() PerformanceTiming.unloadEventEnd