Getting Started

Einen Setup-Vorschlag mit den Installationsanweisungen und der vollständigen Markdown-Anleitung für diesen Plugin erstellen.

        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.

Das Paket installieren

npm i @capgo/capacitor-native-navigation

Natives Projekte synchronisieren
Terminal-Fenster
```
npx cap sync
```

Einstellungen für native Chrome konfigurieren

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

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

Das native Navbar rendern

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

Das native Tabbar rendern

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

Übergangsbetriebsablauf

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-Hilfen für Flüsse von Karte zu Detail oder Medien-Vorschau. Passen Sie das angeklickte Element, bevor sich der Router ändert, und beenden Sie ihn, 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 das native Navbar, Tabbar, Safe-Area-Einrückungen und native Intent-Ereignisse. Verwenden Sie @capgo/capacitor-transitions für die WebView-Seitenspule unterhalb des nativen 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 Wir konzentrieren uns auf Seiten, nicht auf duplicate Web-Bars:

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

Führen Sie beide Pakete von denselben Router-Aktionen aus:

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 Animationsebene pro Routenänderung. Lassen Sie @capgo/capacitor-transitions normale Seitenpushs animieren, und verwenden Sie die Zoom-Hilfen von Native Navigation nur für gemeinsame-Element- oder Zoom-Routen.

CSS-Einrückungen

Mit contentInsetMode: 'css', schreibt das Plugin native Bar-Dimensionen in 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 serialisierbar sein, weil native UI sie rendern. 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 die icon-fokussierte Teilmenge, die von gängigen Icon-Sets wie Lucide und Feather verwendet wird: path, line, polyline, polygon, circle, und rectSVG-Icons werden als Vorlagenbilder standardmäßig gerendert, sodass native Tint-Farben sie umfarben können.

Optionale Web-Komponenten

Das Paket kann für eine framework-agnostische deklarative Einrichtung 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

und UINavigationBar iOS 26+ verwendet das System-Liquid-Glass-Leiste-Verhalten. UITabBarAndroid renderet eine AppCompat-Leiste und eine Material-Bottom-Navigation.
Web-Fallback zeichnet keine nativen Leisten. Es spiegelt Ereignisse und Einstellvariablen für Browser-Entwicklung wider.
Sektion mit dem Titel 'Plattformhinweise'
Das Plugin hält eine vollbildschirmfähige Capacitor WebView. Die native Eigenschaft besitzt den Rahmen, die Leisten, die sichere Bereichsberichterstattung und die Übergangshülle.

Weiter von Getting Started

Wenn Sie native Medien und Schnittstellenverhalten planen, verbinden Sie es mit Getting Started für die native Fähigkeit in Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation Using @capgo/capacitor-native-navigation für die native Fähigkeit in Using @capgo/capacitor-live-activities Using @capgo/capacitor-live-activities für die Implementierungsdetails in @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.