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 à 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-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 cdnUrl si vous passez des adresses URL absolues à bind, src, ou resolve.

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

lier une image ou un vidéo

bind est le chemin d'affichage le plus transparent. Il marque l'élément en cours de chargement, récupère ou révalide l'asset nativement, puis affecte 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 persistant.

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 Direct Pour L'état Du Framework

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

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

videoElement.src = src;

Utilisez 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

Transmettre les en-têtes au fetch natif. 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 uniquement l'URL de source locale retournée par le plugin.

Révalidation

Définir une stratégie par défaut avec configure ou la surcharger pour un actif.

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'asset 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 de la sauvegarde iCloud.
• Les fichiers Android sont stockés dans le répertoire de fichiers internes de l'application.
• Web utilise le cache du navigateur API et les métadonnées de 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 mise à jour d'un plugin. clear() La cache est persistante, mais ce n'est pas une frontière de sécurité par elle-même. Cryptez les actifs sensibles avant de les servir si ils doivent rester inaccessibles sur un appareil compromis. remove().

Contrôle Avancé de la Cache

Section intitulée “Contrôle Avancé de la Cache”

Most UI code should use bind, srcUtilisez ces helpers lorsque vous avez besoin d'une gestion explicite de la cache : resolveMéthode

Les fichiers Android sont stockés dans le répertoire de fichiers internes de l'application.	Description
get	Résoudre une URL distante en métadonnées de fichiers natifs.
list	Renvoyer des actifs cachés qui existent toujours sur le disque.
getCacheSize	Renvoyer le total de bytes cachés.
remove	Supprimer un actif caché par clé ou URL.
clear	Supprimer tous les actifs cachés 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-asset-cache/
• Package : @capgo/capacitor-asset-cache