Iniciar Sesión

Instalar

Puede utilizar nuestra configuración asistida por IA para instalar el plugin. Agregue las Capgo habilidades a su herramienta de IA utilizando el siguiente comando:

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

Luego utilice el siguiente prompt:

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

Si prefiere la configuración manual, instale el plugin ejecutando:

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

Importar

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

Configurar una CDN

Configure la URL base de la CDN una vez que se inicie su aplicación. Los caminos de activos relativos se resolverán en función de esta URL.

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

Puedes saltarte cdnUrl si pasas direcciones URL absolutas a bind, src, o resolve.

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

Asociar Una Imagen O Video

bind es el camino de visualización más transparente. Marca el elemento como de carga, obtiene o revalida el activo nativamente, luego asigna la URL de origen local cuando el archivo local esté listo.

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

El elemento nunca recibe la URL de CDN en el camino exitoso. Recibe la URL de la vista web local después de que el activo existe en el almacenamiento 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>

Fuente Directa Para El Estado Del Marco

Usar src cuando su marco ya controla el estado de carga y error. La promesa se resuelve con una cadena de fuente local solo después de que el archivo local existe.

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

videoElement.src = src;

Usa resolve cuando también necesitas metadatos:

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

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

Recursos protegidos

Pasa encabezados al fetch nativo. Esto es útil para rutas CDN firmadas, medios autenticados o tokens de vida corta.

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

Los encabezados se utilizan por el plugin mientras se realiza la solicitud o se revalida el archivo remoto. La etiqueta de imagen o video todavía recibe solo la URL de origen local devuelta por el plugin.

Revalidación

Establece una estrategia por defecto con configure o sobrescríbela para un recurso.

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

Estategias disponibles:

Estategia	Usar cuando
never	Un archivo local en caché es suficiente hasta que lo elimines explícitamente.
ttl	Quieres una ventana de frescura simple.
always	Quieres que el complemento compruebe el activo remoto cada vez.
etag	Tu CDN devuelve encabezados de ETag estable.
last-modified	Tu CDN devuelve encabezados de Last-Modified fiables.

Almacenamiento y Privacidad

• iOS almacena archivos bajo Aplicación de Soporte y excluye la raíz de caché de iCloud de la copia de seguridad.
• Los archivos Android se almacenan en el directorio de archivos internos de la aplicación.
• Web utiliza la caché del navegador API y localStorage como fallback de desarrollo.
• Los archivos caché están ocultos dentro del sandbox de la aplicación, no se guardan en medios de usuario públicos.
• Los archivos caché se eliminan al desinstalar, limpiar datos de la aplicación o plugin clear() o remove().

La caché es persistente, pero no es un límite de seguridad por sí sola. Cifre activos altamente sensibles antes de servirlos si deben permanecer inaccesibles en un dispositivo comprometido.

Control Avanzado de Caché

La mayoría de los UI code deberían utilizar bind, src, o resolveUtilice estos ayudantes cuando necesite un manejo de caché explícito:

Método	Descripción
get	Resuelve una URL remota en metadatos de archivo nativo.
list	Devuelve activos en caché que aún existen en disco.
getCacheSize	Devuelve bytes totales en caché.
remove	Elimina un activo en caché por clave o URL.
clear	Elimina todos los activos en caché gestionados por el plugin.

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

Referencia completa

• GitHub: https://github.com/Cap-go/capacitor-cache-de-activos/
• Paquete: @capgo/capacitor-asset-cache