CachedNetworkImage: apa itu, konsep kunci dan widget ImageProvider

Apa itu CachedNetworkImage?

CachedNetworkImage adalah widget Flutter dari paket pub.dev dengan nama yang sama, yang menyediakan pemuatan gambar dari jaringan dengan caching otomatis. Ini adalah lapisan di atas Image.network standar, menambahkan caching file, indikator kemajuan dan penanganan kesalahan kustom.

Secara internal, CachedNetworkImage menggunakan flutter_cache_manager — manajer cache dengan database SQLite untuk melacak file. Pada permintaan pertama, gambar diunduh dari jaringan, disimpan di disk, dan pada permintaan berikutnya disediakan dari cache dengan mempertimbangkan TTL (standar 7 hari). Cache in-memory dikelola oleh ImageCache standar Flutter.

Paket ini memiliki lebih dari 4.000 suka di pub.dev dan digunakan di ribuan proyek Flutter. CachedNetworkImage mendukung semua platform Flutter: Android, iOS, Web, macOS, Windows dan Linux. Berkat API yang seragam, pengembang mendapatkan pemuatan gambar lintas platform tanpa kode khusus platform.

Bagaimana caching gambar bekerja di Flutter

Flutter menggunakan sistem caching dua tingkat: ImageCache (memori) dan flutter_cache_manager (disk + SQLite). ImageCache adalah cache global dari gambar yang didekode dengan batas jumlah (standar 1000) dan ukuran (standar 100 MB). flutter_cache_manager mengelola file di disk dan metadatanya.

Urutan pemeriksaan

Ketika CachedNetworkImage menerima permintaan gambar, pertama-tama ia memeriksa ImageCache Flutter — jika gambar sudah didekode di memori, gambar ditampilkan seketika. Jika tidak ditemukan, disk diperiksa melalui flutter_cache_manager: kueri SQLite memeriksa apakah file ada di cache dan apakah TTL-nya belum kedaluwarsa. Jika file masih berlaku — file dibaca dari disk, didekode dan ditampilkan. Jika file tidak ada atau TTL kedaluwarsa — permintaan HTTP dilakukan.

• ImageCache — cache global Flutter, standar 1000 elemen / 100 MB
• flutter_cache_manager — SQLite + sistem file, TTL 7 hari
• Pemuatan HTTP — dilakukan melalui paket http atau HttpClient kustom

Membersihkan cache

DefaultCacheManager menyediakan metode emptyCache() (pembersihan total), cleanCache() (hapus hanya yang kedaluwarsa) dan clearCacheWithAge() dengan tanggal kustom. ImageCache dibersihkan secara otomatis saat tekanan memori atau secara manual melalui imageCache.clear().

Arsitektur widget CachedNetworkImage

CachedNetworkImage dibangun di atas komposisi widget Flutter standar. Implementasi internal menggunakan ImageProvider untuk pemuatan asinkron dan StatefulWidget untuk melacak siklus hidup.

Parameter kunci

imageUrl — parameter wajib, URL gambar (String atau Uri). placeholder — widget yang ditampilkan selama pemuatan. errorWidget — widget saat kesalahan pemuatan. progressIndicatorBuilder — builder yang menerima konteks, URL dan DownloadProgress dengan bidang totalSize dan downloadedSize.

ImageProvider

CachedNetworkImageProvider — implementasi ImageProvider yang mengembalikan CachedNetworkStreamImage, yang mengelola pengunduhan dan caching. Provider ini terintegrasi dengan ImageCache Flutter dan mendukung semua kemampuan ImageProvider standar: penskalaan, pemusatan dan pengulangan.

Konfigurasi flutter_cache_manager

flutter_cache_manager — perpustakaan yang mendasari caching CachedNetworkImage. Ini menyediakan DefaultCacheManager dengan database SQLite yang dikonfigurasi, TTL dan batas file. Jika perlu, CacheManager kustom dengan parameter unik dapat dibuat.

CacheManager kustom dibuat dengan mewarisi CacheManager dan menimpa metode. Ini berguna ketika perlu menyimpan gambar di direktori terpisah atau menggunakan klien HTTP yang berbeda. Kemudian instance manajer diteruskan ke parameter cacheManager CachedNetworkImage.

Database SQLite DefaultCacheManager terletak di direktori temporaryDirectory aplikasi di jalur `{key}/CacheObjects.db`. Ini berisi tabel cacheObjects dengan bidang key (URL), relativePath, url, creationDate, eTag, httpHeaders. Saat membersihkan catatan kedaluwarsa, kueri SQL digunakan dengan kondisi berdasarkan maxAgeCacheObject.

Contoh penggunaan CachedNetworkImage di Dart

CachedNetworkImage menyediakan dua cara utama pemuatan: widget CachedNetworkImage dan provider CachedNetworkImageProvider untuk skenario kustom.

Pemuatan dasar dengan placeholder

CachedNetworkImage — cara utama. Cukup dengan memberikan imageUrl dan placeholder. Widget secara otomatis menampilkan placeholder hingga pemuatan selesai dan menggantinya dengan gambar.

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 dan errorWidget adalah fungsi builder yang menerima konteks, URL dan (untuk errorWidget) objek kesalahan. Pendekatan ini memungkinkan menampilkan cadangan yang berbeda tergantung pada URL atau jenis kesalahan.

Pemuatan dengan kemajuan

progressIndicatorBuilder — parameter yang memungkinkan menampilkan persentase kemajuan pemuatan. DownloadProgress berisi totalSize (bisa -1 jika ukuran tidak diketahui) dan 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 — parameter opsional yang memungkinkan menyesuaikan tampilan gambar: menambahkan pembulatan, bayangan, dekorasi. Dalam contoh, DecorationImage dengan BorderRadius digunakan untuk sudut membulat.

Menggunakan CachedNetworkImageProvider

CachedNetworkImageProvider — provider untuk Image atau DecorationImage tanpa menggunakan widget CachedNetworkImage. Berguna saat bekerja dengan BoxDecoration, FadeInImage atau widget Image kustom.

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

ImageBuilder dan pemrosesan kustom

Parameter imageBuilder di CachedNetworkImage memungkinkan mengganti widget Image standar dengan implementasi kustom. Alih-alih menampilkan Image secara langsung, dapat menggunakan Container dengan dekorasi, ClipRRect dengan pemotongan atau Ink.image untuk efek ripple. imageBuilder menerima konteks dan ImageProvider dari gambar yang siap, memberikan kontrol penuh atas rendering.

Parameter tambahan: memCacheWidth dan memCacheHeight membatasi ukuran gambar yang di-cache di memori RAM, mengurangi beban pada ImageCache Flutter. cacheKey memungkinkan mengatur kunci cache kustom sebagai pengganti URL, berguna untuk gambar dengan token otorisasi di URL (parameter kueri berubah setiap kali, tetapi konten tetap sama).

CachedNetworkImage vs Image.network standar

Widget standar Image.network memuat gambar setiap kali widget dibangun ulang tanpa menyimpannya di disk. CachedNetworkImage menambahkan caching file, kemajuan dan penanganan kesalahan, tetapi menambahkan ketergantungan pada flutter_cache_manager dan SQLite.

Untuk proyek di mana pekerjaan offline dan penghematan bandwidth penting, CachedNetworkImage adalah pilihan yang jelas. Untuk layar sederhana sekali pakai (misalnya, onboarding atau splash), Image.network tidak memerlukan ketergantungan tambahan.

Pengaturan CachedNetworkImage di proyek Flutter

CachedNetworkImage ditambahkan sebagai ketergantungan pub.dev standar. Setelah instalasi, widget siap digunakan. flutter_cache_manager masuk sebagai ketergantungan transitif.

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

Secara default, DefaultCacheManager digunakan dengan pengaturan: TTL = 7 hari, maks 200 file. Untuk mengubah parameter global, instance CacheManager kustom dengan Config dibuat, di mana maxAgeCacheObject, maxNrOfCacheObjects dan repo ditimpa.

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",
    ),
  ),
);

// Menggunakan manajer kustom:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes dan maxHeightBytes — parameter opsional untuk membatasi ukuran file yang di-cache. Ini berguna untuk menghemat ruang disk ketika gambar asli lebih besar dari ukuran layar yang diperlukan.