Super Network Image
A powerful Flutter widget for loading and caching network images, supporting both raster and SVG formats with advanced caching capabilities and precise cache management.
Features
- Automatic Image Type Detection: Automatically detects whether an image is raster or SVG and renders it accordingly.
- Caching Support: Caches images to improve performance and reduce network usage.
- Per-Image and Per-Tag Cache Busting: Ensures effective cache clearing for specific images or groups of images, even on web platforms.
- Custom Cache Duration: Set global or individual cache durations for images.
- Cache Tags: Assign tags to images for grouped cache management.
- Cache Management: Clear cache by image URL, tag, or entirely, with precise control.
- Custom Placeholders and Error Widgets: Provide custom widgets for loading and error states.
- Image Sizing and Fit: Control image dimensions and how they fit within their containers.
- Load Source Callback: Determine if an image was loaded from the cache or network.
- Platform Compatibility: Works seamlessly across mobile and web platforms.
Getting Started
Installation
Add super_network_image
to your project's pubspec.yaml
file:
dependencies:
super_network_image: 0.0.1
Then run:
flutter pub get
Import
import 'package:super_network_image/super_network_image.dart';
Usage
Basic Usage
Load and display a network image:
SuperNetworkImage(
url: 'https://example.com/image.jpg',
width: 300,
height: 300,
),
SVG Image Support
Automatically handle SVG images:
SuperNetworkImage(
url: 'https://example.com/image.svg',
width: 300,
height: 300,
),
Custom Cache Duration
Set a custom cache duration for an image:
SuperNetworkImage(
url: 'https://example.com/image.jpg',
cacheDuration: Duration(days: 1),
),
Set a global cache duration:
void main() {
SuperNetworkImageCache.setGlobalCacheDuration(Duration(days: 7));
runApp(MyApp());
}
Custom Placeholder and Error Widgets
Provide custom widgets for loading and error states:
SuperNetworkImage(
url: 'https://example.com/image.jpg',
placeholderBuilder: () => Center(
child: CircularProgressIndicator(),
),
errorBuilder: () => Center(
child: Text('Failed to load image'),
),
),
Using Cache Tags
Assign a tag to an image:
SuperNetworkImage(
url: 'https://example.com/image.jpg',
tag: 'profile_pictures',
),
Clear cache for a specific tag:
await SuperNetworkImageCache.clearCacheForTag('profile_pictures');
Clearing Cache
Clear a Specific Image from the Cache
await SuperNetworkImageCache.clearCachedImage('https://example.com/image.jpg');
Clear All Cached Images
await SuperNetworkImageCache.clearAllCachedImages();
Per-Image and Per-Tag Cache Busting
On web platforms, due to browser caching mechanisms, clearing the cache programmatically can be challenging. To address this, super_network_image
implements per-image and per-tag cache busting:
- Per-Image Cache Busting: When you clear the cache for a specific image, only that image's cache busting version is incremented, forcing the browser to fetch a fresh copy.
- Per-Tag Cache Busting: When you clear the cache for a tag, only images associated with that tag will have their cache busting versions incremented.
This ensures that cache clearing operations affect only the intended images, providing precise cache management.
Example: Clearing Cache for a Specific Image
await SuperNetworkImageCache.clearCachedImage('https://example.com/image.jpg');
Example: Clearing Cache for a Tag
await SuperNetworkImageCache.clearCacheForTag('profile_pictures');
Load Source Callback
Determine if an image was loaded from the cache or network:
SuperNetworkImage(
url: 'https://example.com/image.jpg',
onLoad: (source) {
if (source == ImageSource.cache) {
print('Image loaded from cache');
} else {
print('Image loaded from network');
}
},
),
Image Fit and Sizing
Control how the image fits within its container:
SuperNetworkImage(
url: 'https://example.com/image.jpg',
width: 300,
height: 200,
fit: BoxFit.cover,
),
Platform Compatibility
The package handles caching differently based on the platform:
- Mobile Platforms (Android/iOS): Uses the device's file system for caching. Clearing the cache deletes files directly.
- Web Platform: Implements cache busting by appending a version query parameter to image URLs. This forces the browser to fetch new versions of images when the cache is cleared.
Example
A comprehensive example is available in the example
directory, demonstrating all features of the package, including cache busting and cache management.
You can also view the example code here.
Contributions
Contributions are welcome! Please feel free to submit a pull request or open an issue on GitHub.
License
This project is licensed under the MIT License - see the LICENSE file for details.