Prise en main

Installation

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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 une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

1. Installer le package

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

2. Afficher un loader 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 });

Démarrage rapide

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

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

Exemple : show

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

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

Exemple : mise à jour

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

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

Erreurs courantes

• Initialiser une seule fois: exécutez le setup lors du bootstrap de l'app.
• Sync native : exécuter bunx cap sync après les mises à jour du plugin.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Configurer les paramètres par défaut

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

Loader supérieur style Chrome

Utiliser style: 'chrome' lorsque vous voulez la barre de progression en haut familière du navigateur, la WebView restant 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 });

Loader edge style Siri V2

Utiliser style: 'siri-v2' lorsque l'état de chargement doit être une animation de couleurs native plein écran sur le bord de l'app plutôt qu'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 });

Progression de la 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 });

Redimensionner la WebView

Utiliser setWebViewLayout lorsqu'un loader natif doit occuper une partie de l'écran tout en laissant 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 mise en page d'origine quand la surface native disparaît :

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

Loaders Lottie et images

Incluez les assets Lottie JSON ou images dans le bundle de l'app native et référencez-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',
  },
});

Remarque

Les assets distants sont pris en charge, mais les assets natifs inclus dans le bundle sont préférables pour les loaders de démarrage, car ils sont disponibles avant la fin de l’initialisation du réseau et de 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 depuis Kotlin ou 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 courantes

Option	Type	Description
style	'siri' | 'siri-v2' | 'chrome' | 'orbit' | 'ring' | 'pulse' | 'dots' | 'bars' | 'wave' | 'halo' | 'lottie' | 'image'	Renderer du loader
placement	'center' | 'top' | 'bottom' | 'left' | 'right' | 'fullscreen' | 'around' | 'custom'	Position de la surface native
interactionMode	'passThrough' | 'block' | 'loaderOnly'	Gestion du tactile
backgroundColor	string	Couleur de l’overlay, alpha compris
scrimColor	string	Couleur du scrim plein écran ou périphérique
colors	string[]	Couleurs du dégradé du loader
progress	number	Valeur déterminée à partir de 0 vers 1
autoHide	number	Délai en millisecondes avant masquage automatique
asset	object	Source de l’asset Lottie ou de l’image

Utiliser reducedMotion: 'system' pour respecter les réglages de mouvement de sa plateforme.