Getting Started

1. Instale el paquete

   npm install @capgo/capacitor-transitions

2. Registra los componentes web

   import '@capgo/capacitor-transitions';

3. Envuelve páginas enrutadas

   <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. Establece la dirección antes de que tu router cambie de ruta

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

Nota

No hay un paso de sincronización nativa para este paquete. Se ejecuta en el capa web de tu aplicación Capacitor.

Configuración de 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

Importando desde @capgo/capacitor-transitions/react incluye tipificaciones JSX para cap-router-outlet, cap-page, cap-header, cap-content, y cap-footer. En la mayoría de los proyectos de React, esa importación hace que los elementos personalizados sean válidos en TSX automáticamente.

Si TypeScript aún informa de errores Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements', agrega un archivo de declaración de proyecto:

src/capgo-transiciones.d.ts

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

Para Vite, Create React App y la mayoría de las aplicaciones de webpack de React, colocar ese archivo dentro de src/ es suficiente. Para Next.js, colócalo en src/ o en la raíz del proyecto y asegúrese de tsconfig.json incluya eso:

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

Para configuraciones de TypeScript o webpack personalizadas que utilicen una carpeta separada types/ incluya esa carpeta en su lugar:

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

Swipe Back

Habilite o deshabilite el gesto de borde de iOS desde la marca de posición:

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

O desde JavaScript:

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

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

auto Habilita el gesto solo cuando Capacitor informa sobre un tiempo de ejecución nativo de iOS. Durante el gesto, la transición de página sigue el dedo. Cuando el usuario suelta, la transición se completa y solicita al historial del navegador que regrese, o cancela y restaura la página actual.

Para evitar que un elemento inicie el gesto, agregue data-swipe-gesture-ignore:

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

Con navegación nativa

Usar @capgo/capacitor-transitions con @capgo/native-navigation cuando la navegación nativa debe controlar las barras superior e inferior mientras el contenido web mantiene la movilidad de página de Ionic.

1. Instale y sincronice el paquete de navegación nativa:

   npm install @capgo/native-navigation
   npx cap sync

2. Configurar el navegador nativo:

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

3. Mantén la salida de transición web responsable solo para páginas:

   <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. Conduce ambos sistemas desde los mismos eventos de 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' },
     });
   }

No renderice la barra superior nativa de nuevo como una barra <cap-header>. Deje @capgo/native-navigation mantenga la barra nativa y utilice @capgo/capacitor-transitions para el contenido de página WebView debajo de ella.

Componentes

<cap-router-outlet>

Atributo	Tipo	Valor por defecto	Descripción
platform	'ios' | 'android' | 'auto'	'auto'	Estilo de animación
duration	number	Por defecto del plataforma	Duración de la animación en milisegundos
keep-in-dom	boolean	true	Mantener páginas inactivas en el DOM
max-cached	number	10	Número máximo de páginas en caché
swipe-gesture	boolean | 'auto'	'auto'	Habilitar, deshabilitar o detectar nativamente la gestión de bordes de iOS

Métodos:

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

<cap-page>

Envuelve una página y emite eventos de ciclo de vida:

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

<cap-content>

Atributo	Tipo	Valor por defecto	Descripción
fullscreen	boolean	false	Hacer que el contenido se desplace detrás del encabezado
scroll-x	boolean	true	Habilitar el desplazamiento horizontal
scroll-y	boolean	true	Habilitar el desplazamiento vertical

Ayudas de marco

El framework expone los mismos ayudantes de núcleo:

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

Entradas disponibles:

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

Sigue adelante desde Getting Started

Si estás utilizando Getting Started para planificar la migración y las operaciones empresariales, conecta con Usando @capgo/capacitor-transiciones para la capacidad nativa en Usando @capgo/capacitor-transiciones, Capgo Empresas para el flujo de trabajo del producto en Capgo Empresas, Alternativas de Ionic Enterprise Plugin para el flujo de trabajo del producto en Alternativas de Ionic Enterprise Plugin Capgo Alternativas para el flujo de trabajo del producto en Capgo Alternativas, y Capgo Consultoría para el flujo de trabajo del producto en Capgo Consultoría.