Getting Started

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 plug-in. 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 plug-in en exécutant les commandes suivantes et suivez les instructions spécifiques au plateforme ci-dessous :

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

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 cliqué 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'outils native, les insets de zone de sécurité et les événements d'intention native. Utilisez @capgo/capacitor-transitions pour la pile de pages WebView sous la chrome native.

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

Initialiser les deux packages une fois :

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

Conserver cap-router-outlet axé sur les pages, pas sur les barres de navigation dupliquées :

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

Fournir les deux packages à partir des mêmes actions de routage :

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

Choisissez un niveau d'animation par changement de route. Laissez @capgo/capacitor-transitions animer les poussées de page normales, et utilisez les assistants de zoom de Native Navigation uniquement pour les routes partagées ou de zoom.

Décalages CSS

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

Déscripteurs d'icônes

Les icônes doivent être sérialisables car les interfaces natives les rendent. Vous pouvez utiliser des SVG cross-plateforme, des SVG spécifiques au plateforme, des SF Symbols, des images iOS bundlées, des ressources de dessins 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 iconocentrique utilisé par les ensembles d'icônes courants tels que Lucide et Feather : path, line, polyline, polygon, circle, et rect. Les icônes SVG sont rendues par défaut comme des images de modèle, afin que les couleurs de teinte natives puissent les recolorer.

Composants web facultatifs

Le package peut enregistrer des éléments personnalisés pour un setup déclaratif sans dépendance de 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>

Notes sur les plateformes

iOS rend UINavigationBar et UITabBar; iOS 26+ utilise la barre Liquid Glass du système.
Android affiche un menu de navigation AppCompat et une navigation inférieure Matérielle.
La version web ne dessine pas les barres natives. Elle 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é contrôle la fenêtre, les barres, le rapport de zone de sécurité et la coquille de transition.

Continuez de l'étape de démarrage

Si vous utilisez Démarrage pour planifier le comportement de médias et d'interface natives, connectez-le avec Utilisation de @capgo/capacitor-native-navigation pour la capacité native dans Utilisation de @capgo/capacitor-native-navigation, Utilisation de @capgo/capacitor-live-activities pour la capacité native dans Utilisation de @capgo/capacitor-activités-en-vive, @capgo/capacitor-activités-en-vive pour le détail d'implémentation dans @capgo/capacitor-activités-en-vive, Utilisation de @capgo/capacitor-joueur-de-videos pour la capacité native dans Utilisation de @capgo/capacitor-joueur-de-videos, et @capgo/capacitor-joueur-de-videos pour le détail d'implémentation dans @capgo/capacitor-joueur-de-videos.