Native Navigation Capacitor Plugin

Verwendung von @capgo/capacitor-native-navigation

@capgo/capacitor-native-navigation rendert native Top-Navigation, Bottom-Tab-Chrome und Route-Transition-Shells über eine einzige Fullscreen-Capacitor-WebView. Dein Web-Framework kümmert sich weiterhin um Routes und Inhalte, während die native Ebene den App-Frame übernimmt.

Installieren und synchronisieren

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

Native Frame konfigurieren

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

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

Native Navbar rendern

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

Mehrstufige Segmentzeilen unter der Navbar hinzufügen

Übergeben segments zu setNavbar um Reihen nativer Segmente unter der Leiste zu stapeln – zum Beispiel einen Scope-Switcher oben und darunter Bereichs-Tabs. Die Reihen werden von oben nach unten gezeichnet; jede Reihe fügt der Navbar und den gemeldeten Insets 44pt (iOS) bzw. 48dp (Android) hinzu. iOS nutzt UISegmentedControl und Glass-Pills; Android nutzt Material Segmented Buttons und 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();

Die Auswahl bewegt sich nativ beim Tippen, aber jeder setNavbar Aufruf wendet sie selectedId erneut an. Speichere die ausgewählten IDs in deinem State und übergib sie bei jedem setNavbar späteren Aufruf; um eine Auswahl abzulehnen, sende die vorherige. selectedIdElemente unterstützen auch icon, accessibilityLabel, und enabled. Übergeben segments: [] , um die Zeilen zu entfernen. Verfügbar ab 8.13.0.

Native Tabbar rendern

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

Native Events mit deinem Router verbinden

Native Bars senden Intents. Dein Router führt den Routenwechsel weiterhin aus:

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

Routenwechsel animieren

Nutze eine Transition-Transaction um dein normales Web-Route-Update herum:

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

Zoom-Transition hinzufügen

Nutze die Zoom-Helper für Routen, die aus einer Card, einem Grid-Item oder einer Media-Preview geöffnet werden.

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

Content mit nativen Insets padden

Wenn contentInsetMode ist css, schreibt das Plugin CSS-Variablen für die nativen Leisten:

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

Icon-Auswahl

Icons sind native Descriptoren, keine React- oder Vue-Knoten. Verwende SVG, wenn du keine nativen Assets bündeln möchtest:

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

Inline-SVG unterstützt path, line, polyline, polygon, circle, und rect, was gängige Icon-Sets wie Lucide und Feather abdeckt.

Kombiniere mit @capgo/capacitor-transitions

Verwende Native Navigation für die native Navbar, Tabbar, Safe-Area-Insets und native Intent-Events. Verwende @capgo/capacitor-transitions für den WebView-Seitenstapel unter dieser nativen Chrome.

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

Initialisiere beide Pakete einmal:

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

Halte den Transition-Outlet auf Seiten fokussiert, nicht auf doppelten Web-Leisten:

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

Beide Pakete über dieselben Router-Actions steuern:

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

Wähle eine Animationsebene pro Routenwechsel. Lass @capgo/capacitor-transitions animiere normale Seiten-Pushes und nutze die Zoom-Helfer von Native Navigation nur für Shared-Element- oder Zoom-Routen.

Vollständige Referenz

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

Weiter von Using @capgo/capacitor-native-navigation

Wenn du es nutzt Verwendung von @capgo/capacitor-native-navigation , um natives Media- und Interface-Verhalten zu planen, verbinde es mit @capgo/capacitor-native-navigation für die Implementierungsdetails in @capgo/capacitor-native-navigation, Erste Schritte für die Implementierungsdetails in Erste Schritte, @capgo/capacitor-live-activities verwenden für die native Funktion in „@capgo/capacitor-live-activities verwenden“, @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-activities und Verwendung von @capgo/capacitor-video-player für die native Funktionalität in „Verwendung von @capgo/capacitor-video-player.“