Inicio

Copia un prompt de configuración con los pasos de instalación y la guía de markdown completa para este plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-native-navigation`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/native-navigation/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Instalación

Puede utilizar nuestra configuración asistida por IA para instalar el complemento. Agregue las Capgo habilidades a su herramienta de IA utilizando el siguiente comando:

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

Luego utilice 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 prefiere la configuración manual, instale el complemento ejecutando los siguientes comandos y siguiendo las instrucciones específicas de la plataforma a continuación:

Instale el paquete

npm i @capgo/capacitor-native-navigation

Sincronizar proyectos nativos
ventana de terminal
```
npx cap sync
```

Configurar el navegador nativo

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

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  colors: {
    tint: '#0f172a',
    inactiveTint: '#64748b',
  },
});

Renderizar la barra de navegación nativa

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

Renderizar la pestaña de navegación nativa

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

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 tu 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, y 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

Utilice la navegación nativa para el menú de navegación nativa, la pestaña de navegación nativa, los ajustes de área segura y los eventos de intención nativa. Utilice @capgo/capacitor-transitions para la pila de navegación de la página WebView debajo del navegador 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>

Dirija 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 de zoom.

espacios 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 subconjunto enfocado en iconos utilizado por conjuntos de iconos comunes como Lucide y Feather: path, line, polyline, polygon, circley rectLos iconos SVG se renderizan como imágenes de plantilla por defecto, por lo que los colores de tono nativos pueden recolorizarlos.

Componentes web opcionales

El paquete puede registrar elementos personalizados para un conjunto de configuración declarativa independiente del framework:

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

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 caída a la web no dibuja barras nativas. Refleja eventos y variables de ajuste para el desarrollo de navegadores.
El plugin mantiene un WebView completo de pantalla Capacitor.

Sigue adelante desde Inicio

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