Padrões de UI SwiftUI
Início rápido
Escolha uma trilha com base no seu objetivo:
Projeto existente
- Identifique a funcionalidade ou tela e o modelo de interação principal (lista, detalhe, editor, configurações, abas).
- Encontre um exemplo próximo no repositório com
rg "TabView\("ou similar, e leia a visualização SwiftUI mais próxima. - Aplique as convenções locais: prefira estado nativo SwiftUI, mantenha estado local quando possível e use injeção de ambiente para dependências compartilhadas.
- Escolha a referência de componente relevante em
references/components-index.mde siga suas orientações. - Construa a visualização com subvisualizações pequenas e focadas e fluxo de dados nativo SwiftUI.
Scaffolding de novo projeto
- Comece com
references/app-scaffolding-wiring.mdpara conectar TabView + NavigationStack + sheets. - Adicione um mínimo
AppTabeRouterPathbaseado nos esqueletos fornecidos. - Escolha a próxima referência de componente baseada na UI que você precisa primeiro (TabView, NavigationStack, Sheets).
- Expanda os enums de rota e sheet conforme novas telas são adicionadas.
Regras gerais a seguir
- Use estado SwiftUI moderno (
@State,@Binding,@Observable,@Environment) e evite modelos de visualização desnecessários. - Prefira composição; mantenha visualizações pequenas e focadas.
- Use async/await com
.taske estados explícitos de carregamento e erro. - Mantenha padrões legados existentes apenas ao editar arquivos legados.
- Siga o formatador e guia de estilo do projeto.
- Sheets: Prefira
.sheet(item:)em vez de.sheet(isPresented:)quando o estado representa um modelo selecionado. Eviteif letdentro do corpo de um sheet. Sheets devem possuir suas próprias ações e chamardismiss()internamente ao invés de encaminhar closuresonCancel/onConfirm.
Fluxo de trabalho para uma nova visualização SwiftUI
- Defina o estado da visualização e sua localização de propriedade.
- Identifique dependências a serem injetadas via
@Environment. - Esboce a hierarquia da visualização e extraia partes repetidas em subvisualizações.
- Implemente carregamento assíncrono com
.taske enum de estado explícito se necessário. - Adicione rótulos ou identificadores de acessibilidade quando a UI for interativa.
- Valide com uma compilação e atualize pontos de chamada de uso se necessário.
Referências de componentes
Use references/components-index.md como ponto de entrada. Cada referência de componente deve incluir:
- Intenção e cenários de melhor ajuste.
- Padrão mínimo de uso com convenções locais.
- Armadilhas e notas de desempenho.
- Caminhos para exemplos existentes no repositório atual.
Padrões de Sheet
Sheet orientado por item (preferido)
@State private var selectedItem: Item?
.sheet(item: $selectedItem) { item in
EditItemSheet(item: item)
}
Sheet possui suas próprias ações
struct EditItemSheet: View {
@Environment(\.dismiss) private var dismiss
@Environment(Store.self) private var store
let item: Item
@State private var isSaving = false
var body: some View {
VStack {
Button(isSaving ? "Salvando…" : "Salvar") {
Task { await save() }
}
}
}
private func save() async {
isSaving = true
await store.save(item)
dismiss()
}
}
Adicionando uma nova referência de componente
- Crie
references/<componente>.md. - Mantenha breve e acionável; vincule a arquivos concretos no repositório atual.
- Atualize
references/components-index.mdcom a nova entrada.