开始

安装

您可以使用我们的AI辅助设置来安装插件。使用以下命令将Capgo技能添加到您的AI工具中：

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

然后使用以下提示：

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

如果您更喜欢手动设置，请运行以下命令安装插件：

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

导入

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

配置 CDN

在应用启动时配置一次 CDN 基础 URL。相对资产路径将根据此 URL 进行解析。

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

您可以跳过 cdnUrl 如果您传递绝对 URL 到 bind, src或 resolve.

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

绑定图片或视频

bind 是最透明的显示路径。它标记元素为加载中，原生地获取或重新验证资产，然后将本地源 URL assignment 当本地文件准备就绪时。

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

注意

元素在成功路径中永远不会接收到 CDN URL。它在持久存储中存在资产后接收到本地 webview URL。

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>

直接源码框架状态

在框架已经控制加载和错误状态的情况下使用。 src Copy to clipboard

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

videoElement.src = src;

Copy to clipboard resolve 直接源

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

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

将头信息传递给原生 fetch。 这对于签名 CDN 路径、认证媒体或短期令牌有用。

头信息用于插件在获取或重新验证远程文件时使用。 仍然接收的图像或视频标签仅接收由插件返回的本地源 URL。

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

保护资产

重新验证

设置一个默认策略 configure 或覆盖它一个资产

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

可用策略：

策略	使用情况
never	当您有一个缓存的本地文件，直到您显式地删除它时就足够了。
ttl	您想要一个简单的新鲜度窗口。
always	您想要每次插件检查远程资产。
etag	您的CDN返回稳定的ETag标头。
last-modified	Your CDN returns reliable Last-Modified headers.

存储和隐私

• iOS在Application Support下存储文件，并将缓存根目录排除在iCloud备份之外.
• Android在应用内部文件目录下存储文件.
• Web使用浏览器缓存API和localStorage元数据作为开发fallback.
• 缓存文件隐藏在应用沙盒内，不保存到公共用户媒体中.
• 缓存文件在卸载、清除应用数据或插件时被删除. clear() 或 remove().

缓存是持久的，但它本身并不是安全边界。若资产必须在被破坏的设备上保持不可读，请在服务前加密它们.

高级缓存控制

大多数 UI code 应该使用 bind, src, 或 resolve. 使用这些助手时需要显式缓存管理:

方法	描述
get	解析远程 URL 为本地文件元数据。
list	返回磁盘上仍然存在的缓存资产。
getCacheSize	返回总缓存字节。
remove	通过键或 URL 删除一个缓存资产。
clear	删除该插件管理的所有缓存资产。

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

全参考

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