CSSCounterStyleRule.speakAs — Eigenschaft · JavaScript-Referenz

Signatur

CSSCounterStyleRule.speakAs

Beschreibung

Die Eigenschaft speakAs der Schnittstelle CSSCounterStyleRule gibt den Deskriptor speak-as einer @counter-style-Regel als Zeichenkette zurück und lässt sich auch setzen. Der Deskriptor legt fest, wie Sprachausgaben (etwa Screenreader) einen Zählermarker vorlesen, zum Beispiel bei Listenpunkten oder Nummerierungen, die mit einem eigenen Zählerstil erzeugt werden.

Gültige Werte sind:

auto: Standardwert. Das Verhalten hängt vom system des Zählerstils ab.
bullets: Der Marker wird wie ein ungeordneter Listenpunkt vorgelesen.
numbers: Der Zählerwert wird als Zahl in der Dokumentsprache vorgelesen.
words: Die Markerdarstellung wird wie normaler Text vorgelesen.
spell-out: Die Markerdarstellung wird Zeichen für Zeichen buchstabiert.
Der Name eines anderen Zählerstils, dessen Sprachausgabe übernommen werden soll.

Das ist vor allem bei Zählerstilen mit Emojis, Symbolen oder Fantasiezeichen wichtig. Ohne passenden speak-as-Wert liest ein Screenreader solche Zeichen oft wörtlich vor, etwa „rakete, rakete“, statt einfach „Aufzählungspunkt“ zu sagen. Mit speakAs kannst du den Wert zur Laufzeit prüfen oder ändern, zum Beispiel abhängig von Benutzereinstellungen.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Setzen: ein gültiger `speak-as`-Wert (`auto`, `bullets`, `numbers`, `words`, `spell-out` oder der Name eines Zählerstils). Ungültige Werte werden stillschweigend ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des speak-as-Deskriptors in serialisierter Form. Ist der Deskriptor in der Regel nicht angegeben, ist das Ergebnis eine leere Zeichenkette "".

Beispiele

speak-as-Wert einer @counter-style-Regel auslesen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @counter-style raketen {
    system: cyclic;
    symbols: "🚀";
    suffix: " ";
    speak-as: bullets;
  }
`);

const rule = [...sheet.cssRules].find(
  (r) => r instanceof CSSCounterStyleRule
);
console.log(rule.name);
console.log(rule.speakAs);

raketen bullets

Wert zur Laufzeit ändern, ungültige Werte werden ignoriert

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

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

rule.speakAs = 'numbers';
console.log(rule.speakAs);

rule.speakAs = 'laut-vorlesen'; // ungültig, wird ignoriert
console.log(rule.speakAs);

"" numbers numbers

Alle Zählerstile im Dokument auf Barrierefreiheit prüfen

// Findet eigene Zählerstile ohne speak-as-Angabe
const fehlendeSpeakAs = [];

for (const sheet of document.styleSheets) {
  let rules;
  try {
    rules = sheet.cssRules; // kann bei fremden Stylesheets eine Ausnahme werfen
  } catch {
    continue;
  }
  for (const rule of rules) {
    if (rule instanceof CSSCounterStyleRule && rule.speakAs === '') {
      fehlendeSpeakAs.push(rule.name);
    }
  }
}

console.log('Zählerstile ohne speak-as:', fehlendeSpeakAs);

Zählerstile ohne speak-as: ["raketen", "sterne"]

// Wichtig · Fallstricke

Browser-Kompatibilität: CSSCounterStyleRule gibt es in Chrome/Edge ab 91, in Firefox ab 33 und in Safari ab 17. Dass der Deskriptor geparst und über speakAs zugänglich ist, bedeutet aber nicht, dass Browser und Screenreader ihn tatsächlich bei der Sprachausgabe berücksichtigen. Diese Unterstützung ist bislang lückenhaft, deshalb solltest du mit echten Screenreadern testen.
Ungültige Werte führen nicht zu einem Fehler. Die Zuweisung wird einfach verworfen, und der alte Wert bleibt erhalten. Prüfe den Wert also nach dem Setzen, wenn es darauf ankommt.
Ein nicht gesetzter Deskriptor ergibt "" und nicht "auto", obwohl auto das effektive Standardverhalten ist.
Verweist der Wert auf einen anderen Zählerstil, der nicht existiert, oder entsteht ein Zirkelbezug, fällt die Sprachausgabe auf auto zurück.
Beim Zugriff auf cssRules von Stylesheets anderer Herkunft ohne CORS-Freigabe wirft der Browser einen SecurityError. Umschließe den Zugriff deshalb mit try/catch.
speak-as ersetzt keine semantisch korrekte Auszeichnung. Verwende weiterhin <ol> und <ul> passend zum Inhalt.

Siehe auch

CSSCounterStyleRule.fallback CSSCounterStyleRule.pad CSSCounterStyleRule.symbols CSSCounterStyleRule.name CSSCounterStyleRule.prefix