快速入门

安装

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

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

然后使用以下 prompt：

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

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

bun add @capgo/capacitor-asset-cache
npx cap sync

导入

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

快速入门

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

await nativePlugin.cancel();

常见坑点

• 原生同步：运行 npx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

配置 CDN

在应用启动时配置一次 CDN base URL。相对资源路径会基于该 URL 解析。

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

你可以跳过 cdnUrl 如果您向 bind, src，或 resolve.

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

绑定图片或视频

bind 是最透明的显示路径。它会把元素标记为加载中，以原生方式获取或重新验证资源，并在本地文件就绪后设置本地源 URL。

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 当你的框架已经控制加载和错误状态时。只有当本地文件存在后，Promise 才会以本地源字符串解析。

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

videoElement.src = src;

使用 resolve 当你还需要元数据时：

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

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

受保护的资源

将 headers 传递给原生 fetch。这对于签名 CDN 路径、认证媒体或短期 token 非常有用。

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

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

重新验证

使用 configure 设置默认策略，或针对单个资源进行覆盖。

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

可用策略：

策略	适用场景
never	缓存的本地文件足够使用，直到您显式删除它。
ttl	您希望有一个简单的新鲜度窗口。
always	您希望插件每次都检查远程资源。
etag	您的 CDN 返回稳定的 ETag 头。
last-modified	您的 CDN 返回可靠的 Last-Modified 头。

存储与隐私

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

缓存是持久的，但本身并非安全边界。如果资产在设备被入侵后必须保持不可读，请在提供之前对其进行加密。

高级缓存控制

大多数 UI code 应使用 bind, src，或 resolve需要显式管理缓存时，请使用这些辅助函数：

方法	描述
get	将远程 URL 解析为原生文件元数据。
list	返回磁盘上仍存在的缓存资源。
getCacheSize	返回缓存总字节数。
remove	按 key 或 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