开始使用

安装

您可以使用我们的 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.

如果您prefer手动设置，安装插件并运行：

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 是最透明的显示路径。它标记元素为加载中，原生获取或重新验证资产，然后在本地文件准备好时 assignments 本地源 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);

受保护的资产

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

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

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

重新验证

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

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

可用策略:

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

存储和隐私

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

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

高级缓存控制

Most UI code should use 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