HTMLLinkElement.sheet — Eigenschaft · JavaScript-Referenz

Signatur

HTMLLinkElement.sheet

Beschreibung

Die Eigenschaft HTMLLinkElement.sheet gibt das CSSStyleSheet-Objekt zurück, das zu einem <link>-Element gehört. Das gilt nur, wenn das Element ein Stylesheet einbindet (rel="stylesheet") und das Stylesheet erfolgreich geladen und geparst wurde. In allen anderen Fällen, etwa bei rel="icon", rel="preload", während des Ladens oder nach einem Ladefehler, ist der Wert null.

Über das zurückgegebene Objekt kommt man per CSSOM an die Regeln des Stylesheets. Man kann sie mit cssRules auslesen, mit insertRule() bzw. deleteRule() ändern oder das ganze Stylesheet über disabled ein- und ausschalten. Das eignet sich für Theme-Umschalter, zum Prüfen, ob ein Stylesheet wirklich geladen ist, und für Werkzeuge, die CSS zur Laufzeit untersuchen.

Die Eigenschaft ist schreibgeschützt. Man kann ihr kein anderes Stylesheet zuweisen. Um das Stylesheet zu wechseln, ändert man stattdessen das href-Attribut des Elements. Der Browser lädt die Datei dann neu und erzeugt ein neues CSSStyleSheet-Objekt.

Rückgabewert

Typ

CSSStyleSheet | null

Beschreibung

Das verknüpfte CSSStyleSheet, oder null, wenn das Element kein Stylesheet einbindet, das Stylesheet noch lädt oder nicht geladen werden konnte.

Beispiele

Stylesheet nach dem Laden auslesen

const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = '/css/theme.css';

link.addEventListener('load', () => {
  // Erst jetzt ist sheet belegt
  console.log(link.sheet instanceof CSSStyleSheet);
  console.log('Regeln:', link.sheet.cssRules.length);
});

link.addEventListener('error', () => {
  console.log('Laden fehlgeschlagen, sheet =', link.sheet);
});

document.head.append(link);
console.log('Direkt nach append:', link.sheet);

Direkt nach append: null true Regeln: 42

Theme per disabled umschalten

// <link id="dark-theme" rel="stylesheet" href="/css/dark.css">
const darkLink = document.querySelector('#dark-theme');

const toggleDarkMode = () => {
  const { sheet } = darkLink;
  if (!sheet) {
    console.warn('Dark-Theme noch nicht geladen');
    return;
  }
  sheet.disabled = !sheet.disabled;
  console.log('Dark-Mode aktiv:', !sheet.disabled);
};

document.querySelector('#toggle').addEventListener('click', toggleDarkMode);

Dark-Mode aktiv: false

Regel zur Laufzeit einfügen

const link = document.querySelector('link[rel="stylesheet"]');
const sheet = link?.sheet;

if (sheet) {
  try {
    const index = sheet.insertRule(
      '.highlight { background: yellow; }',
      sheet.cssRules.length
    );
    console.log('Regel eingefügt an Index', index);
  } catch (err) {
    // z. B. SecurityError bei Cross-Origin-Stylesheets
    console.error(err.name, err.message);
  }
}

Regel eingefügt an Index 42

// Wichtig · Fallstricke

Timing: Direkt nach dem Einfügen des Elements ist sheet meist noch null. Warten Sie auf das load-Event, bevor Sie darauf zugreifen.
Cross-Origin: Bei Stylesheets von einer fremden Origin ohne CORS (crossorigin-Attribut plus passender Access-Control-Allow-Origin-Header) ist sheet zwar vorhanden. Ein Zugriff auf cssRules oder insertRule() wirft aber einen SecurityError.
Laufzeitänderungen über insertRule() gehen verloren, wenn href geändert wird, weil dabei ein neues CSSStyleSheet entsteht.
Bei rel="alternate stylesheet" kann ein Stylesheet vorhanden, aber deaktiviert sein. Prüfen Sie dafür sheet.disabled.
Die Eigenschaft wird von allen modernen Browsern unterstützt. Das Gegenstück für <style>-Elemente ist HTMLStyleElement.sheet.

Siehe auch

HTMLFormElement.target HTMLLinkElement.href HTMLLinkElement.sizes HTMLLinkElement.rel HTMLLinkElement.type