Einstieg

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihre AI-Tool mithilfe 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.

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie den folgenden Befehl ausführen:

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

Importieren

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

Eine CDN konfigurieren

Konfigurieren Sie die CDN-URL einmal, 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 absolute URLs übergeben, z.B. über die 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 die 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 in der erfolgreichen Route. 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 den Framework-Zustand

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

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

videoElement.src = src;

Verwenden 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

Passen Sie Kopfzeilen an die native Fetch-Methode weiter. 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 während des Fetchens oder der Revalidierung der Remote-Datei verwendet. Die Bild- oder Videotag wird jedoch nur den lokalen Quellcode-URL zurückgegeben, der vom Plugin zurückgegeben wird.

Revalidierung

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

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.
always	Sie wollen, dass das Plugin das Remote-Asset jede Zeit überprüft.
etag	Ihr CDN sendet stabile ETag-Kopfzeilen.
last-modified	Ihr CDN gibt zuverlässige Last-Modified-Headers 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 localStorage-Metadaten als Entwicklungsfall-back.
• Gecachte Dateien sind innerhalb des App-Sandbox versteckt, nicht im öffentlichen Benutzer-Medien gespeichert.
• Gecachte Dateien werden bei Deinstallation, App-Daten-Löschen oder Plugin-Entfernung entfernt. clear() oder remove().

Der Cache ist persistent, aber er ist nicht selbst ein Sicherheitsgrenze. Verschlüsseln Sie hochsensiblle Assets, bevor Sie sie ausliefern, wenn sie auf einem kompromittierten Gerät unlesbar bleiben müssen.

Erweiterte Cache-Kontrolle

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

Methode	Beschreibung
get	Lösen Sie eine Remote-URL in native Dateimetadata auf.
list	Geben Sie die gespeicherten Assets zurück, die auf der Festplatte noch existieren.
getCacheSize	Geben Sie die Gesamtzahl der gespeicherten Bytes zurück.
remove	Entfernen Sie ein gespeichertes Asset durch Schlüssel oder URL.
clear	Entfernen Sie alle von dem Plugin verwalteten 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