Anfangen

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten Ihrem AI-Tool hinzu, indem Sie die folgende Befehlszeile verwenden:

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.

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgende Befehlszeile ausführen:

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

Importieren

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

Eine CDN konfigurieren

Konfigurieren Sie einmalig die CDN-URL Ihrer App. 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 ein Video binden

bind ist der transparenteste Anzeigeweg. Er markiert das Element als lädt, holt oder überprüft die Ressource natively, dann zuweist die lokale Quell-URL, 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 Weg. Es erhält die lokale WebView-URL nach der Ressource existiert in der persistenten Speicherung.

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 Sie src wenn Ihr Framework bereits die Lade- und Fehlerzustände steuert. Die Promise löst sich mit einem lokalen Quellcode nur nachdem der lokale Datei existiert.

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

videoElement.src = src;

Verwenden Sie 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}`,
  },
});

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

Wiederprüfung

Setzen Sie eine Standardstrategie mit configure oder überschreiben Sie sie für ein einzelnes Asset.

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

Verfügbare Strategien:

Strategie	Verwenden Sie, wenn
never	Ein lokal gecachter Datei ist bis zum expliziten Entfernen ausreichend.
ttl	Sie möchten eine einfache Gültigkeitszeitfenster haben.
always	Sie möchten, dass das Plugin die remote Asset jede Zeit ü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 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 localStorage-Metadaten als Entwicklungsfall-back.
• Gecachte Dateien sind innerhalb des App-Sandboxes versteckt, werden nicht in öffentliche Benutzermedien gespeichert.
• Gecachte Dateien werden bei der Deinstallation, beim Löschen von App-Daten oder bei der Plugin-Deinstallation 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	Rückgabewert: Gibt die im Cache gespeicherten Assets zurück, die auf dem Disk noch existieren.
getCacheSize	Gibt die Gesamtzahl der im Cache gespeicherten Bytes zurück.
remove	Löscht ein einzelnes im Cache gespeichertes Asset durch Schlüssel oder URL.
clear	Löscht alle im Plugin verwalteten im Cache gespeicherten Assets.

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