Inizio

Installa

Puoi utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo abilità al tuo strumento AI utilizzando il seguente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Poi utilizza la seguente richiesta:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-asset-cache` plugin in my project.

Se preferisci la configurazione manuale, installa il plugin eseguendo:

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

Importa

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

Configura un CDN

Configura l'URL base del CDN una volta che l'applicazione inizia. Le percorrenze relative degli asset saranno risolte in base a questo URL.

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

Puoi saltare cdnUrl se passi URL assoluti a bind, src, o resolve.

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

Lega un'Immagine o un Video

bind è il percorso di visualizzazione più trasparente. Segna l'elemento come in carico, recupera o riconvalida l'asset nativamente, quindi assegna l'URL di origine locale quando il file locale è pronto.

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

Nota

L'elemento non riceve mai l'URL CDN nella via di successo. Riceve l'URL del webview locale dopo che l'asset esiste nel storage persistente.

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>

Fonte diretta per lo stato del framework

Usa src quando il tuo framework controlla già lo stato di caricamento e gli errori. La promessa si risolve con una stringa di fonte locale solo dopo che il file locale esiste.

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

videoElement.src = src;

Usa resolve quando hai anche bisogno di metadati:

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

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

Asset protetti

Passa intestazioni al fetch nativo. Questo è utile per percorsi CDN firmati, media autenticati o token a breve scadenza.

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

Le intestazioni vengono utilizzate dal plugin mentre si effettua il fetch o si rivalida il file remoto. L'immagine o il tag video riceve comunque solo l'URL di fonte locale restituito dal plugin.

Rivalutazione

Imposta una strategia di default con configure o sovrascrivila per un singolo asset.

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

Strategie disponibili:

Strategia	Usa quando
never	Un file locale memorizzato è sufficiente fino a quando non lo rimuovi esplicitamente.
ttl	Vuoi una semplice finestra di freschezza.
always	Vuoi che il plugin controlli l'asset remoto ogni volta.
etag	Il tuo CDN restituisce intestazioni ETag stabili.
last-modified	La tua CDN restituisce intestazioni Last-Modified affidabili.

Storage E Riservatezza

• L'iOS memorizza i file sotto Application Support e esclude la radice della cache dal backup iCloud.
• L'Android memorizza i file sotto la directory dei file interni dell'applicazione.
• Web utilizza il Cache API e localStorage dei metadati come fallback di sviluppo.
• I file memorizzati sono nascosti all'interno del sandbox dell'applicazione, non salvati nella media pubblica dell'utente.
• I file memorizzati vengono eliminati alla disinstallazione, pulizia dei dati dell'applicazione o plugin clear() o remove().

Il cache è persistente, ma non è un confine di sicurezza da solo. Cripta gli asset altamente sensibili prima di servirli se devono rimanere inaccessibili su un dispositivo compromesso.

Controllo Avanzato del Cache

La maggior parte degli elementi UI code dovrebbero utilizzare bind, srco resolve. Utilizza questi aiuti quando hai bisogno di una gestione cache esplicita:

Metodo	Descrizione
get	Risolve una URL remota in metadati di file nativi.
list	Restituisce asset cached che ancora esistono sul disco.
getCacheSize	Restituisce il totale di byte cached.
remove	Elimina un asset cached per chiave o URL.
clear	Elimina ogni asset cached gestito dal plugin.

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

Riferimento Completo

• GitHub: https://github.com/Cap-go/capacitor-cache-assegni/
• Pacchetto: @capgo/capacitor-asset-cache