Frontend-API¶
Seit 1.30.0. Worauf sich Themes und eigene Skripte verlassen können; Änderungen daran stehen im Changelog unter Breaking.
Site-Einstellungen¶
| Einstellung | Wirkung |
|---|---|
ntai.a11yWidget.primaryColor / primaryColorDark |
Hauptfarbe von Widget, Schaltern, Reglern, Fokusrahmen und Vorlese-Markierung (hell / dunkel). Leer = Standardblau. |
ntai.a11yWidget.address |
sie (Standard) oder du für die deutschen Texte. |
ntai.a11yWidget.introText / tooltipText |
Eigene Texte für Einleitung und Hinweis beim ersten Besuch. |
ntai.a11yWidget.hideWhen |
CSS-Selektor; solange er trifft, ist das Widget ausgeblendet (z. B. offener Vollbild-Chat). |
ntai.a11yWidget.hideMedia |
Seit 1.31.0. Media Query, z. B. (max-width: 767px). Mit hideWhen: ausblenden, wenn beides zutrifft; ohne: bei dieser Bildschirmgröße immer ausblenden. |
ntai.tts.scope |
Vorlesebereich, Liste in Reihenfolge (Standard #maincontent, main, [role=main]). |
ntai.tts.readImageAlt |
Bilder mit Alternativtext als „Bild: …" vorlesen (Standard an). |
ntai.tts.expandCollapsed |
Akkordeons, <details> und hidden="until-found" zum Vorlesen öffnen und danach wieder schließen (Standard an). |
CSS-Variablen¶
Farben auf :root, Position auf .nt-a11y-widget (auch in Media Queries): --nt-a11y-primary, --nt-a11y-primary-dark, abgeleitet --nt-a11y-primary-contrast, --nt-a11y-primary-tint, --nt-a11y-on-tint, --nt-a11y-primary-tint-dark, --nt-a11y-on-tint-dark, --nt-a11y-focus, --nt-a11y-focus-dark, --nt-tts-highlight; seit 1.31.0 --nt-a11y-primary-dark-contrast (Text auf der dunklen „EIN"-Markierung), --nt-a11y-launcher-hover / --nt-a11y-launcher-hover-dark (Hintergrund des Auslösers bei Hover und Fokus), --nt-a11y-title-color / --nt-a11y-title-color-dark (Panel-Titel; die h2-Farbe der Website wird nicht übernommen); --nt-a11y-offset-x, --nt-a11y-offset-y, --nt-a11y-z.
Markup¶
Der Container div.nt-a11y-widget hängt am Ende von body und ist seit 1.32.1 eine benannte Landmark (role="region", aria-label = Panel-Titel), damit er bei der Navigation über Landmarks auffindbar ist. Die Vorleseleiste div.nt-tts-bar ist ebenfalls eine benannte Region.
Attribute¶
html[data-nt-theme="dark"]– vom Dunkelmodus-Schalter vor dem ersten Zeichnen gesetzt; das dunkle Seitendesign liefert das Theme. „Fokus hervorheben" nimmt dann--nt-a11y-focus-dark. Ein Betriebssystem im Dunkelmodus allein macht die Seite nicht dunkel und ändert die Fokusfarbe deshalb nicht.html[data-nt-a11y-hidden]– Widget ausgeblendet.[data-nt-tts]am Knopf – Vorlesen starten/stoppen; Wert = optionaler Bereich. Später eingefügte Knöpfe:window.ntTts.wire().[data-nt-tts-skip]– Element wird nicht vorgelesen.
Ereignisse (auf document, Daten in event.detail)¶
nt-tts:beforecollect (abbrechbar; scope, source, waitUntil(promise)), nt-tts:start (source: button/widget/click/api, blocks), nt-tts:segment (index, total, node, engine), nt-tts:pause, nt-tts:resume, nt-tts:stop (reason: user/end/error, seit 1.34.0 auch language), nt-tts:fallback (from, to, index, rest, status = bisher immer null), nt-tts:error (reason), nt-tts:clickmode (on; seit 1.31.0, nur bei echtem Wechsel); nt-a11y:ready, open, close (seit 1.31.0 nur bei echtem Wechsel), reset, nt-a11y:change (key, value, previous; eigene Einträge als custom:<id>), nt-a11y:language (lang; seit 1.34.0, nach einem Sprachwechsel zur Laufzeit).
Globale Objekte¶
window.ntTts (Version 2): play(scope?, source?), pause(), resume(), stop(), toggle(scope?, source?), skip(±1), setVolume(), setRate(), setClickMode(), isPlaying(), onState(cb), wire(), getLang() (seit 1.34.0).
window.ntA11y (Version 1): open(), close(), toggle(), isOpen(), getPrefs(), setPref(key, value), hide(), show(), refresh(), registerToggle({ id, label, description?, isOn(), onToggle(on), position? }) – gibt seit 1.31.0 eine Funktion zum Entfernen zurück –, unregisterToggle(id) (seit 1.31.0), getLang() (seit 1.34.0). Eigene Einträge im Ereignis nt-a11y:ready registrieren.
Sprache (seit 1.34.0)¶
Widget und Vorlesen lesen <html lang> beim Laden und beobachten danach lang und dir am <html>-Element (MutationObserver). Ändert eine Übersetzung im Browser die Sprache – nt-lingua im DOM-Modus oder ein anderes Werkzeug –, folgen beide ohne Neuladen:
- Das Widget setzt seine Texte neu (Panel, Launcher-Label, Tooltip, Hinweise). Die gespeicherten Einstellungen bleiben, ein offenes Panel bleibt offen, der Tastaturfokus bleibt auf dem Bedienelement. Bei
dir="rtl"trägt der Containerdir="rtl"und das Panel ist gespiegelt; die Ecke des Launchers bleibt die eingestellte. - Vorlesen wechselt Sprache und Stimme. Eine laufende Wiedergabe endet (
nt-tts:stopmitreason: language), die nächste liest in der neuen Sprache.
Mitgeliefert sind Texte für de, en, fr, it, es, pt, nl, pl, ro, hr, sr (kyrillisch), bs, sq, el, tr, uk, ru und ar; andere Sprachen erhalten Englisch. Die Anrede (ntai.a11yWidget.address, Sie/du) gilt nur für Deutsch, eigene Texte der Site (introText, tooltipText) nur für die Sprache, in der die Seite ausgeliefert wurde.
Browsertest: NODE_PATH=<pfad>/node_modules node Tests/JavaScript/widget-language.cjs (Playwright, siehe Dateikopf).