メインコンテンツへスキップ

スタートガイド

GitHub

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いのAIツールに Capgo のスキルを追加してください:

ターミナル
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.

手動セットアップを好む場合は、以下のコマンドを実行してプラグインをインストールしてください:

ターミナル
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 のベース 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;
}
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" />;
}
<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」セクション

使用する 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);

保護されたアセット

「Protected Assets」セクション

ヘッダーをネイティブfetchに渡します。署名付きCDNパス、認証付きメディア、または短期有効トークンに便利です。

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

Headers はプラグインがリモートファイルの取得や再検証を行う際に使用されます。image や video タグには、プラグインが返すローカルのソース URL のみが渡されます。

デフォルトの戦略は次のように設定します configure または、特定のアセットだけ上書きできます。

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

利用可能な戦略:

戦略使用シーン
never明示的に削除するまで、キャッシュされたローカルファイルで十分です。
ttlシンプルな鮮度ウィンドウを使いたい場合。
alwaysプラグインに毎回リモートアセットを確認させたい場合。
etagCDN が安定した ETag ヘッダーを返します。
last-modifiedCDN が信頼できる Last-Modified ヘッダーを返します。

ストレージとプライバシー

セクション「Storage And Privacy」
  • iOS はファイルを Application Support に保存し、キャッシュルートは iCloud バックアップから除外されます。
  • Android はファイルをアプリ内部ファイルディレクトリに保存します。
  • Web はブラウザのキャッシュ API と localStorage メタデータを開発用のフォールバックとして使用します。
  • キャッシュされたファイルはアプリサンドボックス内に隠蔽され、公開ユーザーメディアには保存されません。
  • キャッシュされたファイルは、アンインストール、アプリデータ消去、またはプラグイン clear() または remove().

キャッシュは永続的ですが、それ自体はセキュリティ境界ではありません。デバイスが侵害された場合に読み取れない必要がある場合は、配信前に機密性の高いアセットを暗号化してください。

ほとんどのUI code で使うべきです bind, src、または resolve。明示的なキャッシュ管理が必要な場合は、これらのヘルパーを使います:

メソッド説明
getリモートURLをネイティブのファイルメタデータに解決します。
listディスク上にまだ存在するキャッシュ済みアセットを返します。
getCacheSizeキャッシュ済みの合計バイト数を返します。
removeキーまたはURLでキャッシュ済みアセットを1つ削除します。
clearプラグインが管理するキャッシュ済みアセットをすべて削除します。
const asset = await AssetCache.get({
url: 'https://cdn.example.com/assets/videos/intro.mp4',
key: 'videos/intro.mp4',
revalidate: { strategy: 'last-modified' },
});

リファレンス全文

セクション「Full Reference」