Getting Started

Instalación

Puedes utilizar nuestra configuración asistida por IA para instalar el plugin. Agrega las Capgo habilidades a tu herramienta de IA utilizando el siguiente comando:

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

Luego utiliza el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-navigation` plugin in my project.

Si prefieres la configuración manual, instala el plugin ejecutando los siguientes comandos y sigue las instrucciones específicas de la plataforma a continuación:

1. Instale el paquete

   npm i @capgo/capacitor-native-navigation

2. Sincronice proyectos nativos

   npx cap sync

3. Configure el navegador nativo

   import { NativeNavigation } from '@capgo/capacitor-native-navigation';
   
   await NativeNavigation.configure({
     contentInsetMode: 'css',
     animationDuration: 360,
     colors: {
       tint: '#0f172a',
       inactiveTint: '#64748b',
     },
   });

4. Vuelva a dibujar el menú de navegación nativo

   await NativeNavigation.setNavbar({
     title: 'Home',
     subtitle: 'Native chrome',
     transparent: true,
     backButton: { visible: false },
     rightItems: [
       {
         id: 'compose',
         title: 'Compose',
         icon: {
           svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z"/></svg>',
         },
       },
     ],
   });

5. Vuelva a dibujar el menú de pestañas nativo

   await NativeNavigation.setTabbar({
     selectedId: 'home',
     labelVisibilityMode: 'selected',
     icons: true,
     colors: {
       dynamic: true,
       tint: '#0f172a',
       inactiveTint: '#64748b',
     },
     tabs: [
       {
         id: 'home',
         title: 'Home',
         icon: {
           svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 10.5 12 3l9 7.5"/><path d="M5 10v10h14V10"/></svg>',
         },
       },
       {
         id: 'settings',
         title: 'Settings',
         badge: '2',
         icon: {
           svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="3"/><path d="M12 2v3M12 19v3M2 12h3M19 12h3"/></svg>',
         },
       },
     ],
   });

6. Manipular eventos de intención nativa

   await NativeNavigation.addListener('navbarBack', () => {
     router.back();
   });
   
   await NativeNavigation.addListener('navbarItemTap', ({ id }) => {
     if (id === 'compose') router.push('/compose');
   });
   
   await NativeNavigation.addListener('tabSelect', ({ id }) => {
     router.push(`/${id}`);
   });

Flujo de transición

Las transiciones nativas son una transacción alrededor de su cambio de ruta JavaScript normal:

const transition = await NativeNavigation.beginTransition({
  direction: 'forward',
});

router.push('/detail');
await router.ready?.();

await NativeNavigation.setNavbar({
  title: 'Detail',
  backButton: { visible: true, title: 'Back' },
});

await NativeNavigation.finishTransition({
  id: transition.id,
  direction: 'forward',
});

Transición de zoom

Utilice los ayudantes de zoom para flujos de tarjeta a detalles o previsualización de medios. Pase el elemento pulsado antes de que cambie el contenido de su router, luego termine después de que la página de detalles esté lista.

import { beginZoomTransition, finishZoomTransition } from '@capgo/capacitor-native-navigation';

const card = document.querySelector('[data-message-card]');
if (card) {
  const transition = await beginZoomTransition(card, { cornerRadius: 18 });

  router.push('/message/42');
  await router.ready?.();

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

  await finishZoomTransition(undefined, {
    id: transition.id,
    cornerRadius: 18,
  });
}

Utilice con @capgo/capacitor-transiciones

Use la navegación nativa para el navbar nativo, tabbar, insets de área segura y eventos de intención nativa. Use @capgo/capacitor-transitions para la pila de páginas de WebView debajo del chrome nativo.

npm install @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npx cap sync

Inicialice ambos paquetes una vez:

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

initTransitions({ platform: 'auto' });

const outlet = document.querySelector('cap-router-outlet');
if (outlet) {
  setupRouterOutlet(outlet, { platform: 'auto', swipeGesture: 'auto' });
}

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

Mantenga cap-router-outlet enfocado en páginas, no barras web duplicadas:

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

Conduzca ambos paquetes desde las mismas acciones de router:

async function openMessage(id: string) {
  setDirection('forward');
  await router.push(`/messages/${id}`);
  await NativeNavigation.setNavbar({
    title: 'Message',
    backButton: { visible: true, title: 'Inbox' },
  });
}

await NativeNavigation.addListener('navbarBack', () => {
  setDirection('back');
  router.back();
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  setDirection('root');
  router.push(`/${id}`);
});

Elige un capa de animación por cambio de ruta. Deje @capgo/capacitor-transitions animar empujes de página normales, y utilice solo los ayudantes de zoom de Native Navigation para rutas de elementos compartidos o zoom.

insets de CSS

Con contentInsetMode: 'css', el plugin escribe dimensiones de barra nativa a document.documentElement.

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

Variables disponibles:

• --cap-native-navigation-top
• --cap-native-navigation-right
• --cap-native-navigation-bottom
• --cap-native-navigation-left
• --cap-native-navbar-height
• --cap-native-tabbar-height

Descripciones de iconos

Los iconos deben ser serializables porque la interfaz de usuario nativa los renderiza. Puede utilizar SVG de plataforma cruzada, SVG específico de plataforma, SF Symbols, imágenes de iOS empaquetadas, recursos de Android drawable o imágenes de Android empaquetadas.

const icon = {
  svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
  width: 24,
  height: 24,
  template: true,
  src: 'fallback_asset_name',
  ios: {
    svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
    sfSymbol: 'house.fill',
    image: 'BundledAssetName',
  },
  android: {
    svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
    resource: 'ic_menu_view',
    image: 'bundled_drawable_name',
  },
};

SVG en línea admite el conjunto de iconos enfocado utilizado por conjuntos de iconos comunes como Lucide y Feather: path, line, polyline, polygon, circley rectComponentes web opcionales

La paquetería puede registrar elementos personalizados para un conjunto de configuración declarativa independiente del marco:

Copiar a portapapeles

import { defineNativeNavigationElements } from '@capgo/capacitor-native-navigation';

defineNativeNavigationElements();

<cap-native-navigation-provider enabled="true" content-inset-mode="css"></cap-native-navigation-provider>

<cap-native-navbar
  title="Home"
  transparent
  right-items='[{"id":"compose","title":"Compose","icon":{"svg":"<svg viewBox=\"0 0 24 24\"><path d=\"M12 20h9\"/></svg>"}}]'
></cap-native-navbar>

<cap-native-tabbar
  selected-id="home"
  tabs='[{"id":"home","title":"Home","icon":{"ios":{"sfSymbol":"house.fill"}}}]'
></cap-native-tabbar>

Observaciones del sistema

The web components are optional. React, Vue, Angular, Svelte, Solid, and vanilla apps can all use the imperative API directly.

Los componentes web son opcionales. Las aplicaciones de React, Vue, Angular, Svelte, Solid y vanilla pueden utilizar directamente el __CAPGO_KEEP_0__ imperativo.

• iOS renderiza UINavigationBar y UITabBar; iOS 26+ utiliza el comportamiento de la barra de vidrio líquido del sistema.
• Android renderiza una barra de herramientas de AppCompat y navegación inferior de Material.
• La versión web de fallback no dibuja barras nativas. Refleja eventos y variables de ajuste para el desarrollo de navegadores.
• The plugin keeps one full-screen Capacitor WebView. Native owns the frame, bars, safe-area reporting, and transition shell.

Sigue adelante desde Inicio rápido

Si estás utilizando Inicio rápido para planificar el comportamiento de medios y interfaz nativa, conecta con Usando @capgo/capacitor-navegación nativa para la capacidad nativa en Usando @capgo/capacitor-navegación-nativa, Usando @capgo/capacitor-actividades-en-vivo para la capacidad nativa en Usando @capgo/capacitor-actividades-en-vivo, @capgo/capacitor-actividades-en-vivo para el detalle de implementación en @capgo/capacitor-actividades-en-vivo, Usando @capgo/capacitor-reproductor-de-videos para la capacidad nativa en Usando @capgo/capacitor-reproductor-de-videos, y @capgo/capacitor-reproductor-de-videos para el detalle de implementación en @capgo/capacitor-reproductor-de-videos.