TextFormat.underlineStyle — Eigenschaft · JavaScript-Referenz

Signatur

TextFormat.underlineStyle

Beschreibung

Die Eigenschaft underlineStyle der Schnittstelle TextFormat gehört zur EditContext API. Sie gibt den Unterstreichungsstil an, den ein Eingabemethoden-Editor (IME) für einen bestimmten Textbereich vorschlägt. Das passiert zum Beispiel bei der Eingabe von Japanisch, Chinesisch oder Koreanisch, wo der noch nicht bestätigte Kompositionstext meist unterstrichen dargestellt wird.

TextFormat-Objekte erhältst du über die Methode getTextFormats() des Events textformatupdate, das auf einem EditContext ausgelöst wird. Jedes Objekt beschreibt mit rangeStart und rangeEnd einen Bereich und nennt über underlineStyle und underlineThickness die gewünschte Darstellung.

Weil du bei der EditContext API das Rendern des Textes selbst übernimmst (etwa in einem <canvas> oder in eigenem DOM), musst du diese Formatierung auch selbst umsetzen. Das geht zum Beispiel mit der CSS-Eigenschaft text-decoration-style oder mit der CSS Custom Highlight API. Die möglichen Werte passen direkt zu den CSS-Werten: "solid", "dotted", "dashed" und "wavy". Dazu kommt "none" für „keine Unterstreichung“.

Rückgabewert

Typ

"none" | "solid" | "dotted" | "dashed" | "wavy"

Beschreibung

Eine schreibgeschützte Zeichenkette mit dem Unterstreichungsstil, den der IME für den Bereich rangeStart bis rangeEnd vorschlägt.

Beispiele

Unterstreichungsstile beim textformatupdate-Event auslesen

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

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

Bereich 0–3: solid, thin Bereich 3–5: solid, thick

Stil in CSS text-decoration übersetzen (eigenes DOM-Rendering)

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

const thicknessMap = { none: '0', thin: '1px', thick: '2px' };

editContext.addEventListener('textformatupdate', (event) => {
  // Alte Markierungen entfernen
  editor.querySelectorAll('span[data-ime]').forEach((s) => s.replaceWith(...s.childNodes));

  for (const { rangeStart, rangeEnd, underlineStyle, underlineThickness } of event.getTextFormats()) {
    if (underlineStyle === 'none') continue;
    const range = document.createRange();
    range.setStart(editor.firstChild, rangeStart);
    range.setEnd(editor.firstChild, rangeEnd);

    const span = document.createElement('span');
    span.dataset.ime = '';
    span.style.textDecorationLine = 'underline';
    span.style.textDecorationStyle = underlineStyle; // solid | dotted | dashed | wavy
    span.style.textDecorationThickness = thicknessMap[underlineThickness];
    range.surroundContents(span);
  }
});

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

if ('TextFormat' in window) {
  const format = new TextFormat({
    rangeStart: 0,
    rangeEnd: 4,
    underlineStyle: 'wavy',
    underlineThickness: 'thin'
  });
  console.log(format.underlineStyle);
} else {
  console.log('EditContext API wird nicht unterstützt');
}

wavy

// Wichtig · Fallstricke

Experimentell: Die EditContext API gibt es bisher nur in Chromium-Browsern (Chrome/Edge ab Version 121). Prüfe die Unterstützung vorher mit 'EditContext' in window.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung.
Die Groß- und Kleinschreibung der Werte hängt von der Browserversion ab. Frühe Chromium-Versionen lieferten großgeschriebene Werte wie "Solid" oder "Wavy". Vergleiche daher robust, zum Beispiel mit underlineStyle.toLowerCase().
Das Event textformatupdate wird nur während einer aktiven IME-Komposition ausgelöst. Bei normaler Tastatureingabe siehst du keine TextFormat-Objekte.
Wie die Formate verteilt sind, entscheiden IME und Betriebssystem. Ein Stil wie "wavy" kommt je nach Plattform eventuell nie vor.
rangeStart und rangeEnd sind Positionen im Text des EditContext (UTF-16-Codeeinheiten), nicht im DOM. Du musst sie selbst auf deine Darstellung umrechnen.

Siehe auch

TextFormat TextFormat.underlineThickness TextFormat.rangeStart TextFormat.rangeEnd TextFormatUpdateEvent.getTextFormats() EditContext PerformanceScriptTiming.invokerType