FontFace.family — Eigenschaft · JavaScript-Referenz

Signatur

FontFace.family

Beschreibung

Die Eigenschaft family eines FontFace-Objekts enthält den Familiennamen, unter dem die Schrift im Dokument angesprochen wird. Sie entspricht dem Deskriptor font-family innerhalb einer @font-face-Regel. Der Wert wird normalerweise als erstes Argument an den Konstruktor new FontFace(family, source, descriptors) übergeben.

Wichtig ist der Wert, sobald die Schrift über document.fonts.add() registriert wurde. Danach können CSS-Regeln wie font-family: "Meine Schrift" oder Aufrufe wie document.fonts.check('16px "Meine Schrift"') genau diesen Namen verwenden.

Die Eigenschaft ist beschreibbar. Wird ihr ein neuer Wert zugewiesen, parst der Browser ihn wie einen CSS-Familiennamen. Ist der Wert ungültig, wird ein SyntaxError geworfen. Du kannst eine Schrift also nachträglich umbenennen. Das beeinflusst, welche Elemente sie nutzen, ändert aber nichts an den bereits geladenen Schriftdaten.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Beim Setzen: neuer Familienname als String, z. B. `"Roboto"` oder `'"Open Sans"'`. Er muss ein gültiger CSS-Familienname sein.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Familienname der Schrift. Er wird so zurückgegeben, wie der Browser ihn serialisiert hat. Namen mit Leerzeichen können dabei in Anführungszeichen stehen.

Beispiele

Schrift laden und Familiennamen auslesen

const font = new FontFace('Inter', 'url(/fonts/Inter.woff2)', { weight: '400' });
console.log(font.family);

await font.load();
document.fonts.add(font);
document.body.style.fontFamily = `${font.family}, sans-serif`;

Inter

Familiennamen nachträglich ändern

const font = new FontFace('Temp', 'url(/fonts/Brand.woff2)');
font.family = 'Brand Sans';
console.log(font.family);

await font.load();
document.fonts.add(font);
console.log(document.fonts.check('16px "Brand Sans"'));

"Brand Sans" true

Alle registrierten Schriftfamilien auflisten

await document.fonts.ready;
const families = new Set();
for (const face of document.fonts) {
  families.add(face.family.replace(/^"|"$/g, ''));
}
console.log([...families]);

["Inter", "Brand Sans"]

Ungültigen Namen abfangen

const font = new FontFace('Valid', 'url(/fonts/x.woff2)');
try {
  font.family = '';
} catch (err) {
  console.error(err.name);
}

SyntaxError

// Wichtig · Fallstricke

Serialisierung: Namen mit Leerzeichen oder Sonderzeichen gibt der Browser teils mit Anführungszeichen zurück, z. B. "\"Brand Sans\"". Vergleiche deshalb nicht blind per ===, sondern entferne die Anführungszeichen vorher.
Ungültige Werte: Ein ungültiger Familienname löst beim Setzen einen SyntaxError aus. Das gilt je nach Browser auch für einen leeren String.
Generische Namen: Vermeide generische Schlüsselwörter wie serif oder sans-serif als Familiennamen. Sie können mit den generischen CSS-Schriftfamilien kollidieren.
Umbenennen: Wird family nach document.fonts.add() geändert, wirkt sich das sofort auf die Schriftzuordnung aus. Elemente, die den alten Namen verwenden, fallen dann auf die nächste Schrift in ihrer Liste zurück.
Kompatibilität: Die CSS Font Loading API wird in allen aktuellen Browsern unterstützt, im Internet Explorer nicht. In Web Workern ist sie über self.fonts verfügbar, allerdings nicht überall.

Siehe auch

FontFace new FontFace() FontFace.prototype.load() FontFace.style FontFace.weight FontFaceSet Document.fonts