Démarrage

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

1. Installez le package

   npm install @capgo/capacitor-native-loader
   npx cap sync

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

Configurez les valeurs par défaut

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

Chargeur natif Chrome-Style

Utilisez style: 'chrome' lorsque vous souhaitez la barre de progression du navigateur haut de page et que la Vue Web devrait 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 });

Siri V2 Edge Loader

Utilisez style: 'siri-v2' lorsque l'état de chargement doit être une couleur de mouvement autour de l'application écran au lieu 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 });

Mise à jour de la progression

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

Réduire la Vue Web

Utilisez setWebViewLayout lorsque le 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 partie :

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

Chargeurs Lottie et d'images

Packez les fichiers JSON Lottie ou les assets d'images 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',
  },
});

Remarque

Les actifs distants sont pris en charge, mais les actifs natifs encapsulés sont mieux 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 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 communes

Paramètre	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 du toucher
backgroundColor	string	Couleur de l'overlay, y compris l'alphanumérique
scrimColor	string	Couleur de la bande de scrim, plein écran ou autour de l'écran
colors	string[]	Couleurs de la bande de gradient
progress	number	Valeur déterminée à partir de 0 Vers 1
autoHide	number	Temps avant de se cacher automatiquement
asset	object	L'origine de Lottie ou de l'asset d'image

Utilisez reducedMotion: 'system' pour respecter les paramètres de mouvement de la plateforme de l'utilisateur.