CachedNetworkImage: conceitos-chave e o widget ImageProvider

O que é CachedNetworkImage?

CachedNetworkImage é um widget Flutter do pacote homónimo no pub.dev que fornece carregamento de imagens da rede com cache automático. É um invólucro ao redor do Image.network padrão, adicionando cache de arquivos, indicadores de progresso e tratamento personalizado de erros.

Internamente, o CachedNetworkImage usa flutter_cache_manager — um gestor de cache com base de dados SQLite para rastrear ficheiros. No primeiro pedido, a imagem é descarregada da rede, guardada em disco e, em pedidos subsequentes, é servida a partir do cache tendo em conta o TTL (padrão 7 dias). O cache em memória é gerido pelo ImageCache padrão do Flutter.

O pacote tem mais de 4.000 gostos no pub.dev e é usado em milhares de projetos Flutter. O CachedNetworkImage suporta todas as plataformas Flutter: Android, iOS, Web, macOS, Windows e Linux. Graças a uma API unificada, os programadores obtêm carregamento de imagens multiplataforma sem código específico de plataforma.

Como funciona o cache de imagens no Flutter

O Flutter usa um sistema de cache de dois níveis: ImageCache (memória) e flutter_cache_manager (disco + SQLite). O ImageCache é um cache global de imagens descodificadas com limites de quantidade (padrão 1000) e tamanho (padrão 100 MB). O flutter_cache_manager gere os ficheiros em disco e os seus metadados.

Sequência de pesquisa

Quando o CachedNetworkImage recebe um pedido de imagem, primeiro verifica o ImageCache do Flutter — se a imagem já estiver descodificada em memória, é exibida instantaneamente. Em caso de falha de cache, o disco é verificado através do flutter_cache_manager: uma consulta SQLite verifica se o ficheiro existe no cache e se o seu TTL expirou. Se o ficheiro estiver atualizado — é lido do disco, descodificado e exibido. Se o ficheiro estiver ausente ou o TTL tiver expirado — é feito um pedido HTTP.

• ImageCache — cache global do Flutter, 1000 itens / 100 MB por padrão
• flutter_cache_manager — SQLite + sistema de ficheiros, TTL 7 dias
• Download HTTP — realizado através do pacote http ou HttpClient personalizado

Limpeza de cache

O DefaultCacheManager fornece os métodos emptyCache() (limpeza total), cleanCache() (remover apenas expirados) e clearCacheWithAge() com uma data personalizada. O ImageCache é limpo automaticamente sob pressão de memória ou manualmente através de imageCache.clear().

Arquitetura do widget CachedNetworkImage

O CachedNetworkImage é construído sobre a composição de widgets padrão do Flutter. A implementação interna usa ImageProvider para carregamento assíncrono e StatefulWidget para gestão do ciclo de vida.

Parâmetros-chave

imageUrl — parâmetro obrigatório, o URL da imagem (String ou Uri). placeholder — widget exibido durante o carregamento. errorWidget — widget em caso de erro de carregamento. progressIndicatorBuilder — builder que recebe contexto, URL e DownloadProgress com os campos totalSize e downloadedSize.

ImageProvider

CachedNetworkImageProvider — uma implementação de ImageProvider que retorna CachedNetworkStreamImage, que gere o download e o cache. O provedor integra-se com o ImageCache do Flutter e suporta todas as capacidades padrão do ImageProvider: dimensionamento, centralização e repetição.

Configuração do flutter_cache_manager

flutter_cache_manager é a biblioteca subjacente ao sistema de cache do CachedNetworkImage. Fornece o DefaultCacheManager com uma base de dados SQLite configurada, TTL e limite de ficheiros. Se necessário, pode ser criado um CacheManager personalizado com parâmetros únicos.

Um CacheManager personalizado é criado herdando de CacheManager com substituição de métodos. Isto é útil quando as imagens precisam de ser armazenadas num diretório separado ou é necessário um cliente HTTP diferente. A instância do gestor é então passada para o parâmetro cacheManager do CachedNetworkImage.

A base de dados SQLite do DefaultCacheManager está localizada no temporaryDirectory da aplicação no caminho `{key}/CacheObjects.db`. Contém a tabela cacheObjects com os campos: key (URL), relativePath, url, creationDate, eTag, httpHeaders. Ao limpar entradas expiradas, é utilizada uma consulta SQL com condição em maxAgeCacheObject.

Exemplos de uso do CachedNetworkImage em Dart

O CachedNetworkImage fornece duas abordagens principais de carregamento: o widget CachedNetworkImage e o CachedNetworkImageProvider para cenários personalizados.

Carregamento básico com placeholder

CachedNetworkImage — a abordagem principal. Basta passar imageUrl e placeholder. O widget exibe automaticamente o placeholder até o carregamento ser concluído e substitui-o pela imagem.

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 e errorWidget são funções builder que aceitam contexto, URL e (para errorWidget) um objeto de erro. Esta abordagem permite exibir diferentes placeholders dependendo do URL ou tipo de erro.

Carregamento com progresso

progressIndicatorBuilder — um parâmetro que permite exibir o progresso do download como percentagem. O DownloadProgress contém totalSize (pode ser -1 se desconhecido) e 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 — um parâmetro opcional que permite personalizar a exibição da imagem: adicionar cantos arredondados, sombras, decorações. O exemplo usa DecorationImage com BorderRadius para cantos arredondados.

Usando CachedNetworkImageProvider

CachedNetworkImageProvider — um provedor para Image ou DecorationImage sem usar o widget CachedNetworkImage. Útil ao trabalhar com BoxDecoration, FadeInImage ou widgets de imagem personalizados.

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

ImageBuilder e tratamento personalizado

O parâmetro imageBuilder no CachedNetworkImage permite substituir o widget Image padrão por uma implementação personalizada. Em vez de exibir diretamente a Image, pode usar um Container com decoração, ClipRRect para recorte, ou Ink.image para efeitos de ondulação. O imageBuilder recebe o contexto e o ImageProvider da imagem pronta, dando controlo total sobre a renderização.

Parâmetros adicionais: memCacheWidth e memCacheHeight limitam o tamanho da imagem em cache na RAM, reduzindo a carga no ImageCache do Flutter. cacheKey permite definir uma chave de cache personalizada em vez do URL, útil para imagens com tokens de autorização no URL (os parâmetros de consulta mudam a cada pedido mas o conteúdo permanece o mesmo).

CachedNetworkImage vs Image.network padrão

O widget padrão Image.network carrega a imagem em cada reconstrução do widget sem guardar em disco. O CachedNetworkImage adiciona cache de ficheiros, indicadores de progresso e tratamento de erros, mas adiciona uma dependência do flutter_cache_manager e SQLite.

Para projetos onde a capacidade offline e a poupança de largura de banda são importantes, o CachedNetworkImage é a escolha clara. Para ecrãs simples e únicos (por exemplo, onboarding ou splash), o Image.network não requer dependências adicionais.

Configurar CachedNetworkImage num projeto Flutter

O CachedNetworkImage é adicionado como uma dependência padrão do pub.dev. Após a instalação, o widget está pronto a usar. O flutter_cache_manager é incluído como dependência transitiva.

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

Por padrão, é usado o DefaultCacheManager com configurações: TTL = 7 dias, máx. 200 ficheiros. Para alterar os parâmetros globais, é criada uma instância personalizada de CacheManager com Config, onde maxAgeCacheObject, maxNrOfCacheObjects e repo são substituídos.

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

// Usando um gestor personalizado:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes e maxHeightBytes — parâmetros opcionais para limitar o tamanho do ficheiro em cache. Isto é útil para poupar espaço em disco quando a imagem original é maior do que o tamanho de ecrã necessário.