Einstieg

Installieren

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

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

Verwenden Sie dann folgenden Prompt:

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

Wenn Sie eine manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie Folgendes ausführen:

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

Importieren

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

Eine CDN konfigurieren

Eine CDN-Base-URL konfigurieren, wenn Ihre App startet. Relative Asset-Pfade werden gegenüber dieser 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, src, oder 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. 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

Der 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>

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 einer lokalen Quellzeichenkette 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}`,
  },
});

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 fest 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 wollen eine einfache Gültigkeitsdauer haben.
always	Sie wollen, 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 im internen Dateiverzeichnis der App.
• Web verwendet den Browser-Cache API und localStorage-Metadaten als Entwicklungsfall-back.
• Gecachte Dateien sind innerhalb des App-Sandboxes verborgen, werden nicht in öffentliche Benutzermedien gespeichert.
• Gecachte Dateien werden bei Deinstallation, App-Daten-Löschen oder Plugin-Entfernung entfernt. clear() Die Cache ist persistent, aber es ist nicht selbst ein Sicherheitsgrenze. Verschlüsseln Sie hochsensible Assets, bevor Sie sie auf einem kompromittierten Gerät ausliefern, wenn sie unlesbar bleiben müssen. remove().

Erweiterte Cache-Kontrolle

Abschnitt mit dem Titel „Erweiterte Cache-Kontrolle“

Most UI code should use bind, srcVerwenden Sie diese Hilfsmittel, wenn Sie eine explizite Cache-Verwaltung benötigen: resolveMethode

Advanced Cache Control	Beschreibung
get	Lösen Sie eine remote URL in native Dateimetadata auf.
list	Rufen Sie cached Assets ab, die auf dem Disk noch existieren.
getCacheSize	Geben Sie die Gesamtzahl der cached Bytes zurück.
remove	Entfernen Sie einen cached Asset durch Key oder URL.
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