TextFormat.underlineThickness — Eigenschaft · JavaScript-Referenz

Signatur

TextFormat.underlineThickness

Beschreibung

Die Eigenschaft underlineThickness gehört zur Schnittstelle TextFormat aus der EditContext API. Ein TextFormat-Objekt beschreibt, wie ein Textabschnitt während einer Komposition mit einem Eingabemethoden-Editor (IME) aussehen soll. Das betrifft zum Beispiel die Eingabe von Japanisch, Chinesisch oder Koreanisch. Der Abschnitt wird über rangeStart und rangeEnd festgelegt.

Welche Formate gelten, erfährt man über das Ereignis textformatupdate eines EditContext. Dessen Methode getTextFormats() liefert ein Array von TextFormat-Objekten. Weil ein EditContext den Text nicht selbst darstellt, muss der eigene Rendering-Code (z. B. Canvas oder eigenes DOM) diese Hinweise selbst umsetzen. underlineThickness sagt dabei, ob der Abschnitt dünn, dick oder gar nicht unterstrichen werden soll. Typischerweise hebt die IME so das aktuell gewählte Segment (dick) von den übrigen Kompositions-Segmenten (dünn) ab.

Der Wert ist eine der Zeichenketten "none", "thin" oder "thick". Wie viele Pixel „dünn“ oder „dick“ sind, legt die Spezifikation nicht fest. Diese Zuordnung trifft die eigene Anwendung, häufig über die CSS-Eigenschaft text-decoration-thickness.

Rückgabewert

Typ

string

Beschreibung

Einer der Werte "none", "thin" oder "thick". Die Eigenschaft ist nur lesbar.

Beispiele

Unterstreichungsdicke im 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()) {
    console.log(
      `Bereich ${format.rangeStart}–${format.rangeEnd}: ` +
      `Stil=${format.underlineStyle}, Dicke=${format.underlineThickness}`
    );
  }
});

Bereich 0–2: Stil=solid, Dicke=thick Bereich 2–5: Stil=dashed, Dicke=thin

Dicke mit der CSS Custom Highlight API darstellen

// CSS (z. B. im Stylesheet):
// ::highlight(ime-thin)  { text-decoration: underline; text-decoration-thickness: 1px; }
// ::highlight(ime-thick) { text-decoration: underline; text-decoration-thickness: 3px; }

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

const thin = new Highlight();
const thick = new Highlight();
CSS.highlights.set('ime-thin', thin);
CSS.highlights.set('ime-thick', thick);

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

  for (const format of event.getTextFormats()) {
    if (format.underlineThickness === 'none') continue;
    const range = new Range();
    range.setStart(textNode, format.rangeStart);
    range.setEnd(textNode, format.rangeEnd);
    (format.underlineThickness === 'thick' ? thick : thin).add(range);
  }
});

Zuordnung auf Pixelwerte für Canvas-Rendering

const thicknessToPx = { none: 0, thin: 1, thick: 3 };

const drawUnderline = (ctx, format, xStart, xEnd, baselineY) => {
  const width = thicknessToPx[format.underlineThickness] ?? 1;
  if (width === 0) return;
  ctx.lineWidth = width;
  ctx.beginPath();
  ctx.moveTo(xStart, baselineY + 2);
  ctx.lineTo(xEnd, baselineY + 2);
  ctx.stroke();
};

// Testobjekt, aufgebaut wie ein TextFormat
const format = { rangeStart: 0, rangeEnd: 3, underlineStyle: 'solid', underlineThickness: 'thick' };
console.log(thicknessToPx[format.underlineThickness]);

3

// Wichtig · Fallstricke

Experimentell: Die EditContext API gibt es nur in Chromium-Browsern ab Version 121. Firefox und Safari unterstützen sie nicht. Vorher per 'EditContext' in window prüfen, ob die API vorhanden ist, und sonst auf contenteditable oder <textarea> ausweichen.
Die Eigenschaft ist nur lesbar. Den Wert zu ändern, hat keine Wirkung auf die IME.
Der Browser stellt die Unterstreichung nicht selbst dar. Wer das Ereignis textformatupdate nicht auswertet, zeigt keine Hinweise zur Komposition an.
Die Werte werden kleingeschrieben geliefert ("thin", nicht "Thin"). Ältere Entwürfe der Spezifikation nutzten großgeschriebene Werte. Der Vergleich sollte deshalb robust sein.
rangeStart und rangeEnd beziehen sich auf den Text des EditContext, nicht direkt auf DOM-Knoten. Die Positionen müssen also selbst auf das eigene Rendering übertragen werden.

Siehe auch

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