Mulai Beroperasi

Instalasi

Kamu bisa menggunakan Setup Bantuan AI kami untuk menginstal plugin ini. Tambahkan Capgo kemampuan ke alat AI kamu menggunakan perintah berikut:

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

Lalu gunakan prompt berikut:

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

Jika kamu lebih suka Setup Manual, instal plugin ini dengan menjalankan:

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

Import

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

Konfigurasi CDN

Konfigurasi URL dasar CDN sekali ketika aplikasi Anda dimulai. Jalur aset relatif akan diresolusi terhadap URL ini.

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

Anda dapat melewatinya cdnUrl jika Anda melewatkan URL absolut ke bind, src, atau resolve.

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

Pasang Gambar Atau Video

bind adalah jalur tampilan yang paling transparan. Ini menandai elemen sebagai loading, mengambil atau memvalidasi kembali asset secara native, kemudian mengasign URL sumber lokal ketika file lokal siap.

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

Penting

Elemen tersebut tidak pernah menerima URL CDN di jalur sukses. Ia menerima URL webview lokal setelah asset ada di penyimpanan persisten.

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>

Sumber Langsung Untuk Negara Kerangka

Gunakan src ketika kerangka Anda sudah mengontrol penggunaan dan kesalahan negara. Promes beresolusi dengan string sumber lokal hanya setelah file lokal ada.

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

videoElement.src = src;

Gunakan resolve ketika Anda juga membutuhkan metadata:

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

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

Aset Terlindungi

Sampaikan kepala ke panggilan native. Ini berguna untuk jalur CDN yang ditandatangani, media yang terautentikasi, atau token yang hidup singkat.

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

Kepala-kepala digunakan oleh plugin saat mengambil atau memvalidasi ulang file remote. Tag gambar atau video masih menerima hanya URL sumber lokal yang dikembalikan oleh plugin.

Memvalidasi ulang

Setel strategi default dengan configure atau ubahnya untuk satu aset.

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

Strategi yang tersedia:

Strategi	Gunakan saat
never	Sebuah file lokal yang dicache sudah cukup sampai Anda secara eksplisit menghapusnya.
ttl	Anda ingin jendela kebaruan yang sederhana.
always	Anda ingin plugin memeriksa aset jarak jauh setiap kali.
etag	CDN Anda mengembalikan header ETag stabil.
last-modified	CDN Anda mengembalikan header Last-Modified yang dapat diandalkan.

Penyimpanan dan Privasi

• iOS menyimpan file di bawah Support Aplikasi dan mengabaikan root cache dari backup iCloud.
• Android menyimpan file di bawah direktori file internal aplikasi.
• Web menggunakan Cache browser API dan metadata localStorage sebagai fallback pengembangan.
• File yang disimpan di dalam sandbox aplikasi, bukan disimpan di media pengguna publik.
• File yang disimpan dihapus ketika aplikasi diuninstall, data aplikasi dihapus, atau plugin clear() atau remove().

File yang disimpan dihapus ketika aplikasi diuninstall, data aplikasi dihapus, atau plugin, atau ketika pengguna menghapus data aplikasi.

Pengendalian Cache Lanjutan

Sebagian besar UI code harus menggunakan bind, src, atau resolve. Gunakan bantuan ini ketika Anda memerlukan pengelolaan cache eksplisit:

Methode	Deskripsi
get	Resolusi URL remote menjadi metadata file asli.
list	Kembalikan aset yang dikemas yang masih ada di disk.
getCacheSize	Kembalikan total byte yang dikemas.
remove	Hapus satu aset yang dikemas berdasarkan kunci atau URL.
clear	Hapus setiap aset yang dikemas yang dikelola oleh plugin.

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

Referensi Lengkap

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