Per iniziare

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo 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.

Installazione

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

Installa il pacchetto
Finestra del terminale
```
npm i @capgo/capacitor-native-navigation
```
Sincronizza i progetti nativi
Finestra del terminale
```
npx cap sync
```

Configura il chrome nativo

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

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

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

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

Gestisci gli eventi intent nativi

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}`);
});

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.

Flusso di transizione

Le transizioni native sono una transazione che avvolge il normale cambio di rotta JavaScript:

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

Transizione zoom

Usa gli helper dello zoom per i flussi card-to-detail o media-preview. Passa l'elemento cliccato prima che il router cambi contenuto, poi termina quando la pagina di dettaglio è pronta.

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

Usa con @capgo/capacitor-transitions

Usa Native Navigation per la navbar nativa, la tabbar, i safe-area insets e gli eventi intent 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 cap-router-outlet concentrato sulle pagine, non su barre web duplicate:

<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 normali transizioni di pagina e usa gli helper di zoom di Native Navigation solo per le rotte shared-element o zoom.

inset CSS

Con contentInsetMode: 'css', il plugin scrive le dimensioni native della barra in document.documentElement.

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

Variabili disponibili:

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

Descrittori icona

Le icone devono essere serializzabili poiché vengono renderizzate dalla UI nativa. Puoi usare SVG cross-platform, SVG specifici per piattaforma, SF Symbols, immagini iOS incluse nel bundle, risorse drawable di Android o immagini Android incluse nel bundle.

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

L'SVG inline supporta il sottoinsieme di icone utilizzato dai set più comuni come Lucide e Feather: path, line, polyline, polygon, circle, e rect. Le icone SVG vengono renderizzate come template image di default, quindi i tint color nativi possono colorarle.

Web component opzionali

Il pacchetto può registrare custom elements per una configurazione dichiarativa framework-agnostic:

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>

iPhone Duo (iOS 27)

Su iPhone Duo, iOS spesso posiziona la tab bar di sistema e la status bar in un barra laterale verticale. env(safe-area-inset-top) può essere 0 mentre left o right cresce. Imposta viewport-fit=cover sul tuo viewport meta tag quando aggiungi padding con CSS env in qualsiasi punto dell'app. Testa le pose: piegata, aperta, landscape e Split View in Xcode Device Hub.

Native Navigation usa componenti reali UINavigationBar e UITabBar, quindi le tab bar di sistema seguono il rail. L' plugin la forma della tab bar resta in basso; l'azione centrale mantiene un alloggiamento circolare quando la finestra si allarga.

Due layout landscape aperti. A sinistra, la tab bar di sistema è nel rail laterale. A destra, la tab bar curva resta in basso e l'azione centrale è in un alloggiamento circolare.

Con contentInsetMode: 'css', arricchisci i contenuti web con le variabili del plugin. Usa max() con fallback env per ogni bordo, così il layout resta corretto quando una variabile del plugin è 0 senza sommare i duplicate inset:

main {
  padding-top: max(var(--cap-native-navigation-top, 0px), env(safe-area-inset-top, 0px));
  padding-right: max(var(--cap-native-navigation-right, 0px), env(safe-area-inset-right, 0px));
  padding-bottom: max(var(--cap-native-navigation-bottom, 0px), env(safe-area-inset-bottom, 0px));
  padding-left: max(var(--cap-native-navigation-left, 0px), env(safe-area-inset-left, 0px));
}

Ascolta gli safeAreaChanged (o capNativeNavigation:safeAreaChanged su window) quando cambia il rail o lo stato di fold. Nelle tab bar di sistemi ospitati, insets.tabbarHeight may be 0 per evitare il doppio padding inferiore; usa insets.systemTabbarHeight o --cap-native-system-tabbar-height per gli offset del FAB.

Guida completa su Capacitor (viewport-fit, System Bars, Status Bar, testing): Supporto per iPhone Duo nelle app Capacitor.

Note sulla piattaforma

Rendering iOS UINavigationBar e UITabBar; iOS 26+ utilizza il comportamento della barra Liquid Glass di sistema.
Android renderizza una toolbar AppCompat e una Material bottom navigation.
Il fallback Web non disegna barre native. Specchia gli eventi e le variabili inset per lo sviluppo nel browser.
Il plugin mantiene una singola WebView Capacitor a tutto schermo. Il codice nativo gestisce il frame, le barre, il reporting della safe-area e la shell delle transizioni.

Continua da Getting Started

Se stai usando Per iniziare per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a Usando @capgo/capacitor-native-navigation per la funzionalità nativa con @capgo/capacitor-native-navigation, Uso di @capgo/capacitor-live-activities per la funzionalità nativa nella pagina Uso di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio implementativo in @capgo/capacitor-live-activities, Uso di @capgo/capacitor-video-player per la funzionalità nativa nella pagina Uso di @capgo/capacitor-video-player, e @capgo/capacitor-video-player per il dettaglio implementativo in @capgo/capacitor-video-player.