Per iniziare

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-transitions` plugin in my project.

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

1. Installa il pacchetto

   npm install @capgo/capacitor-transitions

2. Registra i web component

   import '@capgo/capacitor-transitions';

3. Avvolgi le pagine con routing

   <cap-router-outlet platform="auto" swipe-gesture="auto">
     <cap-page>
       <cap-header slot="header">
         <h1>Inbox</h1>
       </cap-header>
   
       <cap-content slot="content">
         <button>Open message</button>
       </cap-content>
   
       <cap-footer slot="footer">
         <nav>Tabs</nav>
       </cap-footer>
     </cap-page>
   </cap-router-outlet>

4. Imposta la direzione prima del cambio di rotta del router

   import { setDirection } from '@capgo/capacitor-transitions/react';
   
   setDirection('forward');
   router.push('/message/42');
   
   setDirection('back');
   router.back();

Nota

Non esiste un passaggio di sincronizzazione nativa per questo pacchetto. Viene eseguito nel web layer della tua app Capacitor.

React Setup

import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
import '@capgo/capacitor-transitions';

initTransitions({ platform: 'auto' });

export function AppShell() {
  const outletRef = useRef<HTMLElement>(null);

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

    setupRouterOutlet(outletRef.current, {
      platform: 'auto',
      swipeGesture: 'auto',
    });
  }, []);

  return (
    <cap-router-outlet ref={outletRef}>
      {/* Your router renders cap-page children here. */}
    </cap-router-outlet>
  );
}

export function InboxPage() {
  const navigate = useNavigate();
  const pageRef = useRef<HTMLElement>(null);

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

    return setupPage(pageRef.current, {
      onDidEnter: () => console.log('Inbox visible'),
    });
  }, []);

  return (
    <cap-page ref={pageRef}>
      <cap-header slot="header">
        <h1>Inbox</h1>
      </cap-header>

      <cap-content slot="content">
        <button
          onClick={() => {
            setDirection('forward');
            navigate('/message/42');
          }}
        >
          Open message
        </button>
      </cap-content>
    </cap-page>
  );
}

React JSX TypeScript

Importazione da @capgo/capacitor-transitions/react include le tipizzazioni JSX per cap-router-outlet, cap-page, cap-header, cap-content, e cap-footer. Nella maggior parte dei progetti React, quell'import rende automaticamente validi i custom elements in TSX.

Se TypeScript segnala ancora Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements', aggiungi un file di dichiarazione del progetto:

src/capgo-transitions.d.ts

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

Per Vite, Create React App e la maggior parte delle app React con webpack, inserire quel file in src/ è sufficiente. Per Next.js, mettilo in src/ o nella root del progetto e assicurati che tsconfig.json lo includa:

{
  "include": ["src", "src/capgo-transitions.d.ts"]
}

Per configurazioni personalizzate di TypeScript o webpack che usano una types/ cartella separata, includi invece quella cartella:

{
  "include": ["src", "types"]
}

Swipe Back

Abilita o disabilita l'edge gesture di iOS dal markup:

<cap-router-outlet swipe-gesture="auto"></cap-router-outlet>
<cap-router-outlet swipe-gesture="true"></cap-router-outlet>
<cap-router-outlet swipe-gesture="false"></cap-router-outlet>

Oppure da JavaScript:

const outlet = document.querySelector('cap-router-outlet');

outlet?.setSwipeGesture('auto');
outlet?.setSwipeGesture(true);
outlet?.setSwipeGesture(false);

auto abilita il gesto solo quando Capacitor rileva un runtime nativo iOS. Durante il gesto, la transizione della pagina segue il dito. Al rilascio, la transizione si completa tornando indietro nella cronologia del browser, oppure viene annullata ripristinando la pagina corrente.

Per impedire a un elemento di avviare il gesto, aggiungi data-swipe-gesture-ignore:

<button data-swipe-gesture-ignore>Open drawer</button>

Con la Native Navigation

Usa @capgo/capacitor-transitions con @capgo/native-navigation quando le barre superiore e inferiore devono essere native, mentre il contenuto web mantiene il movimento delle pagine in stile Ionic.

1. Installa e sincronizza il pacchetto native navigation:

   npm install @capgo/native-navigation
   npx cap sync

2. Configura il chrome nativo:

   import { NativeNavigation } from '@capgo/native-navigation';
   
   await NativeNavigation.configure({
     contentInsetMode: 'css',
   });
   
   await NativeNavigation.setNavbar({
     title: 'Inbox',
     backButton: { visible: false },
   });

3. Lascia che l'outlet della transizione web gestisca solo le pagine:

   <cap-router-outlet platform="auto" swipe-gesture="auto">
     <cap-page>
       <cap-content slot="content" fullscreen>
         <main class="native-page">Inbox content</main>
       </cap-content>
     </cap-page>
   </cap-router-outlet>

   .native-page {
     padding-top: var(--cap-native-navigation-top);
     padding-bottom: var(--cap-native-navigation-bottom);
   }

4. Gestisci entrambi i sistemi con gli stessi eventi del router:

   import { NativeNavigation } from '@capgo/native-navigation';
   import { setDirection } from '@capgo/capacitor-transitions/react';
   import { router } from './router';
   
   await NativeNavigation.addListener('navbarBack', () => {
     setDirection('back');
     router.back();
   });
   
   async function openMessage(id: string) {
     setDirection('forward');
     router.push(`/message/${id}`);
   
     await NativeNavigation.setNavbar({
       title: 'Message',
       backButton: { visible: true, title: 'Inbox' },
     });
   }

Non renderizzare nuovamente la top bar nativa come elemento in movimento <cap-header>. Lascia @capgo/native-navigation che la barra rimanga nativa e usa @capgo/capacitor-transitions per il contenuto della pagina WebView sottostante.

Componenti

<cap-router-outlet>

Attributo	Tipo	Predefinito	Descrizione
platform	'ios' | 'android' | 'auto'	'auto'	Stile dell'animazione
duration	number	Predefinito piattaforma	Durata animazione in millisecondi
keep-in-dom	boolean	true	Mantieni le pagine inattive nel DOM
max-cached	number	10	Max pagine in cache
swipe-gesture	boolean | 'auto'	'auto'	Abilita, disabilita o rileva nativamente l'edge gesture su iOS

Metodi:

• push(element, config?)
• pop(config?)
• setRoot(element, config?)
• setSwipeGesture(true | false | 'auto')

<cap-page>

Avvolge una pagina ed emette eventi di lifecycle:

• cap-will-enter
• cap-did-enter
• cap-will-leave
• cap-did-leave

<cap-content>

Attributo	Tipo	Predefinito	Descrizione
fullscreen	boolean	false	Lascia scorrere il contenuto dietro l'header
scroll-x	boolean	true	Abilita lo scrolling orizzontale
scroll-y	boolean	true	Abilita lo scrolling verticale

Helper del Framework

Gli entrypoint del framework espongono gli stessi helper core:

import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });
setDirection('forward');
setupRouterOutlet(element, { platform: 'auto', swipeGesture: 'auto' });
setupPage(element, { onWillEnter, onDidEnter, onWillLeave, onDidLeave });

Entrypoint disponibili:

• @capgo/capacitor-transitions/react
• @capgo/capacitor-transitions/vue
• @capgo/capacitor-transitions/angular
• @capgo/capacitor-transitions/svelte
• @capgo/capacitor-transitions/solid

Continua da Getting Started

Se stai usando Per iniziare per pianificare la migrazione e le operazioni enterprise, collegalo a Uso di @capgo/capacitor-transitions per la funzionalità nativa in Utilizzo di @capgo/capacitor-transitions, Capgo Enterprise per il workflow del prodotto in Capgo Enterprise, Alternative ai plugin Ionic Enterprise per il workflow del prodotto nelle alternative ai plugin Ionic Enterprise, Alternative a Capgo per il workflow di prodotto in Capgo Alternatives, e Consulenza Capgo per il workflow di prodotto in Capgo Consulting.