Fehlerbehebung

Lösungen für Eigenheiten von iOS Safari, die Wiedergabe von Videos, das Vollbild und die Tastaturnavigation.

iOS Safari

Der Viewport füllt den Bildschirm nicht / schwarzer Streifen unten

Durch die einklappbare Adressleiste von Safari ist 100vh höher als der sichtbare Bereich. Nutze 100dvh:

.slider-container {
  height: 100dvh; /* not 100vh */
}

Horizontales Scrollen / Inhalt läuft über

Unter iOS enthält 100vw die Breite der Scrollleiste und schiebt den Inhalt über den Rand hinaus. Nutze 100% und sperre den horizontalen Overflow:

html, body {
  overflow-x: hidden;
}

.slider-container {
  width: 100%; /* not 100vw */
}

Pull-to-Refresh / elastisches Nachfedern

Pull-to-Refresh und das elastische Nachfedern von Safari kommen den vertikalen Wischgesten in die Quere. Setze overscroll-behavior: none nicht auf html, body. Damit funktioniert das normale Scrollen der Seite nicht mehr. ReelPlayerOverlay, LightboxOverlay und StoriesPlayerOverlay regeln das in ihren eigenen Containern. Bei eigenen Layouts begrenzt du es auf den Bereich:

.slider-container {
  overscroll-behavior: none;
}

Sonderfall SwipeToClose nach unten. Jedes SwipeToClose mit direction="down" (Lightbox, Stories Player, eigene Overlays) wird unter iOS Safari ausgebremst: Der Browser löst Pull-to-Refresh auf Ebene des Dokuments aus, bevor der Wrapper die Berührung sieht. Das Overlay sperrt das Scrollen des Body, doch das vertikale Verschieben an der Wurzel behält der Browser. Setze overscroll-behavior-y: contain nur auf <html>, solange das Overlay offen ist, und stelle den Wert beim Schließen wieder her:

useEffect(() => {
  if (!isOpen) return;
  const html = document.documentElement;
  const prev = html.style.overscrollBehaviorY;
  html.style.overscrollBehaviorY = 'contain';
  return () => {
    html.style.overscrollBehaviorY = prev;
  };
}, [isOpen]);

Pinch-to-Zoom stört die Gesten

Deaktiviere den Zoom, damit Pinch und Doppeltippen beim Wischen nicht ausgelöst werden:

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover" />

viewport-fit=cover erweitert dein Layout in den sicheren Bereich von Dynamic Island und Notch.

Layout ist kaputt, nachdem die Tastatur verschwindet

Safari lässt den Viewport manchmal gestaucht, nachdem sich die Tastatur geschlossen hat. Erzwinge beim Blur ein Zurücksetzen:

// React
<input
  onBlur={() => {
    window.scrollTo(0, 0);
    apiRef.current?.adjust();
  }}
/>

// Angular
(blur)="onInputBlur()"

onInputBlur() {
  window.scrollTo(0, 0);
  this.reelApi?.adjust();
}

Allgemein

Slides werden mit 0×0 gerendert

Ohne die Prop size liest der Slider die Maße seines Containers über ResizeObserver. Ein Container ohne CSS-Höhe misst 0×0, also wird nichts gerendert. Übergib size oder gib dem Container Maße:

/* The parent must have a height for auto-sizing to work */
.slider-container {
  width: 100%;
  height: 100dvh;
}

Video

Das Video startet nicht automatisch

Browser blockieren Autoplay mit Ton. ReelKit setzt muted und playsInline auf jedes Video-Element. Videos starten stumm; nach einem Tippen schalten die Nutzer den Ton über den Sound-Schalter ein. Prüfe, ob du diese Attribute in einem eigenen Slide überschreibst.

Vorschaubild / Frame-Capture des Videos bleibt leer

Frame-Capture zeichnet das Video auf ein <canvas>. Videos von einem anderen Origin machen das Canvas unbrauchbar, und das Zeichnen schlägt still fehl. Dein Video-CDN muss CORS-Header zurückgeben:

Access-Control-Allow-Origin: *

ReelKit setzt standardmäßig crossOrigin="anonymous". Wenn du ein eigenes Video-Element verwendest, ergänze es selbst.

Vollbild

Der Vollbild-Button tut in Safari nichts

ReelKit deaktiviert die Fullscreen API in Safari. iOS Safari erlaubt Vollbild nur für <video>-Elemente. Desktop-Safari bringt Overlays mit position: fixed im Vollbild durcheinander: Elemente verlieren ihren Stacking-Kontext oder verschwinden. requestFullscreen() wird in Safari ohne Wirkung aufgelöst.

Tastaturnavigation

Pfeiltasten navigieren nicht mehr, sobald onNavKeyPress gesetzt ist

onNavKeyPress ersetzt die Standardnavigation per Tastatur. ReelKit ruft next()/prev() nicht mehr auf und übergibt dir die Kontrolle. Rufe sie selbst auf:

<Reel
  onNavKeyPress={(increment) => {
    // Your custom logic here
    console.log('Nav key:', increment);
    // You must trigger navigation yourself:
    apiRef.current?.[increment === 1 ? 'next' : 'prev']();
  }}
/>

Escape schließt das Overlay nicht

Der Tastatur-Controller verarbeitet nur die Pfeiltasten. ReelPlayerOverlay und LightboxOverlay lauschen getrennt auf Escape. Wenn du ein eigenes Overlay baust, ergänze einen eigenen Handler für Escape in onClose.