SDWebImage: o que é, conceitos-chave e UIImageView

O que é SDWebImage?

SDWebImage é uma biblioteca para carregamento assíncrono de imagens nas plataformas Apple (iOS, macOS, tvOS, watchOS). Ela fornece uma categoria para UIImageView com o método sd_setImage, que carrega, armazena em cache e exibe uma imagem de qualquer fonte em uma única linha de código.

A biblioteca suporta carregamento progressivo (a imagem aparece à medida que os bytes são recebidos), imagens animadas (GIF, APNG), transformações (arredondamento, corte, marca d’água) e decodificadores personalizados. De acordo com GitHub Stats, o SDWebImage tem mais de 25.000 estrelas e é usado em aplicativos importantes, incluindo Twitter, Pinterest e Instagram.

A arquitetura é construída em uma cadeia de componentes: Coder (decodificação), Cache (armazenamento), Loader (rede) e Transformer (processamento). Cada componente é substituível, permitindo adaptar a biblioteca aos requisitos específicos do projeto.

Como funciona o SDWebImage: gerenciador e cache

SDWebImageManager é o componente central que coordena o processo de carregamento. Ele aceita uma URL, verifica o cache, carrega os dados, decodifica-os em UIImage e os passa para ImageView ou Completion Handler. O gerenciador opera através de um singleton compartilhado, acessível de qualquer lugar do aplicativo.

Processo de carregamento

O gerenciador verifica sequencialmente o Memory Cache (NSDictionary com UIImage), depois o Disk Cache (sistema de arquivos). Em caso de falta, uma requisição de rede é feita via NSURLSession. Após o carregamento, os dados são decodificados, passam por transformações e são salvos em ambos os caches. Todo o processo é executado em uma fila em segundo plano, com resultados entregues na fila principal.

• Memory Cache — busca O(1), armazena UIImage com limite de memória configurável
• Disk Cache — leitura do sistema de arquivos, armazena dados compactados
• NSURLSession — carregamento com suporte HTTP/2 e timeout configurável

Categoria UIImageView

UIImageView+WebCache é uma categoria Objective-C (acessível do Swift) que adiciona o método sd_setImage. Este método aceita uma URL, placeholder, opções (SDWebImageOptions) e um bloco de conclusão. A categoria cancela automaticamente a requisição anterior quando uma célula de tabela é reutilizada através do mecanismo sd_cancelCurrentImageLoad.

Classes principais do SDWebImage

A arquitetura do SDWebImage é dividida em vários módulos com áreas de responsabilidade claras. Cada classe resolve uma tarefa — do carregamento à exibição.

SDWebImageManager

SDWebImageManager é a fachada para todas as operações com imagens. Ele contém referências ao ImageCache (SDImageCache) e ImageLoader (SDWebImageDownloader). Através do delegado SDWebImageManagerDelegate, é possível interceptar o carregamento e alterar a URL ou o comportamento.

SDImageCache

SDImageCache é um cache de dois níveis (memória + disco) inicializado com um namespace único. O Memory Cache armazena UIImage com um limite configurável (por padrão — até aviso de memória do sistema). O Disk Cache armazena dados no diretório Library/Caches com duração de armazenamento configurável (padrão 7 dias).

SDWebImageDownloader

SDWebImageDownloader é um cliente HTTP baseado em NSURLSession com suporte a cabeçalhos, timeouts e tentativas. O downloader deduplica requisições idênticas em uma única chamada de rede e distribui o resultado entre todos os assinantes.

Arquitetura de cache do SDWebImage

O SDWebImage implementa cache de dois níveis com ordem de verificação determinística: primeiro memória, depois disco. A chave do cache é a URL absoluta da imagem sem parâmetros de consulta ou seu hash MD5.

Ao receber um aviso de memória, o iOS notifica o SDImageCache através de UIApplicationDidReceiveMemoryWarningNotification, após o qual o Memory Cache é completamente limpo. O Disk Cache é limpo por TTL ou quando o limite é excedido, ordenando os arquivos por data do último acesso.

Para gerenciamento manual do cache, os seguintes métodos estão disponíveis: clearMemory, clearDisk, calculateSize. O cache pode ser desativado para requisições específicas usando as opções SDWebImageCacheMemoryOnly ou SDWebImageAvoidAutoSetImage.

Exemplos de uso do SDWebImage em Swift

O SDWebImage fornece várias interfaces para carregar imagens: desde a simples categoria UIImageView até o gerenciador avançado com processamento personalizado.

Carregamento básico em UIImageView

sd_setImage é o método principal para carregar uma imagem em UIImageView. Ele aceita uma URL, placeholder e parâmetros opcionais através de Options e Context. Todos os Completion Handler são executados na thread principal.

let imageView = UIImageView()
imageView.sd_setImage(
    with: URL(string: "https://example.com/photo.jpg"),
    placeholderImage: UIImage(named: "placeholder"),
    options: [.progressiveLoad, .retryFailed],
    context: [.imageThumbnailPixelSize : CGSize(width: 300, height: 300)]
)

O método retorna um SDWebImageToken (operação) que pode ser cancelado se necessário. Internamente, sd_setImage chama SDWebImageManager.load, passando ImageView como Target para a configuração automática da imagem.

Carregamento com transformação personalizada

O SDWebImage suporta Transformer — um protocolo com um único método transformedImage. As transformações integradas incluem: círculo, cantos arredondados, sobreposição de filtro de cor e redimensionamento. As transformações podem ser combinadas usando o operador &&.

let transformer = SDImageResizingTransformer(
    size: CGSize(width: 200, height: 200),
    scaleMode: .aspectFill
)
let roundedTransformer = SDImageRoundCornerTransformer(
    radius: 16,
    corners: .allCorners,
    borderWidth: 0
)
imageView.sd_setImage(
    with: url,
    placeholderImage: placeholder,
    context: [.imageTransformer : transformer && roundedTransformer]
)

Uso com SwiftUI

A biblioteca fornece WebImage — um componente View para SwiftUI com suporte a placeholder, indicador de progresso e tratamento de erros. O componente se inscreve automaticamente no ciclo de vida da View e cancela o carregamento ao desaparecer.

struct CachedImageView: View {
    let url: URL

    var body: some View {
        WebImage(url: url) { phase in
            if let image = phase.image {
                image.resizable()
            } else if phase.error {
                Color.red
            } else {
                ProgressView()
            }
        }
    }
}

Transformações de imagem no SDWebImage

O SDWebImage fornece um sistema flexível de transformações através do protocolo SDImageTransformer. As transformações são aplicadas após a decodificação, mas antes do cache — o resultado da transformação é armazenado em disco sob uma nova chave, evitando reaplicação em requisições subsequentes.

As transformações integradas incluem: SDImageResizingTransformer (redimensionamento com mode), SDImageRoundCornerTransformer (cantos arredondados com borda opcional), SDImageFlipTransformer (espelhamento) e SDImageFilterTransformer (filtros CoreImage). A combinação é feita através do operador &&, criando uma cadeia de processamento.

Para transformações personalizadas, basta implementar o protocolo SDImageTransformer com o método transformedImageWithImage:forKey:. A chave de transformação é automaticamente adicionada à chave do cache, evitando colisões entre diferentes versões da mesma imagem.

Comparação SDWebImage vs Kingfisher

Na plataforma iOS, os principais concorrentes do SDWebImage são Kingfisher (Swift puro) e Nuke. A escolha entre SDWebImage e Kingfisher é frequentemente determinada pela linguagem do projeto e pela funcionalidade necessária.

O SDWebImage continua sendo a escolha preferida para projetos em Objective-C ou projetos híbridos. O Kingfisher é mais adequado para projetos em Swift puro devido à segurança de tipos e à sintaxe nativa do Swift. Ambas as bibliotecas têm arquitetura de cache e desempenho semelhantes.

Configuração do SDWebImage em um projeto iOS

O SDWebImage pode ser integrado via Swift Package Manager, CocoaPods ou Carthage. A biblioteca é dividida em módulos: principal (SDWebImage), Coder (formatos adicionais) e MapKit (para MKAnnotationView).

// Swift Package Manager (Package.swift)
dependencies: [
    .package(
        url: "https://github.com/SDWebImage/SDWebImage.git",
        from: "5.19.0"
    )
]

// CocoaPods (Podfile)
pod 'SDWebImage', '~> 5.19.0'
// Plugins para WebP e SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

Após a instalação, a biblioteca está pronta para uso sem configuração adicional. Para personalização do cache, crie uma instância de SDImageCache com um namespace único e passe-a para o SDWebImageManager durante a inicialização. A configuração global é feita através de SDWebImageManager.shared.

// Personalização do cache
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 dias em vez de 7
config.maxDiskSize = 500 * 1024 * 1024 // 500 MB
config.shouldCacheImagesInMemory = .true

let cache = SDImageCache(
    namespace: "custom",
    diskCacheDirectory: FileManager.default.urls(
        for: .cachesDirectory,
        in: .userDomainMask
    ).first?.appendingPathComponent("custom_cache"),
    config: config
)
SDWebImageManager.sharedImageCache = cache