FontFaceSet.check() — Methode · JavaScript-Referenz

Signatur

FontFaceSet.prototype.check(font, text)

Beschreibung

check() ist eine Methode von FontFaceSet. Meist ruft man sie über document.fonts auf, in Workern über self.fonts. Sie nimmt eine Schriftangabe in der Kurzschreibweise der CSS-Eigenschaft font entgegen, etwa "bold 16px Roboto". Anschließend prüft sie synchron, ob alle passenden FontFace-Objekte im Set schon geladen sind. Ist das der Fall, gibt sie true zurück. Braucht die Darstellung dagegen noch eine Schrift mit dem Status "unloaded" oder "loading", gibt sie false zurück.

Die Methode ist gut für Fälle, in denen man sofort wissen muss, ob eine Webfont bereit ist. Das gilt zum Beispiel, bevor man mit einer bestimmten Schrift auf ein <canvas> zeichnet, Textbreiten misst oder das Layout berechnet. Sie startet keinen Ladevorgang. Dafür ist FontFaceSet.load() da, das ein Promise zurückgibt.

Mit dem optionalen Parameter text werden nur die Schriften berücksichtigt, deren unicode-range die Zeichen im Text abdeckt. Das ist wichtig bei Schriften, die in mehrere Teilbereiche aufgeteilt sind (Subsetting). Ein lateinischer Teilbereich kann schon geladen sein, während der kyrillische noch fehlt.

Parameter

Name	Typ	Default	Beschreibung
$font Pflicht	string		Schriftangabe in der Syntax der CSS-Kurzschreibweise `font`. Schriftgröße und Schriftfamilie sind Pflicht, z. B. `"italic 700 1em 'Open Sans'"`.
$text	string	" " (Leerzeichen)	Zeichen, für die geprüft wird. Damit werden nur Schriften berücksichtigt, deren `unicode-range` diese Zeichen abdeckt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn keine passende Schrift im Set mehr geladen werden muss. false, wenn mindestens eine passende Schrift noch nicht geladen ist. Bei einer ungültigen font-Angabe wird ein SyntaxError (DOMException) geworfen.

Beispiele

Einfache Prüfung, ob eine Webfont bereit ist

// Voraussetzung: 'Roboto' ist per @font-face eingebunden
const bereit = document.fonts.check('16px Roboto');
console.log(bereit ? 'Roboto ist geladen' : 'Roboto wird noch geladen');

Roboto wird noch geladen

Canvas erst zeichnen, wenn die Schrift geladen ist

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const font = 'bold 32px "Fira Sans"';

const zeichne = () => {
  ctx.font = font;
  ctx.fillText('Hallo Welt', 20, 50);
};

if (document.fonts.check(font)) {
  zeichne();
} else {
  // load() startet den Ladevorgang und wartet darauf
  document.fonts.load(font).then(zeichne);
}

Prüfung mit Zeichenbereich (unicode-range)

const font = new FontFace('Noto', 'url(/fonts/noto-cyrillic.woff2)', {
  unicodeRange: 'U+0400-04FF'
});
document.fonts.add(font);

console.log(document.fonts.check('16px Noto', 'Hallo')); // kein passender Bereich
console.log(document.fonts.check('16px Noto', 'Привет')); // kyrillisch, noch nicht geladen

await font.load();
console.log(document.fonts.check('16px Noto', 'Привет'));

true false true

Ungültige Schriftangabe abfangen

try {
  document.fonts.check('Roboto'); // Schriftgröße fehlt
} catch (err) {
  console.error(err.name);
}

SyntaxError

// Wichtig · Fallstricke

Häufiger Fallstrick: check() gibt auch dann true zurück, wenn im Set gar keine passende Schrift existiert, etwa bei einem Tippfehler im Familiennamen oder bei einer reinen Systemschrift. true heißt also nur, dass nichts mehr geladen werden muss. Es heißt nicht, dass die gewünschte Schrift verwendet wird.
Die Methode lädt nichts nach. Wenn Sie auf eine Schrift warten müssen, nutzen Sie document.fonts.load() oder document.fonts.ready.
Über CSS eingebundene @font-face-Schriften lädt der Browser oft erst, wenn sie im Dokument tatsächlich gebraucht werden. Bis dahin liefert check() false.
Eine fehlende Schriftgröße oder eine anders ungültige font-Syntax löst einen SyntaxError aus.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Web Workern (self.fonts). Ältere Implementierungen weichen bei Systemschriften und nicht passenden Familien teils voneinander ab.

Siehe auch

FontFaceSet FontFaceSet.load() FontFaceSet.ready FontFace Document.fonts FontFaceSet.add() FontFaceSet.keys()