CSSCounterStyleRule.fallback — Eigenschaft · JavaScript-Referenz

Signatur

CSSCounterStyleRule.fallback

Beschreibung

Die Eigenschaft fallback des Interfaces CSSCounterStyleRule steht für den Deskriptor fallback einer @counter-style-Regel. Dieser gibt an, welcher Zählerstil verwendet wird, wenn der eigene Stil einen Zählerwert nicht darstellen kann. Das passiert zum Beispiel, wenn der Wert außerhalb des mit range festgelegten Bereichs liegt oder wenn ein additive-System für den Wert keine passende Zeichenfolge bilden kann.

Beim Lesen erhältst du den Namen des Ersatzstils als String, etwa "decimal" oder "lower-roman". Ist der Deskriptor in der Regel nicht angegeben, ist der String leer. Der Browser verwendet dann trotzdem decimal als Standard. Beim Setzen wird der neue Wert als <counter-style-name> geprüft. Ist er gültig, wirkt er sofort auf alle Listen, die diesen Zählerstil verwenden.

Das ist praktisch, wenn du Zählerstile zur Laufzeit anpassen willst, zum Beispiel für Themes, für den Wechsel der Sprache (etwa auf eine Nummerierung mit Buchstaben oder Ziffern einer bestimmten Schrift) oder in Werkzeugen, die Stylesheets untersuchen. An die Regel kommst du über document.styleSheets und cssRules: Du filterst nach CSSCounterStyleRule (bzw. nach rule.type === 11).

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Setzen: Name eines Zählerstils (`<counter-style-name>`), z. B. `"decimal"`, `"upper-alpha"` oder der Name einer anderen `@counter-style`-Regel. Ungültige Werte werden ohne Fehlermeldung ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des fallback-Deskriptors als serialisierter String. Ist der Deskriptor nicht gesetzt, ist der String leer ("").

Beispiele

Fallback einer @counter-style-Regel auslesen

// CSS im Dokument:
// @counter-style thumbs {
//   system: cyclic;
//   symbols: "👍";
//   suffix: " ";
//   range: 1 5;
//   fallback: lower-roman;
// }

const findCounterStyle = (name) => {
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules;
    } catch {
      continue; // fremde Stylesheets (CORS) überspringen
    }
    for (const rule of rules) {
      if (rule instanceof CSSCounterStyleRule && rule.name === name) {
        return rule;
      }
    }
  }
  return null;
};

const rule = findCounterStyle('thumbs');
console.log(rule?.fallback);

lower-roman

Fallback zur Laufzeit ändern

const style = document.createElement('style');
style.textContent = `
  @counter-style stars {
    system: fixed;
    symbols: "★" "★★" "★★★";
    suffix: " ";
  }
  ol.rating { list-style: stars; }
`;
document.head.append(style);

const rule = [...style.sheet.cssRules]
  .find((r) => r instanceof CSSCounterStyleRule);

console.log(JSON.stringify(rule.fallback)); // nicht gesetzt

// Ab dem 4. Listeneintrag Großbuchstaben statt Dezimalzahlen
rule.fallback = 'upper-alpha';
console.log(rule.fallback);

"" upper-alpha

Ungültige Werte werden ignoriert

const sheet = new CSSStyleSheet();
sheet.replaceSync('@counter-style demo { system: cyclic; symbols: "*"; fallback: decimal; }');
const [rule] = sheet.cssRules;

rule.fallback = '123 ungültig'; // kein gültiger Stilname
console.log(rule.fallback);

rule.fallback = 'lower-greek';
console.log(rule.fallback);

decimal lower-greek

// Wichtig · Fallstricke

Leerer String ≠ kein Fallback: Wenn der Deskriptor fehlt, liefert die Eigenschaft "". Der Browser verwendet aber trotzdem decimal als Ersatz.
Kein Fehler bei ungültigen Werten: Ungültige Werte (zum Beispiel none, inherit oder mehrere Wörter) werden ohne Meldung verworfen. Lies den Wert nach dem Setzen erneut aus, wenn du prüfen willst, ob es geklappt hat.
Nicht existierende Stile: Du kannst den Namen eines Stils setzen, der gar nicht definiert ist. Das ist syntaktisch gültig, wirkt aber wie decimal. Bei einer zirkulären Fallback-Kette weicht der Browser ebenfalls auf decimal aus.
Stylesheets von fremden Ursprüngen: Wenn ein Stylesheet von einem anderen Ursprung ohne passende CORS-Header geladen wurde, löst der Zugriff auf cssRules einen SecurityError aus. Fang ihn mit try/catch ab.
Kompatibilität: @counter-style und CSSCounterStyleRule werden in Firefox schon lange unterstützt, in Chrome ab Version 91 und in Safari erst ab Version 17. Für ältere Browser prüfst du vorher mit 'CSSCounterStyleRule' in window.

Siehe auch

CSSCounterStyleRule CSSCounterStyleRule.name CSSCounterStyleRule.system CSSCounterStyleRule.range CSSCounterStyleRule.symbols CSSStyleSheet CSSCounterStyleRule.suffix