WidgetKit — qué es, framework de widgets y SwiftUI

¿Qué es WidgetKit y cómo funciona?

WidgetKit es un framework de Apple para crear widgets que muestran contenido en las pantallas del sistema de los dispositivos Apple. Un widget es una representación en miniatura de tu aplicación que el usuario coloca en la pantalla de inicio en modo jiggle. A diferencia de las complicaciones de watchOS que existían antes de WidgetKit, el nuevo framework unificó la creación de widgets para todas las plataformas Apple a través de una API única basada en SwiftUI.

El principio de funcionamiento de WidgetKit se basa en TimelineProvider — un objeto que crea un array ordenado de TimelineEntry, donde cada entrada contiene un Snapshot (un estado específico del widget en un momento determinado). El sistema muestra las entradas secuencialmente, actualizando el widget al pasar a la siguiente entrada en la línea de tiempo. Entre entradas, WidgetKit no ejecuta el código de la aplicación: el tiempo de CPU solo se consume al crear un nuevo Timeline.

Según la sesión WWDC 2024 “WidgetKit: What’s new”, el usuario promedio de iOS tiene entre 8 y 12 widgets en su pantalla de inicio, y las categorías más populares son clima, hora, calendario, fitness y finanzas. WidgetKit consume menos del 1% de la batería al día con un uso típico gracias a que las actualizaciones se realizan según un programa y no en tiempo real.

Qué diferencia a WidgetKit de los antiguos Today Extensions

Antes de iOS 14, los widgets solo existían como Today View — un panel accesible deslizando hacia la izquierda desde la primera pantalla. Today Extensions tenían limitaciones serias: solo estaban disponibles en la pantalla “Hoy”, requerían abrir la aplicación para actualizar el contenido y tenían soporte limitado de tamaños. WidgetKit reemplazó completamente Today Extensions, proporcionando widgets en la pantalla de inicio, la pantalla de bloqueo (iOS 16+) y el escritorio de Mac.

• Widgets en la pantalla de inicio, no solo en Today View
• Actualización autónoma mediante TimelineProvider, sin abrir la aplicación
• Tres tamaños predefinidos en lugar de uno
• Smart Rotate y Smart Stack — rotación automática de widgets por el sistema
• API unificada en SwiftUI para todas las plataformas Apple

Arquitectura de WidgetKit: TimelineProvider y Entry

La arquitectura de WidgetKit se basa en tres protocolos clave: TimelineProvider, TimelineEntry y Widget. TimelineEntry es un modelo de datos que representa el estado del widget en un momento específico. TimelineProvider crea un array de dichas entradas (Timeline), especificando la fecha de activación para cada una. Widget es el punto de entrada que conecta el proveedor con la vista SwiftUI.

El método de Timeline getTimeline es llamado por el sistema cuando el widget se añade por primera vez y luego periódicamente, generalmente cada 1–6 horas dependiendo del tipo de proveedor. Un Timeline puede contener entradas para horas o días adelante, lo que permite que el widget funcione sin llamar al código de la aplicación entre actualizaciones. Si se necesita una actualización urgente (por ejemplo, cambió el tipo de cambio), la aplicación puede llamar a WidgetCenter.shared.reloadAllTimelines() forzosamente.

TimelineProvider básico

struct SimpleEntry: TimelineEntry {
    let date: Date
    let value: Double
}

struct Provider: TimelineProvider {
    typealias Entry = SimpleEntry
    
    func placeholder(in context: Context) -> Entry {
        Entry(date: Date(), value: 0)
    }
    
    func getSnapshot(
        in context: Context,
        completion: @escaping (Entry) -> Void
    ) {
        Entry(date: Date(), value: 42.5)
    }
    
    func getTimeline(
        in context: Context,
        completion: @escaping (Timeline<Entry>, Error?) -> Void
    ) {
        let entry = Entry(date: Date(), value: fetchLatestValue())
        let nextUpdate = Calendar.current
            .date(byAdding: .hour, value: 1, to: Date())!
        let timeline = Timeline(entries: [entry], policy: .after(nextUpdate))
        completion(timeline, nil)
    }
}

Widget Family: small, medium, large

WidgetKit admite tres tamaños de widgets, cada uno con proporciones fijas. Small (170×170 pt en iPhone) muestra información compacta: un solo valor, icono o texto corto. Medium (364×170 pt) es el doble de ancho que small y es adecuado para mostrar pares de valores o minigráficos. Large (364×382 pt) ocupa casi la mitad de la pantalla en vertical y permite mostrar tablas, listas o datos ampliados.

El desarrollador debe admitir al menos dos tamaños: Apple recomienda small + medium. El widget Large solo es necesario si la aplicación tiene suficiente contenido para llenar ese volumen. Cada tamaño obtiene su propia vista SwiftUI, que WidgetKit renderiza en la pantalla del sistema. Es importante que WidgetKit no admite tamaños personalizados, solo tres fijos, lo que garantiza la uniformidad de la interfaz.

Configuración de tamaños mediante WidgetConfiguration

struct WeatherWidget: Widget {
    let kind: String = "WeatherWidget"
    
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            WeatherWidgetView(entry: entry)
        }
        .configurationDisplayName("Weather")
        .description("Current temperature and forecast")
        .supportedFamilies([.systemSmall, .systemMedium])
    }
}

Tipos de configuración de widgets: Static e Intent

WidgetKit ofrece dos tipos de configuración: StaticConfiguration e IntentConfiguration. StaticConfiguration es adecuado para widgets que muestran el mismo contenido para todos los usuarios: tipos de cambio, clima, calendario. IntentConfiguration permite al usuario personalizar el widget al agregarlo mediante el sistema de intents de Siri, por ejemplo, seleccionar una ciudad específica para el clima o un ticker específico para el precio de acciones.

IntentConfiguration utiliza INWidgetIntent — una subclase de INIntent de SiriKit. Cuando el usuario añade un widget y selecciona parámetros (por ejemplo, ciudad), el sistema guarda este intent y lo pasa a TimelineProvider en cada actualización. El proveedor recibe el intent en el método getTimeline y utiliza sus parámetros para formar el contenido. IntentConfiguration es la forma preferida para widgets personalizados, ya que se integra con Siri y Shortcuts.

IntentConfiguration con selección de parámetros

struct WeatherWidgetEntryView: View {
    var entry: WeatherEntry
    
    var body: some View {
        VStack(alignment: .leading) {
            Text(entry.cityName)
                .font(.caption)
                .foregroundColor(.secondary)
            Text("\(entry.temperature)°C")
                .font(.largeTitle)
        }
    }
}

struct WeatherWidget: Widget {
    var body: some WidgetConfiguration {
        IntentConfiguration(
            kind: "WeatherWidget",
            intent: WeatherConfigIntent.self,
            provider: WeatherTimelineProvider()
        ) { entry in
            WeatherWidgetEntryView(entry: entry)
        }
    }
}

Creación de un widget en SwiftUI: ejemplo paso a paso

La creación de un widget comienza añadiendo un Widget Extension Target en Xcode: File → New → Target → Widget Extension. Xcode genera automáticamente una estructura con TimelineEntry, TimelineProvider y WidgetConfiguration. El desarrollador solo necesita implementar la vista SwiftUI para mostrar los datos y configurar el proveedor para un programa de actualización correcto.

A continuación se muestra un ejemplo completo de un widget simple para mostrar el precio actual de Bitcoin: Provider carga la tasa mediante URLSession y crea un Timeline con actualizaciones cada hora. WidgetSwiftUIView muestra la tasa en fuente grande y la hora de la última actualización en fuente pequeña.

struct BTCPriceEntry: TimelineEntry {
    let date: Date
    let price: Double
    let change24h: Double
}

struct BTCWidgetEntryView: View {
    var entry: BTCPriceEntry
    
    var body: some View {
        VStack {
            Text("BTC/USD").font(.caption)
            Text("$\(entry.price, specifier: "%.0f")")
                .font(.title2).fontWeight(.bold)
            Text(entry.change24h > 0 ? "+" : "")
        }
    }
}

Widgets de pantalla de bloqueo iOS 16+

Con iOS 16, WidgetKit amplió el soporte a la Pantalla de bloqueo — la pantalla de bloqueo del iPhone. Los widgets de pantalla de bloqueo son de dos tipos: inline (una sola línea de texto debajo del reloj) y rectangular (un área rectangular). A diferencia de los widgets de la pantalla de inicio, los widgets de pantalla de bloqueo se actualizan con más frecuencia: el activador del sistema permite actualizarlos cada 15–30 minutos para mostrar información actual sin desbloquear el teléfono.

Los widgets de pantalla de bloqueo requieren una configuración separada mediante WidgetConfiguration con accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Estas familias tienen estrictas limitaciones de tamaño y contenido: no admiten imágenes, animaciones ni fuentes personalizadas. Apple recomienda usar solo información textual e iconos del sistema SF Symbols para los widgets de pantalla de bloqueo.

• accessoryCircular — widget circular compacto para el área debajo del reloj
• accessoryRectangular — widget rectangular para el área encima del reloj
• accessoryInline — texto de una línea debajo de la hora, tamaño mínimo
• Limitaciones: solo texto, SF Symbols, degradados; sin imágenes ni video

Mejores prácticas y limitaciones de WidgetKit

Al desarrollar widgets, es importante considerar las limitaciones de WidgetKit. Los widgets son vistas de solo lectura: no manejan eventos táctiles (excepto un toque que abre la aplicación). Los widgets no admiten animaciones, video, entrada de teclado, desplazamiento ni elementos interactivos. Cada widget es una instantánea estática de datos en un momento dado, e intentar agregar interactividad resultará en el rechazo de la aplicación en la App Store.

Las mejores prácticas incluyen usar Widget Center para actualizaciones forzadas, almacenar en caché los datos a nivel de TimelineProvider para una respuesta rápida y usar placeholders para el estado inicial. También es importante admitir múltiples tamaños: los usuarios esperan que el widget esté disponible tanto en variante small como medium. Evita mostrar datos inexactos o desactualizados: los usuarios recuerdan la información incorrecta de los widgets durante mucho tiempo.

Tabla de limitaciones de WidgetKit