Iniziare

Installazione

Puoi utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo competenze 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

Importazione

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

Configura un CDN

Configura l'URL base del CDN una volta che il tuo app inizia. Le percorrenze degli asset relativi saranno risolte rispetto a questo URL.

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

Potresti saltare cdnUrl se passi URL assoluti a bind, srco resolve.

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

Leggi un'immagine o un video

bind è la via di visualizzazione più trasparente. Segna l'elemento come in carico, recupera o riconvalida l'asset nativamente, quindi assegna l'URL della fonte 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 persistente archivio.

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à caricamento e stato di errore. La promessa si risolve con una stringa di origine locale solo dopo che il file locale esiste.

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

videoElement.src = src;

Usa resolve quando hai bisogno anche di metadati:

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

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

Asset protetti

Passa intestazioni alla fetch nativa. Ciò è 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}`,
  },
});

Il plugin utilizza le intestazioni durante il recupero o la riconvalidazione del file remoto. L'immagine o il tag video riceve solo l'URL di origine locale restituito dal plugin.

Riconvalidazione

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	Utilizza quando
never	Un file locale memorizzato è sufficiente fino a quando non lo rimuovi esplicitamente.
ttl	Desideri 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	Il tuo CDN restituisce intestazioni Last-Modified affidabili.

Archiviazione E Riservatezza

• iOS archivia i file sotto Application Support e esclude la radice della cache dal backup iCloud.
• Android archivia 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().

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

Controllo Cache Avanzato

La maggior parte delle interfacce utente code dovrebbe utilizzare bind, src, o resolve. Utilizzare questi aiuti quando hai bisogno di un controllo cache esplicito:

Metodo	Descrizione
get	Risolve una URL remota in metadati di file nativi.
list	Restituisci asset cached che ancora esistono sul disco.
getCacheSize	Restituisci byte cached totali.
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-asset/
• Pacco: @capgo/capacitor-asset-cache