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

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

Renderizar el tablero de navegación 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>',
      },
    },
  ],
});

Hantera 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, 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 barra de herramientas, los ajustes de área segura y los eventos de intención nativa. Utilice @capgo/capacitor-transitions para la pila de página de 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',
});

__CAPGO_KEEP_0__ cap-router-outlet se centra 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>

Haga avanzar 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 una 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.

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 conjunto de iconos enfocado utilizado por conjuntos de iconos comunes como Lucide y Feather: path, line, polyline, polygon, circle, y rect. Los 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 marco:

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>

Notas de plataforma

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.
The plugin keeps one full-screen Capacitor WebView. Native owns the frame, bars, safe-area reporting, and transition shell.

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