CharacterData.insertData() — Methode · JavaScript-Referenz

Signatur

CharacterData.prototype.insertData(offset, data)

Beschreibung

insertData() ist eine Methode der Schnittstelle CharacterData. Diese Schnittstelle ist die gemeinsame Basis von Text, Comment, CDATASection und ProcessingInstruction. Die Methode fügt den übergebenen String data an der Position offset in die bestehenden Zeichendaten des Knotens ein. Der Text, der bisher ab dieser Position stand, rückt nach hinten.

Anders als eine Neuzuweisung über node.data = … oder textContent ändert insertData() den Knoten an Ort und Stelle. Der Knoten bleibt dasselbe Objekt, und aktive Range-Objekte sowie die Auswahl (Selection) werden laut DOM-Spezifikation automatisch an die neuen Positionen angepasst. Das ist nützlich für Editoren, Syntax-Hervorhebung oder Textbausteine, bei denen Cursor und Markierungen erhalten bleiben sollen.

Intern entspricht der Aufruf replaceData(offset, 0, data). Für einen MutationObserver mit characterData: true entsteht dabei genau ein Mutationsdatensatz vom Typ "characterData".

Wichtig: offset zählt UTF-16-Codeeinheiten, keine sichtbaren Zeichen. Emojis und andere Zeichen außerhalb der Basic Multilingual Plane belegen zwei Einheiten.

Parameter

Name	Typ	Default	Beschreibung
$offset Pflicht	number (unsigned long)		Position in UTF-16-Codeeinheiten, an der eingefügt wird. `0` fügt am Anfang ein, `node.length` am Ende. Ist der Wert größer als `node.length`, wird ein `IndexSizeError` geworfen.
$data Pflicht	string		Der einzufügende Text. Andere Werte werden in einen String umgewandelt (z. B. `42` → `"42"`). HTML-Markup wird nicht interpretiert, sondern als reiner Text eingefügt.

Rückgabewert

Typ

undefined

Beschreibung

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

Beispiele

Text in einen Textknoten einfügen

const p = document.createElement('p');
p.textContent = 'Hallo Welt!';
const textNode = p.firstChild;

// Nach "Hallo " (6 Codeeinheiten) einfügen
textNode.insertData(6, 'schöne ');
console.log(textNode.data);

// Am Ende anhängen
textNode.insertData(textNode.length, ' 👋');
console.log(p.textContent);

Hallo schöne Welt! Hallo schöne Welt! 👋

Kommentarknoten erweitern

const comment = document.createComment('Build: ');
document.body.append(comment);

comment.insertData(comment.length, new Date(0).toISOString().slice(0, 10));
console.log(comment.data);
console.log(document.body.lastChild.nodeType === Node.COMMENT_NODE);

Build: 1970-01-01 true

Fehlerbehandlung bei ungültigem Offset

const node = document.createTextNode('abc');

try {
  node.insertData(10, 'x'); // 10 > node.length (3)
} catch (err) {
  console.log(err.name);
}

// Negative Werte werden zu riesigen unsigned-Zahlen umgewandelt
try {
  node.insertData(-1, 'x');
} catch (err) {
  console.log(err.name);
}

IndexSizeError IndexSizeError

Änderungen mit MutationObserver beobachten

const span = document.createElement('span');
span.textContent = 'Preis: EUR';
document.body.append(span);
const text = span.firstChild;

const observer = new MutationObserver((records) => {
  for (const r of records) {
    console.log(r.type, '| alt:', r.oldValue, '| neu:', r.target.data);
  }
  observer.disconnect();
});
observer.observe(text, { characterData: true, characterDataOldValue: true });

text.insertData(7, '19,99 ');

characterData | alt: Preis: EUR | neu: Preis: 19,99 EUR

// Wichtig · Fallstricke

UTF-16-Offsets: '😀a'.length ist 3. Mit insertData(1, 'x') teilst du das Surrogat-Paar des Emojis und erzeugst ungültigen Text. Bei Unicode-lastigem Inhalt solltest du Positionen deshalb z. B. über Intl.Segmenter oder [...str] berechnen.
IndexSizeError: Wird geworfen, wenn offset > length ist. Negative Werte werden per WebIDL in unsigned long umgewandelt (aus -1 wird 4294967295) und lösen deshalb ebenfalls diesen Fehler aus.
Kein HTML: Der eingefügte String wird immer als Text behandelt. Die Methode ist daher XSS-sicher, anders als innerHTML. Wenn du Markup brauchst, verwende insertAdjacentHTML() oder erzeuge Elemente.
Die Methode gibt es nur auf CharacterData-Knoten. Auf Elementen führt der Aufruf zu einem TypeError. Den Textknoten erreichst du z. B. über element.firstChild.
Browser-Kompatibilität: Die Methode wird seit DOM Level 1 in allen Browsern unterstützt und funktioniert auch in DOM-Implementierungen wie jsdom.

Siehe auch

CharacterData.appendData() CharacterData.deleteData() CharacterData.replaceData() CharacterData.substringData() CharacterData.after()