A macro @State: o que o Xcode 27 deixa de compilar

As notas de versão do iOS 27 da Apple abrem a entrada sobre @State descrevendo um bug que o SwiftUI carrega desde o iOS 13:³ “Um @State declarado com uma expressão como valor inicial costumava avaliar essa expressão toda vez que a struct da view era reinstanciada. No caso de @State private var model = Model(), isso significa que Model.init() é chamado muitas vezes ao longo do ciclo de vida da view.”¹

A correção é uma reescrita. “O Xcode 27 introduz uma nova implementação de @State que evita essa avaliação repetida. Esse novo comportamento faz back-deploy para sistemas alinhados ao iOS 17. O novo @State é implementado com uma macro do Swift. Ele é amplamente compatível em nível de código-fonte com a versão em property wrapper, com algumas exceções.”¹

Preste atenção no gatilho dessa frase. A Apple cita o Xcode, não um deployment target.

Resumo

• O Xcode 27 reimplementa @State como uma macro do Swift, e as páginas de símbolo da Apple registram a troca nas duas direções: a página da estrutura State diz “Quando você compila com o Xcode 27 ou posterior, o sistema usa a macro State() no lugar”, e a página da macro State() diz “Quando você compila com o Xcode 26 ou anterior, o sistema usa o property wrapper State no lugar”.²³
• Seu deployment target não tem como escapar da macro. Ela carrega a mesma disponibilidade a partir do iOS 13.0 que o property wrapper substituído, e a troca depende da versão do Xcode, não do target. A metade em tempo de execução só faz back-deploy para “sistemas alinhados ao iOS 17”, então projetos que ainda suportam iOS 15 ou 16 recebem a mudança em tempo de compilação sem esse comportamento.
• O comportamento de descarte silencioso é antigo e continua igual. A Apple escreve que ele “não mudou por causa da macro, mas alguns desses casos deixam de compilar”.¹ A macro converte um bug que engolia o valor do seu inicializador em uma falha de build.
• A compilação quebra em dois padrões: um inicializador que atribui a uma propriedade @State que também traz um valor inicial no ponto de declaração, e uma extension que chama o inicializador memberwise sintetizado pelo compilador para uma struct com todos os membros privados.¹ A Apple escreve “alguns desses casos”, não todos, e em momento algum enumera quais.
• Auditei quatro apps em produção antes de escrever: 267 declarações @State, sendo 201 com valor inicial no ponto de declaração, zero ocorrências de qualquer um dos padrões que quebram, um caso que passou perto e uma construção de grep que fabrica resultados falsamente limpos no macOS.⁶

A entrada está nas notas de versão do iOS e iPadOS 27, na seção do SwiftUI, e não nas notas do Xcode 27, que não trazem nada equivalente.⁷ Um endereço estranho para uma mudança que a própria Apple atribui ao Xcode, e um bom motivo para a notícia chegar tarde a muita gente.

O bug de performance que a Apple corrigiu

A descrição que a Apple faz do comportamento antigo é incomumente direta para uma nota de versão. Model.init() “é chamado muitas vezes ao longo do ciclo de vida da view”.¹ O SwiftUI reinstancia structs de view o tempo todo, e cada reinstanciação reavaliava a expressão à direita do sinal de igual. O SwiftUI descartava o resultado, porque o estado que já existe prevalece, mas o trabalho acontecia mesmo assim.

A página da macro estabelece o novo contrato em uma frase: “Uma propriedade State() instancia seu valor padrão na primeira vez que o SwiftUI instancia a view.”²

A página de atualizações do SwiftUI acrescenta uma ressalva que a nota de versão omite, e é justamente essa ressalva que vale planejar: “Compile seu projeto no Xcode 27 ou posterior para que o atributo @State use a macro State() na criação de um valor de estado em um App, Scene ou View. Essa mudança só inicializa e armazena sua propriedade uma única vez quando ela é uma classe.”⁴

“Quando ela é uma classe” estreita bastante o ganho, e aponta direto para o padrão que abunda em bases de código SwiftUI modernas. Guardar um objeto @Observable em @State é a abordagem documentada pela Apple, e o próprio exemplo da página da macro mantém uma @Observable class Library exatamente assim.² O inicializador de uma struct costuma ser barato. O inicializador de uma classe que abre um armazenamento, dispara uma consulta ou registra um observador não é, e a Apple descreve isso rodando “muitas vezes”.¹

O que mudou de fato, e o que não mudou

A Apple enuncia a semântica e o comportamento de compilação em uma única frase, e as duas metades apontam em direções opostas: “Se você fornece um valor inicial na declaração @State e também tenta atribuir um valor a ele em um inicializador, o valor do inicializador é descartado. Esse comportamento não mudou por causa da macro, mas alguns desses casos deixam de compilar.”¹

Nada mudou no significado do código. Sob o property wrapper, um inicializador que atribuía a uma propriedade @State com valor no ponto de declaração não fazia nada, silenciosamente, e compilava sem reclamar. A macro mantém a regra intacta e elimina o silêncio.

O modo de falha que se aposenta é o mais caro. O desenvolvedor escreve um inicializador, passa um título por ele, vê o título errado aparecer na tela e sai caçando o problema no corpo da view. O compilador sabia disso o tempo todo e não tinha como dizer.

O próprio exemplo da Apple traz os dois comentários que resumem a questão:

struct StickerPageView: View {
    @State private var page = StickerPage()
    let title: String

    init(title: String) {
        // `title` won't have any effect
        // this also won't compile with @State macro
        self.page = StickerPage(title: title)
        self.title = title
    }
}

“Não terá efeito nenhum” e “não vai compilar” estão em linhas vizinhas. A primeira descreve o Xcode 26. A segunda descreve o Xcode 27. Mesmo código, mesmo significado, veredito diferente.

A correção remove o valor do ponto de declaração:

struct StickerPageView: View {
    @State private var page: StickerPage // no initial value expression
    let title: String

    init(title: String) {
        self.page = StickerPage(title: title) // works!
        self.title = title
    }
}

A Apple reduz a regra a uma instrução: “Ao atribuir o valor inicial por meio de um inicializador, não forneça um valor inicial na declaração @State.”¹

Ou seja, o resumo correto não é que a macro quebrou a atribuição em inicializadores. Essa atribuição já estava quebrada, e a macro é a primeira coisa a dizer isso em voz alta. Quem enquadra a mudança como uma regressão inverteu a direção, ainda que a consequência prática para uma branch de release seja idêntica: builds que passavam ontem falham hoje.

Vale carregar uma ressalva. A Apple escreveu “alguns desses casos”, não todos, e nunca enumera quais. Um build limpo no Xcode 27 é evidência sobre o seu código, não prova sobre a regra.

O inicializador sintetizado desaparece

A segunda exceção não tem nada a ver com valores iniciais, e pega código que sequer menciona @State no ponto de chamada.

“Quando todos os membros armazenados de uma struct são privados, o compilador sintetiza um init privado que pode ser usado em uma extension do mesmo tipo:”¹

struct StickerPageView: View {
    @State private var page: StickerPage
    private let title: String
    ...
}

extension StickerPageView {
    init(title: String, _ page: StickerPage) {
        self.init(page: page, title: title) // using the synthesized init
    }
}

“A macro state desabilita esse inicializador sintetizado. Portanto, o código acima deixa de compilar. Para mitigar, atribua valor aos membros explicitamente:”¹

extension StickerPageView {
    init(title: String, _ page: StickerPage) {
        self.title = title
        self.page = page
    }
}

Esse padrão é mais desagradável de encontrar do que o primeiro, porque o ponto de chamada que quebra fica em uma declaração diferente do @State que o causa. Fazer grep por @State não vai revelá-lo.

A Apple enuncia o efeito e para por aí. A declaração publicada da macro combina com o sintoma:

@attached(accessor, names: named(init), named(get), named(set))
@attached(peer, names: prefixed(`_`), prefixed(`__`), prefixed(`$`))
macro State()

Uma macro de accessor que fornece get e set muda o que a propriedade é do ponto de vista do compilador, e a síntese do inicializador memberwise se apoia em propriedades armazenadas.² Ler a declaração como causa é inferência minha, não afirmação da Apple, e a mitigação não depende do mecanismo: escreva as atribuições à mão.

Inferência de genéricos e composição com property wrappers

A Apple dedica uma frase a cada uma das exceções restantes, e as duas merecem uma linha em qualquer checklist de migração, mesmo que nenhuma atinja muitos projetos.

A inferência de genéricos recebe o tratamento mais vago de toda a entrada: “Em situações raras, a inferência automática dos argumentos genéricos de @State é menos flexível com a implementação em macro. Escreva o tipo com mais especificidade.”¹ A Apple não nomeia nenhum caso nem oferece um diagnóstico para procurar. A mitigação é anotar o tipo explicitamente na declaração, onde quer que o compilador reclame.

A Apple apresenta a composição como um limite, não como uma quebra: “Compor @State com outros property wrappers ou macros não é suportado.”¹ Vale conferir se você já envolveu @State dentro de um property wrapper próprio, e vale lembrar que a Apple trata isso como território não suportado, não como algo que funcionava antes.

Nenhum deployment target escapa

Três frases tiradas de três páginas da Apple fecham todas as saídas.

O símbolo da macro State() traz disponibilidade a partir de iOS 13.0, iPadOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0 e visionOS 1.0, idêntica à do property wrapper que ela substitui, então baixar o seu mínimo não livra você da macro.²³ E a troca depende do compilador, não do target: “Quando você compila com o Xcode 27 ou posterior, o sistema usa a macro State() no lugar.”³

A metade em tempo de execução da mudança tem um piso que a metade em tempo de compilação não tem. A Apple escreve que o novo comportamento “faz back-deploy para sistemas alinhados ao iOS 17”, o que deixa uma lacuna embaixo: um projeto que faz deploy para iOS 15 ou 16 recebe a macro em tempo de compilação, e com ela as exceções de compatibilidade de código-fonte, sem o comportamento retroportado em tempo de execução.¹ A Apple não diz o que esses targets recebem no lugar. Se você suporta um sistema anterior ao iOS 17, trate a quebra de build como certa e a correção da inicialização repetida como não confirmada nos seus aparelhos mais antigos.

Abra o projeto no Xcode 27, compile e você tem o novo @State. Nenhuma chave no Info.plist, nenhuma build setting e nenhuma verificação de disponibilidade entram nessa decisão.

O ciclo 27 traz três mudanças que quebram compatibilidade e que os desenvolvedores insistem em arquivar sob o mesmo rótulo, e elas disparam em três momentos diferentes. A exigência da launch screen vale para “apps compilados com o SDK 27.0 ou posterior” e custa uma rejeição na App Store. A obrigatoriedade do ciclo de vida de cenas vale para apps “compilados com o SDK mais recente” e custa um app que não abre. A macro @State está atrelada à versão do Xcode e custa um build. A Apple redige as duas primeiras em função do SDK e a terceira em função do toolchain, o que coloca @State na frente da fila: você a encontra no primeiro build, antes de encostar em qualquer chave de plist ou deployment target.

A pressão para abrir esse toolchain chega em um cronograma publicado, embora ainda não para o iOS 27. A página de requisitos da Apple diz hoje: “A partir de 28 de abril de 2026, apps enviados ao App Store Connect precisam ser compilados com o Xcode 26 ou posterior usando um SDK para iOS 26, iPadOS 26, tvOS 26, visionOS 26 ou watchOS 26.”⁵ A Apple não publicou data equivalente para o SDK do iOS 27. Ela vem elevando o mínimo do SDK todo ano, sempre no primeiro semestre, então um prazo para o 27 é uma expectativa razoável, não um fato, e qualquer data específica que você leia por aí é inferência.

O que quatro apps em produção realmente contêm

Rodei a auditoria no meu próprio código antes de escrever sobre o de qualquer outra pessoa: quatro apps na App Store, todos em SwiftUI, todos compilados atualmente com o Xcode 26.6.⁶

Dois comandos afunilam o trabalho. O primeiro encontra declarações @State que carregam valor inicial, e a classe de caracteres depois de @State justifica sua presença: [^A-Za-z0-9_] mantém @StateObject fora dos resultados, coisa que uma busca simples por @State não faz.

grep -rn --include="*.swift" \
  --exclude-dir=.build --exclude-dir=DerivedData --exclude-dir=build \
  -E '@State[^A-Za-z0-9_][^=]*[^!<>=]=[^=]' .

O comando pressupõe que o atributo e a declaração estejam na mesma linha. Uma propriedade escrita com @State em uma linha própria acima de private var page = StickerPage() não produz correspondência, o que é a mesma falha de “limpo por engano” descrita adiante, só que com outra roupa. Leia as omissões como “ainda não verificado”, não como “limpo”.

O segundo restringe aos arquivos que também declaram um inicializador, o único lugar onde a primeira exceção pode pegar:

find . -name "*.swift" -not -path "*/build/*" -not -path "*/DerivedData/*" -print0 |
while IFS= read -r -d '' f; do
  grep -qE '@State[^A-Za-z0-9_][^=]*[^!<>=]=[^=]' "$f" || continue
  grep -qE '^[[:space:]]*(private |public |internal |fileprivate )?init[[:space:]]*[(<]' "$f" || continue
  echo "$f"
done

O loop parece mais pesado que um pipe para xargs, e ele justifica esse peso no macOS. O grep BSD não emite separadores NUL para -Z como o grep do GNU faz, então grep -rlZ ... | xargs -0 grep -l entrega ao segundo grep um único bloco unido por quebras de linha. Em um projeto cujo caminho contém espaço, Banana List por exemplo, você recebe uma tela de “No such file or directory” na saída de erro e absolutamente nada na saída padrão, o que se parece exatamente com uma auditoria limpa.⁶ Ler saída vazia como “nenhuma correspondência” inverte a resposta justamente nos projetos com mais chance de precisar dela.

Em 215 arquivos Swift, a lista curta ficou em 20: nove no Reps, seis no Return, três no Ace Citizenship e dois no Banana List. Ler os 20 à mão deu o mesmo resultado nos quatro projetos.

• A primeira forma exata descrita pela Apple, valor inicial no ponto de declaração mais uma atribuição à mesma propriedade dentro de um inicializador do mesmo tipo: zero.
• A segunda exceção, uma extension chamando o inicializador memberwise sintetizado de uma struct que declara @State: zero.
• A exceção de composição, @State ao lado de outro property wrapper ou macro na mesma declaração: zero.

Um caso que passou perto merece descrição, porque está a uma linha da forma que a Apple manda remover. Uma view de configuração de perfil no Reps declara @State private var healthWriteStatus: HealthAuthorizationState = .notRequested e depois, dentro do inicializador, atribui self._healthWriteStatus = State(initialValue: ...). Os dois lugares carregam valor, então a frase de mitigação da Apple se aplica ao pé da letra: não forneça um valor inicial na declaração @State.¹ A atribuição usa a forma com underscore em vez da forma de valor encapsulado do exemplo da Apple, e a nota de versão jamais menciona a forma com underscore.

O que deixa em aberto a pergunta que minha auditoria não conseguiu responder. A construção _x = State(initialValue:) aparece 15 vezes em três dos quatro apps, e continua sendo a maneira padrão de alimentar o estado a partir de um parâmetro do inicializador. A entrada da Apple não trata dela. A declaração da macro de fato gera um peer prefixado com underscore,² o que é sugestivo e não é garantia. Eu compilo no Xcode 26.6 (build 17F113), então não pude verificar nem essa construção nem o texto dos erros de compilação resultantes.⁶ Quem tiver um beta do Xcode 27 resolve as duas coisas em uma tarde. Até alguém resolver, procure no seu código pela forma da declaração, não por uma string de erro.

A manchete honesta de 267 declarações é que a maior parte do código SwiftUI passa incólume, o que combina com o “amplamente compatível em nível de código-fonte” da Apple.¹ As views em risco são as que têm inicializadores escritos à mão, e elas se concentram bastante: menos de um arquivo Swift em cada 10, nas quatro bases de código, tinha ao mesmo tempo um inicializador escrito à mão e um @State com valor inicial próprio.

Perguntas frequentes

Preciso mudar as chamadas _page = State(initialValue:)?

A entrada da Apple não diz. A forma com underscore atribui diretamente ao armazenamento projetado em vez do valor encapsulado, e não aparece em lugar nenhum da nota de versão: nenhum initialValue, nenhum exemplo com underscore, nenhuma menção em qualquer direção.¹ A declaração publicada da macro emite, sim, um peer prefixado com _, o que é sugestivo e não é garantia.² Três dos quatro apps que auditei usam essa construção, 15 vezes no total, então a resposta importa para mais bases de código do que as duas exceções documentadas.⁶ Até a Apple tratar do assunto, compile o projeto no Xcode 27 e deixe o compilador responder, em vez de refatorar por especulação.

A macro mudou o que acontece com um valor atribuído em um inicializador?

Não. A Apple é explícita ao dizer que o comportamento de descarte “não mudou por causa da macro, mas alguns desses casos deixam de compilar”.¹ No Xcode 26, um inicializador que atribuía a uma propriedade @State já carregando valor no ponto de declaração não fazia nada e compilava. No Xcode 27, parte desses casos falha no build. A semântica ficou onde estava e os diagnósticos chegaram, então um build que quebra aqui é o compilador relatando um bug que você já tinha.

Como encontro o código em risco no meu projeto?

Procure declarações @State que carreguem valor inicial, restrinja os resultados aos arquivos que também declaram um inicializador e leia essa lista curta à mão. Exclua @StateObject com uma classe de caracteres (@State[^A-Za-z0-9_]) e prefira um loop com find -print0 a grep -rlZ | xargs -0 no macOS, onde o grep BSD não emite separadores NUL e qualquer caminho com espaço produz saída vazia que parece aprovação.⁶ Em quatro apps e 215 arquivos Swift, a lista curta ficou em 20 arquivos. Procure separadamente por extensions que chamam self.init(...) em uma struct de view, já que a segunda exceção não deixa rastro perto do @State que a causa.

Meu app vai ficar mais rápido de verdade?

Só em circunstâncias específicas, e a Apple as estreita mais do que a nota de versão sugere. A nota descreve, de modo geral, a eliminação da avaliação repetida,¹ enquanto a entrada de atualizações do SwiftUI diz que a mudança “só inicializa e armazena sua propriedade uma única vez quando ela é uma classe”.⁴ O ganho aparece em @State private var model = SomeObservableClass(), onde a implementação antiga rodava o inicializador da classe a cada reinstanciação da view e jogava o resultado fora. Um @State private var isPresented = false nunca foi o problema.

Pontos principais

Para desenvolvedores iOS: - Audite duas formas, não uma. A primeira vive em uma declaração @State ao lado de um inicializador; a segunda vive em uma extension que chama self.init(...) em uma struct de view cujos membros armazenados são todos privados.¹ - Corrija a primeira apagando o valor do ponto de declaração, não a atribuição do inicializador. A instrução da Apple é manter o inicializador como fonte única e deixar a declaração sem valor.¹

Para times que mantêm código SwiftUI antigo: - Reserve tempo de revisão para a lista curta, não para a base inteira. Arquivos com um @State com valor inicial e um inicializador escrito à mão foram 20 de 215 nos meus quatro apps, e toda ocorrência do primeiro padrão precisa estar em um deles. Procure o segundo padrão separadamente, já que ele se esconde em extensions.⁶ - Trate um build quebrado como um bug encontrado. O SwiftUI já descartava o valor do inicializador que o compilador agora rejeita, então onde quer que a mudança pegue, algum comportamento já estava errado.¹

Para quem gerencia releases: - Agende a auditoria de @State antes do trabalho disparado pelo SDK no mesmo ciclo. A chave da launch screen e o ciclo de vida de cenas dependem os dois do SDK que você usa para compilar; @State depende da versão do Xcode com que você compila, então ele chega primeiro.¹³ - Não faça planos em torno de um prazo do SDK do iOS 27. O mínimo publicado pela Apple ainda é o SDK do iOS 26, obrigatório desde 28 de abril de 2026, e a Apple não anunciou nada para o 27.⁵

Três pontos de fiscalização chegam em um mesmo ciclo e falham em três lugares diferentes: a chave da launch screen barra um envio, a obrigatoriedade de cenas barra a abertura do app e a macro @State barra um build. Para o resto do que vem no mesmo SDK, veja Novidades do SwiftUI no iOS 27. O índice completo da série é a Série Ecossistema Apple.

Referências