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 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 à l'égard de 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, src, ou 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 de visualisation le plus transparent. Il marque l'élément en cours de chargement, récupère ou révalide l'asset nativement, puis attribue 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;
}

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

Utiliser 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;

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 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 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 voulez 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é

• L'iOS stocke les fichiers sous Application Support et exclut la racine de la cache des sauvegardes iCloud.
• L'Android stocke les fichiers sous le répertoire de fichiers internes de l'application.
• Le Web utilise le cache du navigateur API et les métadonnées de 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().

La cache est persistante, mais elle n'est pas une barriè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.

Contrôle de cache avancé

La plupart des interfaces utilisateur code devraient utiliser bind, src, ou resolve. Utilisez ces helpers lorsque vous avez besoin d'un contrôl’explicite du cache :

Méthode	Description
get	Résoudre une URL distante en métadonnées de fichiers natifs.
list	Retourner les actifs en cache qui existent toujours sur le disque.
getCacheSize	Retourner le total de bytes en cache.
remove	Supprimer un actif en cache par clé ou URL.
clear	Supprimer tous les actifs en 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