@Published: o que é, princípio de funcionamento e aplicação

O que é @Published?

@Published é um property wrapper definido no módulo Combine que adiciona a capacidade de notificar automaticamente os assinantes sobre alterações em uma propriedade de classe. Só pode ser usado dentro de uma classe (não em uma struct) e apenas em propriedades de uma classe em conformidade com o protocolo ObservableObject.

Quando o valor de uma propriedade @Published muda, o Combine gera um evento através de um publisher embutido acessível pelo prefixo cifrão: $propertyName. Este publisher é um ObservableObjectPublisher, que pertence ao próprio ObservableObject. O SwiftUI inscreve-se automaticamente nele quando uma visualização usa @ObservedObject ou @StateObject, e redesenha a visualização sempre que qualquer propriedade @Published dentro do objeto muda.

De acordo com o livro de Matt Neuburg “IOS 18 Programming Fundamentals with Swift” (2025), o @Published é um invólucro conveniente sobre o padrão willSet, chamando automaticamente objectWillChange.send(). Com efeito, o compilador expande @Published em uma propriedade computada com um observador willSet, fornecendo sobrecarga zero em tempo de execução em comparação com a implementação manual.

Use @Published para todas as propriedades ObservableObject cujas alterações devem ser refletidas na interface. Para propriedades que não afetam a UI, propriedades armazenadas comuns sem @Published reduzem redesenho desnecessários.

Como funciona o @Published

@Published gera dois elementos-chave em tempo de compilação. O primeiro é uma propriedade armazenada com um observador willSet que chama objectWillChange.send() antes de escrever o novo valor. O segundo é a projeção $propertyName, que retorna um Published.Publisher que pode ser usado diretamente em pipelines Combine.

Considere a classe Settings com três propriedades: duas @Published e uma normal:

class Settings: ObservableObject {
    @Published var username: String = "Guest"
    @Published var isDarkMode = false
    var lastLogin: Date = Date()  // without @Published
}

Quando username ou isDarkMode muda, o SwiftUI redesenhará todas as visualizações inscritas na instância Settings. Alterar lastLogin não acionará um redesenho. Se precisar notificar manualmente os assinantes sobre uma alteração em uma propriedade normal, você pode chamar objectWillChange.send() no observador willSet.

Um detalhe importante: @Published só publica alterações quando uma propriedade é diretamente atribuída. Se a propriedade for de tipo referência (classe) e seu estado interno mudar sem substituir a referência, o @Published não detectará isso. Nesses casos, é necessário o envio manual de eventos ou a mudança para um tipo valor (struct).

@Published e Combine

@Published é estritamente integrado com Combine — cada propriedade @Published fornece automaticamente um publisher acessível através da projeção $propertyName. Isso permite usar operadores Combine para filtrar, transformar, combinar e processar valores de forma adiada.

Um cenário típico é a pesquisa com debounce. Um campo de entrada está vinculado à propriedade @Published searchText, mas a solicitação ao servidor deve ser enviada apenas após uma pausa de 300 ms. Combine com $searchText.debounce resolve isso em uma linha:

class SearchViewModel: ObservableObject {
    @Published var searchText = ""
    @Published var results: [String] = []
    private var cancellables = Set<AnyCancellable>()

    init() {
        setupSearchSubscription()
    }

    private func setupSearchSubscription() {
        $searchText
            .debounce(for: .milliseconds(300), scheduler: RunLoop.main)
            .removeDuplicates()
            .sink { [weak self] text in
                self?.performSearch(text)
            }
            .store(in: &cancellables)
    }

    private func performSearch(_ text: String) { }
}

De acordo com o artigo de John Sundell (Swift by Sundell, 2024), combinar @Published com Combine é um padrão padrão para pipelines reativos em aplicações SwiftUI: validação, debounce, throttle, combineLatest, merge com outros publishers. @Published atua como uma ponte entre o código UI imperativo e o Combine reativo.

@Published vs macro @Observable

Com o lançamento do iOS 17, a Apple apresentou o macro @Observable, que oferece uma abordagem alternativa à reatividade sem ObservableObject e @Published. O @Observable rastreia automaticamente o acesso às propriedades no nível de leitura em vez de escrita, fornecendo redesenho mais precisos — apenas a visualização que lê uma propriedade alterada específica é atualizada.

No entanto, isso não significa que o @Published esteja obsoleto. O @Published continua necessário quando é necessária integração com pipelines Combine — a projeção $propertyName fornece um publisher que o @Observable não tem. Além disso, para compatibilidade com iOS 16 e inferior, @Published+ObservableObject é a única opção. De acordo com a sessão da Apple WWDC 2023 “Discover Observation in SwiftUI,” a Apple recomenda @Observable para novos projetos, mas mantém explicitamente o suporte para @Published para código existente e cenários Combine.

Na prática, muitos projetos usam uma abordagem híbrida: novos modelos de dados usam @Observable, enquanto ObservableObject existentes com @Published permanecem sem refatoração. O @Published também é indispensável quando é necessário controle preciso sobre a publicação — por exemplo, atrasar a notificação até que uma atualização em lote de várias propriedades seja concluída.

Erros comuns com @Published

O primeiro erro é usar @Published em uma struct. O compilador emitirá um erro: “Property wrapper cannot be applied to a computed property” ou “‘@Published’ is only available on members of a class.” O @Published requer semântica de referência porque ObservableObjectPublisher é uma classe que deve ser única para cada instância.

O segundo erro é mutar o conteúdo de uma propriedade de referência sem substituir a referência. Se uma propriedade @Published for do tipo array [String] e você chamar array.append("novo"), o @Published não detectará a alteração porque a referência ao array não mudou. Solução: atribua um novo valor à propriedade array = array + ["novo"] ou use objectWillChange.send() manualmente.

O terceiro erro é um número excessivo de propriedades @Published. Cada propriedade @Published aciona um redesenho de todas as visualizações inscritas no ObservableObject, não apenas daquelas que leem essa propriedade. De acordo com Point-Free (2025), dividir um grande ObservableObject em vários menores com @StateObject e @EnvironmentObject reduz redesenho desnecessários e melhora o desempenho.

Exemplos de código

O primeiro exemplo é um ViewModel de formulário de registro com validação. As propriedades @Published email e password acionam a exibição de erros de validação através de um pipeline Combine:

class RegistrationViewModel: ObservableObject {
    @Published var email = ""
    @Published var password = ""
    @Published var emailError: String?
    @Published var isFormValid = false
    private var cancellables = Set<AnyCancellable>()

    init() {
        $email
            .map { $0.contains("@") ? nil : "Invalid email" }
            .assign(to: &$emailError)
            .store(in: &cancellables)

        $email.combineLatest($password)
            .map { !$0.isEmpty && !$1.isEmpty }
            .assign(to: &$isFormValid)
            .store(in: &cancellables)
    }
}

O segundo exemplo é a publicação manual para uma coleção de elementos de referência. Em vez de substituir todo o array a cada alteração dentro de um elemento, objectWillChange.send() é usado:

class TodoItem {
    var title: String
    var isDone = false
    init(title: String) { self.title = title }
}

class TodoListViewModel: ObservableObject {
    @Published var items: [TodoItem] = []

    func toggle(item: TodoItem) {
        item.isDone.toggle()
        self.objectWillChange.send()  // manual notification
    }
}

O terceiro exemplo é Assign a uma propriedade @Published através do Combine. Usando a nova sintaxe do Swift 5.9, você pode atribuir diretamente através da projeção assign(to: &$property) sem um invólucro Optional. Esta é a maneira mais curta de conectar um publisher a uma propriedade @Published sem criar uma inscrição.