FontFace.display — Eigenschaft · JavaScript-Referenz

Signatur

FontFace.display

Beschreibung

Die Eigenschaft display eines FontFace-Objekts entspricht dem CSS-Deskriptor font-display in einer @font-face-Regel. Sie legt fest, wie der Browser Text darstellt, solange die Webschrift noch lädt, und was passiert, wenn der Ladevorgang lange dauert oder fehlschlägt. Der Wert ist ein String und kann gelesen und geschrieben werden.

Die Anzeigestrategie besteht aus drei Phasen: einer Block-Phase (Text ist unsichtbar), einer Swap-Phase (Text erscheint in der Ersatzschrift und wird ausgetauscht, sobald die Webschrift da ist) und einer Fehler-Phase (die Ersatzschrift bleibt). Die möglichen Werte gewichten diese Phasen unterschiedlich:

"auto" – der Browser entscheidet selbst, meist wie block (Standardwert).
"block" – kurze Block-Phase (ca. 3 s), danach unbegrenzte Swap-Phase.
"swap" – sehr kurze Block-Phase, unbegrenzte Swap-Phase; Text ist sofort lesbar.
"fallback" – sehr kurze Block-Phase (ca. 100 ms), kurze Swap-Phase (ca. 3 s).
"optional" – sehr kurze Block-Phase, keine Swap-Phase; der Browser darf die Schrift ganz weglassen.

Du setzt den Wert entweder über das descriptors-Objekt im Konstruktor new FontFace(family, source, { display }) oder nachträglich über die Eigenschaft. Das ist nützlich, wenn Schriften per JavaScript über die CSS Font Loading API nachgeladen werden und dabei die gleiche Kontrolle über FOIT (unsichtbarer Text) und FOUT (Schriftwechsel) gewünscht ist wie in CSS.

Parameter

Name	Typ	Default	Beschreibung
$value	"auto" \| "block" \| "swap" \| "fallback" \| "optional"	"auto"	Beim Setzen: die gewünschte Anzeigestrategie. Ungültige Werte lösen einen `SyntaxError` aus.

Rückgabewert

Typ

string

Beschreibung

Die aktuelle Anzeigestrategie als String, z. B. "swap".

Beispiele

Schrift mit font-display: swap per JavaScript laden

const font = new FontFace(
  'Inter',
  'url(/fonts/inter.woff2) format("woff2")',
  { weight: '400', display: 'swap' }
);

document.fonts.add(font);
console.log(font.display);

await font.load();
document.body.style.fontFamily = 'Inter, system-ui, sans-serif';
console.log(font.status);

swap loaded

Anzeigestrategie nachträglich ändern

const font = new FontFace('Brand', 'url(/fonts/brand.woff2)');
console.log(font.display); // Standard

// Für dekorative Schriften: lieber weglassen als Layout-Sprung
font.display = 'optional';
console.log(font.display);

document.fonts.add(font);

auto optional

Ungültige Werte abfangen

const font = new FontFace('Test', 'url(/fonts/test.woff2)');

try {
  font.display = 'sofort';
} catch (err) {
  console.log(err.name);
}
console.log(font.display);

SyntaxError auto

Display-Werte aller registrierten Schriften auflisten

await document.fonts.ready;

for (const face of document.fonts) {
  console.log(`${face.family} (${face.weight}): ${face.display}`);
}

Inter (400): swap Brand (normal): optional

// Wichtig · Fallstricke

Zeitpunkt beachten: display wirkt auf den Ladevorgang. Wenn du den Wert nach load() oder nach dem Beginn des Downloads änderst, hat das meist keinen sichtbaren Effekt mehr. Am besten setzt du ihn gleich im Konstruktor.
Ungültige Werte: Wenn du einen unbekannten String zuweist, wird ein SyntaxError geworfen und der alte Wert bleibt erhalten. Im Konstruktor führt ein ungültiger Deskriptor dazu, dass das FontFace sofort mit dem Status "error" scheitert.
Performance/UX: swap verbessert die gemessene Zeit bis zum ersten sichtbaren Text, kann aber Layout-Verschiebungen (CLS) verursachen. optional vermeidet solche Verschiebungen und eignet sich gut für nicht kritische Schriften. Kombiniere das am besten mit <link rel=\"preload\">.
Explizites load(): Wenn du selbst auf await font.load() wartest und erst danach die Schriftfamilie setzt, steuerst du das Verhalten praktisch selbst. display betrifft dann nur Elemente, die die Schrift schon vorher nutzen.
Kompatibilität: Wird von allen modernen Browsern unterstützt, nicht aber vom Internet Explorer. In Web Workern steht die Eigenschaft über self.fonts ebenfalls zur Verfügung.

Siehe auch

FontFace FontFace.prototype.load() FontFace.status FontFace.loaded FontFaceSet Document.fonts ContactAddress.phone