スタートガイド
インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-asset-cache`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/asset-cache/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
インストール
「インストール」セクション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-cachenpx cap syncインポート
「インポート」セクションimport { AssetCache } from '@capgo/capacitor-asset-cache';クイックスタート
「クイックスタート」セクションimport { nativePlugin } from '@capgo/capacitor-asset-cache';
await nativePlugin.cancel();よくある落とし穴
「よくある落とし穴」セクション- ネイティブ同期: 実行
npx cap syncプラグインのアップグレード後。 - 信頼できる情報源: 信頼
src/definitions.tsGitHub リポジトリ内。
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」セクション使用する 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 | プラグインに毎回リモートアセットを確認させたい場合。 |
etag | CDN が安定した ETag ヘッダーを返します。 |
last-modified | CDN が信頼できる 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」- GitHub: https://github.com/Cap-go/capacitor-asset-cache/
- パッケージ:
@capgo/capacitor-asset-cache