Referência de Containers do SwiftUI
Stacks, grades, outlines e melhorias de scroll. iOS 14 até iOS 26.
Fontes: WWDC 2020-10031, 2022-10056, 2023-10148, 2024-10144, 2025-256
Decisão Rápida
| Caso de Uso | Container | iOS |
|---|---|---|
| Visualizações fixas verticais/horizontais | VStack / HStack | 13+ |
| Visualizações sobrepostas | ZStack | 13+ |
| Lista grande com scroll | LazyVStack / LazyHStack | 14+ |
| Grade de várias colunas | LazyVGrid | 14+ |
| Grade de várias linhas (horizontal) | LazyHGrid | 14+ |
| Grade estática, alinhamento preciso | Grid | 16+ |
| Dados hierárquicos (árvore) | List com children: | 14+ |
| Hierarquias personalizadas | OutlineGroup | 14+ |
| Mostrar/ocultar conteúdo | DisclosureGroup | 14+ |
Parte 1: Stacks
VStack, HStack, ZStack
VStack(alignment: .leading, spacing: 12) {
Text("Título")
Text("Subtítulo")
}
HStack(alignment: .top, spacing: 8) {
Image(systemName: "star")
Text("Avaliação")
}
ZStack(alignment: .bottomTrailing) {
Image("foto")
Badge()
}
Alinhamentos do ZStack: .center (padrão), .top, .bottom, .leading, .trailing, .topLeading, .topTrailing, .bottomLeading, .bottomTrailing
Spacer
HStack {
Text("Esquerda")
Spacer()
Text("Direita")
}
Spacer(minLength: 20) // Tamanho mínimo
LazyVStack, LazyHStack (iOS 14+)
Renderiza os filhos apenas quando visíveis. Use dentro de ScrollView.
ScrollView {
LazyVStack(spacing: 0) {
ForEach(itens) { item in
LinhaItem(item: item)
}
}
}
Cabeçalhos de Seção Fixos
ScrollView {
LazyVStack(pinnedViews: [.sectionHeaders]) {
ForEach(secoes) { secao in
Section(header: CabecalhoSecao(secao)) {
ForEach(secao.itens) { item in
LinhaItem(item: item)
}
}
}
}
}
Parte 2: Grades
Grid (iOS 16+)
Grade não-lazy com alinhamento preciso. Carrega todas as visualizações de uma vez.
Grid(alignment: .leading, horizontalSpacing: 10, verticalSpacing: 10) {
GridRow {
Text("Nome")
TextField("Digite o nome", text: $nome)
}
GridRow {
Text("Email")
TextField("Digite o email", text: $email)
}
}
Modificadores:
gridCellColumns(_:)— Expandir por várias colunasgridColumnAlignment(_:)— Sobrescrever alinhamento da coluna
Grid {
GridRow {
Text("Cabeçalho").gridCellColumns(2)
}
GridRow {
Text("Esquerda")
Text("Direita").gridColumnAlignment(.trailing)
}
}
LazyVGrid (iOS 14+)
Grade de rolagem vertical. Defina colunas; as linhas crescem sem limite.
let colunas = [
GridItem(.flexible()),
GridItem(.flexible()),
GridItem(.flexible())
]
ScrollView {
LazyVGrid(columns: colunas, spacing: 16) {
ForEach(itens) { item in
CartaoItem(item: item)
}
}
}
LazyHGrid (iOS 14+)
Grade de rolagem horizontal. Defina linhas; as colunas crescem sem limite.
let linhas = [GridItem(.fixed(100)), GridItem(.fixed(100))]
ScrollView(.horizontal) {
LazyHGrid(rows: linhas, spacing: 16) {
ForEach(itens) { item in
CartaoItem(item: item)
}
}
}
GridItem.Size
| Tamanho | Comportamento |
|---|---|
.fixed(CGFloat) | Largura/altura exata |
.flexible(minimum:maximum:)) | Preenche o espaço igualmente |
.adaptive(minimum:maximum:)) | Cria quantas couberem |
// Adaptativo: número de colunas responsivo
let colunas = [GridItem(.adaptive(minimum: 150))]
Parte 3: Outlines
List com Dados Hierárquicos (iOS 14+)
struct ItemArquivo: Identifiable {
let id = UUID()
var nome: String
var filhos: [ItemArquivo]? // nil = folha
}
List(arquivos, children: \.filhos) { arquivo in
Label(arquivo.nome, systemImage: arquivo.filhos != nil ? "folder" : "doc")
}
.listStyle(.sidebar)
OutlineGroup (iOS 14+)
Para layouts hierárquicos personalizados fora de List.
List {
ForEach(telas) { tela in
Section(header: Text(tela.nome)) {
OutlineGroup(tela.graficos, children: \.filhos) { grafico in
LinhaGrafico(grafico: grafico)
}
}
}
}
DisclosureGroup (iOS 14+)
@State private var estaExpandido = false
DisclosureGroup("Opções Avançadas", isExpanded: $estaExpandido) {
Toggle("Ativar Funcionalidade", isOn: $funcionalidade)
Slider(value: $intensidade)
}
Parte 4: Padrões Comuns
Grade de Fotos
let colunas = [GridItem(.adaptive(minimum: 100), spacing: 2)]
ScrollView {
LazyVGrid(columns: colunas, spacing: 2) {
ForEach(fotos) { foto in
AsyncImage(url: foto.thumbnailURL) { imagem in
imagem.resizable().aspectRatio(1, contentMode: .fill)
} placeholder: { Color.gray }
.aspectRatio(1, contentMode: .fill)
.clipped()
}
}
}
Carrossel Horizontal
ScrollView(.horizontal, showsIndicators: false) {
LazyHStack(spacing: 16) {
ForEach(itens) { item in
CartaoCarrossel(item: item).frame(width: 280)
}
}
.padding(.horizontal)
}
Navegador de Arquivos
List(selection: $selecao) {
OutlineGroup(itensRaiz, children: \.filhos) { item in
Label {
Text(item.nome)
} icon: {
Image(systemName: item.filhos != nil ? "folder.fill" : "doc.fill")
}
}
}
.listStyle(.sidebar)
Parte 5: Performance
Quando Usar Lazy
| Tamanho | Rolável? | Use |
|---|---|---|
| 1-20 | Não | VStack/HStack |
| 1-20 | Sim | VStack/HStack em ScrollView |
| 20-100 | Sim | LazyVStack/LazyHStack |
| 100+ | Sim | LazyVStack/LazyHStack ou List |
| Grade <50 | Não | Grid |
| Grade 50+ | Sim | LazyVGrid/LazyHGrid |
Armazene arrays de GridItem em cache — defina fora do body:
struct ContentView: View {
let colunas = [GridItem(.adaptive(minimum: 150))] // ✅
var body: some View {
LazyVGrid(columns: colunas) { ... }
}
}
Performance iOS 26
- Carregamento de lista 6x mais rápido para 100k+ itens
- Atualizações de lista 16x mais rápidas
- Quadros perdidos reduzidos em rolagem
- ScrollViews aninhados com lazy stacks agora adiam o carregamento corretamente:
ScrollView(.horizontal) {
LazyHStack {
ForEach(conjuntosFotos) { conjunto in
ScrollView(.vertical) {
LazyVStack {
ForEach(conjunto.fotos) { FotoView(foto: $0) }
}
}
}
}
}
Parte 6: Melhorias de Scroll
containerRelativeFrame (iOS 17+)
Dimensiona visualizações relativas ao container de scroll.
ScrollView(.horizontal) {
LazyHStack {
ForEach(cartoes) { cartao in
CartaoView(cartao: cartao)
.containerRelativeFrame(.horizontal, count: 3, span: 1, spacing: 16)
}
}
}
scrollTargetLayout (iOS 17+)
Habilita snapping.
ScrollView(.horizontal) {
LazyHStack {
ForEach(itens) { CartaoItem(item: $0) }
}
.scrollTargetLayout()
}
.scrollTargetBehavior(.viewAligned)
scrollPosition (iOS 17+)
Rastreia o item visível no topo. Requer .id() em cada item.
@State private var posicao: Item.ID?
ScrollView {
LazyVStack {
ForEach(itens) { item in
LinhaItem(item: item).id(item.id)
}
}
}
.scrollPosition(id: $posicao)
scrollTransition (iOS 17+)
.scrollTransition { conteudo, fase in
conteudo
.opacity(1 - abs(fase.value) * 0.5)
.scaleEffect(fase.identity ? 1.0 : 0.75)
}
onScrollGeometryChange (iOS 18+)
.onScrollGeometryChange(for: Bool.self) { geo in
geo.contentOffset.y < geo.contentInsets.top
} action: { _, isTop in
mostrarBotaoVoltar = !isTop
}
onScrollVisibilityChange (iOS 18+)
VideoPlayer(player: jogador)
.onScrollVisibilityChange(threshold: 0.2) { visivel in
visivel ? jogador.play() : jogador.pause()
}
Recursos
WWDC: 2020-10031, 2022-10056, 2023-10148, 2024-10144, 2025-256
Docs: /swiftui/lazyvstack, /swiftui/lazyvgrid, /swiftui/lazyhgrid, /swiftui/grid, /swiftui/outlinegroup, /swiftui/disclosuregroup
Skills: axiom-swiftui-layout, axiom-swiftui-layout-ref, axiom-swiftui-nav, axiom-swiftui-26-ref