Transitions Plugin Capacitor

Utiliser @capgo/capacitor-transitions

@capgo/capacitor-transitions ajoute des transitions de route de style Ionic aux applications Capacitor sans adopter l'UI d'Ionic. Il s'exécute dans la couche web, conserve votre routeur actuel et peut activer automatiquement le geste de retour par balayage depuis le bord (edge swipe) uniquement dans l'app iOS native Capacitor.

Installer

npm install @capgo/capacitor-transitions

Il n'y a pas d'étape de synchronisation native, car le package n'ajoute aucun plugin natif code.

Enregistrer les éléments

import '@capgo/capacitor-transitions';

Envelopper vos pages

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

Le connecter à un routeur

Définir la direction de la transition avant votre mise à jour de route habituelle :

import { setDirection } from '@capgo/capacitor-transitions/react';

setDirection('forward');
router.push('/message/42');

setDirection('back');
router.back();

Exemple 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}>{/* routes */}</cap-router-outlet>;
}

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

  useEffect(() => {
    if (!pageRef.current) return;
    return setupPage(pageRef.current);
  }, []);

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

Le sous-chemin React inclut les types JSX pour les éléments personnalisés. Si TypeScript signale encore que cap-router-outlet n'existe pas sur JSX.IntrinsicElements, ajoutez ce fichier :

// src/capgo-transitions.d.ts
import '@capgo/capacitor-transitions/react';

Pour Vite, Create React App et la plupart des apps React avec webpack, conservez ce fichier sous src/ est suffisant. Pour Next.js ou les configurations TypeScript personnalisées, assurez-vous qu'il est inclus par tsconfig.json:

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

Activer le swipe back

Utiliser swipe-gesture="auto" pour n'activer le geste que lorsque Capacitor signale un runtime iOS natif :

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

Vous pouvez également le forcer depuis JavaScript :

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

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

Le geste suit le doigt pendant la transition, puis se termine ou s'annule lors du relâchement. Ajoutez data-swipe-gesture-ignore sur les boutons, sliders ou drawers qui ne doivent pas déclencher le geste de bordure.

Utiliser avec la navigation native

Installer @capgo/native-navigation lorsque la couche native doit gérer la navbar ou la tabbar :

npm install @capgo/native-navigation
npx cap sync

Configurez le chrome natif, puis concentrez les transitions sur les pages WebView :

import { NativeNavigation } from '@capgo/native-navigation';
import { setDirection } from '@capgo/capacitor-transitions/react';
import { router } from './router';

await NativeNavigation.configure({
  contentInsetMode: 'css',
});

await NativeNavigation.setNavbar({
  title: 'Inbox',
  backButton: { visible: false },
});

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

Utiliser cap-content pour le corps de page animé et les variables CSS natives pour les insets :

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

Ne dupliquez pas la barre de navigation native en tant qu’en-tête web défilant. @capgo/native-navigation conserve la barre native ; @capgo/capacitor-transitions anime le contenu de la page en dessous.

Référence complète

• GitHub : https://github.com/Cap-go/capacitor-transitions/
• Docs : /docs/plugins/transitions/

Continuer depuis Utilisation de @capgo/capacitor-transitions

Si vous utilisez Utiliser @capgo/capacitor-transitions pour planifier le comportement des médias et de l'interface natifs, connectez-l’à @capgo/capacitor-transitions pour le détail d’implémentation dans @capgo/capacitor-transitions, Prise en main pour les détails d'implémentation dans Getting Started Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour les détails d'implémentation dans @capgo/capacitor-live-activities, et Utiliser @capgo/capacitor-video-player pour la fonctionnalité native dans Utilisation de @capgo/capacitor-video-player.