Getting Started

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um den Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer AI-Tool mithilfe der folgenden Befehl hinzu:

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

Benutzen Sie dann die folgende Anweisung:

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

Import

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

Ein CDN konfigurieren

Konfigurieren Sie einmalig die CDN-Base-URL, 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 nachdem das Asset im persistenten Speicher existiert.

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>

Quelle Direkt für Framework-Zustand

Use src wenn Ihr Framework bereits die Lade- und Fehlerzustände steuert. Die Promise löst sich mit einem lokalen Quellstring nur nachdem der lokale Datei existiert.

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

wenn Sie auch Metadaten benötigen:

Übertragen Sie Kopfzeilen an die native 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}`,
  },
});

Die Header werden vom Plugin während des Abrufs oder der Wiederprüfung des Remote-Dateis verwendet. Die Bild- oder Videotags erhalten nur die lokale Quell-URL, die vom Plugin zurückgegeben wird.

Revalidierung

Eine Standardstrategie festlegen mit configure oder sie für einen Asset überschreiben.

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

Verfügbare Strategien:

Strategie	Wenn
never	Ein lokal gecachter Datei ist bis zum expliziten Entfernen ausreichend.
ttl	Sie möchten eine einfache Gültigkeitsdauer.
always	Sie möchten, dass das Plugin jede Zeit den Remote-Asset überprüft.
etag	Ihr CDN sendet stabile ETag-Kopfzeilen.
last-modified	Ihr CDN sendet zuverlässige Last-Modified-Kopfzeilen.

Speicherung und Datenschutz

• iOS speichert Dateien unter Application Support und ausschließt den Cache-Root von iCloud-Backup.
• Android speichert Dateien unter dem internen Dateiverzeichnis der App.
• Web verwendet den Browser Cache API und lokale Speicher-Metadaten als Entwicklungsfall-back.
• Gecachte Dateien sind innerhalb des App-Sandbox versteckt, nicht gespeichert in öffentlichen Benutzermedien.
• Gelöschte Dateien werden bei Deinstallieren, App-Daten löschen oder Plugin entfernen entfernt. clear() oder remove().

Die Cache ist persistent, aber es ist nicht eine Sicherheitsgrenze an sich. Verschlüsseln Sie hochsensiblen Assets, bevor Sie sie bereitstellen, wenn sie auf einem kompromittierten Gerät unlesbar bleiben müssen.

Erweiterte Cache-Kontrolle

Die meisten UI-code sollten bind, src, oder resolve. Verwenden Sie diese Hilfsfunktionen, wenn Sie eine explizite Cache-Verwaltung benötigen:

Methode	Beschreibung
get	Eine remote URL in native Dateimetadata auflösen.
list	Geladene Assets zurückgeben, die auf dem Festplatte noch existieren.
getCacheSize	Rückgabewert gespeicherter Bytes.
remove	Ein Cache-Asset durch Schlüssel oder URL löschen.
clear	Löscht alle im Plugin verwalteten Assets aus dem Cache.

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/Capgo/capacitor-Asset-Cache/
• Paket: @capgo/capacitor-asset-cache