SwiftUI Layout-API-Referenz
Umfassende API-Referenz für adaptive Layout-Tools in SwiftUI. Für Entscheidungshilfen und Anti-Patterns siehe das Skill axiom-swiftui-layout.
Übersicht
Diese Referenz deckt alle SwiftUI-Layout-APIs zur Erstellung adaptiver Oberflächen ab:
- ViewThatFits — Automatische Variantenauswahl (iOS 16+)
- AnyLayout — Typ-ausgelöschter animierter Layout-Wechsel (iOS 16+)
- Layout-Protokoll — Eigene Layout-Algorithmen (iOS 16+)
- onGeometryChange — Effizientes Auslesen von Geometrie (iOS 16+, zurückportiert)
- GeometryReader — Geometriezugriff in der Layout-Phase (iOS 13+)
- Safe-Area-Padding — .safeAreaPadding() vs. .padding() (iOS 17+)
- Size Classes — Trait-basierte Anpassung
- iOS 26 Fenster-APIs — Frei platzierbare Fenster, Menüleiste, Größenanker
ViewThatFits
Wertet Child-Views der Reihe nach aus und zeigt die erste an, die in den verfügbaren Platz passt.
Grundlegende Verwendung
ViewThatFits {
// Erste Wahl
HStack {
icon
title
Spacer()
button
}
// Zweite Wahl
HStack {
icon
title
button
}
// Fallback
VStack {
HStack { icon; title }
button
}
}
Mit Achsen-Einschränkung
// Nur horizontale Passform prüfen
ViewThatFits(in: .horizontal) {
wideVersion
narrowVersion
}
// Nur vertikale Passform prüfen
ViewThatFits(in: .vertical) {
tallVersion
shortVersion
}
Funktionsweise
- Wendet
fixedSize()auf jedes Child an - Misst die ideale Größe gegen den verfügbaren Platz
- Gibt das erste passende Child zurück
- Fällt auf das letzte Child zurück, wenn keins passt
Einschränkungen
- Die ausgewählte Variante wird nicht offengelegt
- Animation zwischen Varianten ist nicht möglich (stattdessen AnyLayout verwenden)
- Alle Varianten werden gemessen (Leistungsaspekt bei komplexen Views)
AnyLayout
Typ-ausgelöschter Layout-Container für animierte Übergänge zwischen Layouts.
Grundlegende Verwendung
struct AdaptiveView: View {
@Environment(\.horizontalSizeClass) var sizeClass
var layout: AnyLayout {
sizeClass == .compact
? AnyLayout(VStackLayout(spacing: 12))
: AnyLayout(HStackLayout(spacing: 20))
}
var body: some View {
layout {
ForEach(items) { item in
ItemView(item: item)
}
}
.animation(.default, value: sizeClass)
}
}
Verfügbare Layout-Typen
AnyLayout(HStackLayout(alignment: .top, spacing: 10))
AnyLayout(VStackLayout(alignment: .leading, spacing: 8))
AnyLayout(ZStackLayout(alignment: .center))
AnyLayout(GridLayout(alignment: .leading, horizontalSpacing: 10, verticalSpacing: 10))
Benutzerdefinierte Bedingungen
// Basierend auf Dynamic Type
@Environment(\.dynamicTypeSize) var typeSize
var layout: AnyLayout {
typeSize.isAccessibilitySize
? AnyLayout(VStackLayout())
: AnyLayout(HStackLayout())
}
// Basierend auf Geometrie
@State private var isWide = true
var layout: AnyLayout {
isWide
? AnyLayout(HStackLayout())
: AnyLayout(VStackLayout())
}
Warum AnyLayout statt bedingter Views
// ❌ Verliert View-Identität, keine Animation
if isCompact {
VStack { content }
} else {
HStack { content }
}
// ✅ Behält Identität, sanfte Animation
let layout = isCompact ? AnyLayout(VStackLayout()) : AnyLayout(HStackLayout())
layout { content }
Layout-Protokoll
Erstellen Sie benutzerdefinierte Layout-Container mit voller Kontrolle über die Positionierung.
Einfaches benutzerdefiniertes Layout
struct FlowLayout: Layout {
var spacing: CGFloat = 8
func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) -> CGSize {
let sizes = subviews.map { $0.sizeThatFits(.unspecified) }
return calculateSize(for: sizes, in: proposal.width ?? .infinity)
}
func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) {
var point = bounds.origin
var lineHeight: CGFloat = 0
for subview in subviews {
let size = subview.sizeThatFits(.unspecified)
if point.x + size.width > bounds.maxX {
point.x = bounds.origin.x
point.y += lineHeight + spacing
lineHeight = 0
}
subview.place(at: point, proposal: .unspecified)
point.x += size.width + spacing
lineHeight = max(lineHeight, size.height)
}
}
}
// Verwendung
FlowLayout(spacing: 12) {
ForEach(tags) { tag in
TagView(tag: tag)
}
}
Mit Cache
struct CachedLayout: Layout {
struct CacheData {
var sizes: [CGSize] = []
}
func makeCache(subviews: Subviews) -> CacheData {
CacheData(sizes: subviews.map { $0.sizeThatFits(.unspecified) })
}
func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout CacheData) -> CGSize {
// cache.sizes verwenden statt neu zu messen
}
}
Layout-Werte
// Benutzerdefinierten Layout-Wert definieren
struct Rank: LayoutValueKey {
static let defaultValue: Int = 0
}
extension View {
func rank(_ value: Int) -> some View {
layoutValue(key: Rank.self, value: value)
}
}
// Im Layout auslesen
func placeSubviews(...) {
let sorted = subviews.sorted { $0[Rank.self] < $1[Rank.self] }
}
onGeometryChange
Effizientes Auslesen von Geometrie ohne Layout-Nebeneffekte. Zurückportiert auf iOS 16+.
Grundlegende Verwendung
@State private var size: CGSize = .zero
var body: some View {
content
.onGeometryChange(for: CGSize.self) { proxy in
proxy.size
} action: { newSize in
size = newSize
}
}
Bestimmte Werte auslesen
// Nur Breite
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.size.width
} action: { width in
columnCount = max(1, Int(width / 150))
}
// Frame im Koordinatensystem
.onGeometryChange(for: CGRect.self) { proxy in
proxy.frame(in: .global)
} action: { frame in
globalFrame = frame
}
// Seitenverhältnis
.onGeometryChange(for: Bool.self) { proxy in
proxy.size.width > proxy.size.height
} action: { isWide in
self.isWide = isWide
}
Koordinatensysteme
// Benanntes Koordinatensystem
ScrollView {
content
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.frame(in: .named("scroll")).minY
} action: { offset in
scrollOffset = offset
}
}
.coordinateSpace(name: "scroll")
Vergleich mit GeometryReader
| Aspekt | onGeometryChange | GeometryReader |
|---|---|---|
| Layout-Auswirkung | Keine | Gierig (füllt Platz) |
| Zeitpunkt der Auswertung | Nach Layout | Während Layout |
| Anwendungsfall | Nebeneffekte | Layout-Berechnungen |
| iOS-Version | 16+ (zurückportiert) | 13+ |
GeometryReader
Stellt Geometrie-Informationen während der Layout-Phase bereit. Aufgrund der gierigen Größenermittlung sparsam verwenden.
Grundlegende Verwendung (Eingeschränkt)
// ✅ GeometryReader immer einschränken
GeometryReader { proxy in
let width = proxy.size.width
HStack(spacing: 0) {
Rectangle().frame(width: width * 0.3)
Rectangle().frame(width: width * 0.7)
}
}
.frame(height: 100) // Erforderliche Einschränkung
GeometryProxy-Eigenschaften
GeometryReader { proxy in
// Containergröße
let size = proxy.size // CGSize
// Safe-Area-Abstände
let insets = proxy.safeAreaInsets // EdgeInsets
// Frame im Koordinatensystem
let globalFrame = proxy.frame(in: .global)
let localFrame = proxy.frame(in: .local)
let namedFrame = proxy.frame(in: .named("container"))
}
Häufige Muster
// Proportionale Größen
GeometryReader { geo in
VStack {
header.frame(height: geo.size.height * 0.2)
content.frame(height: geo.size.height * 0.8)
}
}
// Zentrieren mit Versatz
GeometryReader { geo in
content
.position(x: geo.size.width / 2, y: geo.size.height / 2)
}
Häufige Fehler vermeiden
// ❌ Nicht eingeschränkt in VStack
VStack {
GeometryReader { ... } // Nimmt den GESAMTEN Platz ein
Button("Weiter") { } // Unsichtbar
}
// ✅ Eingeschränkt
VStack {
GeometryReader { ... }
.frame(height: 200)
Button("Weiter") { }
}
// ❌ Verursacht Layout-Schleifen
GeometryReader { geo in
content
.frame(width: geo.size.width) // Kann Endlosschleife verursachen
}
Safe-Area-Padding
SwiftUI bietet zwei primäre Ansätze für Abstände um Inhalte: .padding() und .safeAreaPadding(). Das Verständnis, wann was zu verwenden ist, ist entscheidend für ein korrektes Layout auf Geräten mit Safe Areas (Notch, Dynamic Island, Home-Button).
Der entscheidende Unterschied
// ❌ FALSCH - Ignoriert Safe Areas, Inhalt stößt an Notch/Home-Button
ScrollView {
content
}
.padding(.horizontal, 20)
// ✅ RICHTIG - Respektiert Safe Areas, fügt zusätzlichen Abstand hinzu
ScrollView {
content
}
.safeAreaPadding(.horizontal, 20)
Wichtige Erkenntnis: .padding() fügt einen festen Abstand von den Rändern der View hinzu. .safeAreaPadding() fügt Abstand jenseits der Safe-Area-Abstände hinzu.
Wann was verwenden
Verwenden Sie .padding(), wenn
- Sie Abstand zwischen Geschwister-Views innerhalb eines Containers hinzufügen
- Sie internen Abstand erstellen, der überall gleich sein soll
- Sie mit Views arbeiten, die Safe Areas bereits respektieren (wie List, Form)
- Sie dekorative Abstände auf macOS hinzufügen (keine Safe-Area-Probleme)
VStack(spacing: 0) {
header
.padding(.horizontal, 16) // ✅ Interner Abstand
Divider()
content
.padding(.horizontal, 16) // ✅ Interner Abstand
}
Verwenden Sie .safeAreaPadding(), wenn (iOS 17+)
- Sie Randabstand zu vollbreiten Inhalten hinzufügen, die bis zu den Bildschirmrändern reichen
- Sie randloses Scrollen mit korrekten Abständen implementieren
- Sie benutzerdefinierte Container erstellen, die Safe-Area-Informationen benötigen
- Sie mit Liquid Glass oder Vollbild-Materialien arbeiten
// ✅ Randlose Liste mit benutzerdefiniertem Abstand
List(items) { item in
ItemRow(item)
}
.listStyle(.plain)
.safeAreaPadding(.horizontal, 20) // Fügt 20pt jenseits der Safe Areas hinzu
// ✅ Vollbild-Inhalt mit korrekten Rändern
ZStack {
Color.blue.ignoresSafeArea()
VStack {
content
}
.safeAreaPadding(.all, 16) // Respektiert Notch, Home-Button
}
Plattformverfügbarkeit
iOS 17+, iPadOS 17+, macOS 14+, visionOS 1.0+
Für ältere iOS-Versionen manuelle Safe-Area-Handhabung verwenden:
// iOS 13-16 Fallback
GeometryReader { geo in
content
.padding(.horizontal, 20 + geo.safeAreaInsets.leading)
}
Oder bedingte Kompilierung:
if #available(iOS 17, *) {
content.safeAreaPadding(.horizontal, 20)
} else {
content.padding(.horizontal, 20)
.padding(.leading, safeAreaInsets.leading)
}
Kantenspezifische Verwendung
// Nur oben (unter Statusleiste/Notch)
.safeAreaPadding(.top, 8)
// Nur unten (über Home-Button)
.safeAreaPadding(.bottom, 16)
// Horizontal (links/rechts der Safe Areas)
.safeAreaPadding(.horizontal, 20)
// Alle Kanten
.safeAreaPadding(.all, 16)
// Einzelne Kanten
.safeAreaPadding(EdgeInsets(top: 8, leading: 20, bottom: 16, trailing: 20))
Häufige Muster
Randloser ScrollView
ScrollView {
LazyVStack(spacing: 12) {
ForEach(items) { item in
ItemCard(item)
}
}
}
.safeAreaPadding(.horizontal, 16) // Inhalt eingerückt von Rändern + Safe Areas
.safeAreaPadding(.vertical, 8)
Vollbild-Hintergrund mit sicherem Inhalt
ZStack {
// Hintergrund erstreckt sich randlos
LinearGradient(...)
.ignoresSafeArea()
// Inhalt respektiert Safe Areas + benutzerdefinierten Abstand
VStack {
header
Spacer()
content
Spacer()
footer
}
.safeAreaPadding(.all, 20)
}
Verschachtelte Padding (Kombinierter Ansatz)
// Äußerer: Safe-Area-Abstand für Geräte-Abstände
VStack(spacing: 0) {
content
}
.safeAreaPadding(.horizontal, 16) // Jenseits der Safe Areas
// Innerer: Reguläres Padding für internen Abstand
VStack {
Text("Titel")
.padding(.bottom, 8) // Interner Abstand
Text("Untertitel")
}
Entscheidungsbaum
Erstreckt sich Ihr Inhalt bis zu den Bildschirmrändern?
├─ JA → .safeAreaPadding() verwenden
│ ├─ Ist es scrollbar? → .safeAreaPadding(.horizontal/.vertical)
│ └─ Ist es Vollbild? → .safeAreaPadding(.all)
│
└─ NEIN (innerhalb eines sicheren Containers wie List/Form)
└─ .padding() für internen Abstand verwenden
Visuelles Debugging
// Visualisiert Safe-Area-Padding (iOS 17+)
content
.safeAreaPadding(.horizontal, 20)
.background(.red.opacity(0.2)) // Zeigt Padding-Bereich
.border(.blue) // Zeigt Inhaltsgrenzen
Migration von manueller Safe-Area-Handhabung
// ❌ ALT: Manuelle Berechnung (iOS 13-16)
GeometryReader { geo in
content
.padding(.top, geo.safeAreaInsets.top + 16)
.padding(.bottom, geo.safeAreaInsets.bottom + 16)
.padding(.horizontal, 20)
}
// ✅ NEU: .safeAreaPadding() (iOS 17+)
content
.safeAreaPadding(.vertical, 16)
.safeAreaPadding(.horizontal, 20)
Verwandte APIs
.safeAreaInset(edge:) - Fügt persistenten Inhalt hinzu, der die Safe Area verkleinert:
ScrollView {
content
}
.safeAreaInset(edge: .bottom) {
// Dies VERKLEINERT die Safe Area, Inhalt scrollt darunter
toolbarButtons
.padding()
.background(.ultraThinMaterial)
}
.ignoresSafeArea() - Vollständiger Verzicht auf Safe Area:
Color.blue
.ignoresSafeArea() // Erstreckt sich bis zu den absoluten Bildschirmrändern
Warum es wichtig ist
Vor iOS 17: Entwickler mussten Safe-Area-Abstände manuell mit GeometryReader berechnen, was zu Folgendem führte:
- Ausführlichem Code
- Leistungseinbußen (GeometryReader erzwingt einen zusätzlichen Layout-Durchlauf)
- Leicht zu übersehenden Fehlern (Vergessen, alle Kanten zu prüfen)
iOS 17+: .safeAreaPadding() bietet:
- Deklarative API (entspricht der SwiftUI-Philosophie)
- Automatische Safe-Area-Erkennung
- Bessere Leistung (keine zusätzlichen Layout-Durchläufe)
- Typsichere Kantenbeschreibung
Auswirkungen in der Praxis
…