Node.nodeValue — Eigenschaft · JavaScript-Referenz

Signatur

Node.nodeValue

Beschreibung

nodeValue ist eine lesbare und schreibbare Eigenschaft des Node-Interfaces. Welchen Wert sie hat, hängt vom Knotentyp ab. Bei Text-, Kommentar- und CDATA-Knoten liefert sie den Textinhalt, bei Attr-Knoten den Wert des Attributs und bei ProcessingInstruction-Knoten den Inhalt der Anweisung. Für Elemente, das Document, DocumentFragment und DocumentType ist der Wert immer null.

Wenn der Wert null ist, hat das Setzen von nodeValue keine Wirkung. Es wird dabei kein Fehler geworfen. Wer den Text eines Elements ändern möchte, nimmt textContent und nicht nodeValue.

In der Praxis braucht man nodeValue vor allem, wenn man gezielt mit einzelnen Textknoten arbeitet. Typische Fälle sind Übersetzungen oder Hervorhebungen, bei denen die übrige Struktur des Elements erhalten bleiben soll, das Auswerten von Kommentaren (etwa Platzhaltern von Frameworks) und das Durchlaufen des DOM mit TreeWalker oder NodeIterator. Bei Textknoten verhält sich nodeValue genauso wie CharacterData.data und textContent.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null		Nur beim Setzen: der neue Wert als Zeichenkette. Wird `null` zugewiesen, wird daraus bei Textknoten eine leere Zeichenkette. Bei Knoten, deren `nodeValue` `null` ist (z. B. Elemente), wird die Zuweisung ignoriert.

Rückgabewert

Typ

string | null

Beschreibung

Der Textwert bei Text, Comment, CDATASection, Attr und ProcessingInstruction. Bei allen anderen Knotentypen null.

Beispiele

Wert je nach Knotentyp auslesen

const p = document.createElement('p');
p.innerHTML = 'Hallo <!-- Hinweis --> Welt';

console.log(p.nodeValue);               // Element
console.log(p.firstChild.nodeValue);    // Textknoten
console.log(p.childNodes[1].nodeValue); // Kommentar

p.setAttribute('title', 'Gruß');
console.log(p.getAttributeNode('title').nodeValue);

null "Hallo " " Hinweis " "Gruß"

Textknoten ändern, ohne Kind-Elemente zu verlieren

const btn = document.createElement('button');
btn.innerHTML = '<span class="icon">★</span> Speichern';

// textContent würde das <span> entfernen – nodeValue ändert nur den Text
const label = [...btn.childNodes].find(n => n.nodeType === Node.TEXT_NODE);
label.nodeValue = ' Gespeichert';

console.log(btn.innerHTML);

<span class="icon">★</span> Gespeichert

Alle Textknoten per TreeWalker ersetzen

const root = document.createElement('div');
root.innerHTML = '<h1>Farbe</h1><p>Die Farbe ist <em>Farbe</em>.</p>';

const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
while (walker.nextNode()) {
  const node = walker.currentNode;
  node.nodeValue = node.nodeValue.replaceAll('Farbe', 'Colour');
}

console.log(root.innerHTML);

<h1>Colour</h1><p>Die Colour ist <em>Colour</em>.</p>

Setzen auf einem Element bewirkt nichts

const div = document.createElement('div');
div.textContent = 'Original';

div.nodeValue = 'Neu'; // wird still ignoriert
console.log(div.textContent);

"Original"

// Wichtig · Fallstricke

Häufigster Fehler: element.nodeValue = '…' ändert nichts, und es erscheint keine Fehlermeldung. Für Elemente verwendet man textContent, oder man greift auf den Textknoten zu, z. B. mit element.firstChild.nodeValue.
firstChild ist nicht unbedingt ein Textknoten. Auch Leerraum wie Zeilenumbrüche im HTML bildet eigene Textknoten. Vor dem Zugriff sollte man deshalb nodeType === Node.TEXT_NODE prüfen.
Der Wert wird unverändert als Text gespeichert und nicht als HTML ausgewertet. Anders als innerHTML kann nodeValue daher keine XSS-Lücke öffnen.
Das Setzen erzeugt einen MutationObserver-Eintrag vom Typ characterData (bei Attributen vom Typ attributes).
Wird null zugewiesen, entsteht bei Textknoten eine leere Zeichenkette und nicht der Text "null".
Die Eigenschaft wird von allen Browsern unterstützt, auch von sehr alten.

Siehe auch

Node.textContent Node.nodeType Node.nodeName CharacterData.data Attr.value Document.createTreeWalker() Text