SDWebImage: qué es, conceptos clave y UIImageView

¿Qué es SDWebImage?

SDWebImage es una biblioteca para la carga asíncrona de imágenes en plataformas Apple (iOS, macOS, tvOS, watchOS). Proporciona una categoría para UIImageView con el método sd_setImage, que carga, almacena en caché y muestra una imagen desde cualquier fuente en una sola línea de código.

La biblioteca admite carga progresiva (la imagen aparece a medida que se reciben los bytes), imágenes animadas (GIF, APNG), transformaciones (redondeo, recorte, marcas de agua) y decodificadores personalizados. Según GitHub Stats, SDWebImage tiene más de 25.000 estrellas y se utiliza en aplicaciones importantes, incluyendo Twitter, Pinterest e Instagram.

La arquitectura se basa en una cadena de componentes: Coder (decodificación), Cache (almacenamiento), Loader (red) y Transformer (procesamiento). Cada componente es reemplazable, lo que permite adaptar la biblioteca a los requisitos específicos del proyecto.

Cómo funciona SDWebImage: gestor y caché

SDWebImageManager es el componente central que coordina el proceso de carga. Acepta una URL, verifica el caché, carga los datos, los decodifica en UIImage y los pasa a ImageView o Completion Handler. El gestor funciona a través de un singleton compartido, accesible desde cualquier parte de la aplicación.

Proceso de carga

El gestor verifica secuencialmente el Memory Cache (NSDictionary con UIImage), luego el Disk Cache (sistema de archivos). En caso de fallo, se realiza una solicitud de red a través de NSURLSession. Después de la carga, los datos se decodifican, pasan por transformaciones y se guardan en ambos cachés. Todo el proceso se ejecuta en una cola en segundo plano y los resultados se entregan en la cola principal.

• Memory Cache — búsqueda O(1), almacena UIImage con un límite de memoria configurable
• Disk Cache — lectura del sistema de archivos, almacena datos comprimidos
• NSURLSession — carga con soporte HTTP/2 y tiempo de espera configurable

Categoría UIImageView

UIImageView+WebCache es una categoría de Objective-C (accesible desde Swift) que añade el método sd_setImage. Este método acepta una URL, placeholder, opciones (SDWebImageOptions) y un bloque de finalización. La categoría cancela automáticamente la solicitud anterior cuando se reutiliza una celda de tabla a través del mecanismo sd_cancelCurrentImageLoad.

Clases principales de SDWebImage

La arquitectura de SDWebImage se divide en varios módulos con zonas de responsabilidad claras. Cada clase resuelve una tarea, desde la carga hasta la visualización.

SDWebImageManager

SDWebImageManager es la fachada para todas las operaciones con imágenes. Contiene referencias a ImageCache (SDImageCache) e ImageLoader (SDWebImageDownloader). A través del delegado SDWebImageManagerDelegate, se puede interceptar la carga y cambiar la URL o el comportamiento.

SDImageCache

SDImageCache es un caché de dos niveles (memoria + disco) inicializado con un namespace único. Memory Cache almacena UIImage con un límite configurable (por defecto, hasta que se recibe una advertencia de memoria del sistema). Disk Cache almacena datos en el directorio Library/Caches con una duración de almacenamiento configurable (por defecto 7 días).

SDWebImageDownloader

SDWebImageDownloader es un cliente HTTP basado en NSURLSession con soporte para cabeceras, tiempos de espera y reintentos. El descargador desduplica solicitudes idénticas en una única llamada de red y distribuye el resultado entre todos los suscriptores.

Arquitectura de caché de SDWebImage

SDWebImage implementa un caché de dos niveles con un orden de verificación determinista: primero memoria, luego disco. La clave de caché es la URL absoluta de la imagen sin parámetros de consulta o su hash MD5.

Al recibir una advertencia de memoria, iOS notifica a SDImageCache a través de UIApplicationDidReceiveMemoryWarningNotification, tras lo cual el Memory Cache se limpia por completo. El Disk Cache se limpia por TTL o cuando se supera el límite, ordenando los archivos por fecha del último acceso.

Para la gestión manual del caché, están disponibles los siguientes métodos: clearMemory, clearDisk, calculateSize. El caché se puede desactivar para solicitudes específicas mediante las opciones SDWebImageCacheMemoryOnly o SDWebImageAvoidAutoSetImage.

Ejemplos de uso de SDWebImage en Swift

SDWebImage proporciona varias interfaces para cargar imágenes: desde la simple categoría UIImageView hasta el gestor avanzado con procesamiento personalizado.

Carga básica en UIImageView

sd_setImage es el método principal para cargar una imagen en UIImageView. Acepta una URL, placeholder y parámetros opcionales a través de Options y Context. Todos los Completion Handler se ejecutan en el hilo 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)]
)

El método devuelve un SDWebImageToken (operación) que se puede cancelar si es necesario. Internamente, sd_setImage llama a SDWebImageManager.load, pasando ImageView como Target para el establecimiento automático de la imagen.

Carga con transformación personalizada

SDWebImage admite Transformer — un protocolo con un único método transformedImage. Las transformaciones integradas incluyen: círculo, esquinas redondeadas, superposición de filtro de color y cambio de tamaño. Las transformaciones se pueden combinar usando el 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 con SwiftUI

La biblioteca proporciona WebImage — un componente View para SwiftUI con soporte para placeholder, indicador de progreso y manejo de errores. El componente se suscribe automáticamente al ciclo de vida de la View y cancela la carga cuando desaparece.

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()
            }
        }
    }
}

Transformaciones de imagen en SDWebImage

SDWebImage proporciona un sistema flexible de transformaciones a través del protocolo SDImageTransformer. Las transformaciones se aplican después de la decodificación pero antes del almacenamiento en caché — el resultado de la transformación se guarda en disco bajo una nueva clave, evitando la reaplicación en solicitudes posteriores.

Las transformaciones integradas incluyen: SDImageResizingTransformer (cambio de tamaño con mode), SDImageRoundCornerTransformer (esquinas redondeadas con borde opcional), SDImageFlipTransformer (reflejo) y SDImageFilterTransformer (filtros CoreImage). La combinación se realiza mediante el operador &&, creando una cadena de procesamiento.

Para transformaciones personalizadas, basta con implementar el protocolo SDImageTransformer con el método transformedImageWithImage:forKey:. La clave de transformación se añade automáticamente a la clave de caché, evitando colisiones entre diferentes versiones de la misma imagen.

Comparación de SDWebImage con Kingfisher

En la plataforma iOS, los principales competidores de SDWebImage son Kingfisher (Swift puro) y Nuke. La elección entre SDWebImage y Kingfisher a menudo viene determinada por el lenguaje del proyecto y la funcionalidad requerida.

SDWebImage sigue siendo la opción preferida para proyectos en Objective-C o proyectos híbridos. Kingfisher es más adecuado para proyectos en Swift puro gracias a la seguridad de tipos y la sintaxis nativa de Swift. Ambas bibliotecas tienen una arquitectura de caché y un rendimiento similares.

Configuración de SDWebImage en un proyecto iOS

SDWebImage se puede integrar a través de Swift Package Manager, CocoaPods o Carthage. La biblioteca está dividida en módulos: principal (SDWebImage), Coder (formatos adicionales) y 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 y SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

Después de la instalación, la biblioteca está lista para usar sin configuración adicional. Para personalizar el caché, crea una instancia de SDImageCache con un namespace único y pásala a SDWebImageManager durante la inicialización. La configuración global se realiza a través de SDWebImageManager.shared.

// Personalización del caché
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 días en lugar 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