CharacterData.substringData() — Methode · JavaScript-Referenz

Signatur

CharacterData.prototype.substringData(offset, count)

Beschreibung

substringData() ist eine Methode der Schnittstelle CharacterData. Sie steht deshalb an allen Knoten zur Verfügung, die Zeichendaten enthalten, also an Text, Comment, CDATASection und ProcessingInstruction. Die Methode liest einen Ausschnitt aus der Eigenschaft data. Er beginnt bei offset und umfasst höchstens count Zeichen.

Das Ergebnis entspricht weitgehend node.data.substring(offset, offset + count). Der Unterschied: Die Methode prüft ihre Argumente strenger. Ist offset größer als die Länge der Daten, wird eine DOMException vom Typ IndexSizeError ausgelöst. Reicht offset + count über das Ende hinaus, liefert die Methode einfach alle Zeichen bis zum Ende.

Nützlich ist substringData() in Programmen, die Textknoten direkt verarbeiten. Beispiele sind das Hervorheben von Suchtreffern, Auswertungen mit Range und Selection oder das Lesen von Kommentarknoten. Zusammen mit insertData(), deleteData() und replaceData() bildet sie einen einheitlichen Satz von Methoden auf Basis von Zeichenpositionen.

Parameter

Name	Typ	Default	Beschreibung
$offset Pflicht	number		Index des ersten zurückzugebenden Zeichens, beginnend bei 0 und gezählt in UTF-16-Codeeinheiten. Ist der Wert größer als `data.length`, wird ein `IndexSizeError` ausgelöst.
$count Pflicht	number		Maximale Anzahl der zurückzugebenden Zeichen. Reicht `offset + count` über das Ende der Daten hinaus, werden alle Zeichen bis zum Ende zurückgegeben.

Rückgabewert

Typ

string

Beschreibung

Der angeforderte Teilstring der Knotendaten. Ist count gleich 0 oder steht offset genau am Ende der Daten, ist es ein leerer String.

Beispiele

Teilstring aus einem Textknoten lesen

const p = document.createElement('p');
p.textContent = 'Willkommen bei programmierung.net';
const text = p.firstChild; // Text-Knoten

console.log(text.substringData(0, 10));
console.log(text.substringData(15, 100)); // count zu groß → bis zum Ende

Willkommen programmierung.net

Kontext um einen Suchtreffer ausschneiden

const getContext = (textNode, term, radius = 10) => {
  const index = textNode.data.indexOf(term);
  if (index === -1) return null;
  const start = Math.max(0, index - radius);
  const count = term.length + 2 * radius;
  return `…${textNode.substringData(start, count)}…`;
};

const node = document.createTextNode('Die Methode substringData liest Zeichen aus Textknoten.');
console.log(getContext(node, 'substringData'));

…e Methode substringData liest Ze…

Kommentarknoten auswerten und Fehler abfangen

const comment = document.createComment('build:2024-05-01');

console.log(comment.substringData(6, 10));

try {
  comment.substringData(50, 5); // offset > length
} catch (err) {
  console.log(err.name);
}

2024-05-01 IndexSizeError

// Wichtig · Fallstricke

Längen in UTF-16: offset und count werden in UTF-16-Codeeinheiten gezählt, nicht in Unicode-Zeichen. Emojis und andere Zeichen außerhalb der BMP belegen zwei Einheiten und können deshalb mitten durchgeschnitten werden. Das Ergebnis enthält dann ungültige halbe Surrogatpaare.
Ausnahme bei ungültigem offset: Ist offset größer als data.length, wird ein IndexSizeError ausgelöst. String.prototype.substring() kürzt solche Werte dagegen stillschweigend.
Negative Werte: Die Argumente werden in vorzeichenlose 32-Bit-Ganzzahlen umgewandelt. Aus -1 wird so 4294967295. Als offset führt das zu einem IndexSizeError, als count zu „alles bis zum Ende".
Beide Argumente sind Pflicht: Fehlt eines, wird ein TypeError ausgelöst.
Kompatibilität: Wird seit DOM Level 1 von allen Browsern unterstützt, ebenso von DOM-Implementierungen wie jsdom.

Siehe auch

CharacterData CharacterData.data CharacterData.length CharacterData.replaceData() CharacterData.deleteData() CharacterData.insertData() String.prototype.substring() Text