Imagens de itens de menu somem no macOS 27 e no iPadOS 27

Um item de menu com imagem e sem título não renderiza absolutamente nada no macOS 27 se você linkar contra o SDK do macOS 27. A Apple protege esse caso em SDKs anteriores, exibindo a imagem automaticamente quando o título e o título com atributos do item estão ambos vazios.¹ Recompile contra o 27 e a proteção deixa de valer.

O macOS 27 e o iPadOS 27 escondem a maioria das imagens de itens de menu por padrão, e o que desaparece depende de qual SDK você usou na linkagem. A Apple descreve o resultado como “semelhante ao comportamento anterior ao macOS 26.0” — ou seja, o macOS 26 espalhou imagens pelos menus e o 27 recolhe quase todas.¹

Três frameworks são afetados e cada um tem uma forma diferente de sair do padrão. Se você pesquisou por preferredImageVisibility e escreve SwiftUI, essa propriedade não existe para você.

Resumo rápido

O macOS 27 esconde por padrão as imagens de símbolo dos itens de menu em apps linkados no macOS 26.0 ou posterior; apps linkados no SDK do macOS 27 também perdem as imagens que não são símbolos.¹² Itens de menu compostos só por ícone ficam protegidos automaticamente em SDKs anteriores ao 27 e perdem essa proteção assim que são recompilados contra o 27.³ O iPadOS 27 esconde por padrão as imagens definidas em elementos de menu.⁴ AppKit e UIKit expõem preferredImageVisibility com .automatic, .visible e .hidden; no SwiftUI, o caminho é labelStyle(.titleAndIcon).⁵ Ajustes, Compartilhar e Imprimir mantêm suas imagens em todo o sistema, então você vai ver alguns ícones e pode concluir que os seus estão quebrados.

O que muda de fato, por SDK

O comportamento do AppKit apareceu em três entradas separadas das notas de versão, duas delas registradas como correções — e é por isso que os resumos dessa mudança se contradizem por aí.

A entrada de base afirma que o NSMenu esconde por padrão todas as imagens de símbolo dos itens de menu, enquanto as imagens que não são símbolos continuam visíveis, e que a mudança se aplica a aplicativos linkados no macOS 26.0 ou posterior.¹

Uma segunda entrada amplia esse ocultamento: “Para aplicativos linkados no SDK do macOS 27, tanto as imagens de símbolo quanto as que não são símbolos agora ficam ocultas automaticamente. Para aplicativos linkados em SDKs anteriores, as imagens que não são símbolos permanecem visíveis automaticamente, preservando a compatibilidade com o comportamento existente do aplicativo.”²

A terceira entrada é a que vale ler duas vezes:³

“Para aplicativos linkados em SDKs anteriores ao macOS 27, o NSMenu agora exibe automaticamente as imagens dos itens de menu quando o título e o título com atributos do item estão ambos vazios. Isso preserva o comportamento existente do aplicativo quando a imagem é a única representação do conteúdo do item de menu. Ao linkar contra o SDK do macOS 27, essas imagens serão automaticamente ocultadas; um menu com esse design deve usar a API preferredImageVisibility para garantir que as imagens dos itens de menu continuem visíveis.”

A Apple construiu uma rede de proteção para itens de menu só com ícone e, em seguida, documentou que essa rede não alcança o novo SDK. Um item de menu cujo conteúdo inteiro é uma imagem passa a ser renderizado vazio depois da recompilação. Nada muda no seu código-fonte. O gatilho é o SDK contra o qual você compilou.

Itens de menu só com ícone são menos exóticos do que parecem. Amostras de cor em um menu de formatação, em que a amostra é a escolha. Seletores de dispositivo ou de conta que identificam cada entrada por avatar ou por um glifo de status. Fileiras de reações e emojis montadas como uma tira horizontal de itens sem texto. Listas de documentos recentes que mostram ícones de tipo de arquivo com o nome renderizado à parte. Em todos esses casos a imagem não é enfeite preso a um rótulo — ela é o rótulo.

Esses menus degradam para uma coluna de linhas vazias que continuam respondendo a cliques. O menu mantém a altura, os separadores e as áreas clicáveis, então nada disso parece uma falha de renderização para um olhar automatizado. Um teste de UI que verifica se o menu tem seis itens continua passando. Um diff de captura de tela pega o problema; uma asserção sobre a contagem de itens, não.

O silêncio é a marca de família. O macOS 27 também nega acesso a contêineres de outra equipe sem perguntar, caso em que a API devolve uma URL de aparência válida e a falha só aparece na leitura. As duas mudanças trocam um sinal visível por silêncio, e ambas se manifestam como algo diferente do que realmente são.

Três frameworks, três correções

AppKit e UIKit compartilham o mesmo formato. As duas propriedades recebem um enum ImageVisibility com .automatic, .visible e .hidden, ambos RawRepresentable sobre NSInteger e ambos Sendable.⁶⁷

// AppKit
menuItem.preferredImageVisibility = .visible

// UIKit — also available on the updated initializers
// for UIMenu, UIAction, UICommand, and UIKeyCommand
let action = UIAction(title: "Export", image: exportImage) { _ in export() }
action.preferredImageVisibility = .visible

O SwiftUI segue outro caminho. Sua nota de versão diz para “usar o modificador de view labelStyle(_:) com o estilo .titleAndIcon para indicar que o ícone de um Label de item de menu deve sempre ser exibido.”⁵

Menu("File") {
    Button {
        openDocument()
    } label: {
        Label("Open Document", systemImage: "doc")
    }
    .labelStyle(.titleAndIcon)
}

Repare também que o padrão do SwiftUI acompanha a linha de base do AppKit, e não o comportamento do SDK 27: imagens de símbolo escondidas, imagens que não são símbolos ainda visíveis.⁵ A tabela de linkagem por SDK acima descreve o AppKit. Não presuma que ela se transfere.

O alcance é mais estreito do que parece

Leia o texto sobre plataformas com atenção, porque as entradas divergem.

A entrada do UIKit cobre “a barra de menus e os menus de contexto” no iPadOS 27.0 e no macOS 27.0.⁴ A do SwiftUI é mais específica: a barra de menus no iPadOS 27.0 e no macOS 27.0, “bem como os menus de contexto no macOS 27.0.”⁵ Menus de contexto do SwiftUI no iPadOS não são citados.

UIMenuElement.preferredImageVisibility está disponível em iOS, iPadOS, Mac Catalyst, tvOS e visionOS 27.0.⁷ O fato de a API existir em uma plataforma não significa que o ocultamento esteja ativo lá. As notas de versão da Apple descrevem o comportamento para iPadOS e macOS. Trate tvOS e visionOS como não declarados, e não como confirmados.

O lado do Interface Builder

Um detalhe não tem equivalente em código. Para itens de menu criados a partir de um arquivo xib, o NSMenu observa uma caixa de seleção “macOS 26.0 only” no inspetor do item de menu: desmarcada, mantém a imagem visível; marcada, esconde.¹

Uma propriedade do Interface Builder passa a alterar a visibilidade da imagem em tempo de execução. Se os seus menus vêm de xibs, a auditoria não é uma busca no código. Alguém precisa abrir o inspetor.

Por que alguns ícones sobrevivem

Tanto o AppKit quanto o UIKit continuam fornecendo imagens visíveis por padrão para itens de menu comuns em todo o sistema, como Ajustes, Compartilhar e Imprimir.¹⁴ O SwiftUI faz o mesmo.⁵

O efeito prático é confusão no diagnóstico. Você atualiza, abre um menu e vê ícones ao lado de Ajustes e Compartilhar, mas não ao lado dos seus próprios itens. A conclusão razoável é que suas imagens não carregaram, ou que o asset catalog quebrou, ou que os nomes dos símbolos estão errados. Nada disso está acontecendo. O sistema está aplicando uma política que isenta um punhado de itens conhecidos.

Como decidir quais ícones manter

As cinco entradas das notas de versão orientam os desenvolvedores a revisar as Human Interface Guidelines atualizadas para decidir quais itens de menu ainda devem exibir imagens.¹⁴⁵ Não consegui verificar o que essa orientação diz: a página de menus das HIG é renderizada no cliente e devolve quase nenhum texto para um coletor automático, e não existe um endpoint JSON para o conteúdo das HIG como existe para a referência de API. Confira você mesmo, em vez de acreditar no resumo de alguém — inclusive neste aqui.

A única heurística concreta nas próprias notas de versão vem da entrada do SwiftUI, que sugere exibir o ícone quando um item de menu “representa um objeto ou um conceito, e não uma ação.”⁵

Essa regra funciona. Um menu que lista documentos abertos, dispositivos disponíveis ou filtros salvos está nomeando objetos, e ali o ícone carrega identidade. Um menu de verbos — que é a maioria dos menus — ganha pouco com um ícone ao lado de cada entrada. A Apple parece ter concluído que o macOS 26 exagerou no uso de imagens, e o 27 é a correção.

O que fazer antes de lançar com o SDK 27

Encontre primeiro os itens de menu só com ícone. São os que quebram de forma mais grave, porque a imagem é o conteúdo inteiro. Todo NSMenuItem com imagem e título vazio, e todo elemento de UIMenu montado da mesma forma, precisa de .visible definido explicitamente.

Decida item a item, não globalmente. Definir .visible em tudo reverte uma mudança deliberada da plataforma e devolve você ao que era o macOS 26. A regra objeto-versus-ação é um filtro melhor do que uma sobreposição geral.

Vasculhe os xibs à parte. A caixa “macOS 26.0 only” não é encontrável com grep como uma atribuição de propriedade, e ela muda o comportamento.

Teste nas duas gerações de SDK se você der suporte às duas. Um build contra o 26 e um build contra o 27 renderizam os menus de formas diferentes a partir do mesmo código-fonte. Isso torna capturas de tela e testes de UI dependentes do SDK de um jeito que não eram antes.

A linkagem de SDK determinando comportamento está virando um padrão recorrente nesta versão. A descontinuação de canOpenURL no iOS 27 gira no mesmo eixo, e a lição prática se repete: quem determina o que o usuário vê é a sua escolha em tempo de compilação, não o seu código-fonte.

Espere que as notas de versão mudem. Duas das três entradas do AppKit estão registradas como correções, o que significa que o comportamento já mudou uma vez durante o ciclo de betas. Reverifiquei as cinco entradas contra as notas do Beta 4 em 2026-08-01 e elas dizem exatamente o que está citado aqui. Confirme nas notas atuais antes de agir com base em qualquer coisa disso.

Auditando uma base de código existente

A mudança é mecânica o bastante para ser auditada de forma sistemática, e vale fazer isso antes da recompilação, não depois que um testador relatar um menu em branco.

Comece pelo caso mais grave. Um NSMenuItem que carrega uma imagem com título vazio é a única falha que produz um menu visivelmente quebrado, e não apenas mais simples. No código, procure atribuição de imagem sem título correspondente:

# Menu items constructed with an image and no title argument
rg 'NSMenuItem\(' --type swift -A3 | rg -B1 'image ='
rg 'setImage|\.image\s*=' --type swift | rg -i 'menu'

Nenhum dos dois padrões é exaustivo, porque o título pode ser definido três linhas depois ou lido de uma tabela de localização. Trate os resultados como uma lista de candidatos a inspecionar, não como um achado.

Depois, os xibs. Nenhum grep ajuda com a caixa “macOS 26.0 only”, que vive no inspetor do item de menu e não em nenhum atributo que o seu build enxergue. Se os seus menus vêm do Interface Builder, a auditoria significa abrir cada menu e checar cada item.

Depois, os construtores de menu do UIKit. UIMenu, UIAction, UICommand e UIKeyCommand ganharam inicializadores atualizados que recebem preferredImageVisibility, então a correção pode ficar na construção, em vez de virar uma atribuição posterior.⁴

Depois, o uso de Label do SwiftUI dentro de menus. São os mais fáceis de deixar passar, porque um Label dentro de um menu é idêntico no código-fonte a um Label em qualquer outro lugar. O modificador vai no rótulo, e só onde você quiser manter o ícone.

Compile duas vezes e compare. A checagem mais confiável não envolve ler código nenhum. Compile contra o SDK 26 e contra o SDK 27, abra os mesmos menus e fotografe os dois. Código-fonte idêntico produzindo dois menus diferentes é justamente o ponto dessa mudança, e um lado a lado encontra o que um grep não encontra.

Esse último passo também protege as suas capturas de tela. Imagens de marketing, documentação e assets da App Store que mostram menus foram capturados sob o SDK que estava vigente quando alguém os tirou. Se eles mostram ícones que o seu build de produção não renderiza mais, agora estão errados — e nada no seu processo de build vai sinalizar isso.

Pontos principais

Para quem desenvolve em AppKit: - Linkar contra o SDK do macOS 27 também esconde as imagens que não são símbolos, não só os símbolos. Auditar apenas os seus SF Symbols deixa metade do problema de fora. - Itens de menu só com ícone perdem a proteção automática no SDK 27 e aparecem vazios. Defina preferredImageVisibility = .visible em cada um deles. - Menus definidos em xibs carregam uma caixa “macOS 26.0 only” que altera a visibilidade fora de qualquer caminho de código.

Para quem desenvolve em UIKit: - preferredImageVisibility está em UIMenuElement e nos inicializadores atualizados de UIMenu, UIAction, UICommand e UIKeyCommand. - A propriedade existe em tvOS e visionOS, mas a Apple documenta o comportamento para iPadOS e macOS. Verifique antes de presumir.

Para quem desenvolve em SwiftUI: - preferredImageVisibility não é a sua API. Use labelStyle(.titleAndIcon) no Label. - O padrão do SwiftUI esconde as imagens de símbolo e mantém as que não são símbolos, acompanhando a linha de base do AppKit em vez do comportamento do SDK 27.

Perguntas frequentes

Por que Ajustes e Compartilhar continuam mostrando ícones?

O sistema isenta certos itens de menu comuns. AppKit, UIKit e SwiftUI continuam fornecendo imagens visíveis por padrão para itens como Ajustes, Compartilhar e Imprimir.¹⁴⁵ Ver esses ícones enquanto os seus estão escondidos é comportamento esperado, não falha de carregamento.

Ficar em um SDK mais antigo evita isso?

Em parte, e a distinção importa. Apps linkados no macOS 26.0 ou posterior já escondem as imagens de símbolo.¹ Ficar abaixo do SDK do macOS 27 preserva a visibilidade das imagens que não são símbolos e mantém a proteção automática dos itens só com ícone.²³ Isso não restaura as imagens de símbolo.

O que acontece com um item de menu que só tem imagem e nenhum título?

Em SDKs anteriores ao macOS 27, o NSMenu exibe a imagem automaticamente porque o título e o título com atributos estão ambos vazios.³ No SDK do macOS 27 essa proteção não se aplica e a imagem fica escondida, o que deixa um item de menu sem conteúdo visível. Defina preferredImageVisibility = .visible.

Isso é igual em tvOS e visionOS?

UIMenuElement.preferredImageVisibility está disponível em ambos na 27.0.⁷ As entradas das notas de versão descrevem o ocultamento para iPadOS e macOS. A existência da API em uma plataforma não confirma que o comportamento esteja ativo lá.

Quais ícones eu devo manter?

As notas de versão apontam para as Human Interface Guidelines, que não consegui ler diretamente. A heurística que a Apple declara na entrada do SwiftUI é exibir um ícone quando o item de menu “representa um objeto ou um conceito, e não uma ação.”⁵

Fontes