CharacterData — Schnittstelle · JavaScript-Referenz

Signatur

interface CharacterData extends Node

Beschreibung

CharacterData ist ein abstraktes Interface. Man erzeugt davon nie direkt ein Objekt, sondern arbeitet mit den abgeleiteten Typen Text, Comment, CDATASection und ProcessingInstruction. Es erbt von Node und stellt die gemeinsamen Eigenschaften und Methoden bereit, mit denen man den Textinhalt eines solchen Knotens liest und gezielt ändert.

Die wichtigsten Mitglieder sind:

Eigenschaften: data (der Textinhalt, lesbar und schreibbar), length (Anzahl der UTF-16-Codeeinheiten, nur lesbar), nextElementSibling und previousElementSibling (das benachbarte Element).
Methoden zur Textbearbeitung: appendData(data), insertData(offset, data), deleteData(offset, count), replaceData(offset, count, data) und substringData(offset, count).
Methoden aus ChildNode: before(...nodes), after(...nodes), replaceWith(...nodes) und remove().

Das Interface ist nützlich, wenn Text innerhalb eines Knotens geändert werden soll, ohne den Knoten neu zu erzeugen. Das ist etwa bei Hervorhebungen, bei Live-Zählern oder bei Editoren wichtig, denn Referenzen, Range-Objekte und die Cursor-Position bleiben dabei erhalten. Die Änderungen lösen bei einem MutationObserver Einträge vom Typ characterData aus.

Parameter

Name	Typ	Beschreibung
$offset Pflicht	number	Position in UTF-16-Codeeinheiten, ab der gearbeitet wird. Gilt für `insertData`, `deleteData`, `replaceData` und `substringData`. Ist der Wert größer als `length`, wird ein `IndexSizeError` ausgelöst.
$count Pflicht	number	Anzahl der Codeeinheiten, die gelöscht, ersetzt oder gelesen werden. Reicht der Bereich über das Ende hinaus, wird er auf das Ende gekürzt.
$data Pflicht	string	Text, der angehängt, eingefügt oder als Ersatz verwendet wird. Gilt für `appendData`, `insertData` und `replaceData`.

Rückgabewert

Typ

string | void

Beschreibung

substringData() gibt den gelesenen Teilstring zurück. Die übrigen Methoden zum Ändern (appendData, insertData, deleteData, replaceData) geben undefined zurück.

Beispiele

Instanzen über abgeleitete Typen erzeugen

const text = document.createTextNode('Hallo');
const kommentar = document.createComment(' Build 42 ');

console.log(text instanceof CharacterData);      // true
console.log(kommentar instanceof CharacterData); // true
console.log(text.data, text.length);

// Direkt instanziieren geht nicht:
try {
  new CharacterData();
} catch (e) {
  console.log(e.name);
}

true true Hallo 5 TypeError

Text im Knoten gezielt bearbeiten

const node = document.createTextNode('Preis: 10 EUR');

node.replaceData(7, 2, '12');   // '10' → '12'
node.insertData(0, '» ');
node.appendData(' (inkl. MwSt.)');
console.log(node.data);

console.log(node.substringData(9, 6));
node.deleteData(0, 2);
console.log(node.data);

» Preis: 12 EUR (inkl. MwSt.) 12 EUR Preis: 12 EUR (inkl. MwSt.)

Live-Zähler ohne neuen DOM-Knoten

const status = document.createElement('p');
status.textContent = 'Ungelesen: 0';
document.body.append(status);

const textNode = status.firstChild; // Text-Knoten
let count = 0;

const tick = () => {
  count += 1;
  // Nur den Zahlenanteil ersetzen – der Knoten bleibt derselbe
  textNode.replaceData(11, textNode.length - 11, String(count));
};

tick();
tick();
console.log(textNode.data);

Ungelesen: 2

Änderungen mit MutationObserver beobachten

const p = document.createElement('p');
p.textContent = 'Entwurf';
document.body.append(p);

const observer = new MutationObserver((records) => {
  for (const r of records) {
    console.log(r.type, JSON.stringify(r.oldValue), '→', JSON.stringify(r.target.data));
  }
});

observer.observe(p, { characterData: true, characterDataOldValue: true, subtree: true });
p.firstChild.appendData(' v2');

characterData "Entwurf" → "Entwurf v2"

// Wichtig · Fallstricke

Offsets zählen UTF-16-Codeeinheiten, nicht Zeichen. Emojis und andere Zeichen außerhalb der BMP belegen 2 Einheiten. Mit deleteData oder substringData kann man daher ein Surrogatpaar zerteilen und erhält so ungültigen Text.
Ein offset größer als length löst eine DOMException vom Typ IndexSizeError aus. Ein zu großes count wird dagegen stillschweigend gekürzt.
Auch null als Wert von data wird zu einem leeren String. textContent und nodeValue verhalten sich bei diesen Knoten genauso wie data.
Zeichendaten werden immer als reiner Text behandelt und nie als HTML interpretiert. Das ist eine sichere Alternative zu innerHTML, wenn Benutzereingaben angezeigt werden sollen (kein XSS-Risiko).
Browser-Kompatibilität: Die Kernmethoden werden überall unterstützt. before, after, replaceWith und remove gibt es erst in modernen Browsern, nicht im Internet Explorer.
CDATASection gibt es nur in XML-Dokumenten. In HTML-Dokumenten löst createCDATASection() einen NotSupportedError aus.

Siehe auch

Node Text Comment CDATASection ProcessingInstruction MutationObserver Document.createTextNode()