TextFormat.rangeStart — Eigenschaft · JavaScript-Referenz

Signatur

TextFormat.rangeStart

Beschreibung

Die Eigenschaft rangeStart gehört zur Schnittstelle TextFormat der EditContext-API. Sie liefert die Position (als Index in der Zeichenkette EditContext.text), an der ein Textbereich beginnt, den der Browser bzw. das Eingabemethoden-Fenster (IME) formatiert darstellen will – etwa unterstrichen während einer laufenden Komposition bei chinesischen, japanischen oder koreanischen Eingaben.

TextFormat-Objekte bekommt man meistens über das Ereignis textformatupdate eines EditContext: Die Methode TextFormatUpdateEvent.getTextFormats() gibt ein Array von TextFormat-Instanzen zurück. Jede davon beschreibt mit rangeStart und rangeEnd einen Bereich und mit underlineStyle sowie underlineThickness das gewünschte Aussehen.

Da ein EditContext den Text nicht selbst darstellt, ist die eigene Anwendung (z. B. ein Canvas-Editor oder ein selbst gebauter Rich-Text-Editor) für die Darstellung zuständig. Mit rangeStart weiß man, ab welchem Zeichen die Formatierung beginnt. Das Ende (rangeEnd) ist exklusiv, der Bereich reicht also von rangeStart bis rangeEnd - 1.

Rückgabewert

Typ

number

Beschreibung

Ein nicht negativer Ganzzahl-Index (UTF-16-Codeeinheiten) in EditContext.text, an dem der zu formatierende Bereich beginnt. Schreibgeschützt.

Beispiele

Formatbereiche beim textformatupdate-Ereignis auslesen

const editor = document.querySelector('#editor');
const editContext = new EditContext();
editor.editContext = editContext;

editContext.addEventListener('textformatupdate', (event) => {
  for (const format of event.getTextFormats()) {
    const { rangeStart, rangeEnd, underlineStyle, underlineThickness } = format;
    const ausschnitt = editContext.text.slice(rangeStart, rangeEnd);
    console.log(`Bereich ${rangeStart}–${rangeEnd} ("${ausschnitt}"): ${underlineStyle}, ${underlineThickness}`);
  }
});

Bereich 0–2 ("にほ"): solid, thin

Komposition mit der CSS Custom Highlight API unterstreichen

// CSS: ::highlight(ime-format) { text-decoration: underline; }
const editor = document.querySelector('#editor');
const editContext = new EditContext();
editor.editContext = editContext;

editContext.addEventListener('textupdate', () => {
  editor.textContent = editContext.text;
});

editContext.addEventListener('textformatupdate', (event) => {
  const textNode = editor.firstChild;
  if (!textNode) return;

  const ranges = event.getTextFormats().map((format) => {
    const range = new Range();
    range.setStart(textNode, format.rangeStart);
    range.setEnd(textNode, format.rangeEnd);
    return range;
  });

  CSS.highlights.set('ime-format', new Highlight(...ranges));
});

TextFormat direkt erzeugen (z. B. für Tests)

const format = new TextFormat({
  rangeStart: 3,
  rangeEnd: 7,
  underlineStyle: 'dashed',
  underlineThickness: 'thick'
});

console.log(format.rangeStart); // 3
console.log(format.rangeEnd - format.rangeStart); // Länge: 4

3 4

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die EditContext-API gibt es ab Chrome/Edge 121. Vor der Nutzung mit if ('EditContext' in window) prüfen und ein Fallback (z. B. contenteditable) bereitstellen.
Nur lesbar: Eine Zuweisung an rangeStart hat keine Wirkung. Werte lassen sich nur über den Konstruktor new TextFormat({ rangeStart, … }) setzen.
Index in UTF-16-Codeeinheiten: Emojis oder Zeichen außerhalb der BMP belegen zwei Einheiten. Bei eigener Darstellung (z. B. Canvas) muss man die Position entsprechend umrechnen.
Bezug auf EditContext.text: Der Index bezieht sich auf den Text des EditContext, nicht auf DOM-Knoten. Stimmt die eigene Darstellung nicht genau mit editContext.text überein, muss man die Positionen abbilden, sonst sitzt die Unterstreichung an der falschen Stelle.
Die Formatierung ist nur ein Hinweis der IME. Wendet man sie nicht an, funktioniert die Eingabe trotzdem, Nutzer von CJK-Eingabemethoden verlieren aber wichtiges visuelles Feedback.

Siehe auch

TextFormat TextFormat.rangeEnd TextFormat.underlineStyle TextFormat.underlineThickness TextFormatUpdateEvent.getTextFormats() EditContext