Getting Started

Installation

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

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

Utilisez ensuite 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 à la plateforme ci-dessous :

1. Installer le package

   npm i @capgo/capacitor-native-navigation

2. Synchroniser les projets natifs

   npx cap sync

3. Configurer le navigateur natif

   import { NativeNavigation } from '@capgo/capacitor-native-navigation';
   
   await NativeNavigation.configure({
     contentInsetMode: 'css',
     animationDuration: 360,
     colors: {
       tint: '#0f172a',
       inactiveTint: '#64748b',
     },
   });

4. Rendre la barre de navigation native

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

5. Rendre la barre d'onglets native

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

6. 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 d'agrandissement

Utilisez les assistants d'agrandissement 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 le navbar natif, la barre d'outils, les insets de zone de sécurité et les événements d'intent natif. Utilisez @capgo/capacitor-transitions pour la pile de pages WebView sous le chrome natif.

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

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

Conservé cap-router-outlet concentré sur les pages, pas les barres web 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>

Gérez les deux packages à partir des mêmes actions de navigateur :

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 une couche d'animation par changement de route. Laissez @capgo/capacitor-transitions animer les poussées de page normales, et utilisez les aides de zoom de Native Navigation uniquement pour les routes partagées ou de zoom.

marges 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ésignateurs d'icône

Il faut que les icônes soient sérialisables car les interfaces natives les rendent. Vous pouvez utiliser des SVG cross-plateforme, des SVG spécifiques au plateau, des SF Symbols, des images iOS embarquées, des ressources de dessin Android ou des images Android embarqué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 iconographique utilisé par les ensembles d'icônes courants comme Lucide et Feather : path, line, polyline, polygon, circle, et rect. Les icônes SVG sont rendues comme des images de modèle par défaut, donc les couleurs de teinte natives peuvent les recolorer.

Composants web facultatifs

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

Note

Les composants web sont optionnels. Les applications React, Vue, Angular, Svelte, Solid et vanilla peuvent utiliser directement l’imperatif API.

Notes de plateforme

• iOS affiche UINavigationBar et UITabBar; iOS 26+ utilise le comportement de la barre de verre liquide système.
• Android affiche un menu d'outils AppCompat et une navigation en bas matérielle.
• 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 Capacitor WebView plein écran unique. Le natif contrôle la frame, les barres, le rapport de zone de sécurité et le shell de transition.

Continuez de Getting Started

Si vous utilisez Getting Started pour planifier le comportement de médias et d'interface natifs, connectez-l’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-live-activities, @capgo/capacitor-activités en direct pour le détail d'implémentation dans @capgo/capacitor-live-activities, Utiliser @capgo/capacitor-player vidéo pour la capacité native dans Utiliser @capgo/capacitor-player vidéo, et @capgo/capacitor-player vidéo pour le détail d'implémentation dans @capgo/capacitor-player vidéo.