Guida
Come usare Native Navigation in Capacitor
Usando @capgo/capacitor-native-navigation
@capgo/capacitor-native-navigation renderizza la navigazione nativa superiore, la barra dei tab inferiore e le transizioni di rotta sopra un'unica Capacitor WebView a tutto schermo. Il tuo framework web gestisce ancora rotte e contenuti, mentre il nativo gestisce l'app frame.
Installa e sincronizza
npm install @capgo/capacitor-native-navigation
npx cap sync
Configura l'app frame nativo
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
colors: {
tint: '#0f172a',
inactiveTint: '#64748b',
},
});
Renderizza una navbar 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>',
},
},
],
});
Aggiungi righe segmentate multi-livello sotto la navbar
Passa segments a setNavbar per impilare righe di segmenti nativi sotto la barra, ad esempio un selettore di scope in alto e le tab di sezione sotto. Le righe si disegnano dall'alto verso il basso e ognuna aggiunge 44pt (iOS) o 48dp (Android) alla navbar e agli inset riportati. iOS usa UISegmentedControl e pillole di vetro; Android utilizza i Material segmented buttons e i filter chips.
| iOS | Android |
|---|---|
 |
 |
const sections = {
account: ['General', 'Notifications', 'Password', 'Two-factor'],
organization: ['General', 'Members', 'Plans', 'Usage', 'Credits', 'Billing', 'Security', 'Webhooks'],
};
const selection = { scope: 'account', section: 'general' };
const renderNavbar = () =>
NativeNavigation.setNavbar({
title: 'Settings',
segments: [
{
id: 'scope',
selectedId: selection.scope,
items: [
{ id: 'account', title: 'Account' },
{ id: 'organization', title: 'Organization' },
],
},
{
id: 'section',
style: 'scroll', // scrolling chips; `auto` uses `segmented` for up to 4 items
selectedId: selection.section,
items: sections[selection.scope].map((title) => ({ id: title.toLowerCase(), title })),
},
],
});
await NativeNavigation.addListener('navbarSegmentSelect', async ({ groupId, id }) => {
if (groupId === 'scope') {
selection.scope = id;
selection.section = 'general'; // the second level depends on the first one
} else {
selection.section = id;
}
await renderNavbar();
});
await renderNavbar();
La selezione si sposta nativamente al tocco, ma ogni setNavbar chiamata applica selectedId di nuovo. Mantieni gli id selezionati nel tuo stato e passali in ogni successiva setNavbar chiamata; per rifiutare una selezione, invia il precedente selectedId. Gli elementi accettano anche icon, accessibilityLabel, e enabled. Pass segments: [] per rimuovere le righe. Disponibile dalla 8.13.0.
Renderizza una tabbar 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>',
},
},
],
});
Collega gli eventi nativi al tuo router
Le barre native emettono intent. Il tuo router esegue comunque il cambio di rotta:
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}`);
});
Anima i cambi di rotta
Usa una transazione di transizione attorno al tuo normale aggiornamento della rotta web:
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',
});
Aggiungi una transizione zoom
Usa gli helper zoom per le rotte che si aprono da una card, un elemento della grid o un'anteprima media.
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,
});
}
Padding del contenuto con inset nativi
Quando contentInsetMode è css, il plugin scrive variabili CSS per le barre native:
.page {
padding-top: var(--cap-native-navigation-top);
padding-bottom: var(--cap-native-navigation-bottom);
}
Scelta delle icone
Le icone sono descrittori nativi, non nodi React o Vue. Usa SVG se non vuoi includere asset nativi:
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' },
};
Supporta SVG inline path, line, polyline, polygon, circle, e rect, che include set di icone comuni come Lucide e Feather.
Combina con @capgo/capacitor-transitions
Usa Native Navigation per navbar, tabbar, safe-area insets ed eventi nativi. Usa @capgo/capacitor-transitions per lo stack delle pagine WebView sotto la chrome nativa.
npm install @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npx cap sync
Inizializza entrambi i pacchetti una sola volta:
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',
});
Mantieni il transition outlet focalizzato sulle pagine, non duplicare le barre 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>
Gestisci entrambi i pacchetti con le stesse azioni del 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}`);
});
Scegli un livello di animazione per ogni cambio di rotta. Lascia @capgo/capacitor-transitions anima le transizioni normali delle pagine e usa gli helper zoom di Native Navigation solo per rotte shared-element o zoom.
Riferimento completo
- GitHub: https://github.com/Cap-go/capacitor-native-navigation/
- Docs: /docs/plugins/native-navigation/
Continua da Using @capgo/capacitor-native-navigation
Se stai usando Usando @capgo/capacitor-native-navigation per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a @capgo/capacitor-native-navigation per il dettaglio implementativo in @capgo/capacitor-native-navigation, Per iniziare per i dettagli di implementazione nella guida introduttiva, Uso di @capgo/capacitor-live-activities per la funzionalità nativa nella pagina Uso di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per i dettagli di implementazione in @capgo/capacitor-live-activities, e Uso di @capgo/capacitor-video-player per la funzionalità nativa in Usare @capgo/capacitor-video-player.