跳过内容
Capgo - Capacitor 应用程序实时更新 Capgo

开始

GitHub

安装

标题为“安装”

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

配置 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。

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

React

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

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>

Direct Source For Framework State

Direct Source For Framework State

Use src When your framework already controls loading and error state. The promise resolves with a local source string only after the local file exists.

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 Copy to clipboard

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 使用浏览器缓存 API 和 localStorage 元数据作为开发fallback。
  • 缓存文件隐藏在应用程序沙盒内，不保存到公共用户媒体。
  • 缓存文件在卸载、清除应用程序数据或插件时被删除。 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' },
});

全参考

全参考