FontFace.variant — Eigenschaft · JavaScript-Referenz

Signatur

FontFace.variant

Beschreibung

Die Eigenschaft variant einer FontFace-Instanz gibt als String an, welche typografischen Varianten die Schrift bereitstellt. Die Werte entsprechen der CSS-Kurzschreibweise font-variant, zum Beispiel "small-caps", "oldstyle-nums" oder "common-ligatures tabular-nums". Der Standardwert ist "normal".

Die Eigenschaft kann gelesen und geschrieben werden. Ein Anfangswert lässt sich im Konstruktor über das Deskriptor-Objekt festlegen (new FontFace(family, source, { variant: "small-caps" })). Man kann ihn aber auch später direkt zuweisen, bevor die Schrift mit document.fonts.add() registriert wird. Wird ein syntaktisch ungültiger Wert zugewiesen, wirft der Browser einen SyntaxError.

Wichtig: Der zugehörige font-variant-Deskriptor für @font-face wurde aus der Spezifikation CSS Fonts Level 4 entfernt. FontFace.variant gilt deshalb als veraltet und nicht standardisiert. Für neuen Code sollte man OpenType-Features über FontFace.featureSettings steuern oder font-variant-* direkt am Element per CSS setzen.

Parameter

Name	Typ	Default	Beschreibung
$value (Setter)	string	"normal"	Ein gültiger Wert für `font-variant`, z. B. `"small-caps"` oder `"oldstyle-nums proportional-nums"`. Bei ungültiger Syntax wird ein `SyntaxError` geworfen.

Rückgabewert

Typ

string

Beschreibung

Die aktuell gesetzten Varianten-Werte als String, standardmäßig "normal". In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Unterstützung prüfen und Wert lesen

const font = new FontFace("Inter", "url(/fonts/inter.woff2)");

if ("variant" in FontFace.prototype) {
  console.log("variant:", font.variant);
} else {
  console.log("FontFace.variant wird nicht unterstützt");
}

variant: normal (oder: FontFace.variant wird nicht unterstützt)

Variante im Konstruktor festlegen und Schrift laden

const loadSmallCaps = async () => {
  const font = new FontFace(
    "MerriweatherSC",
    "url(/fonts/merriweather-sc.woff2) format('woff2')",
    { variant: "small-caps", weight: "400" }
  );

  await font.load();
  document.fonts.add(font);
  console.log(`${font.family} geladen, variant = ${font.variant}`);
};

loadSmallCaps().catch(console.error);

MerriweatherSC geladen, variant = small-caps

Wert nachträglich setzen, mit Fehlerbehandlung und Ersatzlösung

const font = new FontFace("Numbers", "url(/fonts/numbers.woff2)");

try {
  if ("variant" in font) {
    font.variant = "tabular-nums";
  } else {
    // Standardkonforme Alternative über OpenType-Features
    font.featureSettings = '"tnum" 1';
  }
  console.log(font.variant ?? font.featureSettings);
} catch (err) {
  console.error("Ungültiger Wert:", err.name);
}

tabular-nums (oder: "tnum" 1)

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Der font-variant-Deskriptor wurde aus CSS Fonts Level 4 entfernt. Browser unterstützen die Eigenschaft nur teilweise oder gar nicht. Deshalb vorher mit "variant" in FontFace.prototype prüfen.
Die Eigenschaft sagt nur aus, welche Varianten die Schrift bereitstellt. Sie schaltet am Element keine Varianten ein und erzeugt keine künstlichen Kapitälchen. Für die Darstellung sind CSS-Eigenschaften wie font-variant-caps zuständig.
Ungültige Werte lösen einen SyntaxError aus. Zuweisungen deshalb in try/catch einschließen.
Änderungen nach dem Laden, also nach document.fonts.add(), wirken sich nicht in allen Browsern zuverlässig auf die Schriftauswahl aus. Den Wert daher am besten vor dem Registrieren festlegen.
Standardkonforme Alternative: FontFace.featureSettings verwenden, z. B. '"smcp" 1'.

Siehe auch

FontFace.display FontFace.family FontFace.weight FontFace.stretch FontFace.loaded