new TextFormatUpdateEvent() — Methode · JavaScript-Referenz

Signatur

new TextFormatUpdateEvent(type, options)

Beschreibung

Der Konstruktor TextFormatUpdateEvent() gehört zur EditContext API. Ein TextFormatUpdateEvent wird normalerweise vom Browser am EditContext ausgelöst (Ereignistyp textformatupdate), wenn ein Eingabemethoden-Editor (IME) – etwa für Japanisch, Chinesisch oder Koreanisch – festlegt, wie Teile des gerade komponierten Textes dargestellt werden sollen, z. B. mit welcher Unterstreichung.

Den Konstruktor selbst ruft man in der Praxis selten auf. Er ist vor allem nützlich für Tests, Polyfills oder um eigene Editor-Komponenten mit synthetischen Ereignissen zu prüfen, ohne echte IME-Eingaben zu benötigen. Die mitgegebenen Formate lassen sich später über event.getTextFormats() abfragen.

Jedes Format ist ein TextFormat-Objekt mit den Eigenschaften rangeStart, rangeEnd, underlineStyle ("none", "solid", "dotted", "dashed", "wavy") und underlineThickness ("none", "thin", "thick"). Die Bereichsangaben beziehen sich auf Zeichen-Offsets im Text des EditContext.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"textformatupdate"` (Groß-/Kleinschreibung beachten).
$options	object	{}	Optionales Konfigurationsobjekt. Neben den Optionen von `Event()` (`bubbles`, `cancelable`, `composed`) unterstützt es: `textFormats` (`TextFormat[]`): Liste der Formatierungen, die das Ereignis tragen soll. Standard: leeres Array.

Rückgabewert

Typ

TextFormatUpdateEvent

Beschreibung

Ein neues TextFormatUpdateEvent-Objekt, dessen Formate über getTextFormats() abrufbar sind.

Beispiele

Ereignis mit einem Unterstreichungsformat erzeugen

const format = new TextFormat({
  rangeStart: 0,
  rangeEnd: 5,
  underlineStyle: 'wavy',
  underlineThickness: 'thin'
});

const event = new TextFormatUpdateEvent('textformatupdate', {
  textFormats: [format]
});

const [f] = event.getTextFormats();
console.log(event.type, f.rangeStart, f.rangeEnd, f.underlineStyle);

textformatupdate 0 5 wavy

Synthetisches Ereignis zum Testen eines Editors auslösen

const canvas = document.querySelector('#editor');
const editContext = new EditContext({ text: 'こんにちは' });
canvas.editContext = editContext;

editContext.addEventListener('textformatupdate', (e) => {
  for (const fmt of e.getTextFormats()) {
    console.log(`Bereich ${fmt.rangeStart}-${fmt.rangeEnd}: ${fmt.underlineStyle}/${fmt.underlineThickness}`);
  }
});

// IME-Verhalten simulieren
editContext.dispatchEvent(new TextFormatUpdateEvent('textformatupdate', {
  textFormats: [
    new TextFormat({ rangeStart: 0, rangeEnd: 3, underlineStyle: 'solid', underlineThickness: 'thick' }),
    new TextFormat({ rangeStart: 3, rangeEnd: 5, underlineStyle: 'dashed', underlineThickness: 'thin' })
  ]
}));

Bereich 0-3: solid/thick Bereich 3-5: dashed/thin

Feature-Erkennung vor der Verwendung

const supportsEditContext =
  'EditContext' in window && typeof TextFormatUpdateEvent === 'function';

if (supportsEditContext) {
  const evt = new TextFormatUpdateEvent('textformatupdate');
  console.log(evt.getTextFormats().length);
} else {
  console.log('EditContext API wird nicht unterstützt – Fallback auf contenteditable');
}

// Wichtig · Fallstricke

Experimentell: Die EditContext API ist nur in Chromium-Browsern (ab Version 121) verfügbar. Firefox und Safari unterstützen weder TextFormatUpdateEvent noch TextFormat – immer per Feature-Erkennung prüfen.
Synthetisch erzeugte Ereignisse haben isTrusted === false; der Browser rendert dadurch nichts automatisch. Die Darstellung der Unterstreichungen (z. B. auf einem <canvas>) ist stets Aufgabe des eigenen Codes.
Die Formate stehen nicht als Eigenschaft bereit, sondern nur über die Methode getTextFormats().
rangeStart/rangeEnd sind Offsets in UTF-16-Codeeinheiten – bei Emojis oder Surrogatpaaren entspricht das nicht der Anzahl sichtbarer Zeichen.

Siehe auch

TextFormatUpdateEvent TextFormatUpdateEvent.prototype.getTextFormats() TextFormat EditContext CharacterBoundsUpdateEvent TextUpdateEvent