Swift Academy · Lezione

Creazione di un widget WidgetKit

Crei un widget per la schermata Home con una timeline.

Creazione di un widget WidgetKit è una lezione Swift Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Swift Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Swift Academy include 4 lezioni in totale.

Che cos'è un widget

Un widget è una piccola vista consultabile a colpo d'occhio che risiede nella schermata Home, nella schermata di blocco o in StandBy. Non è una mini-app: non può scorrere né eseguire codice arbitrario. Visualizza un'istantanea dei dati che il sistema aggiorna secondo una pianificazione fornita tramite WidgetKit.

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

Il target Widget Extension

I widget vengono distribuiti in un target separato di Widget Extension, non nell'app principale. Dispongono di un proprio bundle ed eseguono in un processo distinto. Lo aggiunga tramite il modello Widget Extension di Xcode, che predispone la configurazione e il provider.

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

Il tipo di widget

Un widget è conforme al protocollo Widget ed espone un body che restituisce una configurazione. La configurazione collega un identificatore kind, un provider della timeline e la view che esegue il rendering di ogni entry.

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.")
    }
}

Configurazione statica e AppIntent

StaticConfiguration è destinata ai widget privi di opzioni per l'utente. AppIntentConfiguration consente agli utenti di personalizzare il widget (scegliere una città o un account) tramite un App Intent. Scelga la configurazione statica per i contenuti fissi e quella basata su intent per i widget configurabili.

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

La timeline entry

Ogni momento nel tempo che il widget può mostrare è una TimelineEntry: una struct con una date e tutti i dati necessari alla view. Il provider fornisce una sequenza di queste entry.

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

La view del widget

La view è una normale SwiftUI, ma con alcune limitazioni: niente scorrimento, interattività limitata e un aspetto corretto a diverse dimensioni fisse. Legga l'entry e disponga un riepilogo pulito, consultabile a colpo d'occhio.

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

Famiglie supportate

Dichiari le dimensioni supportate con supportedFamilies: .systemSmall, .systemMedium, .systemLarge, le famiglie della schermata di blocco .accessoryRectangular/.accessoryCircular e altre ancora. Adatti il layout per ogni famiglia usando l'ambiente della famiglia del widget.

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

Adattamento alla famiglia

Legga @Environment(\.widgetFamily) all'interno della view per scegliere layout diversi, ad esempio un widget small compatto rispetto a uno medium più ricco, senza scrivere widget separati.

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

Sfondo del contenitore

I widget moderni devono dichiarare lo sfondo con containerBackground(for: .widget), affinché il sistema possa eseguirne correttamente il rendering in contesti come StandBy e la schermata di blocco. Senza questa dichiarazione, il widget potrebbe essere rifiutato o apparire in modo errato.

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

Condivisione dei dati con l'app

Il processo del widget è separato, quindi non può leggere lo stato in memoria dell'app. Condivida i dati tramite un App Group, un contenitore condiviso a cui entrambi i target possono accedere, in genere una suite UserDefaults condivisa o un file nel contenitore del gruppo.

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

Aggiornamento del widget

Quando cambiano i dati dell'app, informi WidgetKit di aggiornare il widget chiamando WidgetCenter.shared.reloadTimelines(ofKind:) (o reloadAllTimelines()). In questo modo il sistema viene sollecitato a chiedere al provider una timeline aggiornata.

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

Verifica rapida

Ricordi come un widget condivide i dati con l'app che lo ospita.

Riepilogo

Ha creato un widget WidgetKit:

I widget risiedono in un'estensione separata, sono conformi a Widget e restituiscono una WidgetConfiguration.
Utilizzi StaticConfiguration o AppIntentConfiguration, una TimelineEntry e una view SwiftUI con interattività limitata.
Dichiari supportedFamilies, adatti il layout tramite widgetFamily e aggiunga un containerBackground.
Condivida i dati tramite un App Group e aggiorni il widget con WidgetCenter.reloadTimelines.

Domande Frequenti

La lezione «Creazione di un widget WidgetKit» è gratuita?

Sì — il testo completo di «Creazione di un widget WidgetKit» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Swift Academy, passa a CoddyKit PRO. Il corso Swift Academy include 4 lezioni in totale.

Cosa imparerò in «Creazione di un widget WidgetKit»?

Crei un widget per la schermata Home con una timeline. Eserciti Swift Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Swift Academy?

Non è richiesta alcuna esperienza precedente. Swift Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Creazione di un widget WidgetKit»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Swift Academy?

Sì. Ogni lezione Swift Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a Swift Academy