Panduan Memulai

Instalasi

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

bunx 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-loader` plugin in my project.

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

1. Instal paketnya

   bun add @capgo/capacitor-native-loader
   bunx cap sync

2. Tampilkan native loader dari JavaScript

   import { NativeLoader } from '@capgo/capacitor-native-loader';
   
   const { id } = await NativeLoader.show({
     style: 'siri',
     placement: 'fullscreen',
     message: 'Preparing workspace',
     colors: ['#71f6ff', '#8b5cf6', '#ff4ecd', '#fff7ad'],
     scrimColor: 'rgba(3, 7, 18, 0.42)',
     interactionMode: 'block',
   });
   
   await doExpensiveWork();
   
   await NativeLoader.hide({ id });

Mulai cepat

import { NativeLoader } from '@capgo/capacitor-native-loader';

await NativeLoader.configure({ defaults: {} });

Contoh: tampilkan

import { NativeLoader } from '@capgo/capacitor-native-loader';

const result = await NativeLoader.show();
console.log(result);

Contoh: update

import { NativeLoader } from '@capgo/capacitor-native-loader';

await NativeLoader.update({ id: 'id-123' });

Masalah umum

• Inisialisasi sekali saja: jalankan setup saat bootstrap aplikasi.
• Sinkronisasi native: jalankan bunx cap sync setelah upgrade plugin.
• Sumber kebenaran: percaya src/definitions.ts pada repo GitHub.

Konfigurasi Default

await NativeLoader.configure({
  defaults: {
    style: 'orbit',
    placement: 'center',
    size: 96,
    colors: ['#38bdf8', '#a78bfa'],
    reducedMotion: 'system',
    interactionMode: 'passThrough',
  },
});

Top Loader ala Chrome

Gunakan style: 'chrome' saat Anda ingin progress bar browser yang familiar dan WebView tetap bisa digunakan di bawahnya.

const { id } = await NativeLoader.show({
  style: 'chrome',
  placement: 'top',
  colors: ['#4285f4', '#34a853', '#fbbc05', '#ea4335'],
  thickness: 4,
  interactionMode: 'passThrough',
  webView: {
    mode: 'resize',
    insets: { top: 12 },
    restoreOnHide: true,
  },
});

await NativeLoader.hide({ id, restoreWebView: true });

Siri V2 Edge Loader

Gunakan style: 'siri-v2' saat loading state harus berupa animasi warna native full-screen di pinggiran app, bukan berupa card di tengah.

const { id } = await NativeLoader.show({
  style: 'siri-v2',
  placement: 'fullscreen',
  colors: ['#71f6ff', '#8b5cf6', '#ff4ecd', '#fff7ad'],
  thickness: 10,
  scrimColor: 'rgba(3, 7, 18, 0.10)',
  interactionMode: 'passThrough',
});

await NativeLoader.hide({ id });

Progres Update

const { id } = await NativeLoader.show({
  style: 'ring',
  message: 'Uploading',
  progress: 0,
});

for await (const progress of uploadFile(file)) {
  await NativeLoader.setProgress({ id, progress });
}

await NativeLoader.hide({ id });

Resize WebView

Gunakan setWebViewLayout ketika native loader harus menguasai sebagian layar sementara konten web tetap terlihat dan bisa digunakan.

await NativeLoader.setWebViewLayout({
  mode: 'inset',
  insets: { top: 96, bottom: 24 },
  animated: true,
});

await NativeLoader.show({
  style: 'wave',
  placement: 'top',
  size: 72,
  message: 'Syncing',
  interactionMode: 'passThrough',
});

Kembalikan layout asli saat native surface sudah tidak ada:

await NativeLoader.hideAll({ restoreWebView: true });

Lottie Dan Image Loaders

Bundle aset Lottie JSON atau gambar di dalam native app dan referensikan dari JavaScript.

await NativeLoader.show({
  style: 'lottie',
  placement: 'center',
  asset: {
    type: 'lottie',
    source: 'rocket-loader.json',
    loop: true,
  },
});

await NativeLoader.show({
  style: 'image',
  placement: 'bottom',
  asset: {
    type: 'image',
    source: 'loader-frame',
  },
});

Catatan

Aset remote didukung, namun aset native yang dibundle lebih baik untuk startup loader karena sudah tersedia sebelum proses networking dan inisialisasi JavaScript selesai.

Pemanggilan Native Swift

Plugin iOS lainnya dapat memanggil shared loader secara langsung.

import CapgoCapacitorNativeLoader

let id = NativeLoader.shared.show(options: [
  "style": "siri",
  "placement": "fullscreen",
  "message": "Opening secure session",
  "interactionMode": "block"
])

NativeLoader.shared.setProgress(id: id, progress: 0.6)
NativeLoader.shared.hide(id: id)

Pemanggilan Native Kotlin

Plugin Android lainnya dapat memanggil public object dari Kotlin atau Java.

import app.capgo.nativeloader.NativeLoader

val id = NativeLoader.show(
  activity = activity,
  options = mapOf(
    "style" to "orbit",
    "placement" to "fullscreen",
    "message" to "Loading profile",
    "interactionMode" to "block",
  ),
  webView = bridge.webView,
)

NativeLoader.setProgress(id, 0.6)
NativeLoader.hide(id)

Common Options

Opsi	Tipe	Deskripsi
style	'siri' | 'siri-v2' | 'chrome' | 'orbit' | 'ring' | 'pulse' | 'dots' | 'bars' | 'wave' | 'halo' | 'lottie' | 'image'	Renderer loader
placement	'center' | 'top' | 'bottom' | 'left' | 'right' | 'fullscreen' | 'around' | 'custom'	Posisi surface native
interactionMode	'passThrough' | 'block' | 'loaderOnly'	Penanganan sentuhan
backgroundColor	string	Warna overlay, termasuk alpha
scrimColor	string	Warna scrim fullscreen atau sekitar layar
colors	string[]	Warna gradasi loader
progress	number	Sumber nilai determinate 0 ke 1
autoHide	number	Milidetik sebelum sembunyi otomatis
asset	object	Sumber aset gambar atau Lottie

Gunakan reducedMotion: 'system' untuk menghormati pengaturan motion pada platform pengguna.