@capgo/capacitor-sheets

Framework-agnostische Bottom Sheets, Drawers, Dialoge und Overlays, optimiert für Capacitor WebViews.

Framework-agnostisch

Verwenden Sie standardbasierte Custom Elements direkt oder nutzen Sie Setup-Helfer für React, Vue, Angular, Svelte und Solid.

Capacitor-ready

Berücksichtige Safe Areas, Tastaturbewegungen, native Edge-Gestures und WebView-Theme-Color-Dimming aus dem Web-Layer.

Jede Sheet-Form

Erstelle Bottom Sheets, Side Drawers, Top Sheets, zentrierte Dialoge, Toasts, Detached Sheets, Cards, Pages und Lightboxes.

Modernes CSS

Definiere Detents mit em, rem, Viewport-Einheiten, calc(), und CSS-Variablen, während das Standard-Sizing em basiert.

Plattformunterstützung

Plattform	Support	Notizen
iOS	Web-Layer	Custom Elements in WKWebView
Android	Web-Layer	Custom Elements in Android WebView
Web	Ja	Gleiche Komponenten für Capacitor Web-Builds

Wann verwenden

@capgo/capacitor-sheets ist für Capacitor-Apps gedacht, die hochwertige mobile Overlays benötigen, ohne ein bestimmtes UI-Framework zu verwenden. Es wird als Custom Elements ausgeliefert, sodass das Core-Paket keine Runtime-Abhängigkeiten zu React, Vue, Angular, Svelte oder Solid hat.

Nutze es, wenn du Folgendes benötigst:

Bottom Sheets mit einem oder mehreren Detents
Seitenleisten links oder rechts sowie Top Sheets
zentrierte Dialoge, Lightboxes, Karten und toast-ähnliche Overlays
persistente Sheets, die die App dahinter interaktiv halten
Full-Page-Overlays, die von einer Kante eintreten
Stack-, Tiefen- und Parallax-Effekte, gesteuert durch den Sheet-Fortschritt
Scroll-Helfer, die Fortschritts- und Distanzwerte bereitstellen
Capacitor-sicheres Layout für Notches, Home-Indikatoren, Android-Ausschnitte und Software-Tastaturen

Use-Case-Abdeckung

Use Case	Capgo Sheets-Pattern
Langes Sheet	`cap-sheet` mit natürlichem Content-Scroll oder `cap-scroll`
Sheet mit Detent	`detents="18em 32em"` sowie `stepTo()` oder einem Step-Trigger
Sidebar	`content-placement="left"` oder `content-placement="right"`
Bottom Sheet	Standard `content-placement="bottom"`
Sheet mit Tastatur	`native-focus-scroll-prevention` und Visual Viewport Offset-Handling
Toast	`inert-outside="false"`, `focus-trap="false"`, und kein Schließen durch Klick außerhalb
Abgelöste Sheet	`cap-sheet-special-wrapper` plus individuelle Margen und Eckenradius
Seite von unten	Bottom Sheet-Inhalt in voller Höhe
Top Sheet	`content-placement="top"`
Sheet mit Stacking	`cap-sheet-stack` mit Tiefenvariablen
Sheet mit Tiefe	`cap-sheet-outlet` und progress-basierten Transforms
Parallax-Seite	`cap-sheet-outlet` mit `cap-scroll` Fortschritt
Seite	Full-Viewport-Content, der von einem Rand einfährt
Lightbox	`content-placement="center"` mit Backdrop und Medieninhalt
Persistent Sheet mit Detent	`default-presented`, `swipe-dismissal="false"`, und `inert-outside="false"`
Karte	kompakter, zentrierter Sheet-Inhalt

Kern von API

<cap-sheet> verwaltet Präsentationszustand, Detents, Positionierung, Gesten, Barrierefreiheit und Events.
<cap-sheet-trigger> deklariert present-, dismiss-, toggle- und detent-step-Aktionen.
<cap-sheet-view> positioniert das Overlay und wendet Safe-Area- und Keyboard-Offsets an.
<cap-sheet-backdrop> rendert einen progress-synchronisierten Backdrop.
<cap-sheet-content> rendert die Sheet-Fläche.
<cap-sheet-handle> stellt Drag- und Keyboard-Detent-Steuerungen bereit.
<cap-sheet-stack> koordiniert gestapelte Sheets.
<cap-sheet-outlet> stellt den Sheet-Fortschritt für Page-, Depth- und Parallax-Effekte bereit.
<cap-scroll> und <cap-scroll-content> stellt Scroll-Fortschritt und Distanz-Helfer bereit.
setupSheet(element, options?) konfiguriert ein Sheet über Framework-Effekte oder Lifecycle-Hooks.

Capacitor Layout-Modell

Die Standard-Sheet-Viewport liest env(safe-area-inset-*) und Capacitor-Stil --safe-area-inset-* Fallback-Variablen und wendet die gewählten Kanten als Padding um das Overlay an. safe-area="auto" schützt alle Kanten; verwende safe-area="bottom left right" oder safe-area="none" wenn ein Use Case ein anderes Verhalten benötigt.

Die Tastaturverarbeitung ist standardmäßig aktiviert. Das Sheet lauscht auf visualViewport behandelt Resize- und Scroll-Events, fügt dem Viewport einen Tastatur-Offset hinzu und fokussiert Controls mit preventScroll damit Inputs über der Software-Tastatur sichtbar bleiben.

Das Paket läuft im Web-Layer. Es rendert keine nativen UIKit- oder Android-Bottom-Sheets, sodass deine App volle Kontrolle über das Styling behält und dabei die WebView-Constraints beachtet, die in Capacitor zählen.

Demos und Playgrounds

Animierte WebP-Demos für jeden unterstützten Anwendungsfall sind im Repository README enthalten. Die Beispiele sind auch als StackBlitz-Playgrounds verfügbar:

Langes Sheet	Detents

Sidebar	Lightbox

Weitermachen mit @capgo/capacitor-sheets

Wenn du es nutzt @capgo/capacitor-sheets Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails unter „Plugins hinzufügen oder aktualisieren“, Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow in Ionic Enterprise Plugin-Alternativen und Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds.