@capgo/capacitor-sheets

Bottom sheets, drawers, dialoghi e overlay indipendenti dal framework, ottimizzati per i WebViews di Capacitor.

Indipendente dal framework

Usa elementi custom basati su standard direttamente oppure usa helper di setup per React, Vue, Angular, Svelte e Solid.

Pronto per Capacitor

Rispetta le safe area, il movimento della tastiera, i gesti nativi dai bordi e l'oscuramento del theme-color della WebView dal layer web.

Ogni forma di sheet

Componi bottom sheet, side drawer, top sheet, dialog centrati, toast, sheet staccati, card, pagine e lightbox.

CSS moderno

Definisci i detents con em, rem, unità viewport, calc(), e variabili CSS mentre la dimensione predefinita resta em basata.

Supporto piattaforme

Piattaforma	Supporto	Note
iOS	Livello web	Elementi personalizzati all'interno di WKWebView
Android	Livello web	Elementi personalizzati all'interno di Android WebView
Web	Sì	Stesse componenti per le build web di Capacitor

Quando usarlo

@capgo/capacitor-sheets è pensato per app Capacitor che richiedono overlay mobile di alta qualità senza adottare un framework UI specifico. Viene distribuito come custom elements, quindi il pacchetto core non ha dipendenze runtime da React, Vue, Angular, Svelte o Solid.

Usalo quando ti serve:

bottom sheet con uno o più detents
sidebar a sinistra o a destra e top sheet
dialog centrati, lightbox, card e overlay tipo toast
sheet persistenti che mantengono interattiva l'app sottostante
overlay a pagina intera che entrano da un bordo
effetti di stack, profondità e parallax basati sul progresso dello sheet
helper per lo scroll che espongono valori di progresso e distanza
layout Capacitor-safe per notch, home indicator, cutout Android e tastiere software

Copertura dei casi d'uso

Caso d'uso	Pattern Sheets di Capgo
Sheet lungo	`cap-sheet` con scroll naturale del contenuto o `cap-scroll`
Sheet con detent	`detents="18em 32em"` più `stepTo()` o un trigger a step
Sidebar	`content-placement="left"` oppure `content-placement="right"`
Bottom Sheet	default `content-placement="bottom"`
Sheet con tastiera	`native-focus-scroll-prevention` e gestione dell'offset del visual viewport
Toast	`inert-outside="false"`, `focus-trap="false"`, senza chiusura al click esterno
Foglio staccato	`cap-sheet-special-wrapper` con margini e radius personalizzati
Pagina dal basso	contenuto bottom sheet a tutta altezza
Top Sheet	`content-placement="top"`
Sheet con stacking	`cap-sheet-stack` con variabili di profondità
Sheet con profondità	`cap-sheet-outlet` e trasformazioni basate sul progresso
Pagina con parallasse	`cap-sheet-outlet` con `cap-scroll` progresso
Pagina	contenuto a schermo intero che entra da un bordo
Lightbox	`content-placement="center"` con sfondo e contenuto multimediale
Sheet persistente con detent	`default-presented`, `swipe-dismissal="false"`, e `inert-outside="false"`
Card	contenuto compatto e centrato della sheet

Il core API

<cap-sheet> gestisce lo stato di presentazione, i detents, il posizionamento, i gesti, l'accessibilità e gli eventi.
<cap-sheet-trigger> definisce le azioni di present, dismiss, toggle e detent-step.
<cap-sheet-view> posiziona l'overlay e applica gli offset per safe-area e tastiera.
<cap-sheet-backdrop> renderizza uno sfondo sincronizzato con i progressi.
<cap-sheet-content> renderizza la superficie della sheet.
<cap-sheet-handle> fornisce controlli per detent tramite drag e tastiera.
<cap-sheet-stack> coordina le sheet sovrapposte.
<cap-sheet-outlet> espone il progresso della sheet per effetti di pagina, profondità e parallax.
<cap-scroll> e <cap-scroll-content> espone helper per avanzamento e distanza dello scroll.
setupSheet(element, options?) configura un sheet da effetti del framework o hook di ciclo di vita.

Modello di layout Capacitor

La viewport predefinita del sheet legge env(safe-area-inset-*) e in stile Capacitor --safe-area-inset-* poi applica i bordi selezionati come padding attorno all'overlay. safe-area="auto" protegge tutti i bordi; usa safe-area="bottom left right" oppure safe-area="none" quando un caso d'uso richiede un comportamento diverso.

La gestione della tastiera è abilitata di default. Il sheet ascolta visualViewport eventi di resize e scroll, aggiunge un offset della tastiera al viewport e porta il focus sui controlli con preventScroll così gli input restano visibili sopra la tastiera software.

Il pacchetto gira nel layer web. Non renderizza bottom sheet nativi UIKit o Android, quindi la tua app mantiene il pieno controllo dello stile rispettando comunque i vincoli del WebView che contano in Capacitor.

Demo e playground

Le demo WebP animate per ogni caso d'uso supportato sono incluse nel README del repository. Gli esempi sono disponibili anche come playground su StackBlitz:

Sheet lungo	Detents

Sidebar	Lightbox

Continua da @capgo/capacitor-sheets

Se stai usando @capgo/capacitor-sheets per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli sull'implementazione in Adding or Updating Plugins, Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Ionic Enterprise Plugin Alternatives, e Capgo Native Build per il workflow di prodotto in Capgo Native Builds.