new TextFormat() — Methode · JavaScript-Referenz

Signatur

new TextFormat(options)

Beschreibung

Der Konstruktor TextFormat() gehört zur EditContext-API. Ein TextFormat-Objekt beschreibt die Formatierung eines Textbereichs, den ein Eingabemethoden-Editor (IME) gerade bearbeitet. Das betrifft zum Beispiel die Eingabe von Japanisch, Chinesisch oder Koreanisch. Das Objekt legt fest, wo der Bereich beginnt und endet und welche Unterstreichung (Stil und Stärke) die Anwendung dort zeichnen soll.

In der Praxis erzeugt man TextFormat-Objekte selten selbst. Normalerweise liefert sie der Browser: Er löst auf einem EditContext das Ereignis textformatupdate aus, und dessen Methode getTextFormats() gibt ein Array von TextFormat-Instanzen zurück. Den Konstruktor braucht man vor allem für Unit-Tests, Mocks und die Simulation von IME-Zuständen. Er hilft auch, wenn man eigene Render-Logik unabhängig von echten Eingaben testen möchte.

Alle Eigenschaften (rangeStart, rangeEnd, underlineStyle, underlineThickness) sind schreibgeschützt. Sie werden einmal bei der Erzeugung festgelegt. Für eine andere Formatierung muss man ein neues Objekt anlegen.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Objekt zur Initialisierung. Mögliche Felder siehe unten.
$options.rangeStart	number	0	Startposition des formatierten Bereichs, gezählt in UTF-16-Codeeinheiten (inklusive).
$options.rangeEnd	number	0	Endposition des formatierten Bereichs, gezählt in UTF-16-Codeeinheiten (exklusive).
$options.underlineStyle	"none" \| "solid" \| "dotted" \| "dashed" \| "wavy"	"none"	Stil der Unterstreichung für den Bereich.
$options.underlineThickness	"none" \| "thin" \| "thick"	"none"	Stärke der Unterstreichung für den Bereich.

Rückgabewert

Typ

TextFormat

Beschreibung

Ein neues TextFormat-Objekt mit den übergebenen (schreibgeschützten) Werten.

Beispiele

TextFormat-Objekt direkt erzeugen

// Bereich von Zeichen 0 bis 5 mit dünner Wellenlinie
const format = new TextFormat({
  rangeStart: 0,
  rangeEnd: 5,
  underlineStyle: 'wavy',
  underlineThickness: 'thin'
});

console.log(format.rangeStart, format.rangeEnd);
console.log(format.underlineStyle, format.underlineThickness);

0 5 wavy thin

Formate aus dem textformatupdate-Ereignis rendern

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

// CSS-Werte passend zu den TextFormat-Angaben
const styleMap = { solid: 'solid', dotted: 'dotted', dashed: 'dashed', wavy: 'wavy', none: 'none' };
const thicknessMap = { thin: '1px', thick: '2px', none: '0' };

editContext.addEventListener('textformatupdate', (event) => {
  for (const fmt of event.getTextFormats()) {
    const style = styleMap[fmt.underlineStyle.toLowerCase()] ?? 'none';
    const width = thicknessMap[fmt.underlineThickness.toLowerCase()] ?? '0';
    console.log(`Bereich ${fmt.rangeStart}–${fmt.rangeEnd}: ${style}, ${width}`);
    // Hier z. B. <span> mit text-decoration erzeugen
  }
});

Bereich 0–3: solid, 2px Bereich 3–6: dotted, 1px

IME-Zustand im Test simulieren

// Eigene Render-Funktion, die TextFormat-Objekte verarbeitet
const renderFormats = (text, formats) =>
  formats.map(({ rangeStart, rangeEnd, underlineStyle }) =>
    `[${text.slice(rangeStart, rangeEnd)}:${underlineStyle}]`
  ).join('');

// Test ohne echte IME-Eingabe
const mockFormats = [
  new TextFormat({ rangeStart: 0, rangeEnd: 2, underlineStyle: 'solid', underlineThickness: 'thick' }),
  new TextFormat({ rangeStart: 2, rangeEnd: 4, underlineStyle: 'dashed', underlineThickness: 'thin' })
];

console.log(renderFormats('東京都庁', mockFormats));

[東京:solid][都庁:dashed]

// Wichtig · Fallstricke

Experimentell: TextFormat und die gesamte EditContext-API gibt es bisher nur in Chromium-basierten Browsern (ab Version 121). Vor der Nutzung sollte man per Feature-Erkennung prüfen, ob sie vorhanden ist: if ('TextFormat' in window) { … }.
Ältere Chromium-Versionen lieferten die Werte großgeschrieben (z. B. "Solid", "Thin"). Beim Vergleich sollte man deshalb toLowerCase() verwenden.
Die Eigenschaften sind schreibgeschützt. Zuweisungen wie format.rangeEnd = 10 haben keine Wirkung.
Positionen werden in UTF-16-Codeeinheiten gezählt, nicht in Graphemen. Emojis und Zeichen außerhalb der BMP (Basic Multilingual Plane) belegen also zwei Einheiten.
Der Browser zeichnet die Unterstreichung nicht selbst. Die Anwendung muss sie selbst darstellen, etwa über text-decoration oder die CSS Custom Highlight API.

Siehe auch

TextFormat EditContext TextFormatUpdateEvent new Document() new FormData()