SwiftUI: Layout Adaptável
Visão Geral
Skill disciplinar para construir layouts que respondem ao espaço disponível, em vez de suposições sobre o dispositivo. Abrange seleção de ferramentas, limitações de classes de tamanho, janelas de formato livre do iOS 26 e antipadrões comuns.
Princípio central: Seu layout deve funcionar corretamente se a Apple lançar um novo dispositivo amanhã, ou se o iPadOS adicionar um novo modo de multitarefa no próximo ano. Responda ao seu contêiner, não às suas suposições sobre o dispositivo.
Quando Usar Esta Skill
- "Como faço este layout funcionar no iPad e no iPhone?"
- "Devo usar GeometryReader ou ViewThatFits?"
- "Meu layout quebra no Split View / Stage Manager"
- "As classes de tamanho não estão me dando o que preciso"
- "O designer quer um layout diferente para retrato vs paisagem"
- "Preparando o aplicativo para o redimensionamento de janelas do iOS 26"
Árvore de Decisão
"Preciso que meu layout se adapte..."
│
├─ AO ESPAÇO DISPONÍVEL (orientado pelo contêiner)
│ │
│ ├─ "Escolher a melhor variante"
│ │ → ViewThatFits
│ │
│ ├─ "Alternar animadamente entre H↔V"
│ │ → AnyLayout + condição
│ │
│ ├─ "Ler o tamanho para cálculos"
│ │ → onGeometryChange (iOS 16+)
│ │
│ └─ "Algoritmo de layout personalizado"
│ → Protocolo Layout
│
├─ A CARACTERÍSTICAS DA PLATAFORMA
│ │
│ ├─ "Largura Compacta vs Regular"
│ │ → horizontalSizeClass (⚠️ limitações do iPad)
│ │
│ ├─ "Tamanho do texto de acessibilidade"
│ │ → dynamicTypeSize.isAccessibilitySize
│ │
│ └─ "Diferenças de plataforma"
│ → #if os() / Environment
│
└─ AO FORMATO DA JANELA (proporção)
│
├─ "Semântica de Retrato vs Paisagem"
│ → Geometry + limite personalizado
│
├─ "Mostrar/esconder colunas automaticamente"
│ → NavigationSplitView (automático no iOS 26)
│
└─ "Ciclo de vida da janela"
→ @Environment(\.scenePhase)
Seleção de Ferramentas
Decisão Rápida
Você precisa de um valor calculado (largura, altura)?
├─ SIM → onGeometryChange
└─ NÃO → Você precisa de transições animadas?
├─ SIM → AnyLayout + condição
└─ NÃO → ViewThatFits
Quando Usar Cada Ferramenta
| Preciso... | Use isto | Não use isto |
|---|---|---|
| Escolher entre 2-3 variantes de layout | ViewThatFits | if size > X |
| Alternar H↔V com animação | AnyLayout | HStack/VStack condicional |
| Ler o tamanho do contêiner | onGeometryChange | GeometryReader |
| Adaptar ao texto de acessibilidade | dynamicTypeSize | Pontos de interrupção fixos |
| Detectar largura compacta | horizontalSizeClass | UIDevice.idiom |
| Detectar janela estreita no iPad | Geometry + limite | Apenas classe de tamanho |
| Mostrar/esconder barra lateral | NavigationSplitView | Lógica manual de coluna |
| Algoritmo de layout personalizado | Protocolo Layout | GeometryReaders aninhados |
Padrão 1: ViewThatFits
Use quando: Você tem 2-3 variantes de layout e quer que o SwiftUI escolha a primeira que couber.
ViewThatFits {
// Primeira opção: horizontal
HStack {
Image(systemName: "star")
Text("Favorito")
Spacer()
Button("Adicionar") { }
}
// Alternativa: vertical
VStack {
HStack {
Image(systemName: "star")
Text("Favorito")
}
Button("Adicionar") { }
}
}
Limitação: ViewThatFits não expõe qual variante foi escolhida. Se você precisar desse estado para outras visualizações, use AnyLayout.
Padrão 2: AnyLayout para Alternância Animada
Use quando: Você precisa de transições animadas entre layouts, ou precisa saber o estado atual do layout.
struct AdaptiveStack<Content: View>: View {
@Environment(\.horizontalSizeClass) var sizeClass
let content: Content
var layout: AnyLayout {
sizeClass == .compact
? AnyLayout(VStackLayout(spacing: 12))
: AnyLayout(HStackLayout(spacing: 20))
}
var body: some View {
layout {
content
}
.animation(.default, value: sizeClass)
}
}
Para Dynamic Type:
@Environment(\.dynamicTypeSize) var dynamicTypeSize
var layout: AnyLayout {
dynamicTypeSize.isAccessibilitySize
? AnyLayout(VStackLayout())
: AnyLayout(HStackLayout())
}
Padrão 3: onGeometryChange (Preferido para Geometria)
Use quando: Você precisa de dimensões reais para cálculos. Preferido em relação ao GeometryReader.
struct ResponsiveGrid: View {
@State private var columnCount = 2
var body: some View {
LazyVGrid(columns: Array(repeating: GridItem(.flexible()), count: columnCount)) {
ForEach(items) { item in
ItemView(item: item)
}
}
.onGeometryChange(for: Int.self) { proxy in
max(1, Int(proxy.size.width / 150))
} action: { newCount in
columnCount = newCount
}
}
}
Para detecção de proporção ("orientação" do iPad):
struct WindowShapeReader: View {
@State private var isWide = true
var body: some View {
content
.onGeometryChange(for: Bool.self) { proxy in
proxy.size.width > proxy.size.height * 1.2
} action: { newValue in
isWide = newValue
}
}
}
Padrão 4: GeometryReader (Quando Necessário)
Use quando: Você precisa de geometria E está no iOS 15 ou anterior, OU precisa de geometria durante a fase de layout (não apenas como efeito colateral).
// ✅ CORRETO: GeometryReader com restrição
VStack {
GeometryReader { geo in
Text("Largura: \(geo.size.width)")
}
.frame(height: 44) // DEVE restringir!
Button("Próximo") { }
}
// ❌ ERRADO: Sem restrição (ganancioso)
VStack {
GeometryReader { geo in
Text("Largura: \(geo.size.width)")
}
// Pega todo o espaço disponível, esmaga os irmãos
Button("Próximo") { }
}
Tabela Verdade das Classes de Tamanho (iPad)
| Configuração | Horizontal | Vertical |
|---|---|---|
| Tela cheia retrato | .regular | .regular |
| Tela cheia paisagem | .regular | .regular |
| Split View 70% | .regular | .regular |
| Split View 50% | .regular | .regular |
| Split View 33% | .compact | .regular |
| Slide Over | .compact | .regular |
| Com teclado | (inalterado) | (inalterado) |
Ponto chave: A classe de tamanho só fica .compact no iPad com ~33% de largura ou Slide Over. Para controle mais preciso, use geometria.
Janelas de Formato Livre do iOS 26
O Que Mudou
| Antes do iOS 26 | iOS 26+ |
|---|---|
| Tamanhos fixos do Split View | Redimensionar arrastando (formato livre) |
UIRequiresFullScreen permitido | Obsoleto |
| Sem barra de menus no iPad | Barra de menus via .commands |
| Visibilidade manual de colunas | NavigationSplitView adapta-se automaticamente |
Diretriz da Apple
"Redimensionar um aplicativo não deve alterar seu layout permanentemente. Seja oportunista ao reverter para o estado inicial sempre que possível."
Tradução: Não salve o estado do layout com base no tamanho da janela. Quando a janela retornar ao tamanho original, o layout também deve retornar.
Adaptação Automática do NavigationSplitView
// iOS 26: As colunas mostram/escondem automaticamente
NavigationSplitView {
Sidebar()
} content: {
ContentList()
} detail: {
DetailView()
}
// Nenhum gerenciamento manual de columnVisibility necessário
Checklist de Migração
- Remover
UIRequiresFullScreendo Info.plist - Testar em tamanhos de janela arbitrários (não apenas 33/50/66%)
- Verificar se o layout não "gruda" após o redimensionamento
- Adicionar comandos de barra de menus para ações comuns
- Testar se os controles da janela não se sobrepõem aos itens da barra de ferramentas
Antipadrões
❌ Observador de Orientação do Dispositivo
// ❌ ERRADO: Relata o dispositivo, não a janela
NotificationCenter.default.addObserver(
forName: UIDevice.orientationDidChangeNotification, ...
)
let orientation = UIDevice.current.orientation
if orientation.isLandscape { ... }
Por que falha: Relata a orientação física do dispositivo, não o formato da janela. Errado no Split View, Stage Manager, iOS 26.
Correção: Use onGeometryChange para ler as dimensões reais da janela.
❌ Limites da Tela (Screen Bounds)
// ❌ ERRADO: Retorna a tela inteira, não sua janela
let width = UIScreen.main.bounds.width
if width > 700 { useWideLayout() }
Por que falha: Na multitarefa, seu aplicativo pode ter apenas 40% da tela.
Correção: Leia o tamanho real do contêiner da sua view.
❌ Verificações de Modelo do Dispositivo
// ❌ ERRADO: Quebra em novos dispositivos, errado na multitarefa
if UIDevice.current.userInterfaceIdiom == .pad {
useWideLayout()
}
Por que falha: Um iPad em Split View 1/3 é mais estreito que um iPhone 14 Pro Max em paisagem.
Correção: Responda ao espaço disponível, não à identidade do dispositivo.
❌ GeometryReader Sem Restrição
// ❌ ERRADO: GeometryReader é ganancioso
VStack {
GeometryReader { geo in
Text("Tamanho: \(geo.size)")
}
Button("Próximo") { } // Esmagado
}
Correção: Restrinja com .frame() ou use onGeometryChange.
❌ Classe de Tamanho como Proxy de Orientação
// ❌ ERRADO: iPad é .regular em ambas as orientações
var isLandscape: Bool {
horizontalSizeClass == .regular // Sempre verdadeiro no iPad!
}
Correção: Calcule a partir da geometria real se você precisar da proporção.
Cenários de Pressão
"O designer quer um layout específico para iPhone"
Tentação: if UIDevice.current.userInterfaceIdiom == .phone
Resposta: "Implementarei estes como layouts 'compacto' e 'regular' que alternam com base no espaço disponível. O layout do iPhone aparecerá no iPad quando a janela for estreita. Isso nos protege para o futuro com Stage Manager e iOS 26."
"Só usa GeometryReader, está tudo bem"
Tentação: Envolver tudo em GeometryReader.
Resposta: "GeometryReader tem efeitos colaterais de layout conhecidos — ele se expande gananciosamente. onGeometryChange lê os mesmos dados sem afetar o layout. Ele é retroportado para o iOS 16."
"As classes de tamanho funcionavam antes"
Tentação: Forçar tudo através da classe de tamanho.
Resposta: "As classes de tamanho são grosseiras. O iPad é .regular em ambas as orientações. Usarei a classe de tamanho para categorias amplas e geometria para limites precisos."
"Não suportamos multitarefa no iPad"
Tentação: UIRequiresFullScreen = true
Resposta: "A Apple tornou o modo tela cheia obsoleto no iOS 26. Mesmo sem suporte ativo ao Split View, o aplicativo não pode quebrar quando redimensionado. Um layout baseado em espaço custa o mesmo."
Recursos
WWDC: 2025-208, 2024-10074, 2022-10056
Skills: axiom-swiftui-layout-ref, axiom-swiftui-debugging, axiom-liquid-glass