Langsung ke konten
Capgo - Build, rilis, dan update aplikasi Capacitor Capgo

Panduan Memulai

GitHub

Instalasi

Bagian berjudul “Instalasi”

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

Jendela terminal
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 memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

  1. Instal package

    Jendela terminal
    npm i @capgo/capacitor-native-navigation

  2. Sinkronkan proyek native

    Jendela terminal
    npx cap sync

  3. Konfigurasi native chrome

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

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

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

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

  6. Tangani event native intent

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

Navbar multi-level dengan baris segmen

Bagian berjudul “Navbar multi-level dengan baris segmen”

Gunakan segments ke setNavbar untuk menumpuk baris segmen native di bawah bar, misalnya scope switcher di atas dan tab section di bawahnya. Baris dirender dari atas ke bawah dan masing-masing menambah 44pt (iOS) atau 48dp (Android) ke navbar dan insets yang dilaporkan. iOS menggunakan UISegmentedControl dan glass pills; Android menggunakan Material segmented buttons dan filter chips.

iOSAndroid
Rekaman iOS: mengetuk bagian Account, beralih ke Organization mengubah baris kedua menjadi delapan scrolling chip, memilih BillingRekaman Android: baris segmented Account / Organization di atas scrolling section chips, beralih scope dan memilih Billing
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();

Seleksi berpindah secara native saat pengguna mengetuk, tetapi setiap setNavbar pemanggilan berlaku selectedId lagi. Simpan id yang dipilih di state Anda dan teruskan pada setiap setNavbar panggil; untuk menolak pilihan, kirimkan yang sebelumnya selectedId. Item juga menerima icon, accessibilityLabel, dan enabled. Lewatkan segments: [] untuk menghapus baris. Tersedia sejak 8.13.0.

Alur transisi

Bagian berjudul “Transition flow”

Transisi Native adalah transaksi di sekitar perubahan rute 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

Bagian berjudul “Zoom transition”

Gunakan zoom helpers untuk alur card-to-detail atau media-preview. Masukkan elemen yang diketuk sebelum router mengubah konten, lalu selesaikan 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-transitions

Bagian berjudul “Gunakan dengan @capgo/capacitor-transitions”

Gunakan Native Navigation untuk navbar, tabbar, safe-area insets, dan native intent events bawaan. Gunakan @capgo/capacitor-transitions untuk WebView page stack di bawah native chrome.

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

Inisialisasi kedua package sekali saja:

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

Pertahankan cap-router-outlet fokus pada halaman, bukan menduplikasi web bar:

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

Kendalikan kedua package lewat router action yang sama:

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

Pilih satu layer animasi per perubahan route. Biarkan @capgo/capacitor-transitions animasikan push halaman biasa, dan gunakan zoom helper Native Navigation hanya untuk shared-element atau rute zoom.

Inset CSS

Bagian berjudul “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

Bagian berjudul “Icon descriptors”

Ikon harus dapat diserialisasi karena dirender oleh native UI. Anda bisa menggunakan SVG lintas platform, SVG spesifik platform, SF Symbols, bundled iOS images, Android drawable resources, atau bundled Android images.

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 mendukung subset berbasis ikon yang digunakan oleh icon set populer seperti Lucide dan Feather: path, line, polyline, polygon, circle, dan rect. Ikon SVG secara default dirender sebagai template images, sehingga native tint colors dapat mengubah warnanya.

Web component opsional

Bagian berjudul “Optional web components”

Package ini dapat mendaftarkan custom elements untuk setup deklaratif yang framework-agnostic:

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)

Bagian berjudul “iPhone Duo (iOS 27)”

Pada iPhone Duo, iOS sering menempatkan system tab bar dan status bar di side rail vertikal. env(safe-area-inset-top) bisa 0 sementara left atau right bertambah. Atur viewport-fit=cover pada viewport meta tag Anda saat memberi padding dengan CSS env di mana pun dalam aplikasi. Uji posisi folded, open, landscape, dan Split View di Xcode Device Hub.

Native Navigation menggunakan komponen asli UINavigationBar dan UITabBar, jadi system tab bar mengikuti rail. ini bentuk tab bar tetap di bawah; action tengah tetap memiliki cradle melingkar saat jendela melebar.

Dua layout landscape terbuka. Di kiri, system tab bar berada di rail samping. Di kanan, tab bar curve tetap di bawah, dan action tengah berada dalam cradle melingkar.

Dengan contentInsetMode: 'css', beri padding pada konten web dengan variabel plugin. Gunakan max() dengan fallback env per edge agar layout tetap benar saat variabel plugin 0 tanpa menjumlahkan inset duplikat:

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

Pantau saat safeAreaChanged (atau capNativeNavigation:safeAreaChanged aktif window) saat sisi rail atau status lipatan berubah. Pada tab bar sistem ter-host, insets.tabbarHeight bisa jadi 0 untuk menghindari double bottom padding; gunakan insets.systemTabbarHeight atau --cap-native-system-tabbar-height untuk offset FAB.

Panduan luas Capacitor (viewport-fit, System Bars, Status Bar, testing): Dukungan iPhone Duo di aplikasi Capacitor.

Catatan platform

Bagian berjudul “Catatan platform”
  • Render iOS UINavigationBar dan UITabBar; iOS 26+ menggunakan perilaku bar Liquid Glass bawaan sistem.
  • Android merender toolbar AppCompat dan bottom navigation Material.
  • Fallback web tidak merender bar native. Ini meniru event dan variabel inset untuk pengembangan di browser.
  • Plugin ini mempertahankan satu Capacitor WebView layar penuh. Native mengontrol frame, bar, pelaporan safe-area, dan shell transisi.

Lanjutkan dari Getting Started

Bagian berjudul “Lanjutkan dari Getting Started”

Jika Anda menggunakan Panduan Memulai untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan Menggunakan @capgo/capacitor-native-navigation untuk kapabilitas native di bagian Using @capgo/capacitor-native-navigation, Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-live-activities untuk detail implementasi di @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kemampuan native di Menggunakan @capgo/capacitor-video-player, dan @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player.