Accueil

Copiez un prompt de configuration avec les étapes d'installation et le guide markdown complet pour ce 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.

Installation

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA en utilisant la commande suivante :

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

Ensuite, utilisez la prompt suivante :

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

Si vous préférez la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques au plateforme ci-dessous :

Installez le package

npm i @capgo/capacitor-native-navigation

Synchroniser les projets natifs
Fenêtre de terminal
```
npx cap sync
```

Configurer le navigateur natif

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

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

Rendre le navbar natif

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

Rendre le tabbar natif

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

Gérer les événements d'intention native

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

Flux de transition

Les transitions natives sont une transaction autour de votre changement de route JavaScript normal :

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

Transition de zoom

Utilisez les helpers de zoom pour les flux card-to-detail ou media-preview. Passer l'élément tapé avant que votre routeur change le contenu, puis terminer après que la page de détails est prête.

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

Utilisez avec @capgo/capacitor-transitions

Utilisez la navigation native pour la barre de navigation native, la barre d'onglets, les insets de zone de sécurité et les événements d'intent natifs. @capgo/capacitor-transitions Utilisez

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

Copier dans le presse-papier

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

Copier dans le presse-papier cap-router-outlet __CAPGO_KEEP_0__

<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>

Copier dans le presse-papier

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

Copier dans le presse-papier @capgo/capacitor-transitions animate les poussées de page normales, et utilisez les assistants de zoom de Native Navigation uniquement pour les routes de partage d'éléments ou de zoom.

CSS insets

Avec contentInsetMode: 'css', le plugin écrit les dimensions de la barre native à document.documentElement.

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

Variables disponibles :

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

Descripteurs d'icône

Les icônes doivent être sérialisables car les UI natives les rendent. Vous pouvez utiliser des SVG cross-platform, des SVG spécifiques au plateau, des SF Symbols, des images iOS bundlées, des ressources de drawables Android ou des images Android bundlées.

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

Les SVG en ligne supportent l'ensemble icon-focused utilisé par les ensembles d'icônes courants comme Lucide et Feather : path, line, polyline, polygon, circleet rectSection intitulée « Composants web facultatifs »

Les composants web sont facultatifs. Les applications React, Vue, Angular, Svelte, Solid et vanilla peuvent utiliser directement le __CAPGO_KEEP_0__ de manière impérative.

La note sur la plateforme

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>

La note sur la plateforme

iOS rend UINavigationBar et UITabBar; iOS 26+ utilise le comportement de la barre Liquid Glass système.
Android affiche un menu de navigation AppCompat et une navigation inférieure Matérielle.
Le fallback Web ne dessine pas les barres natives. Il reflète les événements et les variables d'inset pour le développement de navigateur.
Le plugin garde un WebView plein écran complet Capacitor. La nativité possède la fenêtre, les barres, le rapport de zone de sécurité et le shell de transition.

Continuez de l'étape de démarrage

Si vous utilisez Démarrage pour planifier le comportement de la média et de l'interface native, connectez-le avec Utilisez @capgo/capacitor-native-navigation pour la capacité native dans l'utilisation de @capgo/capacitor-native-navigation, Utilisation de @capgo/capacitor-live-activities pour la capacité native dans l'utilisation de @capgo/capacitor-live-activities, @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities, Utilisation de @capgo/capacitor-video-player pour la capacité native dans l'utilisation de @capgo/capacitor-video-player, et @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player.