Criando um WidgetKit Widget
Crie um widget para a tela inicial com uma linha do tempo.
Criando um WidgetKit Widget é uma aula grátis de Swift Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Swift Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Swift Academy inclui 4 aulas no total.
O que é um widget
Um widget é uma visualização pequena, feita para uma consulta rápida, que aparece na Tela de Início, na Tela Bloqueada ou no StandBy. Ele não é um miniaplicativo: não pode rolar nem executar código arbitrário. Ele exibe um instantâneo dos dados que o sistema atualiza conforme uma programação fornecida por você por meio do WidgetKit.
import WidgetKit
import SwiftUI
// A widget = configuration + timeline of entries
// + a SwiftUI view that renders one entryO destino da extensão de widget
Os widgets são distribuídos em um destino separado de extensão de widget, não no aplicativo principal. Ele tem seu próprio pacote e é executado em seu próprio processo. Você o adiciona usando o modelo de extensão de widget do Xcode, que cria a estrutura inicial da configuração e do fornecedor.
import WidgetKit
// File > New > Target > Widget Extension
// The extension declares one or more widgets
// in a WidgetBundle if you have several.O tipo de widget
Um widget está em conformidade com o protocolo Widget e expõe um body que retorna uma configuração. A configuração reúne um identificador de tipo, um fornecedor de linha do tempo e a visualização 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.")
}
}Configuração estática versus AppIntent
StaticConfiguration é usada para widgets sem opções do usuário. AppIntentConfiguration permite que os usuários personalizem o widget (escolhendo uma cidade ou uma conta) por meio de uma intenção de aplicativo. Escolha a configuração estática para conteúdo fixo e a baseada em intenção para widgets configuráveis.
import WidgetKit
// StaticConfiguration -> no user choices
// AppIntentConfiguration -> user-editable parameters
let kinds = "static vs configurable"
_ = kindsA entrada da linha do tempo
Cada momento que o widget pode exibir é uma TimelineEntry: uma estrutura com uma date e todos os dados necessários para a sua visualização. O fornecedor fornece uma sequência dessas entradas.
import WidgetKit
struct WeatherEntry: TimelineEntry {
let date: Date
let temperature: Int
let condition: String
}A visualização do widget
A visualização usa SwiftUI normalmente, mas tem limitações: não pode rolar, oferece interatividade limitada e precisa ter uma boa aparência em vários tamanhos fixos. Leia a entrada e organize um resumo limpo, fácil de consultar rapidamente.
import SwiftUI
import WidgetKit
struct WeatherView: View {
let entry: WeatherEntry
var body: some View {
VStack {
Text(entry.condition)
Text("\(entry.temperature) degrees")
.font(.title)
}
}
}Famílias compatíveis
Declare quais tamanhos são compatíveis com supportedFamilies: .systemSmall, .systemMedium, .systemLarge, os tamanhos da Tela Bloqueada .accessoryRectangular/.accessoryCircular e outros. Adapte o layout a cada família usando o ambiente da família do widget.
import WidgetKit
import SwiftUI
// .configurationDisplayName(...)
// .supportedFamilies([.systemSmall, .systemMedium,
// .accessoryRectangular])
let families = "declare supported sizes"
_ = familiesAdaptação à família
Leia @Environment(\.widgetFamily) dentro da visualização para alternar entre layouts — um widget pequeno e compacto ou um widget médio mais completo — sem escrever widgets separados.
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)")
}
}
}Plano de fundo do contêiner
Os widgets modernos precisam declarar o plano de fundo com containerBackground(for: .widget) para que o sistema possa renderizá-los corretamente em contextos como o StandBy e a Tela Bloqueada. Sem essa declaração, o widget pode ser rejeitado ou aparecer incorretamente.
import SwiftUI
import WidgetKit
struct Bg: View {
var body: some View {
Text("Hi")
.containerBackground(for: .widget) {
Color.blue
}
}
}Compartilhamento de dados com o aplicativo
O processo do widget é separado, portanto não pode ler o estado mantido na memória do aplicativo. Compartilhe dados por meio de um Grupo de Aplicativos — um contêiner compartilhado ao qual os dois destinos têm acesso — normalmente uma suíte compartilhada de UserDefaults ou um arquivo no contêiner do grupo.
import Foundation
let shared = UserDefaults(
suiteName: "group.com.example.app")
// App writes; widget reads the same suite.
_ = sharedAtualização do widget
Quando os dados do aplicativo mudarem, informe ao WidgetKit que deve atualizá-los chamando WidgetCenter.shared.reloadTimelines(ofKind:) (ou reloadAllTimelines()). Isso estimula o sistema a solicitar uma linha do tempo atualizada ao seu fornecedor.
import WidgetKit
func refreshWidget() {
WidgetCenter.shared.reloadTimelines(
ofKind: "WeatherWidget")
}Verificação rápida
Relembre como um widget compartilha dados com o aplicativo que o hospeda.
Recapitulação
Você criou um widget com WidgetKit:
- Os widgets ficam em uma extensão separada e estão em conformidade com
Widget, retornando umaWidgetConfiguration. - Use
StaticConfigurationouAppIntentConfiguration, umaTimelineEntrye uma visualização SwiftUI com limitações. - Declare
supportedFamilies, adapte o layout por meio dewidgetFamilye adicione umcontainerBackground. - Compartilhe dados por meio de um Grupo de Aplicativos e atualize o widget com
WidgetCenter.reloadTimelines.
Aprenda Swift com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 122
- Aulas
- 409
Perguntas Frequentes
A aula “Criando um WidgetKit Widget” é grátis?
Sim — o texto completo de “Criando um WidgetKit Widget” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Swift Academy, atualize para CoddyKit PRO. O curso de Swift Academy inclui 4 aulas no total.
O que vou aprender em “Criando um WidgetKit Widget”?
Crie um widget para a tela inicial com uma linha do tempo. Você pratica Swift Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Swift Academy?
Nenhuma experiência prévia é necessária. Swift Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “Criando um WidgetKit Widget”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Swift Academy?
Sim. Cada aula de Swift Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Criando um WidgetKit Widget
- Provedores de linha do tempo e instantâneos
- Visão geral das extensões de aplicativos
- App Intents e atalhos