Aller au contenu
Capgo - Compilez, déployez et mettez à jour vos apps Capacitor Capgo

Prise en main

GitHub

Installation

Section intitulée « Installation »

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

Fenêtre de terminal
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite le prompt suivant :

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 une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

  1. Installer le package

    Fenêtre de terminal
    npm i @capgo/capacitor-native-navigation

  2. Synchroniser les projets natifs

    Fenêtre de terminal
    npx cap sync

  3. Configurer le chrome natif

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

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

  4. Afficher 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. Afficher 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’intent 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}`);
    });

Barre de navigation multi-niveaux à segments

Section « Barre de navigation multi-niveaux avec rangées de segments »

Passer segments vers setNavbar pour empiler des rangées de segments natifs sous la barre, par exemple un sélecteur de scope en haut et des onglets de section en dessous. Les rangées se dessinent de haut en bas et chacune ajoute 44pt (iOS) ou 48dp (Android) à la navbar et aux insets renvoyés. iOS utilise UISegmentedControl et des pilules en verre ; Android utilise les Material segmented buttons et les filter chips.

iOSAndroid
Enregistrement iOS : appui sur les sections Account, le passage à Organization remplace la deuxième rangée par huit chips défilantes, sélection de BillingEnregistrement Android : rangée segmentée Account / Organization au-dessus de chips de section défilantes, changement de scope et sélection de Billing
const sections = {
  account: ['General', 'Notifications', 'Password', 'Two-factor'],
  organization: ['General', 'Members', 'Plans', 'Usage', 'Credits', 'Billing', 'Security', 'Webhooks'],
};
const selection = { scope: 'account', section: 'general' };


const renderNavbar = () =>
  NativeNavigation.setNavbar({
    title: 'Settings',
    segments: [
      {
        id: 'scope',
        selectedId: selection.scope,
        items: [
          { id: 'account', title: 'Account' },
          { id: 'organization', title: 'Organization' },
        ],
      },
      {
        id: 'section',
        style: 'scroll', // scrolling chips; `auto` uses `segmented` for up to 4 items
        selectedId: selection.section,
        items: sections[selection.scope].map((title) => ({ id: title.toLowerCase(), title })),
      },
    ],
  });


await NativeNavigation.addListener('navbarSegmentSelect', async ({ groupId, id }) => {
  if (groupId === 'scope') {
    selection.scope = id;
    selection.section = 'general'; // the second level depends on the first one
  } else {
    selection.section = id;
  }
  await renderNavbar();
});


await renderNavbar();

Selection moves natively when the user taps, but every setNavbar appel applique selectedId à nouveau. Conservez les ids sélectionnés dans votre état et passez-les à chaque appel ultérieur de setNavbar ; pour rejeter une sélection, envoyez le précédent selectedId. Les éléments acceptent également icon, accessibilityLabel, et enabled. Passer segments: [] pour supprimer les lignes. Disponible depuis la 8.13.0.

Flux de transition

Section intitulée « Flux de transition »

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

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

Section intitulée « Transition zoom »

Utilisez les helpers zoom pour les flux carte-vers-détail ou aperçu de média. Transmettez l’élément tapé avant que votre routeur ne change le contenu, puis terminez une fois la page de détail 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,
  });
}

Utiliser avec @capgo/capacitor-transitions

Section intitulée « Utilisation avec @capgo/capacitor-transitions »

Utilisez Native Navigation pour la barre de navigation native, la tabbar, les insets de safe-area et les événements d’intent natifs. Utilisez @capgo/capacitor-transitions pour la pile de pages WebView sous le chrome natif.

Fenêtre de terminal
npm install @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npx cap sync

Initialisez les deux packages une seule 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',
});

Conservez cap-router-outlet axé sur les pages, pas sur des 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>

Pilotez les deux packages depuis les mêmes actions du routeur :

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 Animez les pushes de pages normales et utilisez les helpers de zoom de Native Navigation uniquement pour les routes à élément partagé ou de zoom.

Insets CSS

Section intitulée « Insets CSS »

Avec contentInsetMode: 'css', le plugin écrit les dimensions des barres natives dans 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ônes

Section intitulée « Descripteurs d’icônes »

Les icônes doivent être sérialisables car l’UI native les rend. Vous pouvez utiliser des SVG multiplateformes, des SVG spécifiques à la plateforme, des SF Symbols, des images iOS incluses, des ressources drawable Android ou des images Android incluses.

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 inline prennent en charge le sous-ensemble centré sur les icônes utilisé par des jeux d’icônes courants comme Lucide et Feather : path, line, polyline, polygon, circle, et rect. Les icônes SVG sont rendues par défaut comme des images modèles, ce qui permet aux couleurs de teinte natives de les recolorer.

Web components optionnels

Section intitulée « Composants web optionnels »

Le package peut enregistrer des éléments personnalisés pour une configuration déclarative indépendante 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>

iPhone Duo (iOS 27)

Section intitulée « iPhone Duo (iOS 27) »

Sur iPhone Duo, iOS place souvent la barre d'onglets système et la barre d'état dans un rail latéral vertical. env(safe-area-inset-top) peut être 0 alors que left ou right croît. Définir viewport-fit=cover sur votre balise meta viewport lorsque vous ajoutez du padding avec CSS env n'importe où dans l'app. Testez les modes plié, ouvert, paysage et Split View dans Xcode Device Hub.

Native Navigation utilise de vrais UINavigationBar et UITabBar, donc les barres d'onglets système suivent le rail. Le courbe la forme de la barre d'onglets reste en bas ; l'action centrale conserve un socle circulaire lorsque la fenêtre s'élargit.

Deux mises en page en paysage ouvert. À gauche, la barre d'onglets système est dans le rail latéral. À droite, la barre d'onglets courbe reste en bas, et l'action centrale est dans un socle circulaire.

Avec contentInsetMode: 'css', rembourrez le contenu web avec des variables de plugin. Utilisez max() avec des replis d'env par edge pour que le layout reste correct lorsqu'une variable de plugin est 0 sans additionner les insets en double :

main {
  padding-top: max(var(--cap-native-navigation-top, 0px), env(safe-area-inset-top, 0px));
  padding-right: max(var(--cap-native-navigation-right, 0px), env(safe-area-inset-right, 0px));
  padding-bottom: max(var(--cap-native-navigation-bottom, 0px), env(safe-area-inset-bottom, 0px));
  padding-left: max(var(--cap-native-navigation-left, 0px), env(safe-area-inset-left, 0px));
}

Écoutez safeAreaChanged (ou capNativeNavigation:safeAreaChanged sur window) lorsque le côté du rail ou l'état du pliage change. Sur les barres d'onglets système hébergées, insets.tabbarHeight peut être 0 pour éviter un padding bas double ; utilisez insets.systemTabbarHeight ou --cap-native-system-tabbar-height pour les décalages des FAB.

Capacitor-large conseils (viewport-fit, System Bars, Status Bar, tests) : Support de l'iPhone Duo dans les apps Capacitor.

Notes sur les plateformes

Section intitulée « Notes sur les plateformes »
  • Rendu iOS UINavigationBar et UITabBar; iOS 26+ utilise le comportement système de la barre Liquid Glass.
  • Android affiche une toolbar AppCompat et une navigation Material en 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 sur navigateur.
  • Le plugin conserve une WebView Capacitor plein écran. Le natif gère le cadre, les barres, le reporting des safe areas et le shell de transition.

Continuer depuis Getting Started

Section intitulée « Continuer après Prise en main »

Si vous utilisez Prise en main pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utilisation de @capgo/capacitor-native-navigation pour la fonctionnalité native dans « Utiliser @capgo/capacitor-native-navigation », Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la capacité native dans Utiliser @capgo/capacitor-video-player, et @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player.