CSSFontFaceRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSFontFaceRule extends CSSRule

Beschreibung

CSSFontFaceRule ist die Objektdarstellung einer @font-face-Regel im CSS Object Model (CSSOM). Solche Objekte findet man in der cssRules-Liste eines CSSStyleSheet (oder verschachtelt in CSSMediaRule/CSSSupportsRule). Man erkennt sie per rule instanceof CSSFontFaceRule oder am Wert rule.type === CSSRule.FONT_FACE_RULE (Wert 5, veraltet).

Das Interface erbt von CSSRule (cssText, parentStyleSheet, parentRule) und ergänzt nur eine Eigenschaft: style, eine CSSStyleDeclaration mit den Deskriptoren der Regel, z. B. font-family, src, font-weight, font-style, font-display oder unicode-range. Lesen geht über style.getPropertyValue().

Typische Einsatzfälle: Debugging- und Analysewerkzeuge, die alle eingebundenen Web-Fonts auflisten, das Prüfen von font-display-Einstellungen für die Performance oder das dynamische Einfügen von Schriften per insertRule(). Für das programmatische Laden von Schriften ist aber meist die CSS Font Loading API (FontFace, document.fonts) besser geeignet.

Rückgabewert

Typ

CSSFontFaceRule

Beschreibung

Instanzen entstehen nicht per Konstruktor, sondern nur durch den CSS-Parser; man liest sie aus CSSStyleSheet.cssRules. Eigenschaft style (schreibgeschützte Referenz) liefert eine CSSStyleDeclaration.

Beispiele

Alle @font-face-Regeln eines Dokuments 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) {
        result.push({
          family: rule.style.getPropertyValue('font-family'),
          weight: rule.style.getPropertyValue('font-weight') || 'normal',
          display: rule.style.getPropertyValue('font-display') || 'auto'
        });
      }
    }
  }
  return result;
};

console.table(listFontFaces());

┌───┬──────────┬────────┬─────────┐ │ │ family │ weight │ display │ │ 0 │ "Inter" │ 400 │ swap │ │ 1 │ "Inter" │ 700 │ swap │ └───┴──────────┴────────┴─────────┘

@font-face-Regel dynamisch einfügen und auslesen

const sheet = new CSSStyleSheet();
sheet.insertRule(`@font-face {
  font-family: "Roboto";
  src: url("/fonts/roboto.woff2") format("woff2");
  font-weight: 400;
  font-display: swap;
}`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const rule = sheet.cssRules[0];
console.log(rule instanceof CSSFontFaceRule);
console.log(rule.style.getPropertyValue('src'));
console.log(rule.cssText);

true url("/fonts/roboto.woff2") format("woff2") @font-face { font-family: Roboto; src: url("/fonts/roboto.woff2") format("woff2"); font-weight: 400; font-display: swap; }

Fehlendes font-display finden (Performance-Audit)

const auditFontDisplay = () =>
  [...document.styleSheets]
    .flatMap((sheet) => {
      try { return [...sheet.cssRules]; } catch { return []; }
    })
    .filter((rule) => rule instanceof CSSFontFaceRule)
    .filter((rule) => !rule.style.getPropertyValue('font-display'))
    .map((rule) => rule.style.getPropertyValue('font-family'));

const missing = auditFontDisplay();
if (missing.length) {
  console.warn('Ohne font-display:', missing.join(', '));
}

Ohne font-display: "Legacy Sans"

// Wichtig · Fallstricke

CORS: Auf cssRules von Stylesheets fremder Herkunft (z. B. Google Fonts ohne crossorigin-Attribut) darf man nicht zugreifen, der Zugriff wirft einen SecurityError. Deshalb immer in try/catch kapseln.
Verschachtelte Regeln: @font-face innerhalb von @media oder @supports liegt in rule.cssRules der Gruppierungsregel und muss rekursiv gesucht werden.
rule.type und die Konstante CSSRule.FONT_FACE_RULE gelten als veraltet. Besser ist instanceof CSSFontFaceRule.
Der Rückgabewert von style ist in modernen Browsern eine CSSFontFaceDescriptors-Instanz, die von CSSStyleDeclaration abgeleitet ist. Werte können je nach Browser leicht anders normalisiert sein (Anführungszeichen, Groß-/Kleinschreibung).
Eine gefundene Regel bedeutet nicht, dass die Schrift schon geladen ist. Den Ladezustand prüft man mit document.fonts.check() bzw. document.fonts.ready.
Das Interface wird von allen aktuellen Browsern unterstützt.

Siehe auch

CSSRule CSSStyleSheet CSSStyleDeclaration FontFace FontFaceSet CSSStyleSheet.insertRule()