Gestos en SwiftUI
Guía completa para el reconocimiento de gestos en SwiftUI con patrones de composición, gestión de estado e integración de accesibilidad.
Cuándo usar este skill
- Implementar gestos de toque, arrastre, presión larga, magnificación o rotación
- Componer múltiples gestos (simultáneamente, en secuencia, exclusivamente)
- Gestionar el estado de los gestos con GestureState
- Crear reconocedores de gestos personalizados
- Depurar conflictos de gestos o gestos que no responden
- Hacer que los gestos sean accesibles con VoiceOver
- Manejo de gestos multiplataforma (iOS, macOS, visionOS)
Ejemplos de consultas
Estas son preguntas reales que los desarrolladores hacen y que este skill está diseñado para responder:
1. "Mi gesto de arrastre no funciona: la vista no se mueve cuando la arrastro. ¿Cómo lo depuro?"
→ El skill cubre patrones de gestión de estado de DragGesture y muestra cómo actualizar correctamente el desplazamiento de la vista con @GestureState
2. "Tengo un gesto de toque y un gesto de arrastre en la misma vista. El toque funciona, pero el arrastre no. ¿Cómo lo soluciono?"
→ El skill demuestra la composición de gestos con .simultaneously, .sequenced y .exclusively para resolver conflictos entre gestos
3. "Quiero que los usuarios mantengan presionado antes de poder arrastrar un elemento. ¿Cómo encadeno los gestos?"
→ El skill muestra el patrón .sequenced para combinar LongPressGesture con DragGesture en el orden correcto
4. "El estado de mi gesto no se reinicia cuando el gesto termina. La vista se queda en la posición incorrecta."
→ El skill cubre el comportamiento de reinicio automático de @GestureState y el parámetro de actualización para una gestión de estado adecuada
5. "Los usuarios de VoiceOver no pueden acceder a las funciones que requieren gestos. ¿Cómo hago que los gestos sean accesibles?"
→ El skill demuestra patrones de .accessibilityAction y proporciona interacciones alternativas para usuarios de VoiceOver
Elegir el gesto correcto (Árbol de decisión)
¿Qué interacción necesitas?
├─ ¿Un solo toque/clic?
│ └─ Usa Button (recomendado) o TapGesture
│
├─ ¿Movimiento de arrastre/pan?
│ └─ Usa DragGesture
│
├─ ¿Mantener presionado antes de una acción?
│ └─ Usa LongPressGesture
│
├─ ¿Pellizcar para hacer zoom?
│ └─ Usa MagnificationGesture
│
├─ ¿Rotación con dos dedos?
│ └─ Usa RotationGesture
│
├─ ¿Varios gestos juntos?
│ ├─ ¿Ambos al mismo tiempo? → .simultaneously
│ ├─ ¿Uno después del otro? → .sequenced
│ └─ ¿Uno O el otro? → .exclusively
│
└─ ¿Comportamiento personalizado complejo?
└─ Crea un Gesture personalizado que cumpla con el protocolo Gesture
Patrón 1: Reconocimiento básico de gestos
TapGesture
❌ INCORRECTO (Toque personalizado en una vista no semántica)
Text("Enviar")
.onTapGesture {
enviarFormulario()
}
Problemas:
- VoiceOver no lo anuncia como botón
- Sin retroalimentación visual de presión
- No respeta la configuración de accesibilidad
✅ CORRECTO (Usa Button para acciones de toque)
Button("Enviar") {
enviarFormulario()
}
.buttonStyle(.bordered)
Cuándo usar TapGesture: Solo cuando necesites datos del toque (ubicación, número de toques) o un comportamiento de toque no estándar:
Imagen("mapa")
.onTapGesture(count: 2) { // Doble toque para detalles
mostrarDetalles()
}
.onTapGesture { location in // Un toque para fijar
agregarPin(en: location)
}
DragGesture
❌ INCORRECTO (Mutación directa del estado en el gesto)
@State private var desplazamiento = CGSize.zero
var body: some View {
Círculo()
.offset(desplazamiento)
.gesture(
DragGesture()
.onChanged { value in
desplazamiento = value.translation // ❌ Se actualiza cada fotograma, causa tirones
}
)
}
Problemas:
- La vista se actualiza en cada evento de arrastre (60-120 veces por segundo)
- No hay forma de restablecer la posición original
- Se pierde el estado intermedio si el arrastre se cancela
✅ CORRECTO (Usa GestureState para estado temporal)
@GestureState private var desplazamientoArrastre = CGSize.zero
@State private var posicion = CGSize.zero
var body: some View {
Círculo()
.offset(x: posicion.width + desplazamientoArrastre.width,
y: posicion.height + desplazamientoArrastre.height)
.gesture(
DragGesture()
.updating($desplazamientoArrastre) { value, state, _ in
state = value.translation // Temporal durante el arrastre
}
.onEnded { value in
posicion.width += value.translation.width // Confirmar final
posicion.height += value.translation.height
}
)
}
Por qué: GestureState se restablece automáticamente al valor inicial cuando el gesto termina, evitando la corrupción del estado.
LongPressGesture
@GestureState private var detectandoPresionLarga = false
@State private var presionLargaCompletada = false
var body: some View {
Text("Presiona y mantén")
.foregroundStyle(detectandoPresionLarga ? .red : .blue)
.gesture(
LongPressGesture(minimumDuration: 1.0)
.updating($detectandoPresionLarga) { estadoActual, estadoGesture, _ in
estadoGesture = estadoActual // Retroalimentación visual durante la presión
}
.onEnded { _ in
presionLargaCompletada = true // Acción después de mantener
}
)
}
Parámetros clave:
minimumDuration: Cuánto tiempo mantener presionado (por defecto 0.5 segundos)maximumDistance: Cuánto se puede mover el dedo antes de cancelar (por defecto 10 puntos)
MagnificationGesture
@GestureState private var cantidadMagnificacion = 1.0
@State private var zoomActual = 1.0
var body: some View {
Imagen("foto")
.scaleEffect(zoomActual * cantidadMagnificacion)
.gesture(
MagnificationGesture()
.updating($cantidadMagnificacion) { value, state, _ in
state = value.magnification
}
.onEnded { value in
zoomActual *= value.magnification
}
)
}
Notas de la plataforma:
- iOS: Gesto de pellizco con dos dedos
- macOS: Pellizco en el trackpad
- visionOS: Gesto de pellizco en el espacio 3D
RotationGesture
@GestureState private var anguloRotacion = Angle.zero
@State private var rotacionActual = Angle.zero
var body: some View {
Rectángulo()
.fill(.blue)
.frame(width: 200, height: 200)
.rotationEffect(rotacionActual + anguloRotacion)
.gesture(
RotationGesture()
.updating($anguloRotacion) { value, state, _ in
state = value.rotation
}
.onEnded { value in
rotacionActual += value.rotation
}
)
}
Patrón 2: Composición de gestos
Gestos simultáneos
Úsalo cuando: Dos gestos deben funcionar al mismo tiempo
@GestureState private var desplazamientoArrastre = CGSize.zero
@GestureState private var cantidadMagnificacion = 1.0
var body: some View {
Imagen("foto")
.offset(desplazamientoArrastre)
.scaleEffect(cantidadMagnificacion)
.gesture(
DragGesture()
.updating($desplazamientoArrastre) { value, state, _ in
state = value.translation
}
.simultaneously(with:
MagnificationGesture()
.updating($cantidadMagnificacion) { value, state, _ in
state = value.magnification
}
)
)
}
Caso de uso: Visor de fotos donde puedes arrastrar Y hacer zoom con pellizco al mismo tiempo.
Gestos secuenciados
Úsalo cuando: Un gesto debe completarse antes de que comience el siguiente
@State private var presionandoLargo = false
@GestureState private var desplazamientoArrastre = CGSize.zero
var body: some View {
Círculo()
.offset(desplazamientoArrastre)
.gesture(
LongPressGesture(minimumDuration: 0.5)
.onEnded { _ in
presionandoLargo = true
}
.sequenced(before:
DragGesture()
.updating($desplazamientoArrastre) { value, state, _ in
state = value.translation
}
.onEnded { _ in
presionandoLargo = false
}
)
)
}
Caso de uso: Pantalla de inicio de iOS: mantén presionado para entrar en modo de edición, luego arrastra para reordenar.
Gestos exclusivos
Úsalo cuando: Solo un gesto debe ganar, no ambos
var body: some View {
Rectángulo()
.gesture(
TapGesture(count: 2) // Doble toque
.onEnded { _ in
hacerZoom()
}
.exclusively(before:
TapGesture(count: 1) // Un toque
.onEnded { _ in
seleccionar()
}
)
)
}
Por qué: Sin .exclusively, el doble toque activa ambos manejadores de toque simple y doble.
Cómo funciona: SwiftUI espera para ver si llega un segundo toque. Si es así → gana el doble toque. Si no → gana el toque simple.
Patrón 3: GestureState vs State
Cuándo usar cada uno
| Caso de uso | Tipo de Estado | Por qué |
|---|---|---|
| Retroalimentación temporal durante el gesto | @GestureState | Se restablece automáticamente cuando el gesto termina |
| Valor final confirmado | @State | Persiste después del gesto |
| Animación durante el gesto | @GestureState | Transiciones suaves |
| Persistencia de datos | @State | Sobrevive a las actualizaciones de la vista |
Ejemplo completo: Tarjeta arrastrable
struct TarjetaArrastrable: View {
@GestureState private var desplazamientoArrastre = CGSize.zero // Temporal
@State private var posicion = CGSize.zero // Permanente
var body: some View {
RoundedRectangle(cornerRadius: 12)
.fill(.blue)
.frame(width: 300, height: 200)
.offset(
x: posicion.width + desplazamientoArrastre.width,
y: posicion.height + desplazamientoArrastre.height
)
.gesture(
DragGesture()
.updating($desplazamientoArrastre) { value, state, transaction in
state = value.translation
// Habilitar animación para una retroalimentación suave
transaction.animation = .interactiveSpring()
}
.onEnded { value in
// Confirmar la posición final con animación
withAnimation(.spring()) {
posicion.width += value.translation.width
posicion.height += value.translation.height
}
}
)
}
}
Información clave: El tercer parámetro transaction de GestureState te permite personalizar la animación durante el gesto.
Patrón 4: Gestos personalizados
Cuándo crear gestos personalizados
- Necesitas un comportamiento de gesto no proporcionado por los gestos integrados
- Quieres encapsular una lógica de gesto compleja
- Reutilizar el gesto en múltiples vistas
Ejemplo: Gesto de deslizar con dirección
struct GestoDeslizar: Gesture {
enum Direccion {
case izquierda, derecha, arriba, abajo
}
let distanciaMinima: CGFloat
let espacioCoordenadas: CoordinateSpace
init(distanciaMinima: CGFloat = 50, espacioCoordenadas: CoordinateSpace = .local) {
self.distanciaMinima = distanciaMinima
self.espacioCoordenadas = espacioCoordenadas
}
// El valor es la dirección
typealias Value = Direccion
// El cuerpo se basa en DragGesture
var body: AnyGesture<Direccion> {
DragGesture(minimumDistance: distanciaMinima, coordinateSpace: espacioCoordenadas)
.map { value in
let horizontal = value.translation.width
let vertical = value.translation.height
if abs(horizontal) > abs(vertical) {
return horizontal < 0 ? .izquierda : .derecha
} else {
return vertical < 0 ? .arriba : .abajo
}
}
.eraseToAnyGesture()
}
}
// Uso
Text("Deslízame")
.gesture(
GestoDeslizar()
.onEnded { direccion in
switch direccion {
case .izquierda: eliminarElemento()
case .derecha: archivarElemento()
default: break
}
}
)
Patrón 5: Velocidad y predicción de gestos
Accediendo a la velocidad
@State private var velocidad: CGSize = .zero
var body: some View {
Círculo()
.gesture(
DragGesture()
.onEnded { value in
// value.velocity está obsoleto en iOS 18+
// Usa value.predictedEndLocation y time
let deltaTiempo = value.time.timeIntervalSince(value.startLocation.time)
let distancia = value.translation
velocidad = CGSize(
width: distancia.width / deltaTiempo,
height: distancia.height / deltaTiempo
)
// Animar con momento
withAnimation(.interpolatingSpring(stiffness: 100, damping: 15)) {
aplicarMomento(velocidad: velocidad)
}
}
)
}
Ubicación final predicha (iOS 16+)
DragGesture()
.onChanged { value in
// Dónde terminará probablemente el gesto según la velocidad
let predicho = value.predictedEndLocation
// Mostrar vista previa de dónde aterrizará el elemento
mostrarVistaPrevia(en: predicho)
}
Caso de uso: Física con elasticidad, desplazamiento con inercia, animaciones de lanzamiento.
Patrón 6: Integración de accesibilidad
Haciendo que los gestos personalizados sean accesibles
❌ INCORRECTO (Solo gesto, sin soporte de VoiceOver)
Imagen("deslizador")
.gesture(
DragGesture()
.onChanged { value in
actualizarVolumen(value.translation.width)
}
)
Problema: Los usuarios de VoiceOver no pueden ajustar el deslizador.
✅ CORRECTO (Agregar acciones de accesibilidad)
@State private var volumen: Double = 50
var body: some View {
Imagen("deslizador")
.gesture(
DragGesture()
.onChanged { value in
volumen = calcularVolumen(de: value.translation.width)
}
)
.accessibilityElement()
.accessibilityLabel("Volumen")
.accessibilityValue("\(Int(volumen))%")
.accessibilityAdjustableAction { direccion in
switch direccion {
case .increment:
volumen = min(100, volumen + 5)
case .decrement:
volumen = max(0, volumen - 5)
@unknown default:
break
}
}
}
Por qué: Los usuarios de VoiceOver ahora pueden deslizar hacia arriba/abajo para ajustar el volumen sin ver ni usar el gesto.
Alternativas de teclado (macOS)
Rectángulo()
.gesture(
DragGesture()
.onChanged { value in
mover(por: value.translation)
}
)
.onKeyPress(.upArrow) {
mover(por: CGSize(width: 0, height: -10))
return .handled
}
.onKeyPress(.downArrow) {
mover(por: CGSize(width: 0, height: 10))
return .handled
}
.onKeyPress(.leftArrow) {
mover(por: CGSize(width: -10, height: 0))
return .handled
}
.onKeyPress(.rightArrow) {
mover(por: CGSize(width: 10, height: 0))
return .handled
}
Patrón 7: Gestos multiplataforma
iOS vs macOS vs visionOS
| Gesto | iOS | macOS | visionOS |
|---|---|---|---|
| TapGesture | Toque con el dedo | Clic del mouse | Toque con el dedo |
| LongPressGesture | Mantener presionado | Clic mantenido | Mantener presionado |
| DragGesture | Arrastrar con el dedo | Arrastrar con el mouse/trackpad | Arrastrar con la mano |
| MagnificationGesture | Pellizcar con dos dedos | Pellizcar en el trackpad | Pellizcar con dos manos |
| RotationGesture | Rotar con dos dedos | Rotar en el trackpad | Rotar con la mano |
Patrón 8: Depuración de gestos
Problema: El gesto no comienza
// Verificar:
// 1. ¿La vista es interactuable?
// - Las vistas deben tener contenido (no vacías)
// - Las vistas con .allowsHitTesting(false) ignoran los gestos
// 2. ¿Hay otro gesto que intercepte el evento?
// - Usa .simultaneously para permitir que ambos gestos funcionen
// - Usa .exclusively para que solo uno gane
// 3. ¿La condición mínima es demasiado alta?
// - LongPressGesture(minimumDuration: 10) → 10 segundos es demasiado
// - DragGesture(minimumDistance: 500) → 500 puntos es demasiado
// 4. ¿La vista está oculta por otra?
// - Usa .zIndex() para controlar el orden de las vistas
Problema: El gesto no se completa
// Verificar:
// 1. ¿El manejador .onEnded está adjunto al gesto correcto?
// - En gestos compuestos, adjunta .onEnded a cada subgesto
// 2. ¿El estado temporal se actualiza correctamente?
// - Usa .updating para @GestureState
// - Usa .onChanged para @State (con precaución)
// 3. ¿El gesto se cancela por otro?
// - Usa GestureMask para controlar la propagación del gesto
// - .gesture(..., including: .gesture) → Solo este gesto
// - .gesture(..., including: .subviews) → Permite gestos de subvistas
// - .gesture(..., including: .all) → Permite todos los gestos
// - .gesture(..., including: .none) → Deshabilita el gesto
Problema: La animación es entrecortada
// Solución: Usa transaction.animation en .updating
DragGesture()
.updating($desplazamientoArrastre) { value, state, transaction in
state = value.translation
transaction.animation = .interactiveSpring()
}
Resumen rápido
Mejores prácticas
- Usa
@GestureStatepara el estado temporal del gesto (se restablece automáticamente) - Usa
@Statepara valores que deben persistir después del gesto - Usa
Buttonpara acciones de toque simple (accesibilidad integrada) - Componer gestos con
.simultaneously,.sequenced,.exclusively - Agregar acciones de accesibilidad para usuarios de VoiceOver
- Probar en todas las plataformas (iOS, macOS, visionOS)
Errores comunes
| Error | Solución |
|---|---|
| Gesto no comienza | Verificar .allowsHitTesting, condiciones mínimas |
| Gesto no se completa | Verificar .onEnded, GestureMask |
| Estado no se restablece | Usar @GestureState en lugar de @State |
| Animación entrecortada | Usar transaction.animation en .updating |
| Sin soporte de accesibilidad | Agregar .accessibilityAdjustableAction |
| Conflicto entre gestos | Usar .simultaneously, .sequenced, .exclusively |