karero/website-hero-carousel

Hero-Carousel für Websites: Fotos, die sich abwechseln, und die Tests, die sie ehrlich halten

Ein Fotoplatz oben auf einer Seite, auf dem sich zwei oder mehr Fotos alle paar Sekunden abwechseln, mit einem Punkt für jedes. Es sieht einfach aus und ist es nicht: Eine Bildunterschrift auf einem Foto lässt die Seite bei jedem Wechsel springen; weiße Punkte verschwinden auf einem hellen Foto; ein Telefon benötigt größere Ziele als eine Maus; und bewegte Inhalte haben ihre eigenen Barrierefreiheitsregeln. Diese Fähigkeit liefert die Komponente und, was noch wichtiger ist, die Tests, die all diese Dinge abfangen.

Warum es so gebaut ist (sagen Sie dies dem Eigentümer in Ihren eigenen Worten)

• Die Seite springt nie. Alle Fotos teilen sich einen Platz, auf eine Form zugeschnitten, sodass die Seite für das erste Foto genauso hoch ist wie für das letzte. Es gibt keine Bildunterschriften oder Quellenangaben auf den Fotos: Sie waren das, was die Seite auf der Website, von der dies stammt, springen ließ. Quellenangaben gehören auf die Bildquellen-Seite der Website.
• Die Punkte sind auf jedem Foto lesbar. Sie sitzen auf einer kleinen dunklen Kapsel, sodass sie sowohl an einem hellen Himmel als auch vor einer dunklen Wand sichtbar sind. Ein Test misst dies an den Pixeln eines hellen und eines dunklen Fotos.
• Es funktioniert ohne JavaScript. Die Fotos stehen dann untereinander und kein Button wird angezeigt.
• Es ist höflich. Es stoppt, wenn die Maus darüber ist, wenn der Tab versteckt ist, wenn der Tastaturfokus hineinkommt, und von Anfang an für Besucher, die ihrem Gerät weniger Bewegung vorgeben.
• Nichts wird gespeichert oder gesendet. Kein Cookie, kein Speicher, keine Anfrage an eine andere Website.

Und die ehrlichen Schwachstellen, damit der Eigentümer sie zuerst von Ihnen hört:

• Rotierende Fotos sind nicht immer das bessere Design. Ein einzelnes starkes Foto ist ruhiger, lädt schneller und kann niemanden irritieren. Sagen Sie es; der Eigentümer entscheidet.
• Jedes zusätzliche Foto kostet den Besucher Ladezeit auf einem Telefon. Drei Fotos in vier Größen sind in Ordnung; zehn nicht. Halten Sie es bei einer Handvoll.
• Der "dots"-Pausemodus tauscht eine sichtbare Steuerung gegen ein saubereres Foto ein (siehe Abschnitt „Pause“ unten).

0. Ist dies das richtige Werkzeug? (vor der Installation fragen)

1. Ist sich der Eigentümer der Rotation sicher? Ein Foto benötigt nichts davon. Fragen Sie einmal, deutlich.
2. Wie viele Fotos und haben sie die gleiche Form? Zwei bis fünf. Jede Form funktioniert (jedes wird auf die Form des Carousels zugeschnitten), aber ein Foto mit seinem Motiv am Rand verliert es im Zuschnitt: Betrachten Sie jedes in der Form des Carousels (standardmäßig 16 / 9) und auf einem Telefon.
3. Verlinken die Fotos irgendwohin? Jede Folie kann auf eine Seite verlinken (z. B. ein Projekt); das Mischen von verlinkten und unverlinkten Folien ist in Ordnung (die CI-Seite tut es).
4. Welcher Pausemodus? Lesen Sie dem Eigentümer „Pause“ unten vor und lassen Sie ihn wählen. Standard: der Button.

1. Was es zur Website hinzufügt

Datei	Aus dieser Fähigkeit templates/	Was es ist
src/components/HeroCarousel.astro	HeroCarousel.astro	das Markup, die Punkte, die Stile
src/components/hero-carousel-text.ts	hero-carousel-text.ts	die Worte, die es sagt, auf Englisch und Deutsch
public/js/hero-carousel.js	hero-carousel.js	das Skript: bringt die Folien an einen Ort, rotiert, bedient die Steuerungen
tests/hero-carousel.spec.ts	hero-carousel.spec.ts	das Carousel, wie ein Besucher es sieht (Liste unten)

Installieren Sie alle vier. Die Vorlagen enthalten keine Bilddatei: Die Fotos sind die eigenen der Website, die als Props übergeben werden.

Wie es funktioniert, in einem Absatz. Der Server sendet jede Folie, eine unter der anderen, und die Steuerungen versteckt. Das Skript, eine eigene Datei der Website unter public/js/ und kein Inline-Skript (damit eine strenge script-src 'self'-Regel es ausführen lässt), platziert dann die Folien in einer Gitterzelle, zeigt die Steuerungen an und markiert die angezeigte Folie. Welche Folie angezeigt wird, ist ein Datenattribut; das CSS erledigt den Rest, einschließlich der Ein-Sekunden-Überblendung. Eine Folie wird nur angezeigt, wenn ihr Bild vollständig geladen ist, sodass ein spätes oder fehlgeschlagenes Foto nie einen leeren Platz hinterlässt.

Was die Spezifikation prüft (die Sicht eines Besuchers, auf der gebauten Seite): das Markup und jeder Punktname; das Intervall auf die Millisekunde auf einer eingefrorenen Uhr; der Pause-Button oder der Punkt, der es stoppt, mit den Labels und der Live-Region; Tastaturfokus (stoppt es, bleibt gestoppt, Fortsetzen); der Zeiger hält es an und ein neues Intervall nach Verlassen; reduzierte Bewegung; ein versteckter Tab; ein spätes und ein fehlgeschlagenes zweites Bild; die Seite ohne JavaScript; kein Höhensprung bei 1280, 768 und 390 px; dass eine nicht angezeigte Folie weder über Tastatur noch im Barrierefreiheitsbaum erreichbar ist; dass ein Fotolink funktioniert und ein Punkt ihn nie öffnet; 32- px Ziele (44 auf Touchscreens); die Punkte auf der Kapsel über jedem Foto, aus gerenderten Pixeln gelesen; erzwungene Farben; axe in beiden Designs; nichts gespeichert oder gesendet; das Skript ist eine Datei, nicht inline; die Überblendung läuft auf einem Teil-Frame und setzt sich, und läuft nicht unter reduzierter Bewegung.

2. Installieren (auf einem Branch, als Pull-Request: AGENTS.md §2)

1. Kopieren Sie die vier Dateien an die in §1 genannten Stellen (mkdir -p public/js zuerst).
2. Setzen Sie das Carousel auf eine Seite, innerhalb des <Base> dieser Seite, ganz oben:

   ---
   import HeroCarousel from '../components/HeroCarousel.astro';
   import first from '../assets/hero-1.jpg';
   import second from '../assets/hero-2.jpg';
   ---
   <HeroCarousel label="Fotos unserer Arbeit" slides={[
     { image: first,  alt: 'Was das erste Foto zeigt', label: 'Kurzer Name', href: '/projekte/eins' },
     { image: second, alt: 'Was das zweite zeigt',      label: 'Ein anderer Name' },
   ]} />
   

   • label: was das Carousel ist, für einen Screenreader. Erforderlich.
   • jede Folie: image (ein importiertes Foto), alt (ein Satz, der sagt, was darauf zu sehen ist, mindestens 10 Zeichen: der Build stoppt bei weniger), label (der kurze Name des Punktes), href (optional).
   • pause: "button" (Standard) oder "dots". swap: "instant" (Standard) oder "fade". intervalMs: Standard 6000, niemals unter 2000. ratio: Standard "16 / 9". lang: die eigene Sprache der Seite. Fotos: JPEG oder PNG, etwa 2.400 px breit, auf das beschränkt, was die Seite benötigt (der Build erstellt vier Größen von jedem, AVIF mit einem WebP-Fallback). Das erste Foto wird zuerst geladen (hohe Priorität); die anderen werden mit niedriger Priorität geladen und behalten ihren Platz.
3. Sprache. Englisch und Deutsch sind eingebaut, und die Komponente übernimmt die eigene Sprache der Seite (Base.astro gibt sie als Astro.locals.lang weiter). Für jede andere: „Eine Sprache hinzufügen“ unten, zuerst.
4. Setzen Sie in tests/hero-carousel.spec.ts PAGE (die Seite mit dem Carousel), PAUSE und SWAP auf das, was die Seite übergibt (die Standardeinstellungen der Komponente sind button und instant; die Spezifikation benötigt sie ausgeschrieben). Die Spezifikation schlägt fehl, während einer leer ist. LANG nur, wenn die Seite lang übergibt. Fotos für den Kontrasttest: Die Spezifikation liest die echten Fotos des Carousels, also trifft sie auf die des Eigentümers zu. Wenn jedes davon dunkel ist, kann der Test „weiße Punkte auf der Kapsel“ nicht fehlschlagen; um ihn fehlschlagen zu sehen, überprüfen Sie einmal von Hand ein helles (der Mutationscheck in §3 tut es).
5. npm run check && npm test.

Pause (lesen Sie dies dem Eigentümer vor, bevor er wählt)

Bewegte Inhalte, die von selbst starten, länger als fünf Sekunden dauern und neben anderen Inhalten liegen, fallen unter WCAG 2.2.2, Level A, das „einen Mechanismus für den Benutzer zum Pausieren, Stoppen oder Ausblenden“ verlangt (lesen Sie unter https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html). Dieselbe Seite definiert Pause als „vom Benutzer gestoppt und erst auf dessen Anfrage hin fortgesetzt“ und sagt nicht, dass der Mechanismus sichtbar sein muss. Sie diskutiert keine Folienindikatoren.

• pause="button" (die Standardeinstellung). Ein Pause-Button neben den Punkten (Fortsetzen während des Stopps). Sichtbar, benannt, die Lesart, die niemand bestreitet, und die, die ein Besucher findet. Sein Preis: ein kleines Wort auf dem Foto.
• pause="dots". Kein Button. Das Auswählen eines Punktes zeigt dieses Foto und stoppt die Rotation, bis der Besucher die Seite neu lädt; der Fokus, der von der Tastatur hineinkommt, stoppt es ebenfalls, und reduzierte Bewegung startet es gestoppt. Das ist wahrscheinlich ein Mechanismus im Sinne von 2.2.2, aber nichts sagt einem Besucher, dass ein Punkt es stoppt, und es gibt keine Möglichkeit, es fortzusetzen. Die erste Website, die diesen Modus verwendete, wählte ihn für das sauberere Foto, wohlwissend.

Diese Fähigkeit zieht keine Konformitätsschlussfolgerung: Ob „dots“ akzeptiert wird, liegt beim eigenen Auditor der Website. Wenn der Eigentümer es wählt, schreiben Sie eine Zeile in die Dokumentation der Website, die dies mit Datum angibt.

Eine Sprache hinzufügen

Auf einer neuen Website in dieser Sprache oder wenn eine Website sie später erhält.

1. Lesen Sie zuerst die Stimme der Website (CONTENT_GUIDE.md; auf Deutsch die Anrede, „du“ oder „Sie“). Die Texte sind eine Handvoll Wörter: Wo die Sprache es erlaubt, sprechen Sie niemanden direkt an.
2. Kopieren Sie in src/components/hero-carousel-text.ts den en-Eintrag von TEXT unter den zweistelligen Code der Sprache (fr, nicht fr-CA) und übersetzen Sie jeden Wert; npm run check schlägt fehl, solange einer fehlt.
3. Die Seite und ihr Test, wie in §2 Schritte 3 und 4.

3. Einmal ausprobieren (der Eigentümer), und die Prüfungen hinter dieser Fähigkeit

Nach npm run build && npm run preview oder auf der Vorschau-Adresse des Pull-Requests kann der Eigentümer:

1. Warten: Die Fotos wechseln sich von selbst, der angezeigte Punkt folgt.
2. Die Maus darüber bewegen: Es hält an. Sie wegnehmen: Es geht weiter, nach einem vollen Intervall.
3. Auf einem Telefon: Auf einen Punkt tippen (er zeigt sein Foto); kein seitliches Scrollen; die Punkte sind leicht zu treffen.
4. Im Button-Modus: Pause drücken, sieht es Fortsetzen sagen, es erneut drücken.

Die Prüfungen, mit denen diese Fähigkeit gebaut wurde, damit eine Änderung an einer Vorlage beurteilt werden kann: Die Spezifikation trägt einen Test für jede dieser Prüfungen, und jeder schlägt fehl, wenn das, was er bewacht, entfernt wird. Führen Sie einmal von Hand aus, wenn sich die Vorlagen ändern (der CI-Job installiert sie in einer frischen Website und führt die Spezifikation aus, in allen drei Kombinationen der verwendeten Einstellungen):

Entfernen Sie dies aus HeroCarousel.astro	Dieser Test schlägt fehl
die Gitterregeln (display: grid, grid-area)	„die Folien teilen sich einen Platz …“
aspect-ratio auf dem Foto	derselbe Test (ein 4:3-Foto ist höher)
der background der Kapsel	„rendered über jedem Foto …“ (weiß auf hellem Foto ist etwa 1:1)
border-width: 5px auf dem angezeigten Punkt	der Test für erzwungene Farben
die transition-Regeln	der Überblendtest („ein Teil-Frame“)
pointer-events: none auf nicht angezeigten Folien	„die Fotolinks zu ihrer Seite …“ (eine ausblendende Folie fängt den Klick ab)
die inert und aria-hidden, die das Skript auf nicht angezeigten Folien setzt (hero-carousel.js)	die Tab-Tasten- und Barrierefreiheitsbaum-Tests (der Link der verschwindenden Folie bleibt erreichbar und lesbar, während sie ausblendet)
das recover() des Skripts (ein fehlgeschlagenes Foto wird durch das erste andere ersetzt, das vorhanden ist, jetzt oder wenn es ankommt)	„ein erstes Bild, das fehlschlägt …“

4. Die Datenschutzseite und der Rückweg

Das Carousel speichert nichts und sendet nichts: Nichts zur Datenschutzseite hinzufügen.

Um es zu entfernen: Löschen Sie die vier Dateien, den <HeroCarousel>-Block und die import HeroCarousel-Zeile (mit den Foto-Importen, die nur sie verwendet hat) von der Seite; setzen Sie ein Foto zurück. Nichts anderes verweist darauf, abgesehen von PAGES-gesteuerten Suiten, die nur die Seite sehen.

5. Nicht in dieser Fähigkeit (damit niemand es annimmt)

Vorherige / nächste Pfeile, Wischgesten, Bildunterschriften auf den Fotos, Quellenangaben auf den Fotos, Videofolien, mehr als ein Carousel auf einer Seite (seine IDs sind fest), verzögertes Laden der späteren Fotos. Jedes kann später hinzugefügt werden; keines ist für die erste Version erforderlich.