HTMLLinkElement.blocking — Eigenschaft · JavaScript-Referenz

Signatur

HTMLLinkElement.blocking

Beschreibung

Die schreibgeschützte Eigenschaft blocking spiegelt das HTML-Attribut blocking eines <link>-Elements als DOMTokenList wider. Die enthaltenen Token legen fest, welche Vorgänge der Browser anhalten soll, bis die externe Ressource geladen ist. Der einzige derzeit spezifizierte Token ist render: Der Browser zeichnet die Seite erst, wenn die Ressource verfügbar ist.

Nützlich ist das vor allem für Stylesheets, die per JavaScript nachträglich eingefügt werden. Ein dynamisch erzeugtes <link rel="stylesheet"> blockiert das Rendern normalerweise nicht, deshalb kann ein kurzes Aufblitzen ungestylter Inhalte (FOUC) entstehen. Mit blocking="render" lässt sich das verhindern, solange das Element vor dem ersten Rendern im <head> landet.

Die Liste ist lebend: Änderungen über add(), remove() oder toggle() schreiben sich direkt in das Attribut zurück und umgekehrt. Die Eigenschaft selbst ist zwar schreibgeschützt, eine Zuweisung eines Strings wird aber an blocking.value weitergereicht ([PutForwards=value]).

Rückgabewert

Typ

DOMTokenList

Beschreibung

Lebende Token-Liste der blockierten Operationen. Ist das Attribut nicht gesetzt, ist die Liste leer (length === 0). Gültiger Token: "render".

Beispiele

Wert des blocking-Attributs auslesen

// HTML: <link id="haupt-css" rel="stylesheet" href="/css/main.css" blocking="render">
const link = document.getElementById('haupt-css');

console.log(link.blocking.value);
console.log(link.blocking.contains('render'));
console.log(link.blocking.length);

render true 1

Dynamisches Stylesheet render-blockierend einfügen

// Möglichst früh im <head> ausführen, vor dem ersten Rendern
const themeLink = document.createElement('link');
themeLink.rel = 'stylesheet';
themeLink.href = `/css/theme-${localStorage.getItem('theme') ?? 'hell'}.css`;

// Feature-Erkennung: nur setzen, wenn der Browser den Token kennt
if ('blocking' in themeLink && themeLink.blocking.supports('render')) {
  themeLink.blocking.add('render');
}

document.head.append(themeLink);
console.log(themeLink.outerHTML);

Token entfernen und per Zuweisung setzen

const link = document.querySelector('link[blocking]');

// Blockade aufheben
link.blocking.remove('render');
console.log(link.getAttribute('blocking'));

// Zuweisung wird an blocking.value weitergereicht
link.blocking = 'render';
console.log(link.blocking.value);

"render" → render

// Wichtig · Fallstricke

Browser-Unterstützung: Bisher nur in Chromium-Browsern (ab Version 105). Firefox und Safari ignorieren das Attribut. Prüfe die Unterstützung vorher mit 'blocking' in HTMLLinkElement.prototype und link.blocking.supports('render').
Wirkt nur vor dem ersten Rendern: Wird ein Element mit blocking="render" erst eingefügt, nachdem die Seite schon gezeichnet wurde, hat das keine Wirkung. Außerdem muss das Element im <head> stehen.
Nicht für jedes rel: Render-blockierend ist ein Link vor allem bei rel="stylesheet". Bei anderen Werten wie preload oder icon hat der Token in der Regel keine Wirkung.
Performance: Render-Blockaden verzögern den First Contentful Paint. Setze sie deshalb nur für Ressourcen ein, ohne die die Seite kaputt aussähe, und halte diese Ressourcen klein.
Unbekannte Token werfen bei add() keinen Fehler. supports() gibt für sie aber false zurück.

Siehe auch

HTMLLinkElement.fetchPriority HTMLLinkElement.hreflang HTMLLinkElement.media HTMLLinkElement.relList HTMLLinkElement.as