Getting Started

Salin prompt pengaturan dengan langkah instalasi dan panduan markdown lengkap untuk plugin ini.

        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.

Pemasangan

Anda dapat menggunakan Pengaturan Bantu AI kami untuk menginstal plugin. Tambahkan Capgo kemampuan ke alat AI Anda menggunakan perintah berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih suka Pengaturan Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

Pasang paket ini

npm i @capgo/capacitor-native-navigation

Sinkronkan proyek native
Jendela terminal
```
npx cap sync
```

Konfigurasi chrome native

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

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

Tampilkan navbar native

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

Tampilkan tabbar native

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

Tangani event-event intent asli

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

Aliran transisi

Transisi asli adalah transaksi sekeliling perubahan jalur JavaScript normal Anda:

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

Transisi zoom

Gunakan bantuan zoom untuk aliran kartu-ke-detail atau media-prediksi. Kirimkan elemen yang diklik sebelum perubahan router konten, lalu selesai setelah halaman detail siap.

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

Gunakan dengan @capgo/capacitor-transisi

Gunakan Native Navigation untuk navbar native, tabbar, insets area aman, dan event intent native. @capgo/capacitor-transitions Gunakan

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

Salin ke clipboard

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

Salin ke clipboard cap-router-outlet Tetapkan

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

Salin ke clipboard

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

Salin ke clipboard @capgo/capacitor-transitions Animasi normal push halaman, dan gunakan bantuan zoom Native Navigation hanya untuk rute elemen bersama atau zoom.

CSS insets

Dengan contentInsetMode: 'css'Plugin ini menulis dimensi bar native ke document.documentElement.

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

Variabel yang tersedia:

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

Deskriptor ikon

Ikon harus dapat di serialisasi karena antarmuka native mengrender mereka. Anda dapat menggunakan SVG lintas platform, SVG spesifik platform, SF Symbols, gambar iOS yang dibundel, sumber daya drawable Android, atau gambar Android yang dibundel.

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

SVG inline mendukung subset ikon yang difokuskan digunakan oleh set ikon umum seperti Lucide dan Feather: path, line, polyline, polygon, circledan rect. Ikon SVG dirender sebagai gambar template oleh default, sehingga warna tinta asli dapat mengubahnya.

Komponen Web Opsional

Paket ini dapat mendaftarkan elemen-elemen kustom untuk pengaturan deklaratif yang tidak berafiliasi dengan framework:

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>

Catatan Platform

iOS menampilkan UINavigationBar dan UITabBar; iOS 26+ menggunakan perilaku Liquid Glass bar sistem.
Android menampilkan toolbar AppCompat dan navigasi bawah Material.
Pengganti web tidak menarik bar-bar native. Ia mencerminkan event dan variabel inset untuk pengembangan browser.
Plugin ini menjaga WebView penuh layar Capacitor. Native menguasai frame, bar-bar, pelaporan area aman, dan shell transisi.

Lanjutkan dari Getting Started

Jika Anda menggunakan Getting Started untuk merencanakan perilaku media dan interface native, hubungkannya dengan Menggunakan @capgo/capacitor-native-navigation untuk kemampuan asli dalam Menggunakan @capgo/capacitor-native-navigation, Menggunakan @capgo/capacitor-live-activities untuk kemampuan asli dalam Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-live-activities untuk detail implementasi dalam @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kemampuan asli dalam Menggunakan @capgo/capacitor-video-player, dan @capgo/capacitor-video-player untuk detail implementasi dalam @capgo/capacitor-video-player.