CachedNetworkImage: τι είναι, βασικές έννοιες και το widget ImageProvider

Τι είναι το CachedNetworkImage;

CachedNetworkImage είναι ένα widget Flutter από το ομώνυμο πακέτο pub.dev που παρέχει φόρτωση εικόνων από το δίκτυο με αυτόματη προσωρινή αποθήκευση. Είναι ένα επίπεδο πάνω από το τυπικό Image.network, προσθέτοντας προσωρινή αποθήκευση αρχείων, δείκτες προόδου και προσαρμοσμένη διαχείριση σφαλμάτων.

Εσωτερικά, το CachedNetworkImage χρησιμοποιεί το flutter_cache_manager — έναν διαχειριστή προσωρινής μνήμης με βάση δεδομένων SQLite για την παρακολούθηση αρχείων. Στο πρώτο αίτημα, η εικόνα μεταφορτώνεται από το δίκτυο, αποθηκεύεται στο δίσκο και σε επόμενα αιτήματα παρέχεται από την προσωρινή μνήμη λαμβάνοντας υπόψη το TTL (από προεπιλογή 7 ημέρες). Η προσωρινή μνήμη in-memory διαχειρίζεται από το τυπικό ImageCache του Flutter.

Το πακέτο έχει περισσότερα από 4.000 likes στο pub.dev και χρησιμοποιείται σε χιλιάδες έργα Flutter. Το CachedNetworkImage υποστηρίζει όλες τις πλατφόρμες Flutter: Android, iOS, Web, macOS, Windows και Linux. Χάρη στο ενιαίο API, ο προγραμματιστής αποκτά πολυπλατφορμική φόρτωση εικόνων χωρίς κώδικα ειδικό για πλατφόρμα.

Πώς λειτουργεί η προσωρινή αποθήκευση εικόνων στο Flutter

Το Flutter χρησιμοποιεί σύστημα προσωρινής αποθήκευσης δύο επιπέδων: ImageCache (μνήμη) και flutter_cache_manager (δίσκος + SQLite). Το ImageCache είναι μια καθολική προσωρινή μνήμη αποκωδικοποιημένων εικόνων με όριο αριθμού (από προεπιλογή 1000) και μεγέθους (από προεπιλογή 100 MB). Το flutter_cache_manager διαχειρίζεται αρχεία στο δίσκο και τα μεταδεδομένα τους.

Σειρά ελέγχου

Όταν το CachedNetworkImage λαμβάνει ένα αίτημα εικόνας, πρώτα ελέγχει το ImageCache του Flutter — αν η εικόνα είναι ήδη αποκωδικοποιημένη στη μνήμη, εμφανίζεται άμεσα. Σε περίπτωση απουσίας, ο δίσκος ελέγχεται μέσω του flutter_cache_manager: ένα ερώτημα SQLite ελέγχει αν το αρχείο υπάρχει στην προσωρινή μνήμη και αν το TTL του δεν έχει λήξει. Αν το αρχείο είναι ενημερωμένο — διαβάζεται από το δίσκο, αποκωδικοποιείται και εμφανίζεται. Αν το αρχείο δεν υπάρχει ή το TTL έχει λήξει — εκτελείται ένα αίτημα HTTP.

• ImageCache — καθολική προσωρινή μνήμη Flutter, από προεπιλογή 1000 στοιχεία / 100 MB
• flutter_cache_manager — SQLite + σύστημα αρχείων, TTL 7 ημέρες
• Φόρτωση HTTP — εκτελείται μέσω του πακέτου http ή προσαρμοσμένου HttpClient

Εκκαθάριση προσωρινής μνήμης

Το DefaultCacheManager παρέχει μεθόδους emptyCache() (πλήρης εκκαθάριση), cleanCache() (διαγραφή μόνο ληγμένων) και clearCacheWithAge() με προσαρμοσμένη ημερομηνία. Το ImageCache καθαρίζεται αυτόματα σε πίεση μνήμης ή χειροκίνητα μέσω του imageCache.clear().

Αρχιτεκτονική του widget CachedNetworkImage

Το CachedNetworkImage είναι χτισμένο στη σύνθεση τυπικών widgets Flutter. Η εσωτερική υλοποίηση χρησιμοποιεί ImageProvider για ασύγχρονη φόρτωση και StatefulWidget για παρακολούθηση του κύκλου ζωής.

Βασικές παράμετροι

imageUrl — υποχρεωτική παράμετρος, URL της εικόνας (String ή Uri). placeholder — widget που εμφανίζεται κατά τη φόρτωση. errorWidget — widget σε σφάλμα φόρτωσης. progressIndicatorBuilder — builder που λαμβάνει context, URL και DownloadProgress με πεδία totalSize και downloadedSize.

ImageProvider

CachedNetworkImageProvider — υλοποίηση του ImageProvider που επιστρέφει CachedNetworkStreamImage, το οποίο διαχειρίζεται τη λήψη και την προσωρινή αποθήκευση. Ο provider ενσωματώνεται με το ImageCache του Flutter και υποστηρίζει όλες τις δυνατότητες του τυπικού ImageProvider: κλίμακα, κεντράρισμα και επανάληψη.

Ρύθμιση του flutter_cache_manager

flutter_cache_manager — η βιβλιοθήκη που αποτελεί τη βάση της προσωρινής αποθήκευσης του CachedNetworkImage. Παρέχει DefaultCacheManager με ρυθμισμένη βάση δεδομένων SQLite, TTL και όριο αρχείων. Εάν χρειαστεί, μπορεί να δημιουργηθεί προσαρμοσμένος CacheManager με μοναδικές παραμέτρους.

Προσαρμοσμένος CacheManager δημιουργείται με κληρονομικότητα από τον CacheManager και παράκαμψη μεθόδων. Αυτό είναι χρήσιμο όταν πρέπει να αποθηκεύονται εικόνες σε ξεχωριστό κατάλογο ή να χρησιμοποιείται διαφορετικός πελάτης HTTP. Στη συνέχεια, το στιγμιότυπο του διαχειριστή μεταβιβάζεται στην παράμετρο cacheManager του CachedNetworkImage.

Η βάση δεδομένων SQLite του DefaultCacheManager βρίσκεται στον temporaryDirectory της εφαρμογής στη διαδρομή `{key}/CacheObjects.db`. Περιέχει τον πίνακα cacheObjects με πεδία key (URL), relativePath, url, creationDate, eTag, httpHeaders. Κατά την εκκαθάριση ληγμένων εγγραφών, χρησιμοποιείται ερώτημα SQL με συνθήκη βάσει του maxAgeCacheObject.

Παραδείγματα χρήσης του CachedNetworkImage σε Dart

Το CachedNetworkImage παρέχει δύο βασικούς τρόπους φόρτωσης: το widget CachedNetworkImage και τον provider CachedNetworkImageProvider για προσαρμοσμένα σενάρια.

Βασική φόρτωση με placeholder

CachedNetworkImage — ο κύριος τρόπος. Αρκεί να μεταβιβάσετε imageUrl και placeholder. Το widget εμφανίζει αυτόματα το placeholder έως ότου ολοκληρωθεί η φόρτωση και το αντικαθιστά με την εικόνα.

CachedNetworkImage(
    imageUrl: "https://example.com/photo.jpg",
    placeholder: (context, url) => CircularProgressIndicator(),
    errorWidget: (context, url, error) => Icon(Icons.error),
    width: 200,
    height: 200,
    fit: BoxFit.cover,
)

Τα placeholder και errorWidget είναι συναρτήσεις builder που λαμβάνουν context, URL και (για errorWidget) αντικείμενο σφάλματος. Αυτή η προσέγγιση επιτρέπει την εμφάνιση διαφορετικών εναλλακτικών ανάλογα με το URL ή τον τύπο σφάλματος.

Φόρτωση με πρόοδο

progressIndicatorBuilder — παράμετρος που επιτρέπει την εμφάνιση ποσοστού προόδου φόρτωσης. Το DownloadProgress περιέχει totalSize (μπορεί να είναι -1 αν το μέγεθος είναι άγνωστο) και downloadedSize.

CachedNetworkImage(
    imageUrl: "https://example.com/large.jpg",
    progressIndicatorBuilder: (context, url, downloadProgress) {
        return Center(
            child: SizedBox(
                width: 50,
                height: 50,
                child: Stack(
                    alignment: Alignment.center,
                    children: [
                        CircularProgressIndicator(
                            value: downloadProgress.progress,
                        ),
                        Text(
                            "\(downloadProgress.downloadedSize ~/ 1024) KB",
                        ),
                    ],
                ),
            ),
        };
    },
    imageBuilder: (context, imageProvider) {
        return Container(
            decoration: BoxDecoration(
                borderRadius: BorderRadius.circular(12),
                image: DecorationImage(
                    image: imageProvider,
                    fit: BoxFit.cover,
                ),
            ),
        };
    },
)

imageBuilder — προαιρετική παράμετρος που επιτρέπει την προσαρμογή της εμφάνισης της εικόνας: προσθήκη στρογγυλοποίησης, σκιάς, διακόσμησης. Στο παράδειγμα χρησιμοποιείται DecorationImage με BorderRadius για στρογγυλεμένες γωνίες.

Χρήση του CachedNetworkImageProvider

CachedNetworkImageProvider — provider για Image ή DecorationImage χωρίς τη χρήση του widget CachedNetworkImage. Χρήσιμο κατά την εργασία με BoxDecoration, FadeInImage ή προσαρμοσμένα widgets Image.

Container(
    decoration: BoxDecoration(
        image: DecorationImage(
            image: CachedNetworkImageProvider(
                "https://example.com/bg.jpg",
                maxWidthBytes: 2048,
                maxHeightBytes: 2048,
            ),
            fit: BoxFit.cover,
        ),
    ),
)

ImageBuilder και προσαρμοσμένη επεξεργασία

Η παράμετρος imageBuilder στο CachedNetworkImage επιτρέπει την αντικατάσταση του τυπικού widget Image με προσαρμοσμένη υλοποίηση. Αντί για άμεση εμφάνιση Image, μπορεί να χρησιμοποιηθεί Container με διακόσμηση, ClipRRect με περικοπή ή Ink.image για εφέ κυματισμού. Το imageBuilder λαμβάνει context και ImageProvider της έτοιμης εικόνας, δίνοντας πλήρη έλεγχο στην απόδοση.

Επιπλέον παράμετροι: τα memCacheWidth και memCacheHeight περιορίζουν το μέγεθος της προσωρινά αποθηκευμένης εικόνας στη μνήμη RAM, μειώνοντας το φορτίο στο ImageCache του Flutter. Το cacheKey επιτρέπει τον ορισμό προσαρμοσμένου κλειδιού προσωρινής μνήμης αντί για URL, χρήσιμο για εικόνες με διακριτικά εξουσιοδότησης στο URL (οι παράμετροι ερωτήματος αλλάζουν σε κάθε αίτημα, αλλά το περιεχόμενο παραμένει το ίδιο).

CachedNetworkImage vs τυπικό Image.network

Το τυπικό widget Image.network φορτώνει την εικόνα σε κάθε ανακατασκευή του widget χωρίς αποθήκευση στο δίσκο. Το CachedNetworkImage προσθέτει προσωρινή αποθήκευση αρχείων, πρόοδο και διαχείριση σφαλμάτων, αλλά προσθέτει εξάρτηση από το flutter_cache_manager και την SQLite.

Για έργα όπου η εργασία εκτός σύνδεσης και η εξοικονόμηση εύρους ζώνης είναι σημαντικά, το CachedNetworkImage είναι η προφανής επιλογή. Για απλές εφάπαξ οθόνες (π.χ. onboarding ή splash), το Image.network δεν απαιτεί πρόσθετες εξαρτήσεις.

Ρύθμιση του CachedNetworkImage σε έργο Flutter

Το CachedNetworkImage προστίθεται ως τυπική εξάρτηση pub.dev. Μετά την εγκατάσταση, το widget είναι έτοιμο για χρήση. Το flutter_cache_manager εισέρχεται ως μεταβατική εξάρτηση.

// pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  cached_network_image: ^3.4.1

Από προεπιλογή χρησιμοποιείται ο DefaultCacheManager με ρυθμίσεις: TTL = 7 ημέρες, μέγιστο 200 αρχεία. Για αλλαγή καθολικών παραμέτρων, δημιουργείται προσαρμοσμένο στιγμιότυπο CacheManager με Config, όπου παρακάμπτονται τα maxAgeCacheObject, maxNrOfCacheObjects και repo.

import 'package:cached_network_image/cached_network_image.dart';
import 'package:flutter_cache_manager/flutter_cache_manager.dart';

final customCacheManager = CacheManager(
  Config(
    "custom_images",
    stalePeriod: Duration(days: 14),
    maxNrOfCacheObjects: 500,
    repo: JsonCacheInfoRepository(
      databaseName: "custom_images_cache.db",
    ),
  ),
);

// Χρήση προσαρμοσμένου διαχειριστή:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes και maxHeightBytes — προαιρετικές παράμετροι για περιορισμό του μεγέθους του προσωρινά αποθηκευμένου αρχείου. Αυτό είναι χρήσιμο για εξοικονόμηση χώρου στο δίσκο όταν η αρχική εικόνα είναι μεγαλύτερη από το απαιτούμενο μέγεθος οθόνης.