Bilder in Menüeinträgen verschwinden in macOS 27 und iPadOS 27

Ein Menüeintrag mit Bild und ohne Titel wird unter macOS 27 gar nicht mehr dargestellt, sofern Sie gegen das macOS-27-SDK linken. Auf früheren SDKs schützt Apple diesen Fall, indem das Bild automatisch angezeigt wird, wenn Titel und attributierter Titel eines Menüeintrags beide leer sind.¹ Bauen Sie erneut gegen 27, greift dieser Schutz nicht mehr.

macOS 27 und iPadOS 27 blenden die meisten Bilder in Menüeinträgen standardmäßig aus, und was dabei verschwindet, hängt vom gelinkten SDK ab. Apple beschreibt das Ergebnis als „ähnlich dem Verhalten vor macOS 26.0“ – anders gesagt: macOS 26 hat Menübilder breitflächig eingeführt, und 27 nimmt den größten Teil davon wieder zurück.¹

Betroffen sind drei Frameworks, und jedes bietet eine andere Möglichkeit, sich davon auszunehmen. Wer nach preferredImageVisibility gesucht hat und in SwiftUI arbeitet: Diese Eigenschaft existiert dort nicht.

Kurzfassung

macOS 27 blendet Symbolbilder in Menüeinträgen standardmäßig aus, sobald eine App gegen macOS 26.0 oder neuer gelinkt ist; Apps, die gegen das macOS-27-SDK gelinkt sind, verlieren zusätzlich alle Nicht-Symbolbilder.¹² Menüeinträge, die nur aus einem Symbol bestehen, sind auf SDKs vor 27 automatisch geschützt – und verlieren diesen Schutz, sobald Sie gegen 27 neu bauen.³ iPadOS 27 blendet Bilder, die auf Menüelementen gesetzt sind, standardmäßig aus.⁴ AppKit und UIKit stellen preferredImageVisibility mit .automatic, .visible und .hidden bereit; SwiftUI verwendet stattdessen labelStyle(.titleAndIcon).⁵ Einstellungen, Teilen und Drucken behalten ihre Bilder systemweit – Sie sehen also durchaus einige Symbole und halten Ihre eigenen womöglich für defekt.

Was sich tatsächlich ändert, nach SDK aufgeschlüsselt

Das AppKit-Verhalten verteilt sich auf drei getrennte Release-Note-Einträge, zwei davon als Fehlerbehebungen abgelegt – deshalb widersprechen sich die kursierenden Zusammenfassungen dieser Änderung.

Der Basiseintrag hält fest, dass NSMenu sämtliche Symbolbilder in Menüeinträgen standardmäßig ausblendet, während Nicht-Symbolbilder sichtbar bleiben, und dass die Änderung für Anwendungen gilt, die gegen macOS 26.0 oder neuer gelinkt sind.¹

Ein zweiter Eintrag weitet das Ausblenden aus: „Für Anwendungen, die gegen das macOS-27-SDK gelinkt sind, werden sowohl Symbol- als auch Nicht-Symbolbilder in Menüeinträgen jetzt automatisch ausgeblendet. Für Anwendungen, die gegen frühere SDKs gelinkt sind, bleiben Nicht-Symbolbilder automatisch sichtbar, womit die Kompatibilität mit bestehendem Anwendungsverhalten gewahrt bleibt.“²

Den dritten Eintrag sollten Sie zweimal lesen:³

„Für Anwendungen, die gegen SDKs vor macOS 27 gelinkt sind, zeigt NSMenu Bilder in Menüeinträgen jetzt automatisch an, wenn Titel und attributierter Titel des Menüeintrags beide leer sind. Damit bleibt bestehendes Anwendungsverhalten erhalten, wenn das Bild die einzige Repräsentation des Menüeintragsinhalts ist. Beim Linken gegen das macOS-27-SDK werden diese Bilder automatisch ausgeblendet; ein Menü mit diesem Aufbau sollte die API preferredImageVisibility verwenden, damit die Bilder in den Menüeinträgen sichtbar bleiben.“

Apple hat ein Sicherheitsnetz für reine Symboleinträge gebaut – und dann dokumentiert, dass dieses Netz nicht bis zum neuen SDK reicht. Ein Menüeintrag, dessen gesamter Inhalt ein Bild ist, wird nach dem nächsten Build leer gerendert. An Ihrem Quellcode ändert sich nichts. Auslöser ist das SDK, gegen das Sie kompiliert haben.

Reine Symboleinträge sind weniger exotisch, als es klingt. Farbfelder in einem Formatierungsmenü, bei denen das Farbfeld die Auswahl ist. Geräte- oder Kontoauswahllisten, die jeden Eintrag über Avatar oder Statussymbol kenntlich machen. Reaktions- und Emoji-Reihen, gebaut als horizontale Leiste aus reinen Bildeinträgen. Listen zuletzt geöffneter Dokumente, die Dateityp-Symbole zeigen und den Namen separat rendern. In all diesen Fällen ist das Bild keine Dekoration neben einer Beschriftung – es ist die Beschriftung.

Solche Menüs verkommen zu einer Spalte leerer Zeilen, die weiterhin auf Klicks reagieren. Das Menü behält seine Höhe, seine Trennlinien und seine Trefferflächen, wirkt für ein automatisiertes Auge also nicht wie ein Darstellungsfehler. Ein UI-Test, der prüft, ob ein Menü sechs Einträge hat, läuft weiterhin durch. Ein Screenshot-Vergleich deckt das auf; eine Prüfung auf die Anzahl der Einträge nicht.

Die Lautlosigkeit ist das verbindende Merkmal. macOS 27 verweigert außerdem teamübergreifenden Container-Zugriff ohne Nachfrage – dort liefert die API eine plausibel aussehende URL zurück, und der Fehlschlag wartet bis zum Lesezugriff. Beide Änderungen ersetzen ein sichtbares Signal durch Stille, und beide zeigen sich als etwas anderes, als sie sind.

Drei Frameworks, drei Lösungen

AppKit und UIKit teilen sich die Form. Beide Eigenschaften nehmen ein ImageVisibility-Enum mit .automatic, .visible und .hidden entgegen, beide RawRepresentable über NSInteger, beide 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

SwiftUI geht einen anderen Weg. In der zugehörigen Release Note heißt es, man solle „den View-Modifier labelStyle(_:) mit dem Stil .titleAndIcon verwenden, um anzugeben, dass das Symbol eines Label in einem Menüeintrag immer angezeigt werden soll.“⁵

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

Beachten Sie außerdem: Der SwiftUI-Standard entspricht dem AppKit-Basisverhalten, nicht dem Verhalten des 27er-SDKs – Symbolbilder ausgeblendet, Nicht-Symbolbilder weiterhin sichtbar.⁵ Die obige Tabelle zur SDK-Bindung beschreibt AppKit. Gehen Sie nicht davon aus, dass sie sich übertragen lässt.

Der Geltungsbereich ist enger, als es klingt

Lesen Sie die Plattformangaben genau, denn die Einträge unterscheiden sich.

Der UIKit-Eintrag deckt „die Menüleiste und Kontextmenüs“ unter iPadOS 27.0 und macOS 27.0 ab.⁴ Der SwiftUI-Eintrag ist spezifischer: die Menüleiste unter iPadOS 27.0 und macOS 27.0 „sowie Kontextmenüs unter macOS 27.0“.⁵ SwiftUI-Kontextmenüs unter iPadOS werden nicht genannt.

UIMenuElement.preferredImageVisibility steht unter iOS, iPadOS, Mac Catalyst, tvOS und visionOS 27.0 zur Verfügung.⁷ Dass die API auf einer Plattform ausgeliefert wird, bedeutet nicht, dass das Ausblendeverhalten dort aktiv ist. Apples Release Notes beschreiben das Verhalten für iPadOS und macOS. Behandeln Sie tvOS und visionOS als unbelegt, nicht als bestätigt.

Die Interface-Builder-Ebene

Ein Detail hat kein Gegenstück im Code. Für Menüeinträge, die aus einer xib-Datei stammen, wertet NSMenu ein Kontrollkästchen „macOS 26.0 only“ im Inspektor des Menüeintrags aus: nicht angehakt hält das Bild sichtbar, angehakt blendet es aus.¹

Eine Eigenschaft im Interface Builder verändert damit zur Laufzeit die Sichtbarkeit von Bildern. Wenn Ihre Menüs aus xibs kommen, ist die Prüfung keine Codesuche. Jemand muss den Inspektor öffnen.

Warum manche Symbole überleben

Sowohl AppKit als auch UIKit liefern für verbreitete systemweite Menüeinträge wie Einstellungen, Teilen und Drucken weiterhin standardmäßig sichtbare Bilder.¹⁴ SwiftUI ebenso.⁵

Praktisch führt das zu diagnostischer Verwirrung. Sie aktualisieren, öffnen ein Menü und sehen Symbole neben Einstellungen und Teilen, aber nicht neben Ihren eigenen Einträgen. Der naheliegende Schluss lautet: Die Bilder wurden nicht geladen, der Asset-Katalog ist kaputt, oder die Symbolnamen stimmen nicht. Nichts davon trifft zu. Das System wendet schlicht eine Regel an, die eine Handvoll bekannter Einträge ausnimmt.

Welche Symbole bleiben sollten

Alle fünf Release-Note-Einträge fordern Entwickler auf, die aktualisierten Human Interface Guidelines heranzuziehen, um zu entscheiden, welche Menüeinträge weiterhin Bilder zeigen sollen.¹⁴⁵ Was dort steht, konnte ich nicht überprüfen: Die HIG-Seite zu Menüs wird clientseitig gerendert und liefert einem Abrufwerkzeug so gut wie keinen Text, und für HIG-Inhalte gibt es keinen JSON-Endpunkt wie für die API-Referenz. Sehen Sie selbst nach, statt einer Zusammenfassung zu glauben – auch dieser hier nicht.

Die einzige konkrete Faustregel in den Release Notes selbst stammt aus dem SwiftUI-Eintrag: Zeigen Sie das Symbol, wenn ein Menüeintrag „ein Objekt oder ein Konzept repräsentiert und keine Aktion“.⁵

Diese Regel taugt in der Praxis. Ein Menü, das geöffnete Dokumente, verfügbare Geräte oder gespeicherte Filter auflistet, benennt Objekte, und ein Symbol trägt dort Identität. Ein Menü aus Verben – und das sind die meisten Menüs – gewinnt wenig durch ein Symbol neben jedem Eintrag. Offenbar ist Apple zu dem Schluss gekommen, dass macOS 26 die Bilder überstrapaziert hat, und 27 ist die Korrektur.

Was zu tun ist, bevor Sie gegen das 27er-SDK ausliefern

Suchen Sie zuerst Ihre reinen Symboleinträge. Sie trifft es am härtesten, weil das Bild der gesamte Inhalt ist. Jedes NSMenuItem mit Bild und leerem Titel und jedes ebenso gebaute UIMenu-Element braucht ein explizit gesetztes .visible.

Entscheiden Sie pro Eintrag, nicht pauschal. Überall .visible zu setzen macht eine bewusste Plattformänderung rückgängig und wirft Sie auf den Stand von macOS 26 zurück. Die Objekt-oder-Aktion-Regel filtert besser als ein pauschales Überschreiben.

Durchsuchen Sie die xibs getrennt. Das Kontrollkästchen „macOS 26.0 only“ lässt sich nicht so greppen wie eine Zuweisung an eine Eigenschaft – und es ändert das Verhalten.

Testen Sie gegen beide SDK-Generationen, wenn Sie beide unterstützen. Ein Build gegen 26 und ein Build gegen 27 rendern aus identischem Quellcode unterschiedlich. Damit werden Screenshots und UI-Tests auf eine Weise SDK-abhängig, wie sie es vorher nicht waren.

Dass die SDK-Bindung über das Verhalten entscheidet, wird in diesem Release zu einem wiederkehrenden Muster. Die Abkündigung von canOpenURL in iOS 27 dreht sich um dieselbe Achse, und die praktische Lehre wiederholt sich: Nicht Ihr Quellcode, sondern Ihre Entscheidung zur Kompilierzeit bestimmt, was Benutzer sehen.

Rechnen Sie damit, dass sich die Release Notes noch bewegen. Zwei der drei AppKit-Einträge sind als Fehlerbehebungen abgelegt, das Verhalten hat sich im Beta-Zyklus also bereits einmal geändert. Ich habe alle fünf Einträge am 1. August 2026 erneut gegen die Beta-4-Notes geprüft; sie lauten wie hier zitiert. Gleichen Sie vor jeder Maßnahme mit den aktuellen Notes ab.

Eine bestehende Codebasis prüfen

Die Änderung ist mechanisch genug für eine systematische Prüfung – und die lohnt sich vor dem erneuten Build, statt erst, wenn ein Tester ein leeres Menü meldet.

Beginnen Sie mit dem schwerwiegendsten Fall. Ein NSMenuItem, das ein Bild trägt und einen leeren Titel hat, ist der einzige Fehlerfall, der ein sichtbar kaputtes Menü erzeugt statt nur ein schlichteres. Suchen Sie im Code nach Bildzuweisungen ohne zugehörigen Titel:

# 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'

Keines der beiden Muster ist vollständig, denn ein Titel kann drei Zeilen später gesetzt oder aus einer Lokalisierungstabelle gelesen werden. Behandeln Sie die Treffer als Kandidatenliste zur Sichtprüfung, nicht als Befund.

Dann die xibs. Beim Kontrollkästchen „macOS 26.0 only“ hilft kein grep; es lebt im Inspektor des Menüeintrags und nicht in irgendeinem Attribut, das Ihr Build sehen kann. Kommen Ihre Menüs aus dem Interface Builder, bedeutet die Prüfung: jedes Menü öffnen und jeden Eintrag durchgehen.

Dann die UIKit-Menükonstruktoren. UIMenu, UIAction, UICommand und UIKeyCommand haben allesamt aktualisierte Initializer erhalten, die preferredImageVisibility entgegennehmen – die Korrektur kann also direkt bei der Konstruktion erfolgen statt als nachgelagerte Zuweisung.⁴

Dann die Verwendung von SwiftUI-Label innerhalb von Menüs. Diese übersieht man am leichtesten, denn ein Label in einem Menü sieht im Quellcode genauso aus wie ein Label anderswo. Der Modifier gehört an das Label, und nur dorthin, wo Sie das Symbol behalten wollen.

Zweimal bauen und vergleichen. Die verlässlichste Prüfung kommt ganz ohne Codelektüre aus. Bauen Sie gegen das 26er- und das 27er-SDK, öffnen Sie dieselben Menüs und fotografieren Sie beide. Dass identischer Quellcode zwei verschiedene Menüs erzeugt, ist der ganze Kern dieser Änderung, und der direkte Vergleich findet, was kein grep findet.

Dieser letzte Schritt schützt zugleich Ihre Screenshots. Marketingbilder, Dokumentation und App-Store-Material, auf denen Menüs zu sehen sind, entstanden unter dem SDK, das jeweils aktuell war, als jemand sie aufgenommen hat. Zeigen sie Symbole, die Ihr ausgelieferter Build nicht mehr rendert, sind sie ab jetzt falsch – und nichts in Ihrem Build-Prozess wird darauf hinweisen.

Das Wichtigste in Kürze

Für AppKit-Entwickler: - Wer gegen das macOS-27-SDK linkt, verliert auch Nicht-Symbolbilder, nicht nur Symbole. Wer nur seine SF Symbols prüft, übersieht die Hälfte. - Reine Symboleinträge verlieren auf dem 27er-SDK ihren automatischen Schutz und werden leer gerendert. Setzen Sie bei jedem einzelnen preferredImageVisibility = .visible. - In xibs definierte Menüs tragen ein Kontrollkästchen „macOS 26.0 only“, das die Sichtbarkeit außerhalb jedes Codepfads verändert.

Für UIKit-Entwickler: - preferredImageVisibility sitzt auf UIMenuElement sowie auf den aktualisierten Initializern von UIMenu, UIAction, UICommand und UIKeyCommand. - Die Eigenschaft existiert unter tvOS und visionOS, aber Apple dokumentiert das Verhalten für iPadOS und macOS. Prüfen Sie nach, statt es anzunehmen.

Für SwiftUI-Entwickler: - preferredImageVisibility ist nicht Ihre API. Verwenden Sie labelStyle(.titleAndIcon) am Label. - SwiftUI blendet standardmäßig Symbolbilder aus und behält Nicht-Symbolbilder – das entspricht dem AppKit-Basisverhalten, nicht dem des 27er-SDKs.

FAQ

Warum zeigen Einstellungen und Teilen weiterhin Symbole?

Das System nimmt bestimmte verbreitete Menüeinträge aus. AppKit, UIKit und SwiftUI liefern für Einträge wie Einstellungen, Teilen und Drucken weiterhin standardmäßig sichtbare Bilder.¹⁴⁵ Dass Sie diese Symbole sehen, während Ihre eigenen ausgeblendet sind, ist erwartetes Verhalten und kein Ladefehler.

Hilft es, auf einem älteren SDK zu bleiben?

Teilweise, und der Unterschied ist wichtig. Apps, die gegen macOS 26.0 oder neuer gelinkt sind, blenden Symbolbilder bereits aus.¹ Unterhalb des macOS-27-SDKs zu bleiben, erhält die Sichtbarkeit von Nicht-Symbolbildern und bewahrt den automatischen Schutz für reine Symboleinträge.²³ Die Symbolbilder kehren dadurch nicht zurück.

Was passiert mit einem Menüeintrag, der nur ein Bild und keinen Titel hat?

Auf SDKs vor macOS 27 zeigt NSMenu das Bild automatisch an, weil Titel und attributierter Titel beide leer sind.³ Auf dem macOS-27-SDK greift dieser Schutz nicht, das Bild wird ausgeblendet – und zurück bleibt ein Menüeintrag ohne sichtbaren Inhalt. Setzen Sie preferredImageVisibility = .visible.

Gilt das unter tvOS und visionOS genauso?

UIMenuElement.preferredImageVisibility ist auf beiden ab 27.0 verfügbar.⁷ Die Release-Note-Einträge beschreiben das Ausblendeverhalten für iPadOS und macOS. Dass die API auf einer Plattform existiert, ist keine Bestätigung, dass das Verhalten dort aktiv ist.

Welche Symbole sollte ich behalten?

Die Release Notes verweisen auf die Human Interface Guidelines, die ich nicht direkt lesen konnte. Die von Apple im SwiftUI-Eintrag genannte Faustregel lautet: Symbol zeigen, wenn der Menüeintrag „ein Objekt oder ein Konzept repräsentiert und keine Aktion“.⁵

Quellen