Skip to main content

Image | Flutter

  • Image | Flutter

Classe Image no Dart (Flutter)​

A classe Image é um widget usado para exibir imagens na interface do Flutter, oferecendo várias propriedades para controlar tamanho, ajuste, alinhamento, qualidade, cache, carregamento e tratamento de erro.

Construtores mais usados​

Image.asset()​

Carrega imagem do diretório de assets do app.

Image.asset(
  'assets/images/logo.png',
  width: 120,
  height: 120,
)

Image.network()​

Carrega imagem via URL.

Image.network(
  'https://picsum.photos/300/200',
  width: 300,
  height: 200,
)

Image.file()​

Carrega imagem do armazenamento do dispositivo.

import 'dart:io';

Image.file(
  File('/storage/emulated/0/Download/imagem.png'),
  width: 200,
)

Image.memory()​

Carrega imagem a partir de bytes (Uint8List).

import 'dart:typed_data';

Image.memory(
  Uint8List.fromList([/* bytes aqui */]),
  width: 150,
)

Propriedades principais com exemplos​

width e height​

Controlam o tamanho do widget.

Image.network(
  'https://picsum.photos/400/400',
  width: 180,
  height: 180,
)

fit​

Controla como a imagem se ajusta ao espaço.

BoxFit.cover (preenche e corta se precisar)​

SizedBox(
  width: 200,
  height: 100,
  child: Image.network(
    'https://picsum.photos/500/300',
    fit: BoxFit.cover,
  ),
)

BoxFit.contain (mostra tudo sem cortar)​

SizedBox(
  width: 200,
  height: 100,
  child: Image.network(
    'https://picsum.photos/500/300',
    fit: BoxFit.contain,
  ),
)

BoxFit.fill (estica a imagem)​

SizedBox(
  width: 200,
  height: 100,
  child: Image.network(
    'https://picsum.photos/500/300',
    fit: BoxFit.fill,
  ),
)

alignment​

Define onde a imagem fica “ancorada” dentro do espaço.

SizedBox(
  width: 200,
  height: 100,
  child: Image.network(
    'https://picsum.photos/500/300',
    fit: BoxFit.cover,
    alignment: Alignment.topCenter,
  ),
)

color e colorBlendMode​

Aplica um efeito por cima da imagem 🎨

Image.network(
  'https://picsum.photos/300/200',
  color: const Color(0xAA000000),
  colorBlendMode: BlendMode.darken,
)

repeat​

Repete a imagem se sobrar espaço.

Container(
  width: 250,
  height: 150,
  decoration: BoxDecoration(border: Border.all()),
  child: Image.asset(
    'assets/images/pattern.png',
    repeat: ImageRepeat.repeat,
  ),
)

errorBuilder​

Exibe algo quando a imagem falhar.

Image.network(
  'https://url-quebrada.com/imagem.png',
  errorBuilder: (context, error, stackTrace) {
    return const Center(
      child: Text('Imagem indisponível'),
    );
  },
)

loadingBuilder​

Exibe progresso enquanto a imagem carrega.

Image.network(
  'https://picsum.photos/1200/800',
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) return child;

    final total = loadingProgress.expectedTotalBytes;
    final loaded = loadingProgress.cumulativeBytesLoaded;

    return Center(
      child: CircularProgressIndicator(
        value: total != null ? loaded / total : null,
      ),
    );
  },
)

filterQuality​

Melhora qualidade ao redimensionar (pode custar performance).

Image.asset(
  'assets/images/foto.png',
  width: 120,
  filterQuality: FilterQuality.high,
)

isAntiAlias​

Suaviza a imagem, útil em rotação ou recorte.

Transform.rotate(
  angle: 0.2,
  child: Image.network(
    'https://picsum.photos/200/200',
    isAntiAlias: true,
  ),
)

Parte de CACHE (✅ agora sim)​

O Flutter pode decodificar e armazenar imagens em cache automaticamente, mas você pode otimizar e controlar isso com:

  • cacheWidth
  • cacheHeight
  • gaplessPlayback
  • ImageCache (global)

cacheWidth e cacheHeight​

Essas propriedades pedem para o Flutter decodificar a imagem em um tamanho específico, reduzindo consumo de memória e melhorando performance (ótimo em listas/grids).

Exemplo: imagem em lista (otimizada)​

ListView.builder(
  itemCount: 50,
  itemBuilder: (context, index) {
    return ListTile(
      leading: Image.network(
        'https://picsum.photos/id/${index + 10}/600/600',
        width: 56,
        height: 56,
        fit: BoxFit.cover,
        cacheWidth: 112,  // 2x do tamanho (boa prática p/ telas densas)
        cacheHeight: 112,
      ),
      title: Text('Item $index'),
    );
  },
)

📌 Dica prática:

  • Se o widget é 56x56, você pode usar cacheWidth: 112 para manter nitidez em telas com densidade alta (2.0x).

gaplessPlayback​

Evita que a imagem “pisque” quando trocar o provider (ex: troca de URL ou rebuild).

Image.network(
  'https://picsum.photos/400/300',
  gaplessPlayback: true,
)

Cache global do Flutter: PaintingBinding.instance.imageCache​

Você pode ajustar limites do cache em memória (com cuidado ⚠️).

import 'package:flutter/painting.dart';

void configurarCache() {
  final cache = PaintingBinding.instance.imageCache;

  cache.maximumSize = 200; // quantidade de imagens
  cache.maximumSizeBytes = 50 * 1024 * 1024; // 50 MB
}

✅ Bom para apps com muita imagem (feed, catálogo) ⚠️ Se exagerar, pode aumentar uso de RAM.

Exemplo completo (com cache + loading + error)​

Image.network(
  'https://picsum.photos/1200/800',
  width: 300,
  height: 180,
  fit: BoxFit.cover,

  // Cache otimizado
  cacheWidth: 600,
  cacheHeight: 360,

  // Loading bonitinho
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) return child;

    return const Center(
      child: SizedBox(
        width: 24,
        height: 24,
        child: CircularProgressIndicator(strokeWidth: 2),
      ),
    );
  },

  // Fallback se der ruim
  errorBuilder: (context, error, stackTrace) {
    return Container(
      width: 300,
      height: 180,
      alignment: Alignment.center,
      color: const Color(0x11000000),
      child: const Text('Falha ao carregar'),
    );
  },
)