Prise en main

Installation

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA en utilisant 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 au plateforme ci-dessous :

1. Installez le package

   npm install @capgo/capacitor-native-loader
   npx 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 dans Chrome

Utiliser style: 'chrome' Lorsque vous souhaitez une barre de progression de navigateur familière 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 d'Edge Siri V2

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

Redimensionner La Vue Web

Utiliser 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 disparue :

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

Chargeurs Lottie et d'images

Packager les JSON Lottie ou les actifs d'image dans l'application native et les référencer 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 empaqueté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 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 à partir de 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

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

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