Swift Academy · Lección

Cómo crear un widget con WidgetKit

Cree un widget para la pantalla de inicio con una línea de tiempo.

Cómo crear un widget con WidgetKit es una lección gratuita de Swift Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Swift Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Swift Academy incluye 4 lecciones en total.

Qué es un widget

Un widget es una vista pequeña que puede consultarse de un vistazo y que aparece en la pantalla de inicio, la pantalla bloqueada o StandBy. No es una miniapp: no puede desplazarse ni ejecutar código arbitrario. Muestra una instantánea de los datos que el sistema actualiza según el calendario que proporcione mediante WidgetKit.

import WidgetKit
import SwiftUI
// A widget = configuration + timeline of entries
// + a SwiftUI view that renders one entry

El destino de extensión del widget

Los widgets se distribuyen en un destino independiente de tipo Widget Extension, no en la app principal. Tiene su propio bundle y se ejecuta en su propio proceso. Puede añadirlo mediante la plantilla Widget Extension de Xcode, que genera la configuración y el proveedor.

import WidgetKit
// File > New > Target > Widget Extension
// The extension declares one or more widgets
// in a WidgetBundle if you have several.

El tipo de widget

Un widget adopta el protocolo Widget y expone un body que devuelve una configuración. La configuración combina un identificador kind, un proveedor de línea de tiempo y la vista que renderiza cada entrada.

import WidgetKit
import SwiftUI
struct WeatherWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "WeatherWidget",
            provider: WeatherProvider()) { entry in
            WeatherView(entry: entry)
        }
        .configurationDisplayName("Weather")
        .description("Shows the current forecast.")
    }
}

Configuración estática frente a configuración con App Intent

StaticConfiguration es para widgets sin opciones para el usuario. AppIntentConfiguration permite a los usuarios personalizar el widget (elegir una ciudad o una cuenta) mediante un App Intent. Elija la configuración estática para contenido fijo y la basada en intents para widgets configurables.

import WidgetKit
// StaticConfiguration     -> no user choices
// AppIntentConfiguration  -> user-editable parameters
let kinds = "static vs configurable"
_ = kinds

La entrada de la línea de tiempo

Cada momento que el widget puede mostrar es un TimelineEntry: una estructura con una date y los datos que necesite la vista. El proveedor proporciona una secuencia de estas entradas.

import WidgetKit
struct WeatherEntry: TimelineEntry {
    let date: Date
    let temperature: Int
    let condition: String
}

La vista del widget

La vista es SwiftUI estándar, pero tiene restricciones: no permite desplazamiento, ofrece interactividad limitada y debe verse correctamente en varios tamaños fijos. Lea la entrada y organice un resumen claro que pueda consultarse de un vistazo.

import SwiftUI
import WidgetKit
struct WeatherView: View {
    let entry: WeatherEntry
    var body: some View {
        VStack {
            Text(entry.condition)
            Text("\(entry.temperature) degrees")
                .font(.title)
        }
    }
}

Familias compatibles

Declare los tamaños compatibles con supportedFamilies: .systemSmall, .systemMedium, .systemLarge, .accessoryRectangular/.accessoryCircular para la pantalla bloqueada, entre otros. Adapte el diseño a cada familia mediante el entorno de familia del widget.

import WidgetKit
import SwiftUI
// .configurationDisplayName(...)
// .supportedFamilies([.systemSmall, .systemMedium,
//                     .accessoryRectangular])
let families = "declare supported sizes"
_ = families

Adaptación a la familia

Lea @Environment(\.widgetFamily) dentro de la vista para elegir distintos diseños —un widget pequeño y compacto frente a uno mediano más completo— sin escribir widgets independientes.

import SwiftUI
import WidgetKit
struct AdaptiveView: View {
    @Environment(\.widgetFamily) var family
    let entry: WeatherEntry
    var body: some View {
        if family == .systemSmall {
            Text("\(entry.temperature)")
        } else {
            Text("\(entry.condition) \(entry.temperature)")
        }
    }
}

Fondo del contenedor

Los widgets modernos deben declarar su fondo con containerBackground(for: .widget) para que el sistema pueda renderizarlos correctamente en contextos como StandBy y la pantalla bloqueada. Sin esta declaración, el widget puede rechazarse o verse incorrectamente.

import SwiftUI
import WidgetKit
struct Bg: View {
    var body: some View {
        Text("Hi")
            .containerBackground(for: .widget) {
                Color.blue
            }
    }
}

Compartir datos con la app

El proceso del widget está separado, por lo que no puede leer el estado en memoria de la app. Comparta los datos mediante un App Group: un contenedor compartido al que pueden acceder ambos destinos, normalmente un conjunto compartido de UserDefaults o un archivo en el contenedor del grupo.

import Foundation
let shared = UserDefaults(
    suiteName: "group.com.example.app")
// App writes; widget reads the same suite.
_ = shared

Actualizar el widget

Cuando cambien los datos de la app, indique a WidgetKit que se actualice llamando a WidgetCenter.shared.reloadTimelines(ofKind:) (o reloadAllTimelines()). Esto hace que el sistema solicite al proveedor una línea de tiempo actualizada.

import WidgetKit
func refreshWidget() {
    WidgetCenter.shared.reloadTimelines(
        ofKind: "WeatherWidget")
}

Comprobación rápida

Recuerde cómo comparte datos un widget con su app anfitriona.

Resumen

Ha creado un widget con WidgetKit:

Los widgets viven en una extensión independiente y adoptan Widget, que devuelve un WidgetConfiguration.
Use StaticConfiguration o AppIntentConfiguration, un TimelineEntry y una vista SwiftUI con restricciones.
Declare supportedFamilies, adapte el diseño mediante widgetFamily y añada un containerBackground.
Comparta los datos mediante un App Group y actualice el widget con WidgetCenter.reloadTimelines.

Preguntas frecuentes

¿La lección «Cómo crear un widget con WidgetKit» es gratis?

Sí — el texto completo de «Cómo crear un widget con WidgetKit» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Swift Academy, actualiza a CoddyKit PRO. El curso de Swift Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Cómo crear un widget con WidgetKit»?

Cree un widget para la pantalla de inicio con una línea de tiempo. Practicas Swift Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Swift Academy?

No se requiere experiencia previa. Swift Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Cómo crear un widget con WidgetKit»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Swift Academy?

Sí. Cada lección de Swift Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Cómo crear un widget con WidgetKit
Proveedores de líneas de tiempo y snapshots
Descripción general de las extensiones de apps
App Intents y Shortcuts

← Volver a Swift Academy