InputEvent.getTargetRanges() — Methode · JavaScript-Referenz

Signatur

InputEvent.prototype.getTargetRanges()

Beschreibung

getTargetRanges() liefert bei einem beforeinput-Ereignis die Bereiche im Dokument, die der Browser gleich verändern will: zum Beispiel die markierte Auswahl, die durch getippten Text ersetzt wird, oder das Zeichen bzw. Wort, das Backspace oder Strg+Backspace löschen würde. So kann ein Editor schon vor der Änderung wissen, was genau betroffen ist.

Am meisten bringt die Methode in eigenen Rich-Text-Editoren auf Basis von contenteditable. Dort bricht man das Standardverhalten mit event.preventDefault() ab und wendet die Änderung selbst auf das eigene Dokumentmodell an. Die Zielbereiche sagen einem dabei, welche Knoten und Offsets der Browser verändert hätte. Das ist besonders wichtig bei Löschvorgängen, deren Umfang von der Sprache, von Graphem-Clustern (Emojis) oder von Wortgrenzen abhängt.

Zurück kommen StaticRange-Objekte. Anders als Range werden sie nicht automatisch angepasst, wenn sich das DOM ändert. Sie zeigen also nur den Zustand zum Zeitpunkt des Ereignisses. Wer sie später noch braucht, sollte sie sofort auswerten oder mit document.createRange() in ein echtes Range umwandeln.

Rückgabewert

Typ

StaticRange[]

Beschreibung

Ein Array von StaticRange-Objekten mit startContainer, startOffset, endContainer, endOffset und collapsed. Bei input-Ereignissen und bei Eingaben in <input>/<textarea> ist das Array in der Regel leer.

Beispiele

Betroffene Bereiche vor dem Löschen protokollieren

// HTML: <div id="editor" contenteditable>Hallo Welt</div>
const editor = document.getElementById('editor');

editor.addEventListener('beforeinput', (event) => {
  const ranges = event.getTargetRanges();
  for (const r of ranges) {
    const text = r.startContainer === r.endContainer
      ? r.startContainer.textContent.slice(r.startOffset, r.endOffset)
      : '(mehrere Knoten)';
    console.log(event.inputType, r.startOffset, r.endOffset, JSON.stringify(text));
  }
});

// Cursor hinter „Welt“, einmal Backspace: deleteContentBackward 9 10 "t"

Löschen selbst übernehmen (eigener Editor)

const editor = document.querySelector('[contenteditable]');

editor.addEventListener('beforeinput', (event) => {
  if (!event.inputType.startsWith('delete')) return;

  const [target] = event.getTargetRanges();
  if (!target || target.collapsed) return;

  event.preventDefault(); // Browser soll nichts ändern

  // StaticRange in ein echtes Range umwandeln und selbst löschen
  const range = document.createRange();
  range.setStart(target.startContainer, target.startOffset);
  range.setEnd(target.endContainer, target.endOffset);
  const removed = range.toString();
  range.deleteContents();

  console.log(`Entfernt: "${removed}"`);
});

// Wort markiert und Entf gedrückt: Entfernt: "Welt"

Schutz für nicht editierbare Elemente

// Löschen verhindern, wenn ein geschützter Platzhalter betroffen wäre
const editor = document.querySelector('#editor');

editor.addEventListener('beforeinput', (event) => {
  const betroffen = event.getTargetRanges().some((r) => {
    const range = document.createRange();
    range.setStart(r.startContainer, r.startOffset);
    range.setEnd(r.endContainer, r.endOffset);
    return [...editor.querySelectorAll('.platzhalter')]
      .some((el) => range.intersectsNode(el));
  });

  if (betroffen) {
    event.preventDefault();
    console.warn('Platzhalter dürfen nicht gelöscht werden.');
  }
});

Platzhalter dürfen nicht gelöscht werden.

// Wichtig · Fallstricke

Nur bei beforeinput nützlich: Im input-Ereignis ist die Änderung schon passiert. Das Array ist dann meist leer.
Nur für contenteditable: Bei <input> und <textarea> gibt es keine DOM-Knoten als Ziel. Hier liefert die Methode ein leeres Array. Stattdessen nutzt man selectionStart/selectionEnd.
StaticRange ist statisch: Nach DOM-Änderungen können die Offsets ungültig sein. Werten Sie die Bereiche deshalb sofort aus.
IME/Komposition: Bei insertCompositionText kann man das Ereignis nicht abbrechen. preventDefault() wirkt dort nicht, und die Bereiche können sich während der Komposition mehrmals ändern.
Kompatibilität: In allen aktuellen Browsern verfügbar (Firefox seit Version 87). Welche Bereiche genau geliefert werden, kann je nach Browser leicht abweichen, etwa bei Wortgrenzen oder Zeilenumbrüchen. Prüfen Sie vorher mit typeof event.getTargetRanges === 'function'.

Siehe auch

Range new XMLHttpRequest() GPUBuffer.getMappedRange() Document.createRange() new EventTarget()