Inizia a utilizzare

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 platform sotto:

Installa il pacchetto
Finestra del terminale
```
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',
  },
});

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 nativo

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 passaggio tra pagine native è 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 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, tabbar, insetti di area sicura e eventi di intento nativi. 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

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

Tieni cap-router-outlet 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>

Gestisci 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 pagine normali e utilizzare gli aiuti di zoom di Native Navigation solo per percorsi 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 icona-focato utilizzato dai set di icone comuni come Lucide e Feather: path, line, polyline, polygon, circlee . Icon SVG vengono visualizzati come immagini di template di default, quindi i colori di tinteggiatura nativi possono ricolorarli. rectComponenti web facoltativi

Il pacchetto può registrare elementi personalizzati per un setup dichiarativo indipendente dal framework:

Copia negli appunti

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>

Optional web components

iOS rende UINavigationBar e UITabBar; iOS 26+ utilizza il comportamento della barra di vetro liquido del sistema.
L'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 Inizia a utilizzare

Inizia a utilizzare per pianificare il comportamento dei media e dell'interfaccia nativa, connettilo con Usando @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation Se stai utilizzando Inizia a utilizzare per pianificare il comportamento dei media e dell'interfaccia nativa, connettilo con Utilizza @capgo/capacitor-native-navigation per la capacità nativa in Utilizzare @capgo/capacitor-native-navigation, Utilizzare @capgo/capacitor-live-activities per la capacità nativa in Utilizzare @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio di implementazione in @capgo/capacitor-live-activities, 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.