Referencia de la API de Diseño de SwiftUI
Referencia completa de la API para herramientas de diseño adaptable en SwiftUI. Para orientación sobre decisiones y antipatrones, consulta el skill axiom-swiftui-layout.
Resumen
Esta referencia cubre todas las APIs de diseño de SwiftUI para construir interfaces adaptables:
- ViewThatFits — Selección automática de variantes (iOS 16+)
- AnyLayout — Cambio de diseño animado con borrado de tipo (iOS 16+)
- Protocolo Layout — Algoritmos de diseño personalizados (iOS 16+)
- onGeometryChange — Lectura eficiente de geometría (iOS 16+ retroportado)
- GeometryReader — Acceso a geometría en la fase de diseño (iOS 13+)
- Relleno de Área Segura —
.safeAreaPadding()vs.padding()(iOS 17+) - Clases de Tamaño — Adaptación basada en rasgos
- APIs de Ventanas de iOS 26 — Ventanas de forma libre, barra de menú, anclas de redimensionamiento
ViewThatFits
Evalúa las vistas hijas en orden y muestra la primera que quepa en el espacio disponible.
Uso Básico
ViewThatFits {
// Primera opción
HStack {
icon
title
Spacer()
button
}
// Segunda opción
HStack {
icon
title
button
}
// Opción de respaldo
VStack {
HStack { icon; title }
button
}
}
Con Restricción de Eje
// Considera solo el ajuste horizontal
ViewThatFits(in: .horizontal) {
wideVersion
narrowVersion
}
// Considera solo el ajuste vertical
ViewThatFits(in: .vertical) {
tallVersion
shortVersion
}
Cómo Funciona
- Aplica
fixedSize()a cada hija - Mide el tamaño ideal contra el espacio disponible
- Devuelve la primera hija que quepa
- Usa la última hija como respaldo si ninguna cabe
Limitaciones
- No expone qué variante fue seleccionada
- No puede animar entre variantes (usa AnyLayout en su lugar)
- Mide todas las variantes (consideración de rendimiento para vistas complejas)
AnyLayout
Contenedor de diseño con borrado de tipo que permite transiciones animadas entre diseños.
Uso Básico
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)
}
}
Tipos de Diseño 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))
Condiciones Personalizadas
// Basado en Dynamic Type
@Environment(\.dynamicTypeSize) var typeSize
var layout: AnyLayout {
typeSize.isAccessibilitySize
? AnyLayout(VStackLayout())
: AnyLayout(HStackLayout())
}
// Basado en geometría
@State private var isWide = true
var layout: AnyLayout {
isWide
? AnyLayout(HStackLayout())
: AnyLayout(VStackLayout())
}
Por Qué Usarlo en Lugar de Vistas Condicionales
// ❌ Pierde la identidad de la vista, sin animación
if isCompact {
VStack { content }
} else {
HStack { content }
}
// ✅ Conserva la identidad, animación suave
let layout = isCompact ? AnyLayout(VStackLayout()) : AnyLayout(HStackLayout())
layout { content }
Protocolo Layout
Crea contenedores de diseño personalizados con control total sobre el posicionamiento.
Diseño Personalizado Básico
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)
}
}
}
// Uso
FlowLayout(spacing: 12) {
ForEach(tags) { tag in
TagView(tag: tag)
}
}
Con Caché
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 {
// Usa cache.sizes en lugar de medir de nuevo
}
}
Valores de Diseño
// Define un valor de diseño personalizado
struct Rank: LayoutValueKey {
static let defaultValue: Int = 0
}
extension View {
func rank(_ value: Int) -> some View {
layoutValue(key: Rank.self, value: value)
}
}
// Lectura en el diseño
func placeSubviews(...) {
let sorted = subviews.sorted { $0[Rank.self] < $1[Rank.self] }
}
onGeometryChange
Lectura eficiente de geometría sin efectos secundarios en el diseño. Retroportado a iOS 16+.
Uso Básico
@State private var size: CGSize = .zero
var body: some View {
content
.onGeometryChange(for: CGSize.self) { proxy in
proxy.size
} action: { newSize in
size = newSize
}
}
Lectura de Valores Específicos
// Solo ancho
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.size.width
} action: { width in
columnCount = max(1, Int(width / 150))
}
// Marco en espacio de coordenadas
.onGeometryChange(for: CGRect.self) { proxy in
proxy.frame(in: .global)
} action: { frame in
globalFrame = frame
}
// Relación de aspecto
.onGeometryChange(for: Bool.self) { proxy in
proxy.size.width > proxy.size.height
} action: { isWide in
self.isWide = isWide
}
Espacios de Coordenadas
// Espacio de coordenadas nombrado
ScrollView {
content
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.frame(in: .named("scroll")).minY
} action: { offset in
scrollOffset = offset
}
}
.coordinateSpace(name: "scroll")
Comparación con GeometryReader
| Aspecto | onGeometryChange | GeometryReader |
|---|---|---|
| Impacto en el diseño | Ninguno | Codicioso (ocupa espacio) |
| Cuándo se evalúa | Después del diseño | Durante el diseño |
| Caso de uso | Efectos secundarios | Cálculos de diseño |
| Versión de iOS | 16+ (retroportado) | 13+ |
GeometryReader
Proporciona información de geometría durante la fase de diseño. Úsalo con moderación debido a su tamaño codicioso.
Uso Básico (Restringido)
// ✅ Siempre restringe 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) // Restricción necesaria
Propiedades de GeometryProxy
GeometryReader { proxy in
// Tamaño del contenedor
let size = proxy.size // CGSize
// Inserciones de área segura
let insets = proxy.safeAreaInsets // EdgeInsets
// Marco en espacio de coordenadas
let globalFrame = proxy.frame(in: .global)
let localFrame = proxy.frame(in: .local)
let namedFrame = proxy.frame(in: .named("container"))
}
Patrones Comunes
// Tamaño proporcional
GeometryReader { geo in
VStack {
header.frame(height: geo.size.height * 0.2)
content.frame(height: geo.size.height * 0.8)
}
}
// Centrado con desplazamiento
GeometryReader { geo in
content
.position(x: geo.size.width / 2, y: geo.size.height / 2)
}
Evitando Errores Comunes
// ❌ Sin restricción en VStack
VStack {
GeometryReader { ... } // Ocupa TODO el espacio
Button("Siguiente") { } // Invisible
}
// ✅ Restringido
VStack {
GeometryReader { ... }
.frame(height: 200)
Button("Siguiente") { }
}
// ❌ Causando bucles de diseño
GeometryReader { geo in
content
.frame(width: geo.size.width) // Puede causar bucle infinito
}
Relleno de Área Segura
SwiftUI ofrece dos enfoques principales para manejar el espaciado alrededor del contenido: .padding() y .safeAreaPadding(). Entender cuándo usar cada uno es crucial para un diseño adecuado en dispositivos con áreas seguras (notch, Dynamic Island, indicador de inicio).
La Diferencia Crítica
// ❌ INCORRECTO - Ignora áreas seguras, el contenido choca con el notch/indicador
ScrollView {
content
}
.padding(.horizontal, 20)
// ✅ CORRECTO - Respeta áreas seguras, añade padding más allá de ellas
ScrollView {
content
}
.safeAreaPadding(.horizontal, 20)
Insight clave: .padding() añade espaciado fijo desde los bordes de la vista. .safeAreaPadding() añade espaciado más allá de las inserciones de área segura.
Cuándo Usar Cada Uno
Usa .padding() cuando
- Añadas espaciado entre vistas hermanas dentro de un contenedor
- Crear espaciado interno que debe ser consistente en todas partes
- Trabajar con vistas que ya respetan áreas seguras (como List, Form)
- Añadir espaciado decorativo en macOS (sin preocupaciones de área segura)
VStack(spacing: 0) {
header
.padding(.horizontal, 16) // ✅ Espaciado interno
Divider()
content
.padding(.horizontal, 16) // ✅ Espaciado interno
}
Usa .safeAreaPadding() cuando (iOS 17+)
- Añadir margen a contenido de ancho completo que se extiende hasta los bordes de la pantalla
- Implementar desplazamiento de borde a borde con inserciones adecuadas
- Crear contenedores personalizados que necesiten conocimiento del área segura
- Trabajar con Liquid Glass o materiales de pantalla completa
// ✅ Lista de borde a borde con padding personalizado
List(items) { item in
ItemRow(item)
}
.listStyle(.plain)
.safeAreaPadding(.horizontal, 20) // Añade 20pt más allá de áreas seguras
// ✅ Contenido de pantalla completa con márgenes adecuados
ZStack {
Color.blue.ignoresSafeArea()
VStack {
content
}
.safeAreaPadding(.all, 16) // Respeta notch, indicador de inicio
}
Disponibilidad en Plataformas
iOS 17+, iPadOS 17+, macOS 14+, axiom-visionOS 1.0+
Para versiones anteriores de iOS, usa manejo manual del área segura:
// iOS 13-16 como respaldo
GeometryReader { geo in
content
.padding(.horizontal, 20 + geo.safeAreaInsets.leading)
}
O compilación condicional:
if #available(iOS 17, *) {
content.safeAreaPadding(.horizontal, 20)
} else {
content.padding(.horizontal, 20)
.padding(.leading, safeAreaInsets.leading)
}
Uso Específico por Borde
// Solo superior (debajo de la barra de estado/notch)
.safeAreaPadding(.top, 8)
// Solo inferior (encima del indicador de inicio)
.safeAreaPadding(.bottom, 16)
// Horizontal (izquierda/derecha de áreas seguras)
.safeAreaPadding(.horizontal, 20)
// Todos los bordes
.safeAreaPadding(.all, 16)
// Bordes individuales
.safeAreaPadding(EdgeInsets(top: 8, leading: 20, bottom: 16, trailing: 20))
Patrones Comunes
ScrollView de Borde a Borde
ScrollView {
LazyVStack(spacing: 12) {
ForEach(items) { item in
ItemCard(item)
}
}
}
.safeAreaPadding(.horizontal, 16) // Inserción de contenido desde bordes + áreas seguras
.safeAreaPadding(.vertical, 8)
Fondo de Pantalla Completa con Contenido Seguro
ZStack {
// El fondo se extiende de borde a borde
LinearGradient(...)
.ignoresSafeArea()
// El contenido respeta áreas seguras + padding personalizado
VStack {
header
Spacer()
content
Spacer()
footer
}
.safeAreaPadding(.all, 20)
}
Padding Anidado (Enfoque Combinado)
// Externo: Padding de área segura para inserciones del dispositivo
VStack(spacing: 0) {
content
}
.safeAreaPadding(.horizontal, 16) // Más allá de áreas seguras
// Interno: Padding regular para espaciado interno
VStack {
Text("Título")
.padding(.bottom, 8) // Espaciado interno
Text("Subtítulo")
}
Árbol de Decisión
¿Tu contenido se extiende hasta los bordes de la pantalla?
├─ SÍ → Usa .safeAreaPadding()
│ ├─ ¿Es desplazable? → .safeAreaPadding(.horizontal/.vertical)
│ └─ ¿Es de pantalla completa? → .safeAreaPadding(.all)
│
└─ NO (contenido dentro de un contenedor seguro como List/Form)
└─ Usa .padding() para espaciado interno
Depuración Visual
// Visualiza el padding de área segura (iOS 17+)
content
.safeAreaPadding(.horizontal, 20)
.background(.red.opacity(0.2)) // Muestra el área de padding
.border(.blue) // Muestra los límites del contenido
Migración desde Manejo Manual de Área Segura
// ❌ ANTIGUO: Cálculo manual (iOS 13-16)
GeometryReader { geo in
content
.padding(.top, geo.safeAreaInsets.top + 16)
.padding(.bottom, geo.safeAreaInsets.bottom + 16)
.padding(.horizontal, 20)
}
// ✅ NUEVO: .safeAreaPadding() (iOS 17+)
content
.safeAreaPadding(.vertical, 16)
.safeAreaPadding(.horizontal, 20)
APIs Relacionadas
.safeAreaInset(edge:) - Añade contenido persistente que reduce el área segura:
ScrollView {
content
}
.safeAreaInset(edge: .bottom) {
// Esto REDUCE el área segura, el contenido se desplaza debajo
toolbarButtons
.padding()
.background(.ultraThinMaterial)
}
.ignoresSafeArea() - Opta por salir completamente del área segura:
Color.blue
.ignoresSafeArea() // Se extiende hasta los bordes absolutos de la pantalla
Por Qué es Importante
Antes de iOS 17: Los desarrolladores tenían que calcular manualmente las inserciones de área segura con GeometryReader, lo que conllevaba:
- Código verboso
- Sobrecarga de rendimiento (GeometryReader fuerza un pase de diseño extra)
- Errores fáciles (olvidar verificar todos los bordes)
iOS 17+: .safeAreaPadding() proporciona:
- API declarativa (coincide con la filosofía de SwiftUI)
- Conocimiento automático del área segura
- Mejor rendimiento (sin pases de diseño extra)
- Especificación de bordes con seguridad de tipos
Impacto en el mundo real
...