Guía
Cómo usar Navegación Nativa en Capacitor
Probar en dispositivo
Descargue la aplicación Capgo, luego escane el código QR code.
Usando @capgo/capacitor-native-navigation
@capgo/capacitor-native-navigation Rendice una navegación nativa superior, barra de abajo de pestañas y cápsulas de transición de ruta sobre una sola pantalla completa Capacitor WebView. Su framework web sigue teniendo control de rutas y contenido, mientras que la nativa tiene control de la ventana de la aplicación.
Instalar y sincronizar
npm install @capgo/capacitor-native-navigation
npx cap sync
Configurar la ventana nativa
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
colors: {
tint: '#0f172a',
inactiveTint: '#64748b',
},
});
Rendir una barra de navegación nativa
await NativeNavigation.setNavbar({
title: 'Inbox',
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>',
},
},
],
});
Rendir una barra de pestañas nativa
await NativeNavigation.setTabbar({
selectedId: 'inbox',
labelVisibilityMode: 'selected',
icons: true,
colors: {
dynamic: true,
tint: '#0f172a',
inactiveTint: '#64748b',
},
tabs: [
{
id: 'inbox',
title: 'Inbox',
icon: {
svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4h16v16H4z"/><path d="m4 13 4 4h8l4-4"/></svg>',
},
},
{
id: 'search',
title: 'Search',
icon: {
svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"/><path d="m20 20-3-3"/></svg>',
},
},
],
});
Conectar eventos nativos a su router
Las barras nativas emiten intención. Su router sigue realizando el cambio de ruta:
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}`);
});
Cambiar animaciones de ruta
Utilice una transacción de transición alrededor de la actualización de ruta web normal:
const transition = await NativeNavigation.beginTransition({
direction: 'forward',
});
router.push('/message/42');
await router.ready?.();
await NativeNavigation.setNavbar({
title: 'Message',
backButton: { visible: true, title: 'Inbox' },
});
await NativeNavigation.finishTransition({
id: transition.id,
direction: 'forward',
});
Agregar una transición de zoom
Use the zoom helpers for routes that open from a card, grid item, or media preview.
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,
});
}
Añadir contenido con ajustes nativos
Cuando contentInsetMode es css, el plugin escribe variables CSS para las barras nativas:
.page {
padding-top: var(--cap-native-navigation-top);
padding-bottom: var(--cap-native-navigation-bottom);
}
Opciones de iconos
Los iconos son descripciones nativas, no nodos de React o Vue. Utilice SVG cuando no desee empaquetar activos nativos:
const icon = {
svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
template: true,
ios: { sfSymbol: 'house.fill' },
android: { resource: 'ic_menu_view' },
};
SVG en línea admite path, line, polyline, polygon, circle, y rectque cubre conjuntos de iconos comunes como Lucide y Feather.
Combine con @capgo/capacitor-transiciones
Utilice la navegación nativa para el navbar nativo, tabbar, ajustes de área segura e eventos de intención nativa. @capgo/capacitor-transitions para la pila de páginas de WebView debajo de ese 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 el outlet de transición enfocado en páginas, no duplique barras web:
<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 nivel 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 la navegación nativa para rutas compartidas o de zoom.
Referencia Completa
- GitHub: https://github.com/Cap-go/capacitor-navegación-nativa/
- Documentación: /docs/plugins/native-navigation/
Sigue adelante desde el uso de @capgo/capacitor-native-navigation
Si estás utilizando Usando @capgo/capacitor-native-navigation para planificar el comportamiento de medios y interfaces nativos, conecta con @capgo/capacitor-navegación nativa para los detalles de implementación en @capgo/capacitor-native-navigation Getting Started para los detalles de implementación en Inicio Usando @capgo/capacitor-actividades-en-vivo para la capacidad nativa en Usando @capgo/capacitor-actividades-en-vivo @capgo/capacitor-actividades-en-vivo para los detalles de implementación en @capgo/capacitor-actividades-en-vivo, y Usando @capgo/capacitor-reproductor-de-videos para la capacidad nativa en Usando @capgo/capacitor-reproductor-de-videos.