Navigation native Plugin Capacitor

Utilisation de @capgo/capacitor-native-navigation

@capgo/capacitor-native-navigation affiche la barre de navigation native en haut, la barre d'onglets en bas et les shells de transition de route par-dessus une seule WebView Capacitor plein écran. Votre framework web garde la main sur les routes et le contenu, tandis que le natif gère le cadre de l'app.

Installer et synchroniser

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

Configurer le cadre natif

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

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

Afficher une navbar native

await NativeNavigation.setNavbar({
  title: 'Inbox',
  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>',
      },
    },
  ],
});

Ajouter des lignes de segments multi-niveaux sous la navbar

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.

iOS	Android

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 setNavbar ; pour rejeter une sélection, envoyez la précédente selectedId. Les éléments acceptent également icon, accessibilityLabel, et enabled. Passer segments: [] pour supprimer les lignes. Disponible depuis la 8.13.0.

Afficher une tabbar native

await NativeNavigation.setTabbar({
  selectedId: 'inbox',
  labelVisibilityMode: 'selected',
  icons: true,
  colors: {
    dynamic: true,
    tint: '#0f172a',
    inactiveTint: '#64748b',
  },
  tabs: [
    {
      id: 'inbox',
      title: 'Inbox',
      icon: {
        svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4h16v16H4z"/><path d="m4 13 4 4h8l4-4"/></svg>',
      },
    },
    {
      id: 'search',
      title: 'Search',
      icon: {
        svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"/><path d="m20 20-3-3"/></svg>',
      },
    },
  ],
});

Connecter les événements natifs à votre routeur

Les barres natives émettent une intention. Votre routeur effectue toujours le changement de route :

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

Animer les changements de route

Utilisez une transaction de transition autour de votre mise à jour de route web habituelle :

const transition = await NativeNavigation.beginTransition({
  direction: 'forward',
});

router.push('/message/42');
await router.ready?.();

await NativeNavigation.setNavbar({
  title: 'Message',
  backButton: { visible: true, title: 'Inbox' },
});

await NativeNavigation.finishTransition({
  id: transition.id,
  direction: 'forward',
});

Ajouter une transition de zoom

Utilisez les helpers de zoom pour les routes ouvertes depuis une carte, un élément de grille ou un aperçu média.

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

Ajouter du padding avec les insets natifs

Quand contentInsetMode est css, le plugin écrit des variables CSS pour les barres natives :

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

Choix des icônes

Les icônes sont des descripteurs natifs, pas des nœuds React ou Vue. Utilisez du SVG si vous ne souhaitez pas inclure d'assets natifs dans le bundle :

const icon = {
  svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
  template: true,
  ios: { sfSymbol: 'house.fill' },
  android: { resource: 'ic_menu_view' },
};

Le SVG inline prend en charge path, line, polyline, polygon, circle, et rect, ce qui couvre les jeux d'icônes courants comme Lucide et Feather.

Combinez 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 cette interface native.

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

Concentrez l'outlet de transition sur les pages, pas sur des barres web en double :

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

Référence complète

• GitHub : https://github.com/Cap-go/capacitor-native-navigation/
• Docs : /docs/plugins/native-navigation/

Continuez depuis Using @capgo/capacitor-native-navigation

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