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

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

1. Installez le package

   npm i @capgo/capacitor-native-navigation

2. Synchronisez les projets natifs

   npx cap sync

3. Configurez le navigateur natif

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

4. Rendez le navbar natif visible

   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. Rendez le tabbar natif visible

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

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

Faites rouler 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 animate les déplacements de page normaux, et utilisez les aides de zoom de Native Navigation uniquement pour les routes partagées 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

Désignateurs d'icônes

Les icônes doivent être sérialisables car l'interface native les affiche. Vous pouvez utiliser des SVG cross-platform, des SVG spécifiques au plateau, des SF Symbols, des images iOS bundlées, des ressources Android drawable 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, circle, et rect. Les icônes SVG sont rendues comme des images de modèle par défaut, donc les couleurs de teint native 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>

Remarque

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

Remarques sur les plateformes

• iOS rend UINavigationBar et UITabBar; iOS 26+ utilise la barre de Liquid Glass système.
• Android affiche un AppCompat d'outil de navigation et de bas.
• 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.
• The plugin keeps one full-screen Capacitor WebView. Native owns the frame, bars, safe-area reporting, and transition shell.

Continuez de Getting Started

Si vous utilisez Getting Started pour planifier le comportement des médias et de l'interface natives, connectez-l’avec Utilisez @capgo/capacitor-native-navigation pour la capacité native dans l'utilisation de @capgo/capacitor-native-navigation, L'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, L'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.