Referência da API de Layout do SwiftUI
Referência abrangente da API para ferramentas de layout adaptativo do SwiftUI. Para orientação sobre decisões e anti-padrões, veja o skill axiom-swiftui-layout.
Visão Geral
Esta referência cobre todas as APIs de layout do SwiftUI para construir interfaces adaptativas:
- ViewThatFits — Seleção automática de variantes (iOS 16+)
- AnyLayout — Troca de layout animada com type-erasure (iOS 16+)
- Protocolo Layout — Algoritmos de layout personalizados (iOS 16+)
- onGeometryChange — Leitura eficiente de geometria (iOS 16+ retroportado)
- GeometryReader — Acesso à geometria durante a fase de layout (iOS 13+)
- Padding de Área Segura — .safeAreaPadding() vs .padding() (iOS 17+)
- Classes de Tamanho — Adaptação baseada em características
- APIs de Janela do iOS 26 — Janelas de forma livre, barra de menus, âncoras de redimensionamento
ViewThatFits
Avalia as visualizações filhas em ordem e exibe a primeira que se ajusta ao espaço disponível.
Uso Básico
ViewThatFits {
// Primeira escolha
HStack {
icon
title
Spacer()
button
}
// Segunda escolha
HStack {
icon
title
button
}
// Opção de fallback
VStack {
HStack { icon; title }
button
}
}
Com Restrição de Eixo
// Considera apenas o ajuste horizontal
ViewThatFits(in: .horizontal) {
wideVersion
narrowVersion
}
// Considera apenas o ajuste vertical
ViewThatFits(in: .vertical) {
tallVersion
shortVersion
}
Como Funciona
- Aplica
fixedSize()a cada filho - Mede o tamanho ideal contra o espaço disponível
- Retorna o primeiro filho que se ajusta
- Usa o último filho como fallback se nenhum se ajustar
Limitações
- Não expõe qual variante foi selecionada
- Não permite animação entre variantes (use AnyLayout)
- Mede todas as variantes (considere desempenho para visualizações complexas)
AnyLayout
Contêiner de layout com type-erasure que permite transições animadas entre layouts.
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 Layout Disponíveis
AnyLayout(HStackLayout(alignment: .top, spacing: 10))
AnyLayout(VStackLayout(alignment: .leading, spacing: 8))
AnyLayout(ZStackLayout(alignment: .center))
AnyLayout(GridLayout(alignment: .leading, horizontalSpacing: 10, verticalSpacing: 10))
Condições Personalizadas
// Baseado no Dynamic Type
@Environment(\.dynamicTypeSize) var typeSize
var layout: AnyLayout {
typeSize.isAccessibilitySize
? AnyLayout(VStackLayout())
: AnyLayout(HStackLayout())
}
// Baseado na geometria
@State private var isWide = true
var layout: AnyLayout {
isWide
? AnyLayout(HStackLayout())
: AnyLayout(VStackLayout())
}
Por Que Usar em Vez de Visualizações Condicionais
// ❌ Perde identidade da visualização, sem animação
if isCompact {
VStack { content }
} else {
HStack { content }
}
// ✅ Preserva identidade, animação suave
let layout = isCompact ? AnyLayout(VStackLayout()) : AnyLayout(HStackLayout())
layout { content }
Protocolo Layout
Crie contêineres de layout personalizados com controle total sobre o posicionamento.
Layout 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)
}
}
Com 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 {
// Use cache.sizes em vez de medir novamente
}
}
Valores de Layout
// Defina um valor de layout personalizado
struct Rank: LayoutValueKey {
static let defaultValue: Int = 0
}
extension View {
func rank(_ value: Int) -> some View {
layoutValue(key: Rank.self, value: value)
}
}
// Leitura no layout
func placeSubviews(...) {
let sorted = subviews.sorted { $0[Rank.self] < $1[Rank.self] }
}
onGeometryChange
Leitura eficiente de geometria sem efeitos colaterais de layout. Retroportado para 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
}
}
Leituras de Valores Específicos
// Apenas largura
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.size.width
} action: { width in
columnCount = max(1, Int(width / 150))
}
// Frame no espaço de coordenadas
.onGeometryChange(for: CGRect.self) { proxy in
proxy.frame(in: .global)
} action: { frame in
globalFrame = frame
}
// Proporção de aspecto
.onGeometryChange(for: Bool.self) { proxy in
proxy.size.width > proxy.size.height
} action: { isWide in
self.isWide = isWide
}
Espaços de Coordenadas
// Espaço de coordenadas nomeado
ScrollView {
content
.onGeometryChange(for: CGFloat.self) { proxy in
proxy.frame(in: .named("scroll")).minY
} action: { offset in
scrollOffset = offset
}
}
.coordinateSpace(name: "scroll")
Comparação com GeometryReader
| Aspecto | onGeometryChange | GeometryReader |
|---|---|---|
| Impacto no layout | Nenhum | Ganancioso (preenche o espaço) |
| Quando avaliado | Após o layout | Durante o layout |
| Caso de uso | Efeitos colaterais | Cálculos de layout |
| Versão iOS | 16+ (retroportado) | 13+ |
GeometryReader
Fornece informações de geometria durante a fase de layout. Use com moderação devido ao tamanho ganancioso.
Uso Básico (Restrito)
// ✅ Sempre restrinja 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) // Restrição necessária
Propriedades do GeometryProxy
GeometryReader { proxy in
// Tamanho do contêiner
let size = proxy.size // CGSize
// Insets da área segura
let insets = proxy.safeAreaInsets // EdgeInsets
// Frame no espaço de coordenadas
let globalFrame = proxy.frame(in: .global)
let localFrame = proxy.frame(in: .local)
let namedFrame = proxy.frame(in: .named("container"))
}
Padrões Comuns
// Dimensionamento proporcional
GeometryReader { geo in
VStack {
header.frame(height: geo.size.height * 0.2)
content.frame(height: geo.size.height * 0.8)
}
}
// Centralização com deslocamento
GeometryReader { geo in
content
.position(x: geo.size.width / 2, y: geo.size.height / 2)
}
Evitando Erros Comuns
// ❌ Sem restrição em VStack
VStack {
GeometryReader { ... } // Ocupa TODO o espaço
Button("Próximo") { } // Invisível
}
// ✅ Restrito
VStack {
GeometryReader { ... }
.frame(height: 200)
Button("Próximo") { }
}
// ❌ Causando loops de layout
GeometryReader { geo in
content
.frame(width: geo.size.width) // Pode causar loop infinito
}
Padding de Área Segura
O SwiftUI oferece duas abordagens principais para lidar com espaçamento ao redor do conteúdo: .padding() e .safeAreaPadding(). Entender quando usar cada uma é crítico para um layout adequado em dispositivos com áreas seguras (notch, Dynamic Island, indicador de início).
A Diferença Crítica
// ❌ ERRADO - Ignora áreas seguras, conteúdo atinge notch/indicador de início
ScrollView {
content
}
.padding(.horizontal, 20)
// ✅ CORRETO - Respeita áreas seguras, adiciona padding além delas
ScrollView {
content
}
.safeAreaPadding(.horizontal, 20)
Insight chave: .padding() adiciona espaçamento fixo a partir das bordas da visualização. .safeAreaPadding() adiciona espaçamento além dos insets da área segura.
Quando Usar Cada Um
Use .padding() quando
- Adicionar espaçamento entre visualizações irmãs dentro de um contêiner
- Criar espaçamento interno que deve ser consistente em todos os lugares
- Trabalhar com visualizações que já respeitam áreas seguras (como List, Form)
- Adicionar espaçamento decorativo no macOS (sem preocupações com área segura)
VStack(spacing: 0) {
header
.padding(.horizontal, 16) // ✅ Espaçamento interno
Divider()
content
.padding(.horizontal, 16) // ✅ Espaçamento interno
}
Use .safeAreaPadding() quando (iOS 17+)
- Adicionar margem a conteúdo de largura total que se estende até as bordas da tela
- Implementar rolagem de ponta a ponta com insets adequados
- Criar contêineres personalizados que precisam de conhecimento da área segura
- Trabalhar com Liquid Glass ou materiais de tela cheia
// ✅ Lista de ponta a ponta com padding personalizado
List(items) { item in
ItemRow(item)
}
.listStyle(.plain)
.safeAreaPadding(.horizontal, 20) // Adiciona 20pt além das áreas seguras
// ✅ Conteúdo de tela cheia com margens adequadas
ZStack {
Color.blue.ignoresSafeArea()
VStack {
content
}
.safeAreaPadding(.all, 16) // Respeita notch, indicador de início
}
Disponibilidade da Plataforma
iOS 17+, iPadOS 17+, macOS 14+, axiom-visionOS 1.0+
Para versões anteriores do iOS, use o tratamento manual da área segura:
// Fallback iOS 13-16
GeometryReader { geo in
content
.padding(.horizontal, 20 + geo.safeAreaInsets.leading)
}
Ou compilação condicional:
if #available(iOS 17, *) {
content.safeAreaPadding(.horizontal, 20)
} else {
content.padding(.horizontal, 20)
.padding(.leading, safeAreaInsets.leading)
}
Uso Específico por Borda
// Apenas topo (abaixo da barra de status/notch)
.safeAreaPadding(.top, 8)
// Apenas inferior (acima do indicador de início)
.safeAreaPadding(.bottom, 16)
// Horizontal (esquerda/direita das áreas seguras)
.safeAreaPadding(.horizontal, 20)
// Todas as bordas
.safeAreaPadding(.all, 16)
// Bordas individuais
.safeAreaPadding(EdgeInsets(top: 8, leading: 20, bottom: 16, trailing: 20))
Padrões Comuns
ScrollView de Ponta a Ponta
ScrollView {
LazyVStack(spacing: 12) {
ForEach(items) { item in
ItemCard(item)
}
}
}
.safeAreaPadding(.horizontal, 16) // Inseto de conteúdo das bordas + áreas seguras
.safeAreaPadding(.vertical, 8)
Fundo de Tela Cheia com Conteúdo Seguro
ZStack {
// Fundo se estende de ponta a ponta
LinearGradient(...)
.ignoresSafeArea()
// Conteúdo respeita áreas seguras + padding personalizado
VStack {
header
Spacer()
content
Spacer()
footer
}
.safeAreaPadding(.all, 20)
}
Padding Aninhado (Abordagem Combinada)
// Externo: Padding de área segura para insets do dispositivo
VStack(spacing: 0) {
content
}
.safeAreaPadding(.horizontal, 16) // Além das áreas seguras
// Interno: Padding regular para espaçamento interno
VStack {
Text("Título")
.padding(.bottom, 8) // Espaçamento interno
Text("Subtítulo")
}
Árvore de Decisão
Seu conteúdo se estende até as bordas da tela?
├─ SIM → Use .safeAreaPadding()
│ ├─ É rolável? → .safeAreaPadding(.horizontal/.vertical)
│ └─ É tela cheia? → .safeAreaPadding(.all)
│
└─ NÃO (contido em um contêiner seguro como List/Form)
└─ Use .padding() para espaçamento interno
Depuração Visual
// Visualize o padding da área segura (iOS 17+)
content
.safeAreaPadding(.horizontal, 20)
.background(.red.opacity(0.2)) // Mostra a área de padding
.border(.blue) // Mostra os limites do conteúdo
Migração do Tratamento Manual de Área Segura
// ❌ ANTIGO: 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)
}
// ✅ NOVO: .safeAreaPadding() (iOS 17+)
content
.safeAreaPadding(.vertical, 16)
.safeAreaPadding(.horizontal, 20)
APIs Relacionadas
.safeAreaInset(edge:) - Adiciona conteúdo persistente que reduz a área segura:
ScrollView {
content
}
.safeAreaInset(edge: .bottom) {
// Isso REDUZ a área segura, o conteúdo rola sob ele
toolbarButtons
.padding()
.background(.ultraThinMaterial)
}
.ignoresSafeArea() - Opta por sair completamente da área segura:
Color.blue
.ignoresSafeArea() // Estende-se até as bordas absolutas da tela
Por Que Isso Importa
Antes do iOS 17: Os desenvolvedores precisavam calcular manualmente os insets da área segura com GeometryReader, levando a:
- Código verboso
- Sobrecarga de desempenho (GeometryReader força uma passagem extra de layout)
- Erros fáceis (esquecer de verificar todas as bordas)
iOS 17+: .safeAreaPadding() fornece:
- API declarativa (combina com a filosofia do SwiftUI)
- Consciência automática da área segura
- Melhor desempenho (sem passagens extras de layout)
- Especificação de borda type-safe
Impacto no mundo real
... [truncado para tradução]
Classes de Tamanho
Adaptação baseada em características para diferentes tamanhos de tela e orientações.
Uso Básico
struct AdaptiveView: View {
@Environment(\.horizontalSizeClass) var horizontalSizeClass
@Environment(\.verticalSizeClass) var verticalSizeClass
var body: some View {
switch (horizontalSizeClass, verticalSizeClass) {
case (.compact, .regular):
iPhonePortraitLayout()
case (.regular, .compact):
iPhoneLandscapeLayout()
case (.regular, .regular):
iPadLayout()
default:
fallbackLayout()
}
}
}
Combinações Comuns
| horizontalSizeClass | verticalSizeClass | Uso Típico |
|---|---|---|
| .compact | .regular | iPhone em retrato |
| .compact | .compact | iPhone em paisagem (modelos menores) |
| .regular | .compact | iPhone Plus/Max em paisagem |
| .regular | .regular | iPad, iPhone Plus/Max em paisagem dividida |
Exemplo: Layout Responsivo com Grade
struct ResponsiveGrid: View {
@Environment(\.horizontalSizeClass) var horizontalSizeClass
var columns: [GridItem] {
horizontalSizeClass == .compact
? [GridItem(.flexible()), GridItem(.flexible())]
: [GridItem(.flexible()), GridItem(.flexible()), GridItem(.flexible())]
}
var body: some View {
ScrollView {
LazyVGrid(columns: columns, spacing: 16) {
ForEach(items) { item in
ItemView(item: item)
}
}
.padding()
}
}
}
Limitações
horizontalSizeClasspode ser.regulartanto para iPad como para iPhone em paisagem- Use com outras técnicas (AnyLayout, ViewThatFits) para adaptação mais precisa
- Não reflete o tamanho real da janela em multitarefa (iPadOS)
APIs de Janela do iOS 26
APIs modernas de gerenciamento de janelas introduzidas no iOS 26 para suporte a janelas de forma livre, barra de menus e âncoras de redimensionamento.
Abertura de Janela Livre
struct ContentView: View {
@Environment(\.openWindow) private var openWindow
var body: some View {
Button("Abrir como Janela Livre") {
openWindow(id: "freeform-window")
}
}
}
Configuração de Cena
@main
struct MyApp: App {
var body: some Scene {
WindowGroup {
ContentView()
}
.windowStyle(.freeform) // Janela de forma livre
.windowResizability(.contentSize) // Redimensionar para tamanho do conteúdo
Window(id: "panel") {
PanelView()
}
.windowStyle(.plain) // Sem decorações
.defaultPosition(.center)
}
}
Âncoras de Redimensionamento
struct ResizablePanel: View {
var body: some View {
VStack {
content
}
.frame(minWidth: 200, idealWidth: 300, maxWidth: 600,
minHeight: 150, idealHeight: 200, maxHeight: 500)
.windowResizeAnchor(.bottomTrailing) // Âncora de redimensionamento
}
}
Integração com Barra de Menus (macOS)
#if os(macOS)
struct MenuBarApp: App {
var body: some Scene {
MenuBarExtra("App Utilitário") {
MenuBarView()
}
.menuBarExtraStyle(.window)
}
}
#endif
Gerenciamento de Múltiplas Janelas
struct DocumentApp: App {
var body: some Scene {
DocumentGroup(newDocument: MyDocument()) { file in
DocumentView(document: file.$document)
}
.windowResizability(.contentMinSize)
WindowGroup("Inspetor", id: "inspector") {
InspectorView()
}
.defaultPosition(.trailing)
.windowStyle(.plain)
MenuBarExtra("Opções") {
SettingsView()
}
}
}
Guia de Referência Rápida
| API | Versão Mínima | Objetivo | Efeito Colateral de Layout |
|---|---|---|---|
| ViewThatFits | iOS 16+ | Seleção automática de variantes | Não* |
| AnyLayout | iOS 16+ | Troca animada de layout | Não |
| Protocolo Layout | iOS 16+ | Layout personalizado | Sim (seu código) |
| onGeometryChange | iOS 16+ | Leitura eficiente de geometria | Não |
| GeometryReader | iOS 13+ | Acesso à geometria | Sim (ganancioso)** |
| .safeAreaPadding() | iOS 17+ | Padding além da área segura | Não |
| .padding() | iOS 13+ | Espaçamento fixo | Não |
| Size Classes | iOS 13+ | Adaptação baseada em características | Não |
| iOS 26 Window APIs | iOS 26+ | Gerenciamento de janelas | Sim |
*ViewThatFits mede todas as variantes, mas não altera o layout por conta própria **GeometryReader sempre preenche o espaço disponível a menos que restrito
Notas do Skill
- Consulte
axiom-swiftui-layoutpara orientação sobre decisões e anti-padrões - Salve este arquivo com uma extensão
.mdcpara formatação automática no Cursor - Para contribuir ou relatar problemas, visite: https://github.com/DavidAlphonse/awesome-swiftui-layout
- Licenciado sob MIT