Iniziare

Installazione

Puoi utilizzare la nostra configurazione assistita dall'IA per installare il plugin. Aggiungi le Capgo abilità al tuo strumento di AI utilizzando il seguente comando:

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

Usa poi 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 l'installazione manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito:

1. Installa il pacchetto

   npm install @capgo/capacitor-sheets

2. Registra i componenti web

   import '@capgo/capacitor-sheets';

3. Aggiungi la impostazione del viewport per aree sicure

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

4. Rendi un foglio

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

Nota

Non esiste un passaggio di registrazione del plugin nativo. Esegui npx cap sync solo come parte del tuo normale flusso di lavoro Capacitor quando hai bisogno di sincronizzare gli asset web o le modifiche del progetto nativo.

Capacitor Zone sicure

Le zone sicure sono abilitate per impostazione predefinita attraverso safe-area="auto". La finestra di visualizzazione della vista legge sia i valori dell'ambiente del browser che 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 le aree protette per la scheda:

<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 sovrapposte o barre di sistema, lascia che i plugin nativi siano responsabili dell'esposizione dei valori di insetto 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;

Il gestione del tastiera è controllata da native-focus-scroll-prevention, che prevede come default true. Disabilitalo solo quando la tua app già gestisce l'evitamento della tastiera:

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

Sezione intitolata “Controllo Imperativo”

Ascolta gli eventi per lo stato controllato, l'analisi o l'animazione coordinata:

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

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

Copia negli appunti

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 le tipizzazioni JSX per gli elementi personalizzati. Se TypeScript segnala ancora tag sconosciuti, aggiungi un file di dichiarazione all'interno del tuo tree di origine:

src/capgo-sheets.d.ts

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 foglio, detent, gesti, comportamento modale e eventi
cap-sheet-trigger	Azioni presentative dichiarative, annulla, alternare e passaggi
cap-sheet-portal	Portale corpo facoltativo per sovrapposizione layering
cap-sheet-view	Host viewport fissato con padding di area sicura e tastiera
cap-sheet-backdrop	Sfondo di retroterra sincronizzato con progresso
cap-sheet-content	Superficie foglio accessibile
cap-sheet-bleeding-background	Estensione di sfondo per fogli con bordi arrotondati
cap-sheet-handle	Maniglia detent trascinabile e accessibile alla tastiera
cap-sheet-title	Titolo accessibile
cap-sheet-description	Descrizione accessibile
cap-sheet-special-wrapper	Hook di composizione per fogli, carte e lightbox separati
cap-sheet-stack	Gruppo di fogli sovrapposti
cap-sheet-outlet	Progress outlet per profondità, parallassi e effetti di pagina
cap-scroll	Aiuto per il progresso della scroll
cap-fixed	Aiuto per layer fissi
cap-island	Contenuto dell'isola galleggiante correlato
cap-external-overlay	Contenuto sovrapposto gestito al di fuori dell'albero della sheet

Opzioni principali

Opzione	Attributo	Predefinito	Descrizione
contentPlacement	content-placement	bottom	top, bottom, left, righto center
detents	detents	nessuna	Dimensioni CSS separate da spazio, come 18em 32em
safeArea	safe-area	auto	Bordi di area sicura protetti
swipe	swipe	true	Abilita gesti del puntatore, touch, trackpad e ruote
swipeDismissal	swipe-dismissal	true	Consenti ai gesti di disporre fino al detent 0
inertOutside	inert-outside	true	Preveni l'interazione dietro le schede modal
focusTrap	focus-trap	true	Mantieni il focus del tastiera all'interno della scheda
closeOnOutsideClick	close-on-outside-click	true	Dismetti quando si clicca sullo sfondo o sulla vista
closeOnEscape	close-on-escape	true	Dismetti quando si preme il tasto Esc
nativeFocusScrollPrevention	native-focus-scroll-prevention	true	Mantieni visibili gli input focalizzati sopra la tastiera
themeColorDimming	theme-color-dimming	auto	Adeguamento del colore del tema WebView mentre è in modalità

Entrypoints 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 Guida introduttiva

Se stai utilizzando Guida introduttiva per pianificare il lavoro di plugin nativo, connettilo con Capgo Directory dei plugin per il flusso di lavoro del prodotto in Capgo Directory dei plugin, Capacitor Plugin da Capgo per i dettagli di implementazione in Capacitor Plugin da Capgo, Aggiungere o Aggiornare Plugin per i dettagli di implementazione in Aggiungere o Aggiornare Plugin, Alternative plugin Ionic Enterprise per per il flusso di lavoro del plugin Ionic Enterprise e Capgo Costruzioni native per il flusso di lavoro di Capgo Costruzioni native.