CSSFontFaceRule.style — Eigenschaft · JavaScript-Referenz

Signatur

CSSFontFaceRule.style

Beschreibung

Die Eigenschaft style eines CSSFontFaceRule-Objekts gibt Zugriff auf die Deskriptoren im Körper einer @font-face-Regel, also etwa font-family, src, font-weight, font-style, font-display oder unicode-range. Das zurückgegebene Objekt ist vom Typ CSSFontFaceDescriptors, das von CSSStyleDeclaration erbt. In älteren Browsern ist es direkt eine CSSStyleDeclaration.

Schreibgeschützt ist nur die Eigenschaft selbst: Ein neues Objekt lässt sich nicht zuweisen. Die Deskriptoren im Objekt kannst du dagegen über getPropertyValue() lesen und über setProperty() ändern. Außerdem kannst du alle Deskriptoren mit length und Indexzugriff durchlaufen oder mit cssText komplett auslesen.

Typische Einsatzfälle sind Werkzeuge, die geladene Stylesheets untersuchen, zum Beispiel um alle eingebundenen Webfonts samt Quellen aufzulisten. Ein weiterer Fall ist das nachträgliche Anpassen von Deskriptoren wie font-display, ohne das CSS neu auszuliefern. Wenn du Schriften zur Laufzeit laden willst, ist die FontFace-API meist die bessere Wahl.

Rückgabewert

Typ

CSSFontFaceDescriptors

Beschreibung

Ein Objekt mit allen Deskriptoren der @font-face-Regel. Es erbt von CSSStyleDeclaration und wird live mit der Regel synchron gehalten.

Beispiele

Alle @font-face-Regeln eines Dokuments auflisten

// Durchsucht alle gleich-originigen Stylesheets nach @font-face-Regeln
const listFontFaces = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules;
    } catch {
      continue; // Cross-Origin-Stylesheet ohne CORS: nicht lesbar
    }
    for (const rule of rules) {
      if (rule instanceof CSSFontFaceRule) {
        result.push({
          family: rule.style.getPropertyValue('font-family'),
          weight: rule.style.getPropertyValue('font-weight') || 'normal',
          src: rule.style.getPropertyValue('src')
        });
      }
    }
  }
  return result;
};

console.table(listFontFaces());

┌─────────┬──────────┬────────┬──────────────────────────────────────┐ │ (index) │ family │ weight │ src │ ├─────────┼──────────┼────────┼──────────────────────────────────────┤ │ 0 │ "Inter" │ "400" │ url("/fonts/inter.woff2") format(...) │ └─────────┴──────────┴────────┴──────────────────────────────────────┘

Deskriptoren einer selbst erzeugten Regel lesen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @font-face {
    font-family: "Roboto";
    src: url("/fonts/roboto.woff2") format("woff2");
    font-weight: 700;
    font-display: swap;
  }
`);

const rule = sheet.cssRules[0];
console.log(rule.style.length);
for (let i = 0; i < rule.style.length; i++) {
  const name = rule.style[i];
  console.log(`${name}: ${rule.style.getPropertyValue(name)}`);
}

4 font-family: Roboto src: url("/fonts/roboto.woff2") format("woff2") font-weight: 700 font-display: swap

font-display nachträglich ändern

// Setzt für alle Webfonts font-display auf 'swap', damit Text nicht unsichtbar bleibt
for (const sheet of document.styleSheets) {
  try {
    for (const rule of sheet.cssRules) {
      if (rule instanceof CSSFontFaceRule &&
          !rule.style.getPropertyValue('font-display')) {
        rule.style.setProperty('font-display', 'swap');
        console.log(rule.cssText);
      }
    }
  } catch {
    // Cross-Origin-Stylesheet überspringen
  }
}

@font-face { font-family: Inter; src: url("/fonts/inter.woff2"); font-display: swap; }

// Wichtig · Fallstricke

Schreibschutz: Eine Zuweisung wie rule.style = … hat keine Wirkung, im Strict Mode kann sie einen Fehler auslösen. Ändere stattdessen einzelne Deskriptoren mit setProperty() oder alle auf einmal über rule.style.cssText.
Keine normalen CSS-Eigenschaften: Das Objekt enthält nur @font-face-Deskriptoren. Eigenschaften wie color werden ignoriert.
Normalisierte Werte: Browser geben Werte teils normalisiert zurück, etwa bold als 700 oder Anführungszeichen bei Familiennamen anders als im Quelltext. Vergleiche Werte daher nicht als exakte Zeichenketten.
Cross-Origin: Wird ein Stylesheet von einer fremden Quelle ohne CORS geladen, löst schon der Zugriff auf cssRules einen SecurityError aus. Fange den Fehler deshalb mit try/catch ab.
Späte Änderungen: Ob Änderungen an src oder font-family nach dem Laden der Schrift sofort wirken, ist nicht garantiert. Für dynamisches Laden eignet sich FontFace mit document.fonts besser.
Kompatibilität: style funktioniert in allen modernen Browsern. Den eigenen Typ CSSFontFaceDescriptors kennen nur neuere Versionen, ältere liefern eine CSSStyleDeclaration. Prüfe daher nicht mit instanceof CSSFontFaceDescriptors.

Siehe auch

CSSFontFaceRule CSSStyleDeclaration CSSStyleDeclaration.getPropertyValue() CSSStyleDeclaration.setProperty() FontFace CSSStyleSheet.cssRules CSSContainerRule.containerName