CharacterData.replaceData() — Methode · JavaScript-Referenz

Signatur

CharacterData.prototype.replaceData(offset, count, data)

Beschreibung

Mit replaceData() ersetzt man einen Teil des Textinhalts eines CharacterData-Knotens, also eines Text-, Comment-, CDATASection- oder ProcessingInstruction-Knotens. Ab dem Zeichenindex offset werden count Zeichen entfernt, und an ihrer Stelle wird data eingefügt. Die Methode ändert den Knoten direkt und gibt nichts zurück.

Im Grunde entspricht der Aufruf einem deleteData(offset, count) mit anschließendem insertData(offset, data), läuft aber als ein einziger Schritt ab. Das ist wichtig, weil eine aktive Range- oder Selection-Grenze im Knoten und ein MutationObserver (Typ characterData) dadurch nur eine einzige Änderung mitbekommen.

Man nutzt die Methode, wenn nur ein Teil eines Textknotens geändert werden soll, ohne textContent oder data komplett neu zu setzen. Typische Fälle sind Hervorhebungen, Platzhalter-Ersetzungen, Rechtschreibkorrekturen oder Editoren, in denen Cursor-Positionen und Ranges im restlichen Text erhalten bleiben sollen.

Alle Positionsangaben zählen in UTF-16-Codeeinheiten, genau wie String.prototype.length, und nicht in sichtbaren Zeichen (Graphemen).

Parameter

Name	Typ	Beschreibung
$offset Pflicht	number	Index (in UTF-16-Codeeinheiten), ab dem ersetzt wird. Ist er größer als `length` des Knotens, wird ein `IndexSizeError` ausgelöst.
$count Pflicht	number	Anzahl der zu entfernenden Codeeinheiten. Reicht `offset + count` über das Textende hinaus, wird bis zum Ende ersetzt. Bei `0` wird nur eingefügt.
$data Pflicht	string	Der Text, der anstelle des entfernten Bereichs eingefügt wird. Andere Werte werden in einen String umgewandelt. Der Text wird nicht als HTML interpretiert.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Der Knoten wird direkt verändert.

Beispiele

Grundlagen: ein Wort in einem Textknoten ersetzen

const text = document.createTextNode('Hallo Welt!');

// Ab Index 6 werden 4 Zeichen ("Welt") ersetzt
text.replaceData(6, 4, 'JavaScript');

console.log(text.data);
console.log(text.length);

Hallo JavaScript! 17

Platzhalter in einem Absatz ersetzen

// <p id="gruss">Guten Tag, {name}! Schön, dass du da bist.</p>
const p = document.getElementById('gruss');
const node = p.firstChild; // Textknoten

const platzhalter = '{name}';
const pos = node.data.indexOf(platzhalter);

if (pos !== -1) {
  node.replaceData(pos, platzhalter.length, 'Anna');
}

console.log(p.textContent);

Guten Tag, Anna! Schön, dass du da bist.

Änderung mit MutationObserver beobachten

const node = document.createTextNode('Status: offline');
document.body.append(node);

const observer = new MutationObserver((records) => {
  for (const r of records) {
    console.log(`Alt: "${r.oldValue}" → Neu: "${r.target.data}"`);
  }
  observer.disconnect();
});

observer.observe(node, { characterData: true, characterDataOldValue: true });

// Nur ein einziger Mutation-Record, nicht zwei
node.replaceData(8, 7, 'online');

Alt: "Status: offline" → Neu: "Status: online"

Fehlerbehandlung bei ungültigem Offset

const comment = document.createComment('TODO: aufräumen');

try {
  comment.replaceData(100, 1, 'x');
} catch (err) {
  console.log(err.name);
}

// count über das Ende hinaus: wird bis zum Ende ersetzt
comment.replaceData(6, 999, 'erledigt');
console.log(comment.data);

IndexSizeError TODO: erledigt

// Wichtig · Fallstricke

IndexSizeError: Ist offset größer als node.length, wird eine DOMException vom Typ IndexSizeError ausgelöst. Ein zu großer count ist dagegen erlaubt und wird auf das Textende gekürzt.
Negative Werte: offset und count werden in unsigned long umgewandelt. Aus -1 wird dabei eine riesige Zahl, was bei offset zu einem IndexSizeError führt. Werte vorher prüfen.
UTF-16: Emojis und viele Sonderzeichen belegen zwei Codeeinheiten. Wer mitten in einem Surrogat-Paar ersetzt, erzeugt kaputte Zeichen. Positionen deshalb mit indexOf() bzw. length ermitteln und nicht „von Hand“ zählen.
Kein HTML: data wird immer als reiner Text eingefügt. Die Methode ist daher sicher gegen XSS, erzeugt aber auch kein Markup. Für Hervorhebungen mit Elementen Text.splitText() oder Range verwenden.
Nur auf CharacterData: Auf Elementen gibt es die Methode nicht. Man braucht den konkreten Textknoten, z. B. über firstChild oder einen TreeWalker.
Wird in allen Browsern seit Jahren unterstützt, auch in jsdom unter Node.js.

Siehe auch

CharacterData CharacterData.insertData() CharacterData.deleteData() CharacterData.appendData() CharacterData.substringData() CharacterData.data Text.splitText() MutationObserver