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 à la plateforme ci-dessous :

1. Installer 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 Chrome

Utilisez style: 'chrome' lorsque vous souhaitez une barre de progression de 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 de bordure édgel V2 de Siri

Utilisez 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 du progrès

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 Vue Web

Utiliser setWebViewLayout Lorsqu'un chargeur natif doit posséder 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 });

Lottie et chargeurs d'image

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

Remarque

Les assets distants sont pris en charge, mais les assets natifs empaquetés sont mieux pour les chargeurs de démarrage car ils sont disponibles avant la fin de l'initialisation de la 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 natifs Kotlin

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 courantes

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 du toucher
backgroundColor	string	Couleur de l'overlay, y compris l'alphanumérique
scrimColor	string	Couleur de la masque de plein écran ou de l'écran autour
colors	string[]	Couleurs de gradient du chargeur
progress	number	Valeur déterminante de 0 à 1
autoHide	number	Millisecondes avant de se cacher automatiquement
asset	object	Source de l'asset Lottie ou image

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