HTMLScriptElement.async — Eigenschaft · JavaScript-Referenz

Signatur

HTMLScriptElement.async

Beschreibung

HTMLScriptElement.async spiegelt das boolesche HTML-Attribut async wider. Ist der Wert true, lädt der Browser ein klassisches externes Skript (mit src) parallel zum Parsen des Dokuments und führt es aus, sobald es verfügbar ist. Das HTML-Parsen wird dabei nicht blockiert. Die Reihenfolge der Ausführung mehrerer async-Skripte ist aber nicht garantiert.

Bei Modul-Skripten (type="module") sorgt async dafür, dass das Modul samt Abhängigkeiten ausgeführt wird, sobald alles geladen ist. Ohne async verhalten sich Module wie mit defer, laufen also erst nach dem Parsen in Dokumentreihenfolge. Anders als bei klassischen Skripten wirkt async bei Modulen auch für Inline-Code.

Ein wichtiger Sonderfall: Skripte, die per document.createElement('script') erzeugt und ins DOM eingefügt werden, haben standardmäßig async === true. Setzt man async vor dem Einfügen ausdrücklich auf false, werden dynamisch eingefügte Skripte in Einfügereihenfolge ausgeführt. Das Laden bleibt trotzdem parallel. So lassen sich voneinander abhängige Bibliotheken nachladen.

Typische Anwendungsfälle sind Analyse-, Werbe- und Widget-Skripte, die unabhängig vom restlichen Code laufen, sowie Loader, die Skripte zur Laufzeit gezielt nachladen.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean	false (im HTML-Markup) / true (bei createElement)	Beim Setzen: `true` fügt das Attribut `async` hinzu, `false` entfernt es. Andere Werte werden in einen booleschen Wert umgewandelt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Skript asynchron ausgeführt wird, sonst false. Bei dynamisch erzeugten, noch nicht veränderten Skripten ist der Wert true.

Beispiele

Standardwert bei dynamisch erzeugten Skripten

const script = document.createElement('script');
console.log(script.async); // dynamisch erzeugt => true

script.src = 'https://example.com/analytics.js';
script.addEventListener('load', () => console.log('Analytics geladen'));
document.head.append(script);

true Analytics geladen

Abhängige Skripte in fester Reihenfolge nachladen

const loadInOrder = (urls) =>
  Promise.all(
    urls.map((url) => new Promise((resolve, reject) => {
      const s = document.createElement('script');
      s.src = url;
      s.async = false; // Ausführung in Einfügereihenfolge, Download trotzdem parallel
      s.onload = () => resolve(url);
      s.onerror = () => reject(new Error(`Fehler beim Laden: ${url}`));
      document.head.append(s);
    }))
  );

const main = async () => {
  await loadInOrder(['/js/lib-core.js', '/js/lib-plugin.js']);
  console.log('Core und Plugin bereit');
};
main();

Core und Plugin bereit

async-Status vorhandener Skripte auslesen

// HTML: <script src="/a.js" async></script> <script src="/b.js" defer></script>
const report = [...document.querySelectorAll('script[src]')].map((s) => ({
  src: s.getAttribute('src'),
  async: s.async,
  defer: s.defer
}));
console.table(report);

/a.js async: true defer: false /b.js async: false defer: true

// Wichtig · Fallstricke

Reihenfolge nicht garantiert: Mehrere Skripte mit async laufen in der Reihenfolge, in der ihr Download fertig wird. Verlass dich nicht darauf, dass ein async-Skript vor einem anderen läuft oder dass DOMContentLoaded schon ausgelöst wurde.
Inline-Skripte: Bei klassischen Skripten ohne src hat async keine Wirkung. Bei type="module" dagegen schon.
Nachträgliches Ändern: async muss vor dem Einfügen ins DOM gesetzt werden. Nach dem Einfügen hat eine Änderung keinen Einfluss mehr auf das Ladeverhalten.
async und defer zusammen: Sind beide gesetzt, hat async Vorrang. defer diente früher nur als Rückfallebene für sehr alte Browser.
document.write: Async-Skripte dürfen kein document.write() verwenden. Der Aufruf wird ignoriert oder erzeugt eine Warnung.
Sicherheit: Dynamisch geladene Skripte fremder Anbieter laufen mit vollen Rechten auf der Seite. Setze integrity (SRI), crossOrigin und eine passende Content Security Policy (CSP) ein.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Der Internet Explorer kannte async erst ab Version 10.

Siehe auch

import() HTMLScriptElement.src HTMLScriptElement.type HTMLScriptElement.defer HTMLScriptElement.text