CSSFontFaceDescriptors — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSFontFaceDescriptors extends CSSStyleDeclaration

Beschreibung

CSSFontFaceDescriptors ist der Typ des Objekts, das die Eigenschaft style einer CSSFontFaceRule zurückgibt. Es erbt von CSSStyleDeclaration und bietet damit dieselben Methoden (getPropertyValue(), setProperty(), removeProperty(), item(), length, cssText). Anders als ein allgemeiner Deklarationsblock enthält es aber nur die Deskriptoren, die in einer @font-face-Regel gültig sind.

Jeder Deskriptor ist zweimal verfügbar: in camelCase (fontFamily, fontDisplay, unicodeRange) und in Bindestrich-Schreibweise über die Klammer-Notation (style["font-family"]). Verfügbar sind unter anderem:

src, fontFamily, fontStyle, fontWeight, fontStretch/fontWidth
fontDisplay, unicodeRange, fontFeatureSettings, fontVariationSettings
ascentOverride, descentOverride, lineGapOverride, sizeAdjust

Sinnvoll ist das Interface, wenn du Webfont-Regeln zur Laufzeit untersuchen oder anpassen willst, etwa um alle eingebundenen Schriftquellen aufzulisten, font-display nachträglich auf swap umzustellen oder Fallback-Metriken (size-adjust, ascent-override) gegen Layoutverschiebungen (CLS) zu testen. Ein eigener Konstruktor existiert nicht; du bekommst das Objekt immer über eine vorhandene @font-face-Regel.

Parameter

Name	Typ	Default	Beschreibung
$src	string	""	Deskriptor `src`: Liste der Schriftquellen (`url()`, `local()`, `format()`).
$fontFamily	string	""	Deskriptor `font-family`: Name, unter dem die Schrift in CSS angesprochen wird.
$fontDisplay	string	""	Deskriptor `font-display`: `auto`, `block`, `swap`, `fallback` oder `optional`.
$fontWeight / fontStyle / fontStretch	string	""	Gewicht, Stil und Breite, für die diese Schriftdatei zuständig ist (auch Bereiche wie `100 900`).
$unicodeRange	string	""	Deskriptor `unicode-range`: Zeichenbereiche, für die die Schrift geladen wird.
$ascentOverride / descentOverride / lineGapOverride / sizeAdjust	string	""	Metrik-Überschreibungen, mit denen sich Fallback-Schriften an die Webfont angleichen lassen.

Beispiele

Objekt über eine @font-face-Regel erhalten

// Stylesheet mit @font-face zur Laufzeit anlegen
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @font-face {
    font-family: "Inter";
    src: url("/fonts/inter.woff2") format("woff2");
    font-weight: 100 900;
    font-display: swap;
  }
`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const rule = sheet.cssRules[0];      // CSSFontFaceRule
const descriptors = rule.style;      // CSSFontFaceDescriptors

console.log(descriptors.constructor.name);
console.log(descriptors.fontFamily);
console.log(descriptors["font-weight"]);
console.log(descriptors.fontDisplay);

CSSFontFaceDescriptors (ältere Browser: CSSStyleDeclaration) "Inter" 100 900 swap

Alle Webfonts der Seite auflisten

const listFontFaces = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // wirft bei fremden Stylesheets ohne CORS
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSFontFaceRule) {
        const { fontFamily, src, fontDisplay } = rule.style;
        result.push({ fontFamily, src, fontDisplay: fontDisplay || "auto" });
      }
    }
  }
  return result;
};

console.table(listFontFaces());

Tabelle mit fontFamily, src und fontDisplay je @font-face-Regel

font-display nachträglich auf swap setzen

for (const sheet of document.styleSheets) {
  try {
    for (const rule of sheet.cssRules) {
      if (rule instanceof CSSFontFaceRule && !rule.style.getPropertyValue("font-display")) {
        // funktioniert mit CSSFontFaceDescriptors und dem älteren CSSStyleDeclaration
        rule.style.setProperty("font-display", "swap");
      }
    }
  } catch {
    // Cross-Origin-Stylesheet überspringen
  }
}

Fallback-Schrift metrisch angleichen

const sheet = new CSSStyleSheet();
sheet.insertRule(`@font-face {
  font-family: "Inter Fallback";
  src: local("Arial");
}`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const fallback = sheet.cssRules[0].style;
fallback.setProperty("size-adjust", "107%");
fallback.setProperty("ascent-override", "90%");

console.log(fallback.cssText);

font-family: "Inter Fallback"; src: local("Arial"); size-adjust: 107%; ascent-override: 90%;

// Wichtig · Fallstricke

Browser-Kompatibilität: Das eigene Interface CSSFontFaceDescriptors ist neu (zuerst in Firefox 143). Andere Browser geben für CSSFontFaceRule.style noch ein allgemeines CSSStyleDeclaration zurück. Dort gibt es die camelCase-Eigenschaften wie fontDisplay oder src teils nicht. Für browserübergreifenden Code solltest du deshalb getPropertyValue() und setProperty() mit Bindestrich-Namen verwenden. Die Unterstützung kannst du mit typeof CSSFontFaceDescriptors !== "undefined" prüfen.

Es gibt keinen Konstruktor: new CSSFontFaceDescriptors() wirft einen TypeError.
Ungültige Werte oder Eigenschaften, die keine @font-face-Deskriptoren sind (z. B. color), werden stillschweigend ignoriert.
Bei Cross-Origin-Stylesheets ohne CORS-Freigabe wirft schon der Zugriff auf sheet.cssRules einen SecurityError. Setze solche Zugriffe deshalb in try/catch.
Wenn du src oder font-family änderst, kann der Browser Schriften neu laden und das Layout neu berechnen. Für programmgesteuertes Laden von Schriften ist die FontFace-API mit document.fonts meist die bessere Wahl.

Siehe auch

CSSFunctionDescriptors CSSPageDescriptors CSSPositionTryDescriptors AudioParamDescriptor CSSFontFaceRule