Démarrage

Installer

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-asset-cache` plugin in my project.

Si vous préférez la configuration manuelle, installez le plugin en exécutant :

npm install @capgo/capacitor-asset-cache
npx cap sync

Importer

import { AssetCache } from '@capgo/capacitor-asset-cache';

Configurer un CDN

Configurez une URL de base CDN une fois que votre application démarre. Les chemins d'actifs relatifs seront résolus par rapport à cette URL.

AssetCache.configure({
  cdnUrl: 'https://cdn.example.com/assets/',
  revalidate: {
    strategy: 'ttl',
    maxAgeSeconds: 86400,
  },
});

Vous pouvez passer à côté cdnUrl si vous passez des URL absolues à bind, srcou resolve.

const src = await AssetCache.src('https://cdn.example.com/assets/videos/intro.mp4');

Lié à une image ou un vidéo

bind est le chemin d'affichage le plus transparent. Il marque l'élément comme en chargement, récupère ou révalide l'actif nativement, puis attribue l'URL de source locale lorsque le fichier local est prêt.

const image = document.querySelector<HTMLImageElement>('#hero');

if (image) {
  const binding = AssetCache.bind(image, 'images/hero.jpg');
  await binding.promise;
}

<img id="hero" alt="Product preview" />

img[data-asset-cache-state='loading'],
video[data-asset-cache-state='loading'] {
  opacity: 0.45;
}

img[data-asset-cache-state='ready'],
video[data-asset-cache-state='ready'] {
  opacity: 1;
}

Remarque

L'élément ne reçoit jamais l'URL CDN dans le chemin réussi. Il reçoit l'URL de la vue web locale après que l'asset existe dans le stockage de données persistantes.

React

import { useEffect, useRef } from 'react';
import { AssetCache } from '@capgo/capacitor-asset-cache';

AssetCache.configure({ cdnUrl: 'https://cdn.example.com/assets/' });

export function HeroImage() {
  const imageRef = useRef<HTMLImageElement>(null);

  useEffect(() => {
    if (!imageRef.current) return;

    const binding = AssetCache.bind(imageRef.current, 'images/hero.jpg');
    return () => binding.cancel();
  }, []);

  return <img ref={imageRef} alt="Product preview" />;
}

Vue

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue';
import { AssetCache, type AssetCacheBinding } from '@capgo/capacitor-asset-cache';

const image = ref<HTMLImageElement | null>(null);
let binding: AssetCacheBinding | undefined;

onMounted(() => {
  if (image.value) {
    binding = AssetCache.bind(image.value, 'images/hero.jpg', {
      cdnUrl: 'https://cdn.example.com/assets/',
    });
  }
});

onUnmounted(() => binding?.cancel());
</script>

<template>
  <img ref="image" alt="Product preview" />
</template>

Source directe pour l'état du framework

Utilisez-le src lorsque votre framework contrôle déjà la charge et l'état d'erreur. La promesse se résout avec une chaîne de source locale uniquement après l'existence du fichier local.

const src = await AssetCache.src('videos/intro.mp4');

videoElement.src = src;

Utilisez-le resolve lorsque vous avez également besoin de métadonnées :

const source = await AssetCache.resolve('images/hero.jpg');

console.log(source.src, source.local, source.fromCache, source.status);

Actifs Protégés

Transmettez des en-têtes à la requête native Fetch. Cela est utile pour les chemins CDN signés, les médias authentifiés ou les jetons à durée de vie courte.

const src = await AssetCache.src('private/videos/intro.mp4', {
  cdnUrl: 'https://cdn.example.com/assets/',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Les en-têtes sont utilisés par le plugin lors de la récupération ou de la révalidation du fichier distant. La balise d'image ou de vidéo reçoit toujours uniquement l'URL de source locale renvoyée par le plugin.

Revalidation

Définissez une stratégie par défaut avec configure ou la surécrivez pour un seul élément.

await AssetCache.src('videos/intro.mp4', {
  revalidate: {
    strategy: 'etag',
  },
});

Stratégies disponibles :

Stratégie	Utilisez lorsque
never	Un fichier local en cache est suffisant jusqu'à ce que vous le supprimiez explicitement.
ttl	Vous souhaitez une fenêtre de fraîcheur simple.
always	Vous souhaitez que le plugin vérifie l'élément distant à chaque fois.
etag	Votre CDN retourne des en-têtes ETag stables.
last-modified	Votre CDN retourne des en-têtes Last-Modified fiables.

Stockage et Confidentialité

• iOS stocke les fichiers sous Application Support et exclut la racine de la cache des sauvegardes iCloud.
• Android stocke les fichiers sous le répertoire de fichiers internes de l'application.
• Web utilise le cache du navigateur API et localStorage comme fallback de développement.
• Les fichiers cachés sont dissimulés à l'intérieur du sandbox de l'application, et ne sont pas sauvegardés dans les médias utilisateur publics.
• Les fichiers cachés sont supprimés lors de la désinstallation, de la suppression des données de l'application ou de la suppression du plugin. clear() ou remove().

La cache est persistante, mais ce n'est pas une frontière de sécurité par elle-même. Chiffrez les actifs très sensibles avant de les servir si ils doivent rester inaccessibles sur un appareil compromis.

Contrôle Avancé de la Cache

La plupart des UI code devraient utiliser bind, src, ou resolve. Utilisez ces helpers lorsque vous avez besoin d'une gestion explicite de la cache :

Méthode	Description
get	Résolvez une URL distante en métadonnées de fichier natif.
list	Renvoyez les actifs de cache qui existent toujours sur le disque.
getCacheSize	Renvoyez les octets de cache totaux.
remove	Supprimez un actif de cache par clé ou URL.
clear	Supprimez tous les actifs de cache gérés par le plugin.

const asset = await AssetCache.get({
  url: 'https://cdn.example.com/assets/videos/intro.mp4',
  key: 'videos/intro.mp4',
  revalidate: { strategy: 'last-modified' },
});

Référence complète

• GitHub: https://github.com/Cap-go/capacitor-cache-d'actifs/
• Package : @capgo/capacitor-asset-cache