CSSCounterStyleRule.pad — Eigenschaft · JavaScript-Referenz

Signatur

CSSCounterStyleRule.pad

Beschreibung

Die Eigenschaft pad des Interfaces CSSCounterStyleRule gibt den Wert des pad-Deskriptors einer @counter-style-Regel zurück und lässt ihn auch zur Laufzeit ändern. Der Deskriptor legt fest, wie viele Zeichen die Zählerdarstellung mindestens hat und mit welchem Zeichen kürzere Werte aufgefüllt werden. Aus pad: 3 "0" wird so zum Beispiel 001, 002 und so weiter.

Der Wert ist ein String und besteht aus einer nicht-negativen Ganzzahl und einem Symbol (String, Bild oder Bezeichner), zum Beispiel '3 "0"'. Wurde in der Regel kein pad angegeben, liefert die Eigenschaft einen leeren String. Dann gilt der Standardwert 0 "", es wird also nichts aufgefüllt.

Gebraucht wird das vor allem, wenn man Zählerstile per Skript anpassen will: nummerierte Listen mit einheitlicher Breite (etwa Kapitel- oder Zeilennummern), Einstellungen für den Nutzer oder Themes, bei denen sich die Formatierung ohne neues Stylesheet ändern soll. Nach einer Zuweisung stellt der Browser alle Elemente neu dar, die diesen Zählerstil verwenden.

Die Füllzeichen kommen vor das Symbol der Zahl, aber nach ein negatives Vorzeichen (negative-Deskriptor). prefix und suffix zählen bei der Länge nicht mit.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Setzen: neuer Wert in der CSS-Syntax des `pad`-Deskriptors, z. B. `'3 "0"'`. Ungültige Werte werden stillschweigend ignoriert, der alte Wert bleibt dann erhalten.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des pad-Deskriptors in serialisierter Form, z. B. '3 "0"', oder ein leerer String, wenn der Deskriptor nicht gesetzt ist.

Beispiele

pad-Wert einer @counter-style-Regel auslesen

// CSS: @counter-style padded { system: numeric; symbols: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9"; pad: 3 "0"; }
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @counter-style padded {
    system: numeric;
    symbols: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9";
    pad: 3 "0";
  }
`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const rule = [...sheet.cssRules].find(
  (r) => r instanceof CSSCounterStyleRule && r.name === 'padded'
);
console.log(rule.pad);

3 "0"

Zeilennummern zur Laufzeit auf feste Breite bringen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @counter-style line-no {
    system: extends decimal;
    suffix: " ";
  }
  ol.code { list-style: line-no; }
`);
document.adoptedStyleSheets = [sheet];

const rule = sheet.cssRules[0];
console.log(JSON.stringify(rule.pad)); // nicht gesetzt

// Anzahl der Zeilen bestimmt die nötige Breite
const setPadForLines = (lineCount) => {
  const width = String(lineCount).length;
  rule.pad = `${width} "0"`;
};

setPadForLines(250);
console.log(rule.pad);

"" 3 "0"

Ungültige Zuweisung wird ignoriert

const sheet = new CSSStyleSheet();
sheet.replaceSync('@counter-style demo { system: extends decimal; pad: 2 "0"; }');
const rule = sheet.cssRules[0];

rule.pad = '-1 "0"';   // negative Länge ist ungültig
console.log(rule.pad);

rule.pad = '4 "·"';    // gültig: anderes Füllzeichen
console.log(rule.pad);

2 "0" 4 "·"

// Wichtig · Fallstricke

Stilles Scheitern: Eine ungültige Zuweisung (negative Zahl, fehlendes Symbol, falsche Syntax) wirft keinen Fehler. Der alte Wert bleibt einfach stehen. Wenn es darauf ankommt, liest man den Wert nach dem Setzen noch einmal aus.
Anführungszeichen: Ein String als Symbol muss in CSS-Anführungszeichen stehen, im JavaScript-String also etwa '3 "0"'. '3 0' ist ungültig, weil 0 kein gültiger Bezeichner ist.
Serialisierung: Wie der Wert zurückkommt (Leerzeichen, Anführungszeichen), kann sich je nach Browser leicht unterscheiden. Vergleiche mit fest eingetragenen Strings sind deshalb nicht robust.
Systemabhängigkeit: Bei system: extends … übernimmt man zwar Deskriptoren, pad lässt sich aber überschreiben. Beim System cyclic oder bei Aufzählungszeichen wie disc ist das Auffüllen meist nicht sinnvoll.
Kompatibilität: CSSCounterStyleRule gibt es in Firefox schon lange. Chromium unterstützt es ab Version 91, Safari erst ab 17. Für ältere Browser prüft man vorher mit 'CSSCounterStyleRule' in window.
Konstruierbare Stylesheets (new CSSStyleSheet(), replaceSync) sind in den Beispielen nur der Kürze wegen benutzt. Genauso gut funktioniert es über document.styleSheets, bei fremden Stylesheets allerdings nur, wenn CORS den Zugriff auf cssRules erlaubt.

Siehe auch

CSSCounterStyleRule.name CSSCounterStyleRule.range CSSCounterStyleRule.prefix CSSCounterStyleRule.speakAs CSSCounterStyleRule.suffix