Démarrage rapide

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

Associer 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 la 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;
}

Note

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

Utiliser src Lorsque votre framework contrôle déjà la charge et l'état d'erreur. La promesse se résout par 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;

Utiliser 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 des en-têtes à la requête native. 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 vidéo reçoit uniquement l'URL de la source locale renvoyée par le plugin.

Révalidation

Définir une stratégie par défaut avec configure ou la remplacer pour un seul élément.

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

Stratégies disponibles :

Stratégie	Utiliser 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'actif 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.
• Le navigateur utilise le Cache API et localStorage comme fallback de développement.
• Les fichiers stockés sont cachés à l'intérieur du sandbox de l'application, et ne sont pas sauvegardés dans les médias utilisateur publics.
• Les fichiers stocké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().

Le cache est persistant, mais il ne constitue pas une frontière de sécurité par lui-même. Chiffrez les actifs très sensibles avant de les servir si ils doivent rester inaccessibles sur un appareil compromis.

Contrôl’Avancé de Cache

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

Méthode	Description
get	Résolvez une URL distante en métadonnées de fichiers natives.
list	Renvoyez les actifs cachés qui existent toujours sur le disque.
getCacheSize	Renvoyez les octets cachés totaux.
remove	Supprimez un actif caché par clé ou URL.
clear	Supprimez 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-cache-d'actifs/
• Package : @capgo/capacitor-asset-cache