开始使用

安装

您可以使用我们的 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 这是最透明的显示路径。它标记元素为加载中，原生地获取或重新验证资产，然后在本地文件准备好时 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。它在持久存储中存在 asset 后接收到本地 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返回可靠的最后修改标头。

存储和隐私

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

context

在Capacitor live-update替代方案比较页面上，用于显示Capacitor、Appflow和Capawesome替代方案的长营销或法律段落。

Most UI code should use bind, src, or resolve在Appflow比较/迁移营销复制页面上，用于显示Appflow插件或的短UI标签或导航项。

方法	描述
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/
• Package: @capgo/capacitor-asset-cache