Getting Started

Copia un prompt di configurazione con le istruzioni 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 utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo competenze al tuo strumento AI utilizzando il seguente comando:

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

Usa poi 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 i seguenti comandi e segui le istruzioni specifiche del tuo platform:

Installa il pacchetto

npm i @capgo/capacitor-native-navigation

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

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

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

Gestisci eventi di intento 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}`);
});

Flusso di transizione

Il flusso di transizione nativo è un'operazione di transazione intorno al tuo 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 di zoom

Utilizza gli aiuti di zoom per flussi da scheda a dettaglio o anteprima dei media. Passa l'elemento premuto prima che il tuo router cambi il contenuto, poi finisci dopo che 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,
  });
}

Utilizza con @capgo/capacitor-transizioni

Utilizza la navigazione nativa per il menu di navigazione nativo, la barra dei tab, gli insetti di area sicura e gli eventi di intent nativi. Utilizza @capgo/capacitor-transitions per la pila di pagine di WebView sotto il chrome nativo.

npm install @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npx cap sync

Inizializza entrambi i pacchetti una volta sola:

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 focalizzato su pagine, non 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>

Guida entrambi i pacchetti dalle 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 layer di animazione per ogni cambio di route. Lascia @capgo/capacitor-transitions animare spinte di pagina normali, e utilizza gli aiuti di zoom di Native Navigation solo per percorsi condivisi o di zoom.

Insetti CSS

Con contentInsetMode: 'css', il plugin scrive dimensioni native di barra a 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 di icona

Le icone devono essere serializzabili perché le interfacce utente native le rendono. Puoi utilizzare SVG cross-platform, SVG specifico della piattaforma, SF Symbols, immagini iOS bundle, risorse drawable Android o immagini Android 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',
  },
};

SVG inline supporta l'insieme icona-focale utilizzato dai set di icone comuni come Lucide e Feather: path, line, polyline, polygon, circle, e rectLe icone SVG vengono renderizzate come immagini di template di default, quindi i colori di sfumatura native possono ricolorarle.

Componenti web facoltativi

Il pacchetto può registrare elementi personalizzati per una configurazione dichiarativa indipendente dal 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>

Nota sulla piattaforma

iOS rende UINavigationBar e UITabBar; iOS 26+ utilizza il comportamento della barra Liquida Glass del sistema.
Android rende una toolbar AppCompat e una navigazione inferiore Material.
La caduta di rete non disegna le barre native. Riflette gli eventi e le variabili di insetto per lo sviluppo del browser.
The plugin keeps one full-screen Capacitor WebView. Native owns the frame, bars, safe-area reporting, and transition shell.

Continua da Iniziare

Se stai utilizzando Iniziare per pianificare il comportamento dei media e dell'interfaccia nativa, connettilo con Usando @capgo/capacitor-navigazione-nativa per la capacità nativa in Usando @capgo/capacitor-navigazione-nativa, Usando @capgo/capacitor-attività-vive per la capacità nativa in Utilizzare @capgo/capacitor-live-attività @capgo/capacitor-live-attività per il dettaglio di implementazione in @capgo/capacitor-live-attività Utilizzare @capgo/capacitor-video-player per la capacità nativa in Utilizzare @capgo/capacitor-video-player, e @capgo/capacitor-video-player per il dettaglio di implementazione in @capgo/capacitor-video-player