Panduan Memulai

Instalasi

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command 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 memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

1. Instal package

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

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

Kesalahan umum

• Inisialisasi sekali saja: jalankan setup saat app bootstrap.
• Sinkronisasi Native: jalankan bunx cap sync setelah upgrade plugin.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Konfigurasi Default

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

Loader Atas Gaya Chrome

Gunakan style: 'chrome' saat Anda ingin progress bar atas khas browser 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 status loading harus berupa animasi warna native full-screen di sepanjang tepi aplikasi, bukan kartu 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 });

Ubah Ukuran WebView

Gunakan setWebViewLayout ketika native loader harus memiliki sebagian layar sementara konten web tetap terlihat dan dapat 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',
});

Pulihkan tata letak asli ketika permukaan native sudah hilang:

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

Loader Lottie dan Gambar

Bundle aset Lottie JSON atau gambar di aplikasi native dan rujuk 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, tapi aset native yang dibundle lebih baik untuk startup loader karena sudah tersedia sebelum networking dan inisialisasi JavaScript selesai.

Pemanggilan Swift Native

Plugin iOS lain bisa 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 lain bisa 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 permukaan native
interactionMode	'passThrough' | 'block' | 'loaderOnly'	Penanganan sentuhan
backgroundColor	string	Warna overlay, termasuk alpha
scrimColor	string	Warna scrim fullscreen atau di sekitar layar
colors	string[]	Warna gradien loader
progress	number	Nilai determinate dari 0 ke 1
autoHide	number	Milidetik sebelum disembunyikan secara otomatis
asset	object	Sumber aset Lottie atau gambar

Gunakan reducedMotion: 'system' untuk menghormati pengaturan gerakan platform pengguna.