Panduan Memulai

Instalasi

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command 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-transitions` 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

   npm install @capgo/capacitor-transitions

2. Daftarkan web components

   import '@capgo/capacitor-transitions';

3. Bungkus routed pages

   <cap-router-outlet platform="auto" swipe-gesture="auto">
     <cap-page>
       <cap-header slot="header">
         <h1>Inbox</h1>
       </cap-header>
   
       <cap-content slot="content">
         <button>Open message</button>
       </cap-content>
   
       <cap-footer slot="footer">
         <nav>Tabs</nav>
       </cap-footer>
     </cap-page>
   </cap-router-outlet>

4. Atur arah sebelum router berpindah route

   import { setDirection } from '@capgo/capacitor-transitions/react';
   
   setDirection('forward');
   router.push('/message/42');
   
   setDirection('back');
   router.back();

Catatan

Tidak ada langkah sinkronisasi native untuk paket ini. Paket ini berjalan di web layer aplikasi Capacitor Anda.

Setup React

import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
import '@capgo/capacitor-transitions';

initTransitions({ platform: 'auto' });

export function AppShell() {
  const outletRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (!outletRef.current) return;

    setupRouterOutlet(outletRef.current, {
      platform: 'auto',
      swipeGesture: 'auto',
    });
  }, []);

  return (
    <cap-router-outlet ref={outletRef}>
      {/* Your router renders cap-page children here. */}
    </cap-router-outlet>
  );
}

export function InboxPage() {
  const navigate = useNavigate();
  const pageRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (!pageRef.current) return;

    return setupPage(pageRef.current, {
      onDidEnter: () => console.log('Inbox visible'),
    });
  }, []);

  return (
    <cap-page ref={pageRef}>
      <cap-header slot="header">
        <h1>Inbox</h1>
      </cap-header>

      <cap-content slot="content">
        <button
          onClick={() => {
            setDirection('forward');
            navigate('/message/42');
          }}
        >
          Open message
        </button>
      </cap-content>
    </cap-page>
  );
}

React JSX TypeScript

Mengimpor dari @capgo/capacitor-transitions/react menyertakan typings JSX untuk cap-router-outlet, cap-page, cap-header, cap-content, dan cap-footer. Di sebagian besar proyek React, import tersebut otomatis membuat custom elements valid di TSX.

Jika TypeScript masih melaporkan Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements', tambahkan file deklarasi proyek:

src/capgo-transitions.d.ts

import '@capgo/capacitor-transitions/react';

Untuk Vite, Create React App, dan sebagian besar aplikasi React webpack, cukup letakkan file tersebut di dalam src/ Untuk Next.js, letakkan di src/ atau root proyek dan pastikan tsconfig.json menyertakannya:

{
  "include": ["src", "src/capgo-transitions.d.ts"]
}

Untuk setup TypeScript atau webpack kustom yang menggunakan folder types/ terpisah, sertakan folder tersebut sebagai gantinya:

{
  "include": ["src", "types"]
}

Geser Kembali

Aktifkan atau nonaktifkan edge gesture iOS dari markup:

<cap-router-outlet swipe-gesture="auto"></cap-router-outlet>
<cap-router-outlet swipe-gesture="true"></cap-router-outlet>
<cap-router-outlet swipe-gesture="false"></cap-router-outlet>

Atau dari JavaScript:

const outlet = document.querySelector('cap-router-outlet');

outlet?.setSwipeGesture('auto');
outlet?.setSwipeGesture(true);
outlet?.setSwipeGesture(false);

auto hanya mengaktifkan gesture jika Capacitor melaporkan runtime iOS native. Saat gesture berlangsung, transisi halaman mengikuti gerakan jari. Saat user melepas, transisi akan selesai dan meminta browser history untuk kembali, atau dibatalkan dan memulihkan halaman saat ini.

Agar elemen tertentu tidak memicu gesture, tambahkan data-swipe-gesture-ignore:

<button data-swipe-gesture-ignore>Open drawer</button>

Dengan Native Navigation

Gunakan @capgo/capacitor-transitions dengan @capgo/native-navigation ketika native harus mengontrol bar atas dan bawah, sementara konten web tetap menggunakan gerakan halaman gaya Ionic.

1. Install dan sync package native navigation:

   npm install @capgo/native-navigation
   npx cap sync

2. Konfigurasi chrome native:

   import { NativeNavigation } from '@capgo/native-navigation';
   
   await NativeNavigation.configure({
     contentInsetMode: 'css',
   });
   
   await NativeNavigation.setNavbar({
     title: 'Inbox',
     backButton: { visible: false },
   });

3. Biarkan web transition outlet hanya bertanggung jawab untuk halaman:

   <cap-router-outlet platform="auto" swipe-gesture="auto">
     <cap-page>
       <cap-content slot="content" fullscreen>
         <main class="native-page">Inbox content</main>
       </cap-content>
     </cap-page>
   </cap-router-outlet>

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

4. Jalankan kedua sistem dari router events yang sama:

   import { NativeNavigation } from '@capgo/native-navigation';
   import { setDirection } from '@capgo/capacitor-transitions/react';
   import { router } from './router';
   
   await NativeNavigation.addListener('navbarBack', () => {
     setDirection('back');
     router.back();
   });
   
   async function openMessage(id: string) {
     setDirection('forward');
     router.push(`/message/${id}`);
   
     await NativeNavigation.setNavbar({
       title: 'Message',
       backButton: { visible: true, title: 'Inbox' },
     });
   }

Jangan render ulang native top bar sebagai elemen yang bergerak <cap-header>. Biarkan @capgo/native-navigation bar tetap native dan gunakan @capgo/capacitor-transitions untuk konten halaman WebView di bawahnya.

Komponen

<cap-router-outlet>

Atribut	Tipe	Default	Deskripsi
platform	'ios' | 'android' | 'auto'	'auto'	Gaya animasi
duration	number	Default platform	Durasi animasi dalam milidetik
keep-in-dom	boolean	true	Simpan halaman tidak aktif di DOM
max-cached	number	10	Maksimal halaman yang di-cache
swipe-gesture	boolean | 'auto'	'auto'	Aktifkan, nonaktifkan, atau deteksi otomatis gesture edge iOS

Metode:

• push(element, config?)
• pop(config?)
• setRoot(element, config?)
• setSwipeGesture(true | false | 'auto')

<cap-page>

Membungkus satu halaman dan memancarkan lifecycle events:

• cap-will-enter
• cap-did-enter
• cap-will-leave
• cap-did-leave

<cap-content>

Atribut	Tipe	Default	Deskripsi
fullscreen	boolean	false	Biarkan konten scroll di belakang header
scroll-x	boolean	true	Aktifkan horizontal scrolling
scroll-y	boolean	true	Aktifkan vertical scrolling

Helper Framework

Entrypoint framework menyediakan core helper yang sama:

import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });
setDirection('forward');
setupRouterOutlet(element, { platform: 'auto', swipeGesture: 'auto' });
setupPage(element, { onWillEnter, onDidEnter, onWillLeave, onDidLeave });

Entrypoint yang tersedia:

• @capgo/capacitor-transitions/react
• @capgo/capacitor-transitions/vue
• @capgo/capacitor-transitions/angular
• @capgo/capacitor-transitions/svelte
• @capgo/capacitor-transitions/solid

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan migrasi dan operasional enterprise, hubungkan dengan Menggunakan @capgo/capacitor-transitions untuk kapabilitas native saat menggunakan @capgo/capacitor-transitions, Capgo Enterprise untuk workflow produk di Capgo Enterprise, Alternatif Plugin Ionic Enterprise untuk workflow produk di Alternatif Plugin Ionic Enterprise, Alternatif Capgo untuk alur kerja produk di Capgo Alternatives, dan Konsultasi Capgo untuk alur kerja produk di Capgo Consulting.