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 utilizzare la nostra configurazione assistita dall'IA per installare il plugin. Aggiungi le Capgo competenze al tuo strumento di AI utilizzando il seguente comando:

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

Poi utilizza 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 sistema operativo qui sotto:

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

Configura il browser nativo

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

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

Rendi visibile il menu di navigazione 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>',
      },
    },
  ],
});

Rendi visibile la barra dei tab 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 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

Le transizioni native sono una 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 zoom

Utilizza gli aiuti di zoom per flussi da scheda a dettaglio o anteprima media. Passa l'elemento toccato 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

Usa la navigazione nativa per il navbar nativo, tabbar, insetti di area sicura e eventi di intento nativo. Usa @capgo/capacitor-transitions per la pila di pagine 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',
});

__CAPGO_KEEP_0__ cap-router-outlet Focalizzati sulle pagine, non sui 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 di 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 le spinte di pagina normale e utilizzare gli aiuti di zoom di Native Navigation solo per le rotte con elementi condivisi o di zoom.

CSS insets

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

Le icone devono essere serializzabili perché la UI nativa le rende. Puoi utilizzare SVG cross-platform, SVG specifici 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 il subset icon-focused utilizzato dai set di icone comuni come Lucide e Feather: path, line, polyline, polygon, circle, e rect. Gli icon SVG vengono visualizzati come immagini di template di default, quindi i colori di sfumatura nativi possono ricolorarli.

Componenti web facoltativi

Il pacchetto può registrare elementi personalizzati per impostare in modo dichiarativo e 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 sulle piattaforme

iOS rende UINavigationBar e UITabBar; iOS 26+ utilizza il comportamento della barra di vetro liquido del sistema.
Android rende una barra di strumenti AppCompat e una navigazione in basso di Material.
La versione web non disegna 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 Inizia

Inizia per pianificare il comportamento dei media e dell'interfaccia nativa, connettilo con Usa @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation Using @capgo/capacitor-native-navigation per la capacità nativa in Utilizzo di @capgo/capacitor-native-navigation, Utilizzo di @capgo/capacitor-live-attività per la capacità nativa in Utilizzo di @capgo/capacitor-live-attività, @capgo/capacitor-live-attività per il dettaglio di implementazione in @capgo/capacitor-live-attività, Utilizzo di @capgo/capacitor-video-player per la capacità nativa in Utilizzo di @capgo/capacitor-video-player, e @capgo/capacitor-video-player per il dettaglio di implementazione in @capgo/capacitor-video-player.