Getting Started

Installation

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA à l'aide de la commande suivante :

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

Ensuite, utilisez la prompt suivante :

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

Si vous préférez la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à la plateforme ci-dessous :

1. Installer le package

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

2. Afficher un chargeur natif depuis 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 });

Configurer les valeurs par défaut

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

Chargeur en haut comme Chrome

Utiliser style: 'chrome' lorsque vous voulez la barre de progression du navigateur familier et que la vue Web doit rester utilisable en dessous.

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

Chargeur Edge Siri V2

Utilisez style: 'siri-v2' lorsque l'état de chargement doit être une couleur de mouvement autour de l'application, en lieu et place d'une carte centrée.

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

Progrès de mise à jour

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

Agrandir la fenêtre WebView

Utilisez setWebViewLayout lorsqu'un chargeur natif doit occuper une partie de l'écran tout en gardant le contenu web visible et utilisable.

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

Restaurer la disposition d'origine lorsque la surface native est disparue :

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

Chargeurs Lottie et Image

Packez les fichiers JSON Lottie ou les assets image dans l'application native et référez-les depuis 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',
  },
});

Note

Actifs distants sont pris en charge, mais les actifs natifs encapsulés sont préférables pour les chargeurs de démarrage car ils sont disponibles avant la fin de l'initialisation du réseau et du JavaScript.

Appels Swift natifs

Les autres plugins iOS peuvent appeler directement le chargeur partagé.

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)

Appels Kotlin natifs

Les autres plugins Android peuvent appeler l'objet public à partir de Kotlin ou de 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)

Options communes

Option	Type	Description
style	'siri' | 'siri-v2' | 'chrome' | 'orbit' | 'ring' | 'pulse' | 'dots' | 'bars' | 'wave' | 'halo' | 'lottie' | 'image'	Rendu du chargeur
placement	'center' | 'top' | 'bottom' | 'left' | 'right' | 'fullscreen' | 'around' | 'custom'	Position de la surface native
interactionMode	'passThrough' | 'block' | 'loaderOnly'	Gestion des touches
backgroundColor	string	Couleur de l'overlay, y compris l'alphanumérique
scrimColor	string	Couleur de masque plein écran ou autour de l'écran
colors	string[]	Couleurs de gradient du chargeur
progress	number	Valeur déterminée à partir de 0 Vers 1
autoHide	number	Millisecondes avant de se cacher automatiquement
asset	object	Source de l'asset Lottie ou image

Utiliser reducedMotion: 'system' to respect the user’s platform motion settings.