Zum Inhalt springen
Capgo - Capacitor-Apps bauen, ausliefern und updaten Capgo

Erste Schritte

GitHub

Installation

Abschnitt mit dem Titel „Installation“

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

  1. Paket installieren

    Terminalfenster
    npm i @capgo/capacitor-native-navigation

  2. Native Projekte synchronisieren

    Terminalfenster
    npx cap sync

  3. Native Chrome konfigurieren

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

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

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

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

  6. Native Intent-Events 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}`);
    });

Mehrstufige Navbar mit Segmentzeilen

Abschnitt: „Mehrstufige Navbar mit Segmentzeilen“

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

iOSAndroid
iOS-Aufnahme: Tippen auf Account-Bereiche, Wechsel zu Organization tauscht die zweite Reihe gegen acht scrollbare Chips aus, Auswahl von BillingAndroid-Aufnahme: Segmentierte Account/Organization-Reihe über scrollbaren Bereichs-Chips, Scope wechseln und Billing auswählen
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.

Transition-Flow

Abschnitt „Transition flow“

Native Transitions sind eine Transaktion um deinen normalen JavaScript-Route-Change herum:

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

Abschnitt: „Zoom-Übergang“

Nutze die Zoom-Helfer für Card-to-Detail- oder Media-Preview-Flows. Übergib das getippte Element, bevor dein Router den Inhalt ändert, und schließe den Vorgang ab, sobald 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,
  });
}

Mit @capgo/capacitor-transitions nutzen

Abschnitt: „Verwendung mit @capgo/capacitor-transitions“

Nutze Native Navigation für die native Navbar, Tabbar, Safe-Area-Insets und native Intent-Events. Nutze @capgo/capacitor-transitions für den WebView-Page-Stack unterhalb der nativen Chrome.

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

Behalten cap-router-outlet Fokus auf Seiten, nicht auf doppelte 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>

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 normale Page-Pushes animieren und nutze die Zoom-Helper von Native Navigation nur für Shared-Element- oder Zoom-Routen.

CSS-Insets

Abschnitt mit dem Titel „CSS insets“

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

Abschnitt „Icon descriptors“

Icons müssen serialisierbar sein, da sie vom nativen UI gerendert werden. Du kannst plattformübergreifende SVGs, plattformspezifische SVGs, SF Symbols, gebündelte iOS-Bilder, Android Drawable-Ressourcen oder gebündelte 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 in gängigen Icon-Sets wie Lucide und Feather verwendet wird: path, line, polyline, polygon, circle, und rect. SVG-Icons werden standardmäßig als Template-Images gerendert, sodass sie durch native Tint Colors umgefärbt werden können.

Optionale Web-Components

Abschnitt „Optional web components“

Das Package kann Custom Elements für ein framework-agnostisches, deklaratives Setup 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>

iPhone Duo (iOS 27)

Abschnitt mit dem Titel „iPhone Duo (iOS 27)“

Auf dem iPhone Duo platziert iOS die System-Tabbar und die Statusbar oft in einer vertikalen Seitenleiste. env(safe-area-inset-top) kann 0 während left oder right wächst. Setze viewport-fit=cover auf deinem Viewport-Meta-Tag, wenn du irgendwo in der App mit CSS env paddingst. Teste geklappte, offene, Querformat- und Split-View-Zustände im Xcode Device Hub.

Native Navigation nutzt echte UINavigationBar und UITabBar, also System-Tab-Bars folgen der Rail. Die Kurve Die Tab-Bar-Form bleibt unten; die Center-Action behält eine kreisförmige Aufnahme, wenn das Fenster breiter wird.

Zwei offene Querformat-Layouts. Links sitzt die System-Tab-Bar in der seitlichen Rail. Rechts bleibt die Kurven-Tab-Bar unten, und die Center-Action sitzt in einer kreisförmigen Aufnahme.

Mit contentInsetMode: 'css', gib Web-Content per Plugin-Variablen Padding. Nutze max() mit env-Fallbacks pro Kante, damit das Layout korrekt bleibt, wenn eine Plugin-Variable 0 ohne doppelte Insets zu addieren:

main {
  padding-top: max(var(--cap-native-navigation-top, 0px), env(safe-area-inset-top, 0px));
  padding-right: max(var(--cap-native-navigation-right, 0px), env(safe-area-inset-right, 0px));
  padding-bottom: max(var(--cap-native-navigation-bottom, 0px), env(safe-area-inset-bottom, 0px));
  padding-left: max(var(--cap-native-navigation-left, 0px), env(safe-area-inset-left, 0px));
}

Listen for safeAreaChanged (oder capNativeNavigation:safeAreaChanged auf window) wenn sich der Rail- oder Fold-Status ändert. Bei Tab-Bars in gehosteten Systemen insets.tabbarHeight könnte 0 um doppeltes Bottom-Padding zu vermeiden; verwende insets.systemTabbarHeight oder --cap-native-system-tabbar-height für FAB-Offsets.

Capacitor-weite Anleitung (viewport-fit, System Bars, Status Bar, Testing): iPhone Duo in Capacitor-Apps unterstützen.

Plattform-Hinweise

Abschnitt mit dem Titel „Plattform-Hinweise“
  • iOS rendert UINavigationBar und UITabBar; iOS 26+ nutzt das systemeigene Liquid-Glass-Bar-Verhalten.
  • Android rendert eine AppCompat-Toolbar und Material Bottom Navigation.
  • Der Web-Fallback zeichnet keine nativen Bars. Er spiegelt Events und Inset-Variablen für die Browser-Entwicklung wider.
  • Das Plugin hält eine einzige Fullscreen-Capacitor-WebView. Native übernimmt den Frame, die Bars, das Safe-Area-Reporting und die Transition-Shell.

Weiter geht's nach Getting Started

Abschnitt: „Weiter geht’s mit Getting Started“

Wenn du es nutzt Erste Schritte , um natives Media- und Interface-Verhalten zu planen, verbinde es mit Verwendung von @capgo/capacitor-native-navigation für die native Funktionalität bei der Nutzung von @capgo/capacitor-native-navigation, @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, Verwendung von @capgo/capacitor-video-player für die native Funktion in „@capgo/capacitor-video-player verwenden“, und @capgo/capacitor-video-player für das Implementierungsdetail in @capgo/capacitor-video-player.