Référence de l'API de mise en page SwiftUI
Référence complète de l'API pour les outils de mise en page adaptative SwiftUI. Pour des conseils de décision et des anti-modèles, voir le skill axiom-swiftui-layout.
Aperçu
Cette référence couvre toutes les API de mise en page SwiftUI pour construire des interfaces adaptatives :
- ViewThatFits — Sélection automatique de variantes (iOS 16+)
- AnyLayout — Commutation animée de mise en page avec effacement de type (iOS 16+)
- Protocole Layout — Algorithmes de mise en page personnalisés (iOS 16+)
- onGeometryChange — Lecture efficace de la géométrie (iOS 16+ rétroporté)
- GeometryReader — Accès à la géométrie en phase de mise en page (iOS 13+)
- Remplissage des zones sûres — .safeAreaPadding() vs .padding() (iOS 17+)
- Classes de taille — Adaptation basée sur les traits
- API de fenêtre iOS 26 — Fenêtres libres, barre de menu, ancres de redimensionnement
ViewThatFits
Évalue les vues enfants dans l'ordre et affiche la première qui tient dans l'espace disponible.
Utilisation de base
ViewThatFits {
// Premier choix
HStack {
icon
title
Spacer()
button
}
// Deuxième choix
HStack {
icon
title
button
}
// Solution de repli
VStack {
HStack { icon; title }
button
}
}
Avec contrainte d'axe
// Considérer uniquement l'ajustement horizontal
ViewThatFits(in: .horizontal) {
wideVersion
narrowVersion
}
// Considérer uniquement l'ajustement vertical
ViewThatFits(in: .vertical) {
tallVersion
shortVersion
}
Comment ça fonctionne
- Applique
fixedSize()à chaque enfant - Mesure la taille idéale par rapport à l'espace disponible
- Renvoie le premier enfant qui tient
- Revient au dernier enfant si aucun ne tient
Limitations
- N'expose pas quelle variante a été sélectionnée
- Ne peut pas animer entre les variantes (utiliser AnyLayout à la place)
- Mesure toutes les variantes (considération de performance pour les vues complexes)
AnyLayout
Conteneur de mise en page à type effacé permettant des transitions animées entre les mises en page.
Utilisation de base
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)
}
}
Types de mise en page disponibles
AnyLayout(HStackLayout(alignment: .top, spacing: 10))
AnyLayout(VStackLayout(alignment: .leading, spacing: 8))
AnyLayout(ZStackLayout(alignment: .center))
AnyLayout(GridLayout(alignment: .leading, horizontalSpacing: 10, verticalSpacing: 10))
Conditions personnalisées
// Basé sur le type dynamique
@Environment(\.dynamicTypeSize) var typeSize
var layout: AnyLayout {
typeSize.isAccessibilitySize
? AnyLayout(VStackLayout())
: AnyLayout(HStackLayout())
}
// Basé sur la géométrie
@State private var isWide = true
var layout: AnyLayout {
isWide
? AnyLayout(HStackLayout())
: AnyLayout(VStackLayout())
}
Pourquoi utiliser AnyLayout plutôt que des vues conditionnelles
// ❌ Perd l'identité de la vue, pas d'animation
if isCompact {
VStack { content }
} else {
HStack { content }
}
// ✅ Préserve l'identité, animation fluide
let layout = isCompact ? AnyLayout(VStackLayout()) : AnyLayout(HStackLayout())
layout { content }
Protocole Layout
Créez des conteneurs de mise en page personnalisés avec un contrôle total sur le positionnement.
Mise en page personnalisée de base
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)
}
}
}
// Utilisation
FlowLayout(spacing: 12) {
ForEach(tags) { tag in
TagView(tag: tag)
}
}
Avec 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 {
// Utiliser cache.sizes au lieu de mesurer à nouveau
}
}
Valeurs de mise en page
// Définir une valeur de mise en page personnalisée
struct Rank: LayoutValueKey {
static let defaultValue: Int = 0
}
extension View {
func rank(_ value: Int) -> some View {
layoutValue(key: Rank.self, value: value)
}
}
// Lire dans la mise en page
func placeSubviews(...) {
let sorted = subviews.sorted { $0[Rank.self] < $1[Rank.self] }
}
onGeometryChange
Lecture efficace de la géométrie sans effets de bord de mise en page. Rétroporté vers iOS 16+.
Utilisation de base
@State private var size: CGSize = .zero
var body: some View {
content
.onGeometryChange(for: CGSize.self) { proxy in
proxy.size
} action: { newSize in
size = newSize
}
}
Lecture de valeurs spécifiques
// Largeur uniquement
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.size.width
} action: { width in
columnCount = max(1, Int(width / 150))
}
// Cadre dans un espace de coordonnées
.onGeometryChange(for: CGRect.self) { proxy in
proxy.frame(in: .global)
} action: { frame in
globalFrame = frame
}
// Rapport d'aspect
.onGeometryChange(for: Bool.self) { proxy in
proxy.size.width > proxy.size.height
} action: { isWide in
self.isWide = isWide
}
Espaces de coordonnées
// Espace de coordonnées nommé
ScrollView {
content
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.frame(in: .named("scroll")).minY
} action: { offset in
scrollOffset = offset
}
}
.coordinateSpace(name: "scroll")
Comparaison avec GeometryReader
| Aspect | onGeometryChange | GeometryReader |
|---|---|---|
| Impact sur la mise en page | Aucun | Gourmand (remplit l'espace) |
| Moment d'évaluation | Après la mise en page | Pendant la mise en page |
| Cas d'utilisation | Effets de bord | Calculs de mise en page |
| Version iOS | 16+ (rétroporté) | 13+ |
GeometryReader
Fournit des informations de géométrie pendant la phase de mise en page. À utiliser avec parcimonie en raison du dimensionnement gourmand.
Utilisation de base (contraint)
// ✅ Toujours contraindre GeometryReader
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) // Contrainte requise
Propriétés de GeometryProxy
GeometryReader { proxy in
// Taille du conteneur
let size = proxy.size // CGSize
// Insets de zone sûre
let insets = proxy.safeAreaInsets // EdgeInsets
// Cadre dans l'espace de coordonnées
let globalFrame = proxy.frame(in: .global)
let localFrame = proxy.frame(in: .local)
let namedFrame = proxy.frame(in: .named("container"))
}
Schémas courants
// Dimensionnement proportionnel
GeometryReader { geo in
VStack {
header.frame(height: geo.size.height * 0.2)
content.frame(height: geo.size.height * 0.8)
}
}
// Centrage avec décalage
GeometryReader { geo in
content
.position(x: geo.size.width / 2, y: geo.size.height / 2)
}
Éviter les erreurs courantes
// ❌ Non contraint dans VStack
VStack {
GeometryReader { ... } // Prend TOUT l'espace
Button("Suivant") { } // Invisible
}
// ✅ Contraint
VStack {
GeometryReader { ... }
.frame(height: 200)
Button("Suivant") { }
}
// ❌ Provoque des boucles de mise en page
GeometryReader { geo in
content
.frame(width: geo.size.width) // Peut provoquer une boucle infinie
}
Remplissage des zones sûres
SwiftUI propose deux approches principales pour gérer l'espacement autour du contenu : .padding() et .safeAreaPadding(). Comprendre quand utiliser chacune est essentiel pour une mise en page correcte sur les appareils avec zones sûres (encoche, Dynamic Island, indicateur d'accueil).
La différence cruciale
// ❌ FAUX - Ignore les zones sûres, le contenu touche l'encoche/l'indicateur d'accueil
ScrollView {
content
}
.padding(.horizontal, 20)
// ✅ CORRECT - Respecte les zones sûres, ajoute un remplissage au-delà
ScrollView {
content
}
.safeAreaPadding(.horizontal, 20)
Point clé : .padding() ajoute un espacement fixe à partir des bords de la vue. .safeAreaPadding() ajoute un espacement au-delà des insets de zone sûre.
Quand utiliser chacun
Utiliser .padding() quand
- Ajouter un espacement entre des vues sœurs dans un conteneur
- Créer un espacement interne qui doit être cohérent partout
- Travailler avec des vues qui respectent déjà les zones sûres (comme List, Form)
- Ajouter un espacement décoratif sur macOS (aucun problème de zone sûre)
VStack(spacing: 0) {
header
.padding(.horizontal, 16) // ✅ Espacement interne
Divider()
content
.padding(.horizontal, 16) // ✅ Espacement interne
}
Utiliser .safeAreaPadding() quand (iOS 17+)
- Ajouter une marge à un contenu pleine largeur qui s'étend jusqu'aux bords de l'écran
- Implémenter un défilement bord à bord avec des insets appropriés
- Créer des conteneurs personnalisés nécessitant une connaissance des zones sûres
- Travailler avec Liquid Glass ou des matériaux plein écran
// ✅ Liste bord à bord avec remplissage personnalisé
List(items) { item in
ItemRow(item)
}
.listStyle(.plain)
.safeAreaPadding(.horizontal, 20) // Ajoute 20pt au-delà des zones sûres
// ✅ Contenu plein écran avec marges appropriées
ZStack {
Color.blue.ignoresSafeArea()
VStack {
content
}
.safeAreaPadding(.all, 16) // Respecte l'encoche, l'indicateur d'accueil
}
Disponibilité sur les plateformes
iOS 17+, iPadOS 17+, macOS 14+, axiom-visionOS 1.0+
Pour les versions iOS antérieures, utiliser une gestion manuelle des zones sûres :
// Alternative iOS 13-16
GeometryReader { geo in
content
.padding(.horizontal, 20 + geo.safeAreaInsets.leading)
}
Ou compilation conditionnelle :
if #available(iOS 17, *) {
content.safeAreaPadding(.horizontal, 20)
} else {
content.padding(.horizontal, 20)
.padding(.leading, safeAreaInsets.leading)
}
Utilisation par bord spécifique
// Haut uniquement (sous la barre d'état/encoche)
.safeAreaPadding(.top, 8)
// Bas uniquement (au-dessus de l'indicateur d'accueil)
.safeAreaPadding(.bottom, 16)
// Horizontal (gauche/droite des zones sûres)
.safeAreaPadding(.horizontal, 20)
// Tous les bords
.safeAreaPadding(.all, 16)
// Bords individuels
.safeAreaPadding(EdgeInsets(top: 8, leading: 20, bottom: 16, trailing: 20))
Schémas courants
ScrollView bord à bord
ScrollView {
LazyVStack(spacing: 12) {
ForEach(items) { item in
ItemCard(item)
}
}
}
.safeAreaPadding(.horizontal, 16) // Inset de contenu à partir des bords + zones sûres
.safeAreaPadding(.vertical, 8)
Arrière-plan plein écran avec contenu sécurisé
ZStack {
// L'arrière-plan s'étend bord à bord
LinearGradient(...)
.ignoresSafeArea()
// Le contenu respecte les zones sûres + remplissage personnalisé
VStack {
header
Spacer()
content
Spacer()
footer
}
.safeAreaPadding(.all, 20)
}
Remplissage imbriqué (approche combinée)
// Externe : Remplissage de zone sûre pour les insets de l'appareil
VStack(spacing: 0) {
content
}
.safeAreaPadding(.horizontal, 16) // Au-delà des zones sûres
// Interne : Remplissage régulier pour l'espacement interne
VStack {
Text("Titre")
.padding(.bottom, 8) // Espacement interne
Text("Sous-titre")
}
Arbre de décision
Votre contenu s'étend-il jusqu'aux bords de l'écran ?
├─ OUI → Utiliser .safeAreaPadding()
│ ├─ Est-il défilable ? → .safeAreaPadding(.horizontal/.vertical)
│ └─ Est-il plein écran ? → .safeAreaPadding(.all)
│
└─ NON (contenu dans un conteneur sécurisé comme List/Form)
└─ Utiliser .padding() pour l'espacement interne
Débogage visuel
// Visualiser le remplissage de zone sûre (iOS 17+)
content
.safeAreaPadding(.horizontal, 20)
.background(.red.opacity(0.2)) // Affiche la zone de remplissage
.border(.blue) // Affiche les limites du contenu
Migration depuis la gestion manuelle des zones sûres
// ❌ ANCIEN : Calcul manuel (iOS 13-16)
GeometryReader { geo in
content
.padding(.top, geo.safeAreaInsets.top + 16)
.padding(.bottom, geo.safeAreaInsets.bottom + 16)
.padding(.horizontal, 20)
}
// ✅ NOUVEAU : .safeAreaPadding() (iOS 17+)
content
.safeAreaPadding(.vertical, 16)
.safeAreaPadding(.horizontal, 20)
API connexes
.safeAreaInset(edge:) - Ajoute un contenu persistant qui réduit la zone sûre :
ScrollView {
content
}
.safeAreaInset(edge: .bottom) {
// Cela RÉDUIT la zone sûre, le contenu défile en dessous
toolbarButtons
.padding()
.background(.ultraThinMaterial)
}
.ignoresSafeArea() - Opte complètement en dehors de la zone sûre :
Color.blue
.ignoresSafeArea() // S'étend jusqu'aux bords absolus de l'écran
Pourquoi c'est important
Avant iOS 17 : Les développeurs devaient calculer manuellement les insets de zone sûre avec GeometryReader, ce qui entraînait :
- Du code verbeux
- Une surcharge de performance (GeometryReader force un passage supplémentaire de mise en page)
- Des erreurs faciles (oublier de vérifier tous les bords)
iOS 17+ : .safeAreaPadding() fournit :
- Une API déclarative (correspond à la philosophie SwiftUI)
- Une connaissance automatique des zones sûres
- De meilleures performances (pas de passages de mise en page supplémentaires)
- Une spécification de bord typée et sécurisée
Impact réel
...