Getting Started

Einen Setup-Prompt mit den Installations-Schritten und der vollständigen Markdown-Guideline für diesen Plugin kopieren.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-native-navigation`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/native-navigation/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Installation

Sie können unser KI-gestütztes Setup verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer KI-Tool mithilfe der folgenden Befehl hinzu:

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

Verwenden Sie dann die folgende Anfrage:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-navigation` plugin in my project.

Wenn Sie die manuelle Installation bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den Plattform-spezifischen Anweisungen unten:

Install die Paket

npm i @capgo/capacitor-native-navigation

Synchronisiere native Projekte
Terminalfenster
```
npx cap sync
```

Konfiguriere native Chrome

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

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

Rendere die native Navbar

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

Rendere die native Tabbar

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

Native-Intent-Ereignisse verarbeiten

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

Übergangsbild

Native Übergänge sind eine Transaktion um Ihre normale JavaScript Routenänderung:

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

Zoom-Übergang

Verwenden Sie die Zoom-Hilfsmittel für Karten-zu-Detail- oder Medien-Vorschau-Flüsse. Passen Sie das angeklickte Element, bevor Ihr Router den Inhalt ändert, dann beenden Sie nachdem die Detailseite bereit ist.

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

Verwenden Sie mit @capgo/capacitor-Übergängen

Verwenden Sie Native Navigation für die native Navbar, Tabbar, safe-Area-Einrückungen und native Intent-Ereignisse. Verwenden Sie @capgo/capacitor-transitions für die WebView-Seitenspeicherung unterhalb der native Chrome.

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

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

__CAPGO_KEEP_0__ cap-router-outlet Geben Sie den Fokus auf Seiten, nicht auf Duplikate von Web-Balken:

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

Steueren Sie beide Pakete von denselben Router-Aktionen:

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ählen Sie eine Animationsschicht pro Routenänderung. Lassen Sie @capgo/capacitor-transitions animate normal page pushes, und verwenden Sie die Zoom-Hilfen von Native Navigation nur für gemeinsame-Elemnt- oder Zoom- Routen.

CSS-Einschübe

Mit der contentInsetMode: 'css'Plugin schreibt die nativen Bar-Dimensionen zu document.documentElement.

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

Verfügbare Variablen:

--cap-native-navigation-top
--cap-native-navigation-right
--cap-native-navigation-bottom
--cap-native-navigation-left
--cap-native-navbar-height
--cap-native-tabbar-height

Icon-Beschreibungen

Icons müssen serielierbar sein, weil sie von der native UI gerendert werden. Sie können cross-plattformige SVG, plattform-spezifische SVG, SF Symbols, eingebundene iOS-Bilder, Android-Drawable-Ressourcen oder eingebundene Android-Bilder verwenden.

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

Inline-SVG unterstützt den icon-fokussierten Subset, der von gängigen Icon-Sets wie Lucide und Feather verwendet wird: path, line, polyline, polygon, circleund rect. SVG Icons werden als Vorlagenbilder standardmäßig gerendert, sodass native Tintfarben sie neu einfärben können.

Optional Web-Komponenten

Das Paket kann für eine framework-agnostische deklarative Konfiguration benutzerdefinierte Elemente registrieren:

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>

Plattformhinweise

iOS rendert UINavigationBar und UITabBar; iOS 26+ verwendet das System-Liquid-Glas-Leiste-Verhalten.
Android render eine AppCompat-Leiste und Material-Bottom-Navigation.
Die Web-Fallback-Version zeichnet keine nativen Leisten. Es spiegelt Ereignisse und Inset-Variablen für Browser-Entwicklung wider.
Das Plugin hält eine vollbildschirmige Capacitor WebView. Die Native-Verwaltung besitzt den Rahmen, die Leisten, die sichere Bereichsberichterstattung und die Übergangshülle.

Weitermachen von Getting Started

Wenn Sie native Medien und Schnittstellenverhalten planen, verbinden Sie es mit Getting Started um native Medien und Schnittstellenverhalten zu planen, verbinden Sie es mit Verwenden Sie @capgo/capacitor-native-navigation für die native Fähigkeit in @capgo/capacitor-native-navigation Mit @capgo/capacitor-live-activities für die native Fähigkeit in Mit @capgo/capacitor-live-activities @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-activities Mit @capgo/capacitor-video-player für die native Fähigkeit in Mit @capgo/capacitor-video-player und @capgo/capacitor-video-player für die Implementierungsdetails in @capgo/capacitor-video-player