Prise en main

Copiez un prompt de configuration incluant 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 une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Ajouter le paramètre viewport pour les safe areas

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

Afficher une 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: importez @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 documentée du défilement au focus lorsque des champs se trouvent dans des bottom sheets.

Capacitor Zones de sécurité

Les safe areas sont activées par défaut via safe-area="auto". Le viewport de la sheet lit à la fois les valeurs d’environnement du navigateur et 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 pour chaque 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 applications avec des barres de statut superposées ou des barres système, conservez les plugins natifs chargés d’exposer les 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, dont la valeur par défaut est true. Désactivez-l’uniquement si votre application gère déjà l’évitement du clavier :

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

Contrôl’impératif

Tous les helpers de framework configurent le même élément personnalisé sous-jacent. Vous pouvez aussi piloter un 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 un état contrôlé, les analytics ou une animation coordonnée :

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>
  );
}

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

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	Objectif
`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`	Portail body optionnel pour la superposition des overlays
`cap-sheet-view`	Conteneur viewport fixe avec safe-area et padding clavier
`cap-sheet-backdrop`	Arrière-plan synchronisé avec la progression
`cap-sheet-content`	Surface de 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 les sheets détachées, cartes et lightboxes
`cap-sheet-stack`	Regroupement de sheets empilées
`cap-sheet-outlet`	Sortie de progression pour les effets de profondeur, de parallaxe et de page
`cap-scroll`	Helper de progression du scroll
`cap-fixed`	Helper de couche fixe
`cap-island`	Contenu associé à l'île flottante
`cap-external-overlay`	Contenu overlay géré hors de l'arborescence de la sheet

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, comme `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 de fermeture vers un detent `0`
`inertOutside`	`inert-outside`	`true`	Empêcher l'interaction derrière les feuilles modales
`focusTrap`	`focus-trap`	`true`	Maintenir le focus clavier dans la feuille
`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 ayant le focus visibles au-dessus du clavier
`themeColorDimming`	`theme-color-dimming`	`auto`	Assombrir la couleur du thème WebView en mode 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 depuis Getting Started

Si vous utilisez Prise en main 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.