CSSCounterStyleRule.symbols — Eigenschaft · JavaScript-Referenz

Signatur

CSSCounterStyleRule.symbols

Beschreibung

Die Eigenschaft symbols der Schnittstelle CSSCounterStyleRule gibt den Deskriptor symbols einer @counter-style-Regel als String zurück. Dieser Deskriptor legt fest, welche Symbole (Zeichenketten, Bezeichner oder Bilder) der Zählerstil verwendet, etwa "★" "☆" oder "Ⓐ" "Ⓑ" "Ⓒ".

Du kannst die Eigenschaft auch beschreiben und so einen benutzerdefinierten Listen- oder Zählerstil zur Laufzeit ändern, ohne das Stylesheet neu zu laden. Alle Elemente, deren list-style-type oder counter()-Funktion diesen Stil nutzen, werden dann sofort mit den neuen Symbolen dargestellt.

Ob symbols gebraucht wird, hängt vom system-Deskriptor ab: Bei cyclic, numeric, alphabetic, symbolic und fixed ist er Pflicht. Bei additive gilt dagegen additiveSymbols, bei extends darf symbols nicht angegeben werden. Wenn die Regel keinen symbols-Deskriptor enthält, ist der Wert ein leerer String.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Setzen: eine gültige `symbols`-Liste in CSS-Syntax, z. B. `'"●" "○"'`. Zeichenketten müssen in CSS-Anführungszeichen stehen.

Rückgabewert

Typ

string

Beschreibung

Der serialisierte Wert des Deskriptors symbols, z. B. '"★" "☆"'. Leerer String, wenn der Deskriptor fehlt.

Beispiele

Symbole einer @counter-style-Regel auslesen

// CSS im Dokument:
// @counter-style sterne { system: cyclic; symbols: "★" "☆"; suffix: " "; }

const findCounterStyle = (name) => {
  for (const sheet of document.styleSheets) {
    for (const rule of sheet.cssRules) {
      if (rule instanceof CSSCounterStyleRule && rule.name === name) {
        return rule;
      }
    }
  }
  return null;
};

const rule = findCounterStyle('sterne');
console.log(rule?.symbols);

"★" "☆"

Symbole zur Laufzeit ändern (Theme-Wechsel)

const style = document.createElement('style');
style.textContent = `
  @counter-style punkte { system: cyclic; symbols: "●"; suffix: " "; }
  ul.custom { list-style: punkte; }
`;
document.head.append(style);

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

document.querySelector('#theme-toggle')?.addEventListener('click', () => {
  // Wechsel zwischen gefülltem und leerem Kreis
  rule.symbols = rule.symbols === '"●"' ? '"○" "◇"' : '"●"';
  console.log('Neue Symbole:', rule.symbols);
});

Neue Symbole: "○" "◇"

Ungültige Werte werden ignoriert

const sheet = new CSSStyleSheet();
sheet.replaceSync('@counter-style abc { system: alphabetic; symbols: "a" "b" "c"; }');
const rule = sheet.cssRules[0];

rule.symbols = ''; // ungültig: leere Liste
console.log(rule.symbols);

rule.symbols = '"x" "y"';
console.log(rule.symbols);

"a" "b" "c" "x" "y"

// Wichtig · Fallstricke

Anführungszeichen nicht vergessen: Der Wert ist CSS-Syntax. rule.symbols = '★' wird je nach Browser als Bezeichner gelesen oder verworfen. Richtig ist '"★"'.
Ungültige Werte werden ohne Fehlermeldung ignoriert: Es wird keine Exception geworfen und der alte Wert bleibt erhalten. Das gilt auch, wenn die Anzahl der Symbole nicht zum system passt (alphabetic und numeric brauchen mindestens zwei).
Bei system: additive hat symbols keine Wirkung. Verwende dort additiveSymbols.
Bei Stylesheets von anderen Ursprüngen (Cross-Origin) ohne CORS löst der Zugriff auf cssRules einen SecurityError aus.
Kompatibilität: Firefox unterstützt die Eigenschaft seit Langem, Chrome seit Version 91, Safari erst seit 17. Für ältere Browser brauchst du eine Feature-Erkennung, z. B. mit 'CSSCounterStyleRule' in window.
Die Serialisierung (Leerzeichen, Anführungszeichen) kann sich zwischen Browsern leicht unterscheiden. Vergleiche Werte deshalb möglichst nicht direkt als Strings.

Siehe auch

CSSCounterStyleRule.additiveSymbols CSSCounterStyleRule.speakAs CSSCounterStyleRule.system CSSCounterStyleRule.name CSSCounterStyleRule.suffix