Premiers pas

Copiez un prompt de configuration avec les étapes d'installation et le guide markdown complet pour ce plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-sheets`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/sheets/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Installation

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite le prompt suivant :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-sheets` plugin in my project.

Si vous préférez la configuration manuelle, installez le plugin avec les commandes suivantes, puis suivez les instructions spécifiques à chaque plateforme ci-dessous :

Installer le package
Fenêtre de terminal
```
bun add @capgo/capacitor-sheets
```
Enregistrer les web components
```
import '@capgo/capacitor-sheets';
```

Ajouter le réglage du viewport pour les safe areas

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />

Rendre un sheet

<cap-sheet-trigger for="booking-sheet" action="present">Open route</cap-sheet-trigger>

<cap-sheet id="booking-sheet" detents="18em 32em" content-placement="bottom">
  <cap-sheet-portal>
    <cap-sheet-view>
      <cap-sheet-backdrop></cap-sheet-backdrop>
      <cap-sheet-content class="route-sheet">
        <cap-sheet-bleeding-background></cap-sheet-bleeding-background>
        <cap-sheet-handle></cap-sheet-handle>
        <cap-sheet-title>Evening route</cap-sheet-title>
        <cap-sheet-description>Choose a route and confirm pickup.</cap-sheet-description>
        <cap-sheet-trigger action="dismiss">Done</cap-sheet-trigger>
      </cap-sheet-content>
    </cap-sheet-view>
  </cap-sheet-portal>
</cap-sheet>

.route-sheet {
  width: min(100%, 34em);
  padding: 0 1.25em 1.25em;
}

Erreurs courantes

Enregistrer les composants: import @capgo/capacitor-sheets once at bootstrap or elements will not upgrade.
Ajustement du viewport: manquant viewport-fit=cover casse le padding de la safe area sur les téléphones à encoche.
Clavier: activez la prévention du scroll au focus documentée lorsque les inputs se trouvent dans des bottom sheets.

Capacitor Safe Areas

Les safe areas sont activées par défaut via safe-area="auto"La vue de la feuille lit les valeurs de l'environnement du navigateur ainsi que les variables de repli Capacitor :

env(safe-area-inset-top)
env(safe-area-inset-bottom)
env(safe-area-inset-left)
env(safe-area-inset-right)
var(--safe-area-inset-top)
var(--safe-area-inset-bottom)
var(--safe-area-inset-left)
var(--safe-area-inset-right)

Choisissez les bords protégés par sheet :

<cap-sheet safe-area="auto"></cap-sheet>
<cap-sheet safe-area="bottom left right"></cap-sheet>
<cap-sheet safe-area="none"></cap-sheet>

Pour les apps avec des barres de statut ou système en overlay, conservez les plugins natifs responsables de l'exposition des valeurs d'inset correctes :

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    StatusBar: {
      overlaysWebView: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    SystemBars: {
      insetsHandling: 'css',
    },
  },
};

export default config;

La gestion du clavier est contrôlée par native-focus-scroll-prevention, qui utilise par défaut true. Désactivez-l’uniquement si votre app gère déjà l'évitement du clavier :

<cap-sheet native-focus-scroll-prevention="false"></cap-sheet>

Contrôl’impératif

Tous les helpers du framework configurent le même élément personnalisé sous-jacent. Vous pouvez également contrôler une sheet directement :

const sheet = document.querySelector('cap-sheet');

await sheet?.present();
await sheet?.stepTo(2);
await sheet?.step('down');
await sheet?.dismiss();

Écoutez les événements pour gérer l'état, l'analytics ou coordonner les animations :

sheet?.addEventListener('cap-sheet-presented-change', (event) => {
  console.log(event.detail.presented);
});

sheet?.addEventListener('cap-sheet-active-detent-change', (event) => {
  console.log(event.detail.activeDetent);
});

sheet?.addEventListener('cap-sheet-travel', (event) => {
  console.log(event.detail.progress);
});

React

import { useEffect, useRef } from 'react';
import { setupSheet } from '@capgo/capacitor-sheets/react';
import '@capgo/capacitor-sheets';

export function BookingSheet() {
  const sheetRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (!sheetRef.current) return;

    return setupSheet(sheetRef.current, {
      detents: ['18em', '32em'],
      contentPlacement: 'bottom',
      onPresentedChange: ({ presented }) => console.log({ presented }),
    });
  }, []);

  return (
    <cap-sheet id="booking-sheet" ref={sheetRef}>
      <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
      <cap-sheet-view>
        <cap-sheet-backdrop />
        <cap-sheet-content>
          <cap-sheet-handle />
          <cap-sheet-title>React sheet</cap-sheet-title>
        </cap-sheet-content>
      </cap-sheet-view>
    </cap-sheet>
  );
}

Importation depuis @capgo/capacitor-sheets/react enregistre également les typages JSX pour les éléments personnalisés. Si TypeScript signale toujours des balises inconnues, ajoutez un fichier de déclaration dans votre arborescence source :

import '@capgo/capacitor-sheets/react';

Vue

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue';
import { setupSheet } from '@capgo/capacitor-sheets/vue';
import '@capgo/capacitor-sheets';

const sheetRef = ref<HTMLElement | null>(null);
let cleanup: (() => void) | undefined;

onMounted(() => {
  if (sheetRef.value) {
    cleanup = setupSheet(sheetRef.value, {
      detents: ['18em', '32em'],
      contentPlacement: 'bottom',
    });
  }
});

onUnmounted(() => cleanup?.());
</script>

<template>
  <cap-sheet id="booking-sheet" ref="sheetRef">
    <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
    <cap-sheet-view>
      <cap-sheet-backdrop />
      <cap-sheet-content>
        <cap-sheet-handle />
        <cap-sheet-title>Vue sheet</cap-sheet-title>
      </cap-sheet-content>
    </cap-sheet-view>
  </cap-sheet>
</template>

Angular

import { AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild } from '@angular/core';
import { setupSheet } from '@capgo/capacitor-sheets/angular';
import '@capgo/capacitor-sheets';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <cap-sheet id="booking-sheet" #sheet>
      <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
      <cap-sheet-view>
        <cap-sheet-backdrop></cap-sheet-backdrop>
        <cap-sheet-content>
          <cap-sheet-handle></cap-sheet-handle>
          <cap-sheet-title>Angular sheet</cap-sheet-title>
        </cap-sheet-content>
      </cap-sheet-view>
    </cap-sheet>
  `,
})
export class AppComponent implements AfterViewInit {
  @ViewChild('sheet', { static: true }) sheet?: ElementRef<HTMLElement>;

  ngAfterViewInit(): void {
    if (this.sheet?.nativeElement) {
      setupSheet(this.sheet.nativeElement, {
        detents: ['18em', '32em'],
        contentPlacement: 'bottom',
      });
    }
  }
}

Svelte

<script lang="ts">
  import { sheet } from '@capgo/capacitor-sheets/svelte';
  import '@capgo/capacitor-sheets';
</script>

<cap-sheet id="booking-sheet" use:sheet={{ detents: ['18em', '32em'], contentPlacement: 'bottom' }}>
  <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
  <cap-sheet-view>
    <cap-sheet-backdrop />
    <cap-sheet-content>
      <cap-sheet-handle />
      <cap-sheet-title>Svelte sheet</cap-sheet-title>
    </cap-sheet-content>
  </cap-sheet-view>
</cap-sheet>

Solid

import { onCleanup, onMount } from 'solid-js';
import { setupSheet } from '@capgo/capacitor-sheets/solid';
import '@capgo/capacitor-sheets';

export function BookingSheet() {
  let sheetEl!: HTMLElement;

  onMount(() => {
    const cleanup = setupSheet(sheetEl, {
      detents: ['18em', '32em'],
      contentPlacement: 'bottom',
    });

    onCleanup(cleanup);
  });

  return (
    <cap-sheet id="booking-sheet" ref={sheetEl}>
      <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
      <cap-sheet-view>
        <cap-sheet-backdrop />
        <cap-sheet-content>
          <cap-sheet-handle />
          <cap-sheet-title>Solid sheet</cap-sheet-title>
        </cap-sheet-content>
      </cap-sheet-view>
    </cap-sheet>
  );
}

Composants

Élément	Finalité
`cap-sheet`	État de la sheet, detents, gestes, comportement modal et événements
`cap-sheet-trigger`	Actions déclaratives : present, dismiss, toggle et step
`cap-sheet-portal`	Body portal optionnel pour l'empilement des overlays
`cap-sheet-view`	Conteneur viewport fixe avec padding safe-area et clavier
`cap-sheet-backdrop`	Backdrop synchronisé avec la progression
`cap-sheet-content`	Surface de la sheet accessible
`cap-sheet-bleeding-background`	Extension d'arrière-plan pour les sheets à bords arrondis
`cap-sheet-handle`	Poignée de detent déplaçable et accessible au clavier
`cap-sheet-title`	Titre accessible
`cap-sheet-description`	Description accessible
`cap-sheet-special-wrapper`	Hook de composition pour sheets, cards et lightboxes détachés
`cap-sheet-stack`	Groupement de sheets empilés
`cap-sheet-outlet`	Sortie de progression pour effets de profondeur, parallaxe et de page
`cap-scroll`	Aide à la progression du scroll
`cap-fixed`	Aide pour les couches fixes
`cap-island`	Contenu lié en îlot flottant
`cap-external-overlay`	Contenu en overlay géré hors de l'arbre des sheets

Options principales

Option	Attribut	Par défaut	Description
`contentPlacement`	`content-placement`	`bottom`	`top`, `bottom`, `left`, `right`, ou `center`
`detents`	`detents`	aucune	Longueurs CSS séparées par des espaces, telles que `18em 32em`
`safeArea`	`safe-area`	`auto`	Bords de la safe-area protégés
`swipe`	`swipe`	`true`	Activer les gestes de pointeur, tactile, trackpad et molette
`swipeDismissal`	`swipe-dismissal`	`true`	Autoriser les gestes pour revenir au detent `0`
`inertOutside`	`inert-outside`	`true`	Empêcher l'interaction derrière les modal sheets
`focusTrap`	`focus-trap`	`true`	Maintenir le focus du clavier dans la sheet
`closeOnOutsideClick`	`close-on-outside-click`	`true`	Fermer en cliquant sur l'arrière-plan ou la vue
`closeOnEscape`	`close-on-escape`	`true`	Fermer en appuyant sur Échap
`nativeFocusScrollPrevention`	`native-focus-scroll-prevention`	`true`	Garder les champs de saisie visibles au-dessus du clavier
`themeColorDimming`	`theme-color-dimming`	`auto`	Assombrir la couleur du thème WebView pendant le modal

Points d'entrée disponibles

@capgo/capacitor-sheets
@capgo/capacitor-sheets/react
@capgo/capacitor-sheets/vue
@capgo/capacitor-sheets/angular
@capgo/capacitor-sheets/svelte
@capgo/capacitor-sheets/solid

Continuer après le Getting Started

Si vous utilisez Premiers pas pour planifier le travail sur les plugins natifs, connectez-l’à Répertoire des plugins Capgo pour le workflow produit dans le répertoire des plugins Capgo, Plugins Capacitor par Capgo pour les détails d'implémentation dans les 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 Ionic Enterprise Plugin Alternatives, et Capgo Native Build pour le workflow produit dans Capgo Native Builds.