CachedNetworkImage: ano ito, mga pangunahing konsepto at widget na ImageProvider

Ano ang CachedNetworkImage?

CachedNetworkImage ay isang Flutter widget mula sa parehong pangalan ng pub.dev package na nagbibigay ng pag-load ng mga larawan mula sa network na may awtomatikong caching. Ito ay isang layer sa ibabaw ng karaniwang Image.network, nagdadagdag ng file caching, mga indicator ng progreso at custom na paghawak ng error.

Sa loob, ang CachedNetworkImage ay gumagamit ng flutter_cache_manager — isang cache manager na may SQLite database para sa pagsubaybay ng mga file. Sa unang request, ang larawan ay nadi-download mula sa network, nai-save sa disk, at sa mga susunod na request ay ibinibigay mula sa cache na isinasaalang-alang ang TTL (default 7 araw). Ang in-memory cache ay pinamamahalaan ng karaniwang ImageCache ng Flutter.

Ang package ay may higit sa 4,000 likes sa pub.dev at ginagamit sa libu-libong Flutter projects. Sinusuportahan ng CachedNetworkImage ang lahat ng Flutter platforms: Android, iOS, Web, macOS, Windows at Linux. Dahil sa pare-parehong API, ang developer ay nakakakuha ng cross-platform na pag-load ng larawan nang walang platform-specific na code.

Paano gumagana ang caching ng larawan sa Flutter

Ang Flutter ay gumagamit ng dalawang antas na caching system: ImageCache (memorya) at flutter_cache_manager (disk + SQLite). Ang ImageCache ay isang global na cache ng mga decoded na larawan na may limitasyon sa bilang (default 1000) at laki (default 100 MB). Ang flutter_cache_manager ay namamahala ng mga file sa disk at ng kanilang metadata.

Pagkakasunod-sunod ng pagsusuri

Kapag nakatanggap ang CachedNetworkImage ng request para sa larawan, una nitong sinusuri ang ImageCache ng Flutter — kung ang larawan ay naka-decode na sa memorya, ito ay agad na ipinapakita. Kung wala, ang disk ay sinusuri sa pamamagitan ng flutter_cache_manager: isang SQLite query ang nagsusuri kung ang file ay nasa cache at kung ang TTL nito ay hindi nag-expire. Kung ang file ay napapanahon — ito ay binabasa mula sa disk, dinedecode at ipinapakita. Kung ang file ay wala o ang TTL ay nag-expire — isang HTTP request ang isinasagawa.

• ImageCache — global na cache ng Flutter, default 1000 elemento / 100 MB
• flutter_cache_manager — SQLite + file system, TTL 7 araw
• HTTP loading — isinasagawa sa pamamagitan ng http package o custom na HttpClient

Pag-clear ng cache

Ang DefaultCacheManager ay nagbibigay ng mga method na emptyCache() (buong pag-clear), cleanCache() (pagtanggal lamang ng mga nag-expire) at clearCacheWithAge() na may custom na petsa. Ang ImageCache ay awtomatikong nag-clear sa memory pressure o manu-mano sa pamamagitan ng imageCache.clear().

Arkitektura ng CachedNetworkImage widget

Ang CachedNetworkImage ay binuo sa komposisyon ng mga karaniwang Flutter widgets. Ang internal na implementasyon ay gumagamit ng ImageProvider para sa asynchronous na pag-load at StatefulWidget para sa pagsubaybay ng lifecycle.

Mga pangunahing parameter

imageUrl — mandatoryong parameter, URL ng larawan (String o Uri). placeholder — widget na ipinapakita habang naglo-load. errorWidget — widget kapag may error sa pag-load. progressIndicatorBuilder — builder na tumatanggap ng context, URL at DownloadProgress na may mga field na totalSize at downloadedSize.

ImageProvider

CachedNetworkImageProvider — implementasyon ng ImageProvider na nagbabalik ng CachedNetworkStreamImage, na namamahala sa pag-download at caching. Ang provider ay nagsasama sa ImageCache ng Flutter at sumusuporta sa lahat ng kakayahan ng karaniwang ImageProvider: pag-scale, pag-center at pag-ulit.

Configuration ng flutter_cache_manager

flutter_cache_manager — ang library na nasa ilalim ng caching ng CachedNetworkImage. Nagbibigay ito ng DefaultCacheManager na may configured na SQLite database, TTL at limitasyon ng file. Kung kinakailangan, maaaring gumawa ng custom na CacheManager na may natatanging mga parameter.

Ang custom na CacheManager ay ginagawa sa pamamagitan ng pagmana mula sa CacheManager na may pag-override ng mga method. Ito ay kapaki-pakinabang kapag kailangang mag-imbak ng mga larawan sa hiwalay na direktoryo o gumamit ng ibang HTTP client. Pagkatapos ang instance ng manager ay ipinapasa sa cacheManager parameter ng CachedNetworkImage.

Ang SQLite database ng DefaultCacheManager ay matatagpuan sa temporaryDirectory ng application sa path na `{key}/CacheObjects.db`. Naglalaman ito ng table na cacheObjects na may mga field na key (URL), relativePath, url, creationDate, eTag, httpHeaders. Kapag nag-clear ng mga nag-expire na record, ginagamit ang SQL query na may kondisyon batay sa maxAgeCacheObject.

Mga halimbawa ng paggamit ng CachedNetworkImage sa Dart

Ang CachedNetworkImage ay nagbibigay ng dalawang pangunahing paraan ng pag-load: ang CachedNetworkImage widget at ang CachedNetworkImageProvider para sa mga custom na scenario.

Pangunahing pag-load na may placeholder

CachedNetworkImage — ang pangunahing paraan. Sapat na ibigay ang imageUrl at placeholder. Awtomatikong ipinapakita ng widget ang placeholder hanggang sa matapos ang pag-load at pinapalitan ito ng larawan.

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

Ang placeholder at errorWidget ay mga builder function na tumatanggap ng context, URL at (para sa errorWidget) error object. Ang approach na ito ay nagbibigay-daan sa pagpapakita ng iba't ibang kapalit depende sa URL o uri ng error.

Pag-load na may progreso

progressIndicatorBuilder — parameter na nagbibigay-daan sa pagpapakita ng porsyento ng progreso ng pag-load. Ang DownloadProgress ay naglalaman ng totalSize (maaaring -1 kung hindi alam ang laki) at 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 — opsyonal na parameter na nagbibigay-daan sa pag-customize ng display ng larawan: pagdagdag ng rounding, anino, dekorasyon. Sa halimbawa, ginagamit ang DecorationImage na may BorderRadius para sa mga bilog na sulok.

Paggamit ng CachedNetworkImageProvider

CachedNetworkImageProvider — provider para sa Image o DecorationImage nang hindi ginagamit ang CachedNetworkImage widget. Kapaki-pakinabang kapag nagtatrabaho sa BoxDecoration, FadeInImage o custom na Image widgets.

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

ImageBuilder at custom na pagproseso

Ang parameter na imageBuilder sa CachedNetworkImage ay nagbibigay-daan sa pagpapalit ng karaniwang Image widget ng custom na implementasyon. Sa halip na direktang pagpapakita ng Image, maaaring gumamit ng Container na may dekorasyon, ClipRRect na may pagputol o Ink.image para sa ripple effect. Ang imageBuilder ay tumatanggap ng context at ImageProvider ng handa na larawan, na nagbibigay ng buong kontrol sa rendering.

Mga karagdagang parameter: memCacheWidth at memCacheHeight ay naglilimita sa laki ng naka-cache na larawan sa RAM, binabawasan ang load sa ImageCache ng Flutter. Ang cacheKey ay nagbibigay-daan sa pag-set ng custom na cache key sa halip na URL, kapaki-pakinabang para sa mga larawan na may authorization token sa URL (nagbabago ang query parameter sa bawat request, ngunit nananatiling pareho ang content).

CachedNetworkImage vs karaniwang Image.network

Ang karaniwang widget na Image.network ay naglo-load ng larawan sa bawat rebuild ng widget nang hindi ito nai-save sa disk. Ang CachedNetworkImage ay nagdadagdag ng file caching, progreso at paghawak ng error, ngunit nagdadagdag ng dependency sa flutter_cache_manager at SQLite.

Para sa mga project kung saan mahalaga ang offline na trabaho at pagtitipid ng bandwidth, ang CachedNetworkImage ay ang malinaw na pagpipilian. Para sa mga simpleng isang beses na screen (hal. onboarding o splash), ang Image.network ay hindi nangangailangan ng karagdagang dependency.

Pag-set up ng CachedNetworkImage sa Flutter project

Ang CachedNetworkImage ay idinadagdag bilang isang karaniwang pub.dev dependency. Pagkatapos ng pag-install, ang widget ay handa nang gamitin. Ang flutter_cache_manager ay pumapasok bilang isang transitive dependency.

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

Bilang default, ang DefaultCacheManager ay ginagamit na may mga setting: TTL = 7 araw, max 200 file. Para baguhin ang global na parameter, isang custom na CacheManager instance na may Config ay ginagawa, kung saan ang maxAgeCacheObject, maxNrOfCacheObjects at repo ay na-o-override.

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

// Paggamit ng custom na manager:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes at maxHeightBytes — mga opsyonal na parameter para sa paglilimita sa laki ng naka-cache na file. Ito ay kapaki-pakinabang para sa pagtitipid ng disk space kapag ang orihinal na larawan ay mas malaki kaysa sa kinakailangang laki ng screen.