@capgo/capacitor-sheets

Bottom sheets, drawers, dialogues et overlays agnostiques du framework, optimisés pour les WebViews Capacitor.

Indépendant du framework

Utilisez directement des custom elements basés sur les standards, ou les helpers de configuration pour React, Vue, Angular, Svelte et Solid.

Prêt pour Capacitor

Respectez les zones sûres, le déplacement du clavier, les gestes edge natifs et l'assombrissement de la theme-color de la WebView depuis la couche web.

Chaque forme de sheet

Composez des bottom sheets, des side drawers, des top sheets, des dialogs centrés, des toasts, des detached sheets, des cards, des pages et des lightboxes.

CSS moderne

Définissez les detents avec em, rem, des unités de viewport, calc(), et des variables CSS, tandis que le dimensionnement par défaut reste em basé.

Support des plateformes

Plateforme	Support	Notes
iOS	Couche web	Éléments personnalisés dans WKWebView
Android	Couche web	Éléments personnalisés dans Android WebView
Le Web	Oui	Mêmes composants pour les builds web Capacitor

Quand l'utiliser

@capgo/capacitor-sheets est destiné aux applications Capacitor qui ont besoin d'overlays mobiles de haute qualité sans adopter un framework UI spécifique. Il est distribué sous forme de custom elements, donc le package principal n'a aucune dépendance runtime à React, Vue, Angular, Svelte ou Solid.

Utilisez-le lorsque vous avez besoin de :

bottom sheets avec un ou plusieurs detents
sidebars à gauche ou à droite et top sheets
dialogues centrés, lightboxes, cartes et overlays de type toast
sheets persistantes qui gardent l'app interactive en arrière-plan
overlays pleine page qui arrivent depuis un edge
effets de stack, de profondeur et de parallaxe pilotés par la progression de la sheet
des helpers de scroll qui exposent la progression et la distance
layout sécurisé pour Capacitor (encoches, indicateurs home, découpes Android et claviers logiciels)

Couverture des cas d'usage

Cas d'usage	Modèle de Capgo Sheets
Sheet long	`cap-sheet` avec défilement naturel du contenu ou `cap-scroll`
Sheet avec detent	`detents="18em 32em"` , ce qui `stepTo()` ou un déclencheur d'étape
Barre latérale	`content-placement="left"` ou `content-placement="right"`
Bottom Sheet	par défaut `content-placement="bottom"`
Sheet avec clavier	`native-focus-scroll-prevention` et gestion du décalage du viewport visuel
Toast	`inert-outside="false"`, `focus-trap="false"`, et pas de fermeture par clic extérieur
Sheet détaché	`cap-sheet-special-wrapper` plus marges et rayon personnalisés
Page depuis le bas	contenu de bottom sheet en pleine hauteur
Sheet du haut	`content-placement="top"`
Sheet avec empilement	`cap-sheet-stack` avec des variables de profondeur
Sheet avec profondeur	`cap-sheet-outlet` et transformations pilotées par la progression
Page parallaxe	`cap-sheet-outlet` par `cap-scroll` progression
Page	contenu sur tout le viewport entrant depuis un bord
Lightbox	`content-placement="center"` avec fond et contenu média
Sheet persistant avec detent	`default-presented`, `swipe-dismissal="false"`, et `inert-outside="false"`
Carte	contenu de feuille compacte et centré

Cœur API

<cap-sheet> gère l’état de présentation, les detents, le placement, les gestes, l’accessibilité et les événements.
<cap-sheet-trigger> déclare les actions present, dismiss, toggle et detent-step.
<cap-sheet-view> positionne l’overlay et applique les décalages de zone sûre et de clavier.
<cap-sheet-backdrop> renders a progress-synced backdrop.
<cap-sheet-content> affiche la surface de la feuille.
<cap-sheet-handle> fournit des contrôles de crans par glissement et au clavier.
<cap-sheet-stack> coordonne les feuilles empilées.
<cap-sheet-outlet> expose la progression de la feuille aux effets de page, de profondeur et de parallaxe.
<cap-scroll> et <cap-scroll-content> expose des helpers de progression et distance de défilement.
setupSheet(element, options?) configure une feuille à partir d'effets du framework ou de hooks de cycle de vie.

Modèle de mise en page Capacitor

Le viewport de la feuille par défaut lit env(safe-area-inset-*) et au style Capacitor --safe-area-inset-* puis applique les bords sélectionnés comme padding autour de l'overlay. safe-area="auto" protège tous les edge ; utilisez safe-area="bottom left right" ou safe-area="none" quand un cas d’usage nécessite un comportement différent.

La gestion du clavier est activée par défaut. La feuille écoute les événements visualViewport les événements de redimensionnement et de défilement, ajoute un décalage clavier au viewport et met le focus sur preventScroll afin que les champs restent visibles au-dessus du clavier logiciel.

Le package s’exécute dans la couche web. Il n’affiche pas de feuilles inférieures natives UIKit ou Android, ce qui vous laisse un contrôle total sur le style tout en respectant les contraintes du WebView essentielles dans Capacitor.

Démonstrations et playgrounds

Les démos WebP animées pour chaque cas d’usage pris en charge sont incluses dans le README du dépôt. Les exemples sont également disponibles en playgrounds StackBlitz :

Sheet long	Detents

Barre latérale	Lightbox

Continuer avec @capgo/capacitor-sheets

Si vous utilisez @capgo/capacitor-sheets pour planifier le travail sur les plugins natifs, connectez-l’à Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, et Capgo Native Build pour le workflow produit dans Capgo Native Builds.