Prise en main

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-transitions` 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 :

1. Installer le package

   npm install @capgo/capacitor-transitions

2. Enregistrer les web components

   import '@capgo/capacitor-transitions';

3. Encapsuler les pages routées

   <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. Définir la direction avant le changement de route du router

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

Remarque

Ce package ne nécessite pas d'étape de synchronisation native. Il s'exécute dans la couche web de votre application Capacitor.

Configuration React

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

Importation depuis @capgo/capacitor-transitions/react inclut les typages JSX pour cap-router-outlet, cap-page, cap-header, cap-content, et cap-footer. Dans la plupart des projets React, cet import rend automatiquement les éléments personnalisés valides en TSX.

Si TypeScript signale toujours Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements', ajoutez un fichier de déclaration de projet :

src/capgo-transitions.d.ts

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

Pour Vite, Create React App et la plupart des apps React utilisant webpack, placer ce fichier dans src/ suffit. Pour Next.js, placez-le dans src/ ou à la racine du projet et assurez-vous que tsconfig.json l'inclut :

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

Pour les configurations TypeScript ou webpack personnalisées utilisant un types/ dossier séparé, incluez ce dossier à la place :

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

Swipe Back

Activer ou désactiver le geste edge sur iOS via le 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>

Ou depuis JavaScript :

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

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

auto active le geste uniquement lorsque Capacitor indique un runtime iOS natif. Pendant le geste, la transition de page suit le doigt. Lorsque l'utilisateur relâche, la transition soit se termine en demandant au navigateur de revenir en arrière, soit s'annule et restaure la page actuelle.

Pour empêcher un élément de déclencher le geste, ajoutez data-swipe-gesture-ignore:

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

Avec la navigation native

Utiliser @capgo/capacitor-transitions par @capgo/native-navigation lorsque le natif doit gérer les barres haute et basse pendant que le contenu web conserve les mouvements de page de style Ionic.

1. Installez et synchronisez le package de navigation native :

   npm install @capgo/native-navigation
   npx cap sync

2. Configurez le chrome natif :

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

3. Gardez le web transition outlet en charge des pages uniquement :

   <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. Pilotez les deux systèmes à partir des mêmes événements du 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' },
     });
   }

Ne réaffichez pas la barre supérieure native comme un élément en mouvement <cap-header>. Laissez @capgo/native-navigation la barre native et utilisez @capgo/capacitor-transitions pour le contenu de la page WebView en dessous.

Composants

<cap-router-outlet>

Attribut	Type	Par défaut	Description
platform	'ios' | 'android' | 'auto'	'auto'	Style d'animation
duration	number	Par défaut sur la plateforme	Durée de l'animation en millisecondes
keep-in-dom	boolean	true	Garder les pages inactives dans le DOM
max-cached	number	10	Nombre maximum de pages en cache
swipe-gesture	boolean | 'auto'	'auto'	Activer, désactiver ou détecter nativement le geste edge sur iOS

Méthodes :

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

<cap-page>

Encapsule une page et émet des événements de cycle de vie :

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

<cap-content>

Attribut	Type	Par défaut	Description
fullscreen	boolean	false	Laisser le contenu défiler derrière le header
scroll-x	boolean	true	Activer le défilement horizontal
scroll-y	boolean	true	Activer le défilement vertical

Helpers du framework

Les points d'entrée du framework exposent les mêmes helpers de base :

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

Points d'entrée disponibles :

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

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier la migration et les opérations d'entreprise, connectez-l’à Utiliser @capgo/capacitor-transitions pour la capacité native dans Using @capgo/capacitor-transitions, Capgo Enterprise pour le workflow produit dans Capgo Enterprise, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, Alternatives Capgo pour le workflow produit dans les alternatives Capgo, et Conseil Capgo pour le workflow produit chez Capgo Consulting.