Getting Started

GitHub

Kopieren Sie einen Einrichtungsprompt mit den Installationsanweisungen und der vollständigen Markdown-Dokumentation für dieses Plugin.

        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 unsere KI-gestützte Einrichtung verwenden, um den Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten zu Ihrer KI-Anwendung hinzu, indem Sie die folgende Befehlszeile verwenden:

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 Einrichtung bevorzugen, installieren Sie den Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den unten angegebenen Plattform-spezifischen Anweisungen:

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-Flows. Geben Sie das angeklickte Element vor dem Wechsel des Inhalts Ihres Routern an, 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-Page-Stack unter 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',
});

Bleiben Sie cap-router-outlet fokussiert auf Seiten, nicht auf Duplikate von 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 Animationsschicht pro Routenänderung. Lassen Sie @capgo/capacitor-transitions normalen Seitenverschiebungen animieren und verwenden Sie die Zoom-Hilfen von Native Navigation nur für gemeinsame Elemente oder Zoom-Routen.

CSS-Einrückungen

Mit contentInsetMode: 'css', schreibt der Plugin die nativen 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, da 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, circle, und rect. SVG Icons werden als Vorlagenbilder standardmäßig gerendert, sodass native Tintfarben sie neu einfärben können.

Optionale Web-Komponenten

Das Paket kann benutzerdefinierte Elemente für eine framework-agnostische deklarative Einrichtung 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 UITabBariOS 26+ verwendet das System-Liquid-Glas-Leiste-Verhalten.
Android rendert eine AppCompat-Leiste und eine Material-Unterleiste.
Die Web-Fallback-Version zeichnet native Leisten nicht. Sie spiegelt Ereignisse und Einstellvariablen für Browser-Entwicklung wider.
Der Plugin hält eine vollbildschirmige Capacitor-Ansicht auf. Die Native-App besitzt den Rahmen, die Leisten, die sichere Bereichsberichterstattung und die Übergangshülle.

Weitermachen von Getting Started

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