xue_hua_navite_cache_manager 1.1.5
xue_hua_navite_cache_manager: ^1.1.5 copied to clipboard
Flutter native network file cache with CachedNetworkImage, HTTP 304 revalidation, LRU/LFU/FIFO/TTL eviction, MD5/SHA-256 checksums, and progress.
xue_hua_navite_cache_manager #
English | 简体中文
A production-ready, cross-platform native network file cache manager and zero-jank image caching library for Flutter supporting Android, iOS, macOS, Windows, Linux, and Web.
xue_hua_navite_cache_manager provides CachedNetworkImage and CachedNetworkImageProvider for 60/120 FPS image rendering alongside automatic HTTP/HTTPS file downloading, conditional HTTP revalidation (ETag / Last-Modified / 304 Not Modified), Cache-Control: max-age parsing, high-volume 10,000+ entry disk quota eviction (LRU, LFU, FIFO, TTL-only), native MD5 and SHA-256 checksum verification, category tag management, pinned entry protection, and real-time download progress streams.
Features #
- Zero-Jank
CachedNetworkImage&CachedNetworkImageProvider:- Synchronous
ImageCacheShort-Circuit: Automatically skips fade animations when an image hits Flutter's in-memoryImageCache(wasSynchronouslyLoaded), preventing list/grid scroll flicker. - Zero-Copy Engine IO Decoding: Loads cached files directly on the Flutter Engine IO thread via
ui.ImmutableBuffer.fromFilePathwithout copying multi-megabyteUint8Listarrays acrossMethodChannel. - C++ Codec Target-Size Downsampling: Supports
memCacheWidthandmemCacheHeight(maxWidth/maxHeighton provider) so 4K photos are downsampled during C++ decoding before GPU texture upload.
- Synchronous
- 10,000+ Entries High-Throughput Index Engine:
- Defaults to
maxEntries = 20000withO(1)running byte quota tracking (totalCachedBytes) and 600ms debounced asynchronous index flushing so thousands of rapid cache hits/writes coalesce into a single non-blocking background disk write without SQLite FFI overhead.
- Defaults to
- 6-Platform Native Engine:
- Android:
HttpURLConnection+MessageDigest(MD5/SHA-256) + atomic file persistence underContext.getCacheDir(). - iOS:
URLSession+ AppleCryptoKit+NSCachesDirectorywithNSURLIsExcludedFromBackupKeyenabled automatically. - macOS:
URLSession+ AppleCryptoKit+~/Library/Caches/<BundleID>/. - Windows: Native
WinHTTP+ WindowsBCrypt(MD5/SHA-256) +%LOCALAPPDATA%\Temp\. - Linux: GLib
GChecksum(MD5/SHA-256) +XDG_CACHE_HOME(g_get_user_cache_dir()) +curltransfer. - Web: Browser
CacheStorageAPI (window.caches) +fetch()(AbortController) +BlobObject URLs + debouncedlocalStoragemetadata index.
- Android:
- Smart HTTP Cache Revalidation: Automatically stores
ETagandLast-Modifiedresponse headers and sendsIf-None-Match/If-Modified-Sinceon subsequent refreshes to save bandwidth via304 Not Modified. - Resilient Offline Fallback: When
fallbackToCacheOnError: true(default), returns existing cached files if the device is offline or the remote server fails. - Flexible Quota & Eviction Policies: Supports
LRU(Least Recently Used),LFU(Least Frequently Used),FIFO(First In, First Out), andttlOnlyeviction strategies with entry pinning (pinned: true). - Native Checksum Verification: Validates downloaded files against expected
MD5orSHA-256hex digests before committing them to cache. - Built-in AI Coding Agent Skill: Ships with a standard package skill in
skills/xue-hua-navite-cache-manager/SKILL.mdcompatible withdart run skills@ get.
System Requirements #
| Platform | Minimum Version | Native APIs Used |
|---|---|---|
| Dart SDK | ^3.13.0 |
plugin_platform_interface, web: ^1.0.0 |
| Flutter | >=3.47.0 |
MethodChannel, EventChannel, flutter_web_plugins |
| Android | API 24+ (Android 7.0+) | HttpURLConnection, MessageDigest, Context.cacheDir |
| iOS | iOS 15.0+ | URLSession, CryptoKit, FileManager (.cachesDirectory) |
| macOS | macOS 12.0+ | URLSession, CryptoKit, FileManager (.cachesDirectory) |
| Windows | Windows 10+ | WinHTTP, BCrypt, SHGetKnownFolderPath |
| Linux | GLib 2.56+ / GTK 3 | GLib, GChecksum, curl |
| Web | Modern Browsers | window.caches (CacheStorage), fetch, URL.createObjectURL |
Installation & Platform Setup #
Add xue_hua_navite_cache_manager to your pubspec.yaml:
dependencies:
xue_hua_navite_cache_manager: ^1.1.0
Android #
The plugin's AndroidManifest.xml automatically declares <uses-permission android:name="android.permission.INTERNET" />. No extra configuration is required for HTTPS URLs.
iOS #
No additional configuration is required for HTTPS downloads. Cached files are stored inside Library/Caches with isExcludedFromBackup = true so they do not consume the user's iCloud backup quota.
macOS #
Enable outbound network access in both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:
<key>com.apple.security.network.client</key>
<true/>
Windows & Linux #
- Windows: Links
winhttp.lib,bcrypt.lib, andshell32.libautomatically via the plugin'sCMakeLists.txt. - Linux: Ensure
curlandca-certificatesare installed on the target system.
Web #
Cross-origin downloads use the browser fetch() API and require the remote server to include valid CORS headers (Access-Control-Allow-Origin).
Quick Start #
1. Display Cached Network Images (CachedNetworkImage & CachedNetworkImageProvider) #
import 'package:flutter/material.dart';
import 'package:xue_hua_navite_cache_manager/xue_hua_navite_cache_manager.dart';
// 1a. Standard widget with C++ codec downsampling and progress indicator
CachedNetworkImage(
imageUrl: 'https://httpbin.org/image/jpeg',
tag: 'wildlife',
width: 200,
height: 200,
memCacheWidth: 400, // Downsamples in C++ codec to prevent UI jank
fit: BoxFit.cover,
progressIndicatorBuilder: (context, url, progress) {
final double? ratio = progress?.expectedTotalBytes != null &&
progress!.expectedTotalBytes! > 0
? progress.cumulativeBytesLoaded / progress.expectedTotalBytes!
: null;
return Center(child: CircularProgressIndicator(value: ratio));
},
errorWidget: (context, url, error, stackTrace) =>
const Center(child: Icon(Icons.broken_image_outlined)),
);
// 1b. Using CachedNetworkImageProvider directly with CircleAvatar / DecorationImage
const CircleAvatar(
radius: 40,
backgroundImage: CachedNetworkImageProvider(
'https://flutter.github.io/assets-for-api-docs/assets/widgets/falcon.jpg',
tag: 'avatars',
maxWidth: 160,
),
);
2. Configure the Global Cache Manager (10,000+ Entries Support) #
import 'package:xue_hua_navite_cache_manager/xue_hua_navite_cache_manager.dart';
final cache = XueHuaNaviteCacheManager.instance;
Future<void> initCache() async {
await cache.configure(
const CacheManagerConfig(
maxDiskCacheBytes: 500 * 1024 * 1024, // 500 MB quota
maxEntries: 20000, // Supports 10,000+ entries with O(1) running byte tracking
defaultTtlSeconds: 7 * 24 * 3600, // 7 days default TTL
evictionPolicy: CacheEvictionPolicy.lru,
cacheSubdirectory: 'app_media_cache',
maxConcurrentDownloads: 4,
connectTimeoutMs: 15000,
readTimeoutMs: 30000,
defaultHeaders: <String, String>{
'User-Agent': 'MyFlutterApp/1.1.0',
},
respectHttpCacheHeaders: true,
autoTrimOnWrite: true,
),
);
}
3. Download or Retrieve Any Network File #
final result = await cache.downloadFile(
const CacheRequest(
url: 'https://httpbin.org/image/jpeg',
tag: 'wildlife',
fallbackToCacheOnError: true,
checksumAlgorithm: CacheChecksumAlgorithm.sha256,
),
);
print('Origin: ${result.source.wireValue}'); // cacheHit, revalidated, networkDownload, or staleCacheFallback
print('Local path / URI: ${result.filePath}');
print('Size: ${result.entry.sizeBytes} bytes, SHA-256: ${result.entry.checksum}');
Or use the concise getSingleFile helper when you only need the CacheEntry:
final entry = await cache.getSingleFile(
'https://flutter.github.io/assets-for-api-docs/assets/widgets/falcon.jpg',
tag: 'wildlife',
);
4. Listen to Real-Time Download Progress #
final subscription = cache
.watchProgress('https://flutter.github.io/assets-for-api-docs/assets/videos/butterfly.mp4')
.listen((event) {
final percent = ((event.progress ?? 0) * 100).toStringAsFixed(1);
print('[${event.state.wireValue}] $percent% (${event.bytesReceived}/${event.totalBytes})');
});
// Remember to cancel in dispose():
// await subscription.cancel();
5. Batch Prefetching & Offline Lookup #
// Prefetch multiple files
final entries = await cache.prefetchAll(const <CacheRequest>[
CacheRequest(
url: 'https://httpbin.org/image/jpeg',
tag: 'onboarding',
pinned: true,
),
CacheRequest(
url: 'https://flutter.github.io/assets-for-api-docs/assets/widgets/falcon.jpg',
tag: 'onboarding',
),
]);
// Query cache without making a network call
final cachedEntry = await cache.getFileFromCache(
'https://httpbin.org/image/jpeg',
);
final bytes = await cache.readCacheBytes(
'https://httpbin.org/image/jpeg',
);
6. Manual Insertion (putBytes / putFile) & Cache Eviction #
import 'dart:typed_data';
// Store generated bytes directly into cache
await cache.putBytes(
key: 'user_theme_config',
bytes: Uint8List.fromList('{"darkMode":true}'.codeUnits),
fileExtension: 'json',
mimeType: 'application/json',
tag: 'settings',
pinned: true,
);
// Selective cleanup
await cache.removeByTag('onboarding');
await cache.removeExpired();
await cache.trimToSize(50 * 1024 * 1024); // Trim to 50 MB
await cache.clearAll(includePinned: false); // Clear all except pinned entries
7. Inspect Telemetry & Platform Capabilities #
final stats = await cache.getStats();
print('Total files: ${stats.totalEntries}, Hit rate: ${(stats.hitRate * 100).toStringAsFixed(1)}%');
final capabilities = await cache.getCapabilities();
print('Platform: ${capabilities.platformName}, Engine: ${capabilities.storageMechanism}');
Important Notes & Platform Gotchas #
- Preventing High-Resolution Image Jank:
- Always pass
memCacheWidthormemCacheHeighttoCachedNetworkImage(ormaxWidth/maxHeighttoCachedNetworkImageProvider) when rendering large images inside compact list/grid cells.
- Always pass
- Web File Paths vs. Native File Paths:
- On Android, iOS, macOS, Windows, and Linux (
capabilities.supportsFileSystemPaths == true),entry.filePathis an absolute OS filesystem path suitable forFile(entry.filePath). - On Web (
capabilities.supportsFileSystemPaths == false),entry.filePathis a browserBlobobject URL orCacheStorageURI. UseCachedNetworkImageorcache.readCacheBytes(keyOrUrl)when you need cross-platform compatibility.
- On Android, iOS, macOS, Windows, and Linux (
- Pinned Entries:
- Entries with
pinned: trueare never evicted by automaticLRU,LFU, orFIFOquota enforcement orremoveExpired(). To clear everything except pinned files, callclearAll(includePinned: false).
- Entries with
- AI Agent Skills:
- Consumers can install this package's bundled AI coding skill by running
dart run skills@ get.
- Consumers can install this package's bundled AI coding skill by running
Author & Repository #
- Author: Matkurban
- Email: 3496354336@qq.com
- Repository: https://github.com/Matkurban/xue_hua_navite_cache_manager