WidgetKit — o que é, framework de widgets e SwiftUI

O que é WidgetKit e como funciona?

WidgetKit é um framework da Apple para criar widgets que exibem conteúdo nas telas do sistema dos dispositivos Apple. Um widget é uma representação em miniatura do seu aplicativo que o usuário coloca na tela inicial no modo jiggle. Ao contrário das complicações do watchOS que existiam antes do WidgetKit, o novo framework unificou a criação de widgets para todas as plataformas Apple através de uma API única baseada em SwiftUI.

O princípio de funcionamento do WidgetKit é baseado em TimelineProvider — um objeto que cria um array ordenado de TimelineEntry, onde cada entrada contém um Snapshot (um estado específico do widget em um determinado momento). O sistema exibe as entradas sequencialmente, atualizando o widget ao passar para a próxima entrada na linha do tempo. Entre as entradas, o WidgetKit não chama o código do aplicativo — o tempo de CPU é gasto apenas ao criar uma nova Timeline.

De acordo com a sessão WWDC 2024 “WidgetKit: What’s new”, o usuário médio do iOS tem 8–12 widgets na tela inicial, e as categorias mais populares são clima, hora, calendário, fitness e finanças. O WidgetKit consome menos de 1% da carga da bateria por dia em uso típico, graças a atualizações programadas em vez de atualizações em tempo real.

O que diferencia o WidgetKit dos antigos Today Extensions

Antes do iOS 14, os widgets existiam apenas como Today View — um painel acessível deslizando para a esquerda a partir da primeira tela. Os Today Extensions tinham limitações sérias: estavam disponíveis apenas na tela “Hoje”, exigiam abrir o aplicativo para atualizar o conteúdo e tinham suporte limitado de tamanhos. O WidgetKit substituiu completamente os Today Extensions, fornecendo widgets na tela inicial, tela de bloqueio (iOS 16+) e área de trabalho do Mac.

• Widgets na tela inicial, não apenas no Today View
• Atualização autônoma via TimelineProvider, sem abrir o aplicativo
• Três tamanhos predefinidos em vez de um
• Smart Rotate e Smart Stack — rotação automática de widgets pelo sistema
• API unificada em SwiftUI para todas as plataformas Apple

Arquitetura do WidgetKit: TimelineProvider e Entry

A arquitetura do WidgetKit é construída em três protocolos principais: TimelineProvider, TimelineEntry e Widget. TimelineEntry é um modelo de dados que representa o estado do widget em um momento específico. TimelineProvider cria um array de tais entradas (Timeline), especificando a data de ativação para cada uma. Widget é o ponto de entrada que conecta o provedor à view SwiftUI.

O método Timeline getTimeline é chamado pelo sistema quando o widget é adicionado pela primeira vez e depois periodicamente — geralmente a cada 1–6 horas, dependendo do tipo de provedor. Uma Timeline pode conter entradas para horas ou dias à frente, permitindo que o widget funcione sem chamar o código do aplicativo entre as atualizações. Se for necessária uma atualização urgente (por exemplo, a taxa de câmbio mudou), o aplicativo pode chamar WidgetCenter.shared.reloadAllTimelines() forçadamente.

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

O WidgetKit suporta três tamanhos de widgets, cada um com proporções fixas. Small (170×170 pt no iPhone) exibe informações compactas — um único valor, ícone ou texto curto. Medium (364×170 pt) tem o dobro da largura do small e é adequado para exibir pares de valores ou minigráficos. Large (364×382 pt) ocupa quase metade da tela verticalmente e permite exibir tabelas, listas ou dados expandidos.

O desenvolvedor deve suportar pelo menos dois tamanhos — a Apple recomenda small + medium. O widget Large é necessário apenas se o aplicativo tiver conteúdo suficiente para preencher esse volume. Cada tamanho recebe sua própria SwiftUI View, que o WidgetKit renderiza na tela do sistema. É importante que o WidgetKit não suporta tamanhos personalizados — apenas três tamanhos fixos, garantindo uniformidade da interface.

Configuração de tamanhos via 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 configuração de widgets: Static e Intent

O WidgetKit oferece dois tipos de configuração — StaticConfiguration e IntentConfiguration. StaticConfiguration é adequado para widgets que exibem o mesmo conteúdo para todos os usuários: taxas de câmbio, clima, calendário. IntentConfiguration permite ao usuário personalizar o widget ao adicioná-lo através do sistema de intents do Siri — por exemplo, selecionar uma cidade específica para o clima ou um ticker específico para o preço de ações.

IntentConfiguration usa INWidgetIntent — uma subclasse de INIntent do SiriKit. Quando o usuário adiciona um widget e seleciona parâmetros (por exemplo, cidade), o sistema salva este intent e o passa para o TimelineProvider a cada atualização. O provedor recebe o intent no método getTimeline e usa seus parâmetros para formar o conteúdo. IntentConfiguration é a abordagem preferida para widgets personalizados, pois se integra com Siri e Shortcuts.

IntentConfiguration com seleção 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)
        }
    }
}

Criação de um widget em SwiftUI: exemplo passo a passo

A criação de um widget começa adicionando um Widget Extension Target no Xcode: File → New → Target → Widget Extension. O Xcode gera automaticamente uma estrutura com TimelineEntry, TimelineProvider e WidgetConfiguration. O desenvolvedor só precisa implementar a SwiftUI View para exibir os dados e configurar o provedor para um cronograma de atualização correto.

Abaixo está um exemplo completo de um widget simples para exibir o preço atual do Bitcoin: Provider carrega a taxa via URLSession e cria uma Timeline com atualizações a cada hora. WidgetSwiftUIView exibe a taxa em fonte grande e a hora da última atualização em fonte pequena.

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 tela de bloqueio iOS 16+

Com o iOS 16, o WidgetKit estendeu o suporte para a Tela de bloqueio — a tela de bloqueio do iPhone. Os widgets de tela de bloqueio são de dois tipos: inline (uma única linha de texto abaixo do relógio) e rectangular (uma área retangular). Ao contrário dos widgets da tela inicial, os widgets de tela de bloqueio são atualizados com mais frequência — o gatilho do sistema permite atualizações a cada 15–30 minutos para exibir informações atuais sem desbloquear o telefone.

Os widgets de tela de bloqueio exigem configuração separada via WidgetConfiguration com accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Essas famílias têm limitações estritas de tamanho e conteúdo — não suportam imagens, animações ou fontes personalizadas. A Apple recomenda usar apenas informações textuais e ícones do sistema SF Symbols para widgets de tela de bloqueio.

• accessoryCircular — widget circular compacto para a área abaixo do relógio
• accessoryRectangular — widget retangular para a área acima do relógio
• accessoryInline — texto de uma linha abaixo da hora, tamanho mínimo
• Limitações: apenas texto, SF Symbols, gradientes; sem imagens ou vídeo

Melhores práticas e limitações do WidgetKit

Ao desenvolver widgets, é importante considerar as limitações do WidgetKit. Os widgets são visualizações somente leitura: eles não manipulam eventos de toque (exceto um toque que abre o aplicativo). Os widgets não suportam animação, vídeo, entrada de teclado, rolagem ou elementos interativos. Cada widget é uma captura instantânea estática de dados em um determinado momento, e tentar adicionar interatividade resultará na rejeição do aplicativo na App Store.

As melhores práticas incluem usar o Widget Center para atualizações forçadas, armazenar dados em cache no nível do TimelineProvider para resposta rápida e usar placeholders para o estado inicial. Também é importante suportar vários tamanhos — os usuários esperam que o widget esteja disponível tanto na variante small quanto medium. Evite rigorosamente exibir dados imprecisos ou desatualizados — os usuários se lembram de informações incorretas dos widgets por muito tempo.

Tabela de limitações do WidgetKit