Getting Started

GitHub

Kopieren Sie einen Einrichtungsprompt mit den Installationsanweisungen und der vollständigen Markdown-Guideline 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 AI-gestützte Einrichtung verwenden, um den Plugin zu installieren. Fügen Sie die Capgo Fähigkeiten zu Ihrem KI-Tool hinzu, indem Sie die folgende Befehl ausführen:

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

Dann verwenden Sie 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 das Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den Plattform-spezifischen Anweisungen unten:

Install die Pakete

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

Übergang

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 card-to-detail oder media-preview-Flows. Geben Sie das getippte Element vor dem Wechsel Ihres Routen-Content ein, 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 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',
});

Behalten Sie sich auf den Seiten, nicht Duplikate von Web-Bars: cap-router-outlet Auf die Zwischenablage kopieren

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

Auf die Zwischenablage kopieren

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

__CAPGO_KEEP_0__ @capgo/capacitor-transitions animate normale Seitenverschiebungen und verwenden Sie die Zoom-Hilfen von Native Navigation nur für gemeinsame Elemente oder Zoom- Routen.

CSS-Einrückungen

Mit contentInsetMode: 'css', das 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

Ikondescriptoren

Ikons müssen serialisierbar sein, da 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 ikon-zentrierte Teilmenge, die 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-Unterseite-Navigation.
Die Web-Fallback-Version zeichnet native Leisten nicht. Sie spiegelt Ereignisse und Inset-Variablen für Browser-Entwicklung wider.
Der Plugin hält eine vollbildschirmige Capacitor WebView aufrecht. 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 planen, verbinden Sie es mit Getting Started Verwenden Sie @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation Um native Medien und Schnittstellenverhalten zu planen, verbinden Sie es mit @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 Implementierungsdetail 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 Implementierungsdetail in @capgo/capacitor-video-player.