Per iniziare

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo 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.

Installazione

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

Installa il pacchetto
Finestra del terminale
```
bun add @capgo/capacitor-sheets
```
Registra i web component
```
import '@capgo/capacitor-sheets';
```

Aggiungi l'impostazione viewport per le safe areas

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

Renderizza uno 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;
}

Errori comuni

Registra i componenti: importa @capgo/capacitor-sheets once at bootstrap or elements will not upgrade.
Adattamento viewport: mancante viewport-fit=cover rompe il padding della safe area sui telefoni con notch.
Tastiera: attiva la prevenzione dello scroll al focus documentata quando gli input si trovano all'interno di bottom sheet.

Safe Areas di Capacitor

Le safe area sono abilitate di default tramite safe-area="auto". La viewport del sheet legge sia i valori dell'ambiente browser sia le variabili di fallback 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)

Scegli i bordi protetti per ogni sheet:

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

Per le app con barre di stato o di sistema sovrapposte, mantieni i plugin nativi responsabili dell'esposizione dei valori di inset corretti:

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 gestione della tastiera è controllata da native-focus-scroll-prevention, che di default è impostato su true. Disabilitalo solo se la tua app gestisce già l'keyboard avoidance:

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

Controllo imperativo

Tutti gli helper del framework configurano lo stesso custom element sottostante. Puoi anche controllare uno sheet direttamente:

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

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

Ascolta gli eventi per gestire lo stato controllato, l'analytics o animazioni coordinate:

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

Importazione da @capgo/capacitor-sheets/react registra anche i typings JSX per i custom elements. Se TypeScript segnala ancora tag sconosciuti, aggiungi un file di dichiarazione nel tuo source tree:

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

Componenti

Elemento	Scopo
`cap-sheet`	Stato dello sheet, detents, gesture, comportamento modale ed eventi
`cap-sheet-trigger`	Azioni dichiarative per present, dismiss, toggle e step
`cap-sheet-portal`	Body portal opzionale per il layering degli overlay
`cap-sheet-view`	Host con viewport fisso e padding per safe-area e tastiera
`cap-sheet-backdrop`	Backdrop sincronizzata con il progresso
`cap-sheet-content`	Superficie del sheet accessibile
`cap-sheet-bleeding-background`	Estensione dello sfondo per i bordi arrotondati dei sheet
`cap-sheet-handle`	Maniglia detent trascinabile e accessibile da tastiera
`cap-sheet-title`	Titolo accessibile
`cap-sheet-description`	Descrizione accessibile
`cap-sheet-special-wrapper`	Hook di composizione per sheet staccati, card e lightbox
`cap-sheet-stack`	Raggruppamento di sheet impilati
`cap-sheet-outlet`	Outlet di progresso per profondità, parallasse ed effetti di pagina
`cap-scroll`	Helper per il progresso dello scroll
`cap-fixed`	Helper per il layer fisso
`cap-island`	Contenuti correlati alla floating island
`cap-external-overlay`	Contenuti overlay gestiti fuori dall'albero dello sheet

Opzioni principali

Opzione	Attributo	Predefinito	Descrizione
`contentPlacement`	`content-placement`	`bottom`	`top`, `bottom`, `left`, `right`, o `center`
`detents`	`detents`	nessuno	Lunghezze CSS separate da spazi come `18em 32em`
`safeArea`	`safe-area`	`auto`	Bordi protetti della safe area
`swipe`	`swipe`	`true`	Abilita gesti con puntatore, touch, trackpad e rotella
`swipeDismissal`	`swipe-dismissal`	`true`	Consenti i gesti per chiudere al detent `0`
`inertOutside`	`inert-outside`	`true`	Impedisci l'interazione dietro i fogli modali
`focusTrap`	`focus-trap`	`true`	Mantieni il focus della tastiera all'interno del sheet
`closeOnOutsideClick`	`close-on-outside-click`	`true`	Chiudi al clic sullo sfondo o sulla vista
`closeOnEscape`	`close-on-escape`	`true`	Chiudi premendo Escape
`nativeFocusScrollPrevention`	`native-focus-scroll-prevention`	`true`	Mantieni i campi in focus visibili sopra la tastiera
`themeColorDimming`	`theme-color-dimming`	`auto`	Dim the WebView theme color while modal

Entrypoint disponibili

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

Continua da Getting Started

Se stai usando Per iniziare 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.