Einführung in den Asset Cache Capgo-Repository

Installieren

Sie können unser AI-gestütztes Setup verwenden, um das Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten Ihrem AI-Tool mit der folgenden Befehl hinzu:

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

Verwenden Sie dann die folgende Anfrage:

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

If you prefer Manual Setup, install the plugin by running:

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

Importieren

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

Eine CDN konfigurieren

Konfigurieren Sie einmalig die Basis-URL einer CDN, wenn Ihre App startet. Relative Asset-Pfade werden gegen diese URL aufgelöst.

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

Sie können überspringen cdnUrl wenn Sie absoluten URLs übergeben bind, srcoder resolve.

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

Ein Bild oder Video binden

bind ist der transparenteste Anzeigeweg. Es markiert das Element als lädt, lädt oder überprüft die Ressource natively, dann wird die lokale Quell-URL zugewiesen, wenn das lokale Datei bereit ist.

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

Hinweis

Das Element erhält nie die CDN-URL im erfolgreichen Pfad. Es erhält die lokale WebView-URL nach dem Bestehen des Assets im persistenten Speicher.

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>

Direkter Quellcode für Framework-Zustand

Verwenden src Wenn Ihr Framework bereits die Lade- und Fehlerzustände steuert. Die Promise löst sich mit einer lokalen Quellzeichenfolge nur nach dem Bestehen des lokalen Dateisystems auf.

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

videoElement.src = src;

Use resolve wenn Sie auch Metadaten benötigen:

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

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

Geschützte Assets

Übergeben Sie Kopfzeilen an den nativen fetch. Dies ist nützlich für signierte CDN-Pfade, authentifizierte Medien oder kurzlebige Token.

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

Kopfzeilen werden vom Plugin verwendet, während es das Remote-File abruft oder revalidiert. Die Bild- oder Videotag erhält jedoch nur die lokale Quell-URL, die vom Plugin zurückgegeben wird.

Revalidierung

Legen Sie eine Standardstrategie mit configure oder überschreiben Sie es für einen Asset.

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

Verfügbare Strategien:

Strategie	Benutzen Sie
never	Ein lokal gecachierter Datei ist bis zum expliziten Entfernen ausreichend.
ttl	Sie möchten eine einfache Gültigkeitsdauer haben.
always	Sie möchten, dass das Plugin die remote Asset jede Zeit überprüft.
etag	Ihr CDN gibt stabile ETag-Kopfzeilen zurück.
last-modified	Ihr CDN gibt zuverlässige Last-Modified-Kopfzeilen zurück.

Speicherung und Datenschutz

• iOS speichert Dateien unter Application Support und schließt den Cache-Root von iCloud-Backup aus.
• Android speichert Dateien unter dem internen Dateiverzeichnis der App.
• Web verwendet den Browser-Cache API und lokale Speicher-Metadaten als Entwicklungsfall-back.
• Gespeicherte Dateien sind innerhalb des App-Sandboxes versteckt, nicht in öffentlichen Benutzermedien gespeichert.
• Cached files are removed on uninstall, app data clear, or plugin clear() oder remove().

The cache is persistent, but it is not a security boundary by itself. Encrypt highly sensitive assets before serving them if they must remain unreadable on a compromised device.

Was sind die Alternativen zu Appflow?

Most UI code should use bind, src, or resolveVerwenden Sie diese Hilfsfunktionen, wenn Sie eine explizite Cache-Verwaltung benötigen.

Methode	Beschreibung
get	Auflösen Sie eine remote URL in native Dateimetadata.
list	Rufen Sie cached Assets ab, die noch auf der Festplatte existieren.
getCacheSize	Rückgabewert gespeicherter Bytes.
remove	Ein Cache-Asset durch Schlüssel oder URL löschen.
clear	Entfernen Sie alle cached Assets, die vom Plugin verwaltet werden.

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

Vollständige Referenz

• GitHub: https://github.com/Cap-go/capacitor-Asset-Cache/
• Paket: @capgo/capacitor-asset-cache