Padrões de UI do SwiftUI

Início rápido

Quando Usar

• Ao criar ou refatorar telas, fluxos ou componentes de UI reutilizáveis no SwiftUI.
• Quando precisar de orientação sobre navegação, sheets, estado assíncrono, previews ou padrões de componentes.

Escolha um caminho com base no seu objetivo:

Projeto existente

• Identifique o recurso ou tela e o modelo de interação principal (lista, detalhe, editor, configurações, com abas).
• Encontre um exemplo próximo no repositório com rg "TabView\(" ou similar, e então leia a view SwiftUI mais próxima.
• Aplique convenções locais: prefira estado nativo do SwiftUI, mantenha o 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.md e siga suas orientações.
• Se a interação revelar conteúdo secundário arrastando ou rolando o conteúdo principal para fora, leia references/scroll-reveal.md antes de implementar gestos manualmente.
• Construa a view com subviews pequenas e focadas e fluxo de dados nativo do SwiftUI.

Estrutura de novo projeto

• Comece com references/app-wiring.md para conectar TabView + NavigationStack + sheets.
• Adicione um AppTab e RouterPath mínimos com base nos esqueletos fornecidos.
• Escolha a próxima referência de componente com base na UI que você precisa primeiro (TabView, NavigationStack, Sheets).
• Expanda os enums de rota e sheet à medida que novas telas são adicionadas.

Pré-requisitos de exemplo

As referências contêm esboços de aplicativos, não um aplicativo completo. Forneça as views, modelos, adaptadores e tokens de tema nomeados do projeto; verifique as importações, contratos de erro reais e o sistema operacional mínimo com o SDK instalado antes de adaptá-los. Vincule toda ação visível a um manipulador testado real, torne as falhas de persistência observáveis e use dados de preview inertes. Um exemplo de código bem-sucedido não é evidência de uma tela testada ou serviço implantado.

Regras gerais a seguir

• Use estado moderno do SwiftUI (@State, @Binding, @Observable, @Environment) e evite view models desnecessários.
• Se o alvo de implantação incluir iOS 16 ou anterior e não puder usar a API de Observação introduzida no iOS 17, use ObservableObject com @StateObject para propriedade raiz, @ObservedObject para observação injetada e @EnvironmentObject apenas para estado de nível de aplicativo verdadeiramente compartilhado.
• Prefira composição; mantenha as views pequenas e focadas.
• Use async/await com .task e estados explícitos de carregamento/erro. Para orientação sobre reinício, cancelamento e debouncing, leia references/async-state.md.
• Mantenha serviços de aplicativo compartilhados em @Environment, mas prefira injeção explícita de inicializador para dependências e modelos locais de recursos. Para padrões de conexão raiz, leia references/app-wiring.md.
• Prefira a API mais recente do SwiftUI que se encaixe no alvo de implantação e indique o sistema operacional mínimo sempre que um padrão depender dela.
• Mantenha padrões legados existentes apenas ao editar arquivos legados.
• Siga o formatador e o guia de estilo do projeto.
• Sheets: Prefira .sheet(item:) em vez de .sheet(isPresented:) quando o estado representa um modelo selecionado. Evite if let dentro do corpo de um sheet. Sheets devem possuir suas ações e chamar dismiss() internamente em vez de encaminhar closures onCancel/onConfirm.
• Revelações acionadas por scroll: Prefira derivar um valor de progresso normalizado a partir do deslocamento do scroll e controlar o estado visual a partir dessa única fonte de verdade. Evite máquinas de estado de gestos paralelas, a menos que o scroll sozinho não possa expressar a interação.

Resumo de propriedade de estado

Use a ferramenta de estado mais restrita que corresponda ao modelo de propriedade:

Escolha primeiro o local de propriedade, depois selecione o wrapper. Não introduza um modelo de referência quando um estado de valor simples for suficiente.

Referências transversais

• references/navigationstack.md: propriedade de navegação, histórico por aba e roteamento por enum.
• references/sheets.md: apresentação centralizada de modais e sheets controlados por enum.
• references/deeplinks.md: tratamento de URL e roteamento de links externos para destinos do aplicativo.

…