Patrones de UI SwiftUI
Inicio rápido
Elige un camino según tu objetivo:
Proyecto existente
- Identifica la funcionalidad o pantalla y el modelo de interacción principal (lista, detalle, editor, configuración, con pestañas).
- Busca un ejemplo cercano en el repositorio con
rg "TabView\("o similar, luego lee la vista SwiftUI más cercana. - Aplica las convenciones locales: prefiere estado nativo de SwiftUI, mantén el estado local cuando sea posible y utiliza inyección de entorno para dependencias compartidas.
- Elige la referencia de componente relevante de
references/components-index.mdy sigue su guía. - Construye la vista con subvistas pequeñas y enfocadas y flujo de datos nativo de SwiftUI.
Andamiaje de nuevo proyecto
- Comienza con
references/app-scaffolding-wiring.mdpara cablear TabView + NavigationStack + hojas. - Agrega un
AppTabyRouterPathmínimos basados en los esqueletos proporcionados. - Elige la siguiente referencia de componente según la UI que necesites primero (TabView, NavigationStack, hojas).
- Expande los enums de ruta y hoja a medida que se agreguen nuevas pantallas.
Reglas generales a seguir
- Usa estado moderno de SwiftUI (
@State,@Binding,@Observable,@Environment) y evita modelos de vista innecesarios. - Prefiere la composición; mantén las vistas pequeñas y enfocadas.
- Usa async/await con
.tasky estados explícitos de carga/error. - Mantén los patrones heredados existentes solo cuando edites archivos heredados.
- Sigue el formateador y la guía de estilo del proyecto.
- Hojas: Prefiere
.sheet(item:)sobre.sheet(isPresented:)cuando el estado represente un modelo seleccionado. Evitaif letdentro del cuerpo de una hoja. Las hojas deben ser dueñas de sus acciones y llamar adismiss()internamente en lugar de reenviar closuresonCancel/onConfirm.
Flujo de trabajo para una nueva vista SwiftUI
- Define el estado de la vista y su ubicación de propiedad.
- Identifica las dependencias a inyectar mediante
@Environment. - Esboza la jerarquía de la vista y extrae las partes repetidas en subvistas.
- Implementa la carga asíncrona con
.tasky un enum de estado explícito si es necesario. - Agrega etiquetas o identificadores de accesibilidad cuando la UI sea interactiva.
- Valida con una compilación y actualiza los puntos de uso si es necesario.
Referencias de componentes
Usa references/components-index.md como punto de entrada. Cada referencia de componente debe incluir:
- Intención y escenarios de mejor ajuste.
- Patrón de uso mínimo con convenciones locales.
- Errores comunes y notas de rendimiento.
- Rutas a ejemplos existentes en el repositorio actual.
Patrones de hojas
Hoja basada en ítem (preferida)
@State private var selectedItem: Item?
.sheet(item: $selectedItem) { item in
EditItemSheet(item: item)
}
La hoja es dueña de sus acciones
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 ? "Guardando…" : "Guardar") {
Task { await save() }
}
}
}
private func save() async {
isSaving = true
await store.save(item)
dismiss()
}
}
Agregar una nueva referencia de componente
- Crea
references/<componente>.md. - Mantenlo corto y accionable; enlaza a archivos concretos en el repositorio actual.
- Actualiza
references/components-index.mdcon la nueva entrada.