Gestos no SwiftUI
Guia abrangente sobre reconhecimento de gestos no SwiftUI com padrões de composição, gerenciamento de estado e integração de acessibilidade.
Quando Usar Este Skill
- Implementar gestos de toque, arrastar, pressionar longamente, ampliação ou rotação
- Compor múltiplos gestos (simultaneamente, sequenciados, exclusivamente)
- Gerenciar estado de gestos com GestureState
- Criar reconhecedores de gestos personalizados
- Depurar conflitos de gestos ou gestos que não respondem
- Tornar gestos acessíveis com VoiceOver
- Manipulação de gestos entre plataformas (iOS, macOS, visionOS)
Exemplos de Comandos
Estas são perguntas reais que desenvolvedores fazem e que este skill foi projetado para responder:
1. "Meu gesto de arrastar não está funcionando - a visualização não se move quando eu arrasto. Como faço para depurar isso?"
→ O skill aborda padrões de gerenciamento de estado do DragGesture e mostra como atualizar corretamente o deslocamento da visualização com @GestureState
2. "Tenho um gesto de toque e um gesto de arrastar na mesma visualização. O toque funciona, mas o arrastar não. Como faço para corrigir isso?"
→ O skill demonstra a composição de gestos com .simultaneously, .sequenced e .exclusively para resolver conflitos de gestos
3. "Quero que os usuários pressionem longamente antes de poderem arrastar um item. Como faço para encadear gestos?"
→ O skill mostra o padrão .sequenced para combinar LongPressGesture com DragGesture na ordem correta
4. "O estado do meu gesto não está sendo redefinido quando o gesto termina. A visualização permanece na posição errada."
→ O skill aborda o comportamento de redefinição automática do @GestureState e o parâmetro updating para gerenciamento adequado de estado
5. "Usuários do VoiceOver não conseguem acessar recursos que exigem gestos. Como torno os gestos acessíveis?"
→ O skill demonstra padrões de .accessibilityAction e fornece interações alternativas para usuários do VoiceOver
Escolhendo o Gesto Certo (Árvore de Decisão)
Qual interação você precisa?
├─ Toque/clique único?
│ └─ Use Button (preferido) ou TapGesture
│
├─ Movimento de arrastar/pan?
│ └─ Use DragGesture
│
├─ Segurar antes da ação?
│ └─ Use LongPressGesture
│
├─ Pinça para zoom?
│ └─ Use MagnificationGesture
│
├─ Rotação com dois dedos?
│ └─ Use RotationGesture
│
├─ Vários gestos juntos?
│ ├─ Ambos ao mesmo tempo? → .simultaneously
│ ├─ Um após o outro? → .sequenced
│ └─ Um OU o outro? → .exclusively
│
└─ Comportamento personalizado complexo?
└─ Crie um Gesture personalizado conforme o protocolo Gesture
Padrão 1: Reconhecimento Básico de Gestos
TapGesture
❌ ERRADO (Toque personalizado em visualização não semântica)
Text("Enviar")
.onTapGesture {
submitForm()
}
Problemas:
- Não é anunciado como botão para o VoiceOver
- Sem feedback visual de pressão
- Não respeita as configurações de acessibilidade
✅ CORRETO (Use Button para ações de toque)
Button("Enviar") {
submitForm()
}
.buttonStyle(.bordered)
Quando usar TapGesture: Apenas quando você precisa de dados do toque (localização, contagem) ou comportamento de toque não padrão:
Image("mapa")
.onTapGesture(count: 2) { // Toque duplo para detalhes
showDetails()
}
.onTapGesture { localizacao in // Toque único para fixar
addPin(at: localizacao)
}
DragGesture
❌ ERRADO (Mutação direta de estado no gesto)
@State private var offset = CGSize.zero
var body: some View {
Circle()
.offset(offset)
.gesture(
DragGesture()
.onChanged { value in
offset = value.translation // ❌ Atualiza a cada frame, causa travamentos
}
)
}
Problemas:
- A visualização é atualizada a cada evento de arrasto (60-120 vezes por segundo)
- Sem maneira de redefinir para a posição original
- Perde estado intermediário se o arrasto for cancelado
✅ CORRETO (Use GestureState para estado temporário)
@GestureState private var dragOffset = CGSize.zero
@State private var position = CGSize.zero
var body: some View {
Circle()
.offset(x: position.width + dragOffset.width,
y: position.height + dragOffset.height)
.gesture(
DragGesture()
.updating($dragOffset) { value, state, _ in
state = value.translation // Temporário durante o arrasto
}
.onEnded { value in
position.width += value.translation.width // Confirmar final
position.height += value.translation.height
}
)
}
Por quê: GestureState é redefinido automaticamente para o valor inicial quando o gesto termina, prevenindo corrupção de estado.
LongPressGesture
@GestureState private var isDetectingLongPress = false
@State private var completedLongPress = false
var body: some View {
Text("Pressione e segure")
.foregroundStyle(isDetectingLongPress ? .red : .blue)
.gesture(
LongPressGesture(minimumDuration: 1.0)
.updating($isDetectingLongPress) { currentState, gestureState, _ in
gestureState = currentState // Feedback visual durante a pressão
}
.onEnded { _ in
completedLongPress = true // Ação após segurar
}
)
}
Parâmetros chave:
minimumDuration: Quanto tempo segurar (padrão 0,5 segundos)maximumDistance: Quanto o dedo pode se mover antes de cancelar (padrão 10 pontos)
MagnificationGesture
@GestureState private var magnificationAmount = 1.0
@State private var currentZoom = 1.0
var body: some View {
Image("foto")
.scaleEffect(currentZoom * magnificationAmount)
.gesture(
MagnificationGesture()
.updating($magnificationAmount) { value, state, _ in
state = value.magnification
}
.onEnded { value in
currentZoom *= value.magnification
}
)
}
Observações de plataforma:
- iOS: Gesto de pinça com dois dedos
- macOS: Pinça no trackpad
- visionOS: Gesto de pinça no espaço 3D
RotationGesture
@GestureState private var rotationAngle = Angle.zero
@State private var currentRotation = Angle.zero
var body: some View {
Rectangle()
.fill(.blue)
.frame(width: 200, height: 200)
.rotationEffect(currentRotation + rotationAngle)
.gesture(
RotationGesture()
.updating($rotationAngle) { value, state, _ in
state = value.rotation
}
.onEnded { value in
currentRotation += value.rotation
}
)
}
Padrão 2: Composição de Gestos
Gestos Simultâneos
Use quando: Dois gestos devem funcionar ao mesmo tempo
@GestureState private var dragOffset = CGSize.zero
@GestureState private var magnificationAmount = 1.0
var body: some View {
Image("foto")
.offset(dragOffset)
.scaleEffect(magnificationAmount)
.gesture(
DragGesture()
.updating($dragOffset) { value, state, _ in
state = value.translation
}
.simultaneously(with:
MagnificationGesture()
.updating($magnificationAmount) { value, state, _ in
state = value.magnification
}
)
)
}
Caso de uso: Visualizador de fotos onde você pode arrastar E aplicar zoom com pinça ao mesmo tempo.
Gestos Sequenciados
Use quando: Um gesto deve completar antes do próximo iniciar
@State private var isLongPressing = false
@GestureState private var dragOffset = CGSize.zero
var body: some View {
Circle()
.offset(dragOffset)
.gesture(
LongPressGesture(minimumDuration: 0.5)
.onEnded { _ in
isLongPressing = true
}
.sequenced(before:
DragGesture()
.updating($dragOffset) { value, state, _ in
state = value.translation
}
.onEnded { _ in
isLongPressing = false
}
)
)
}
Caso de uso: Tela Inicial do iOS — pressione longamente para entrar no modo de edição, depois arraste para reordenar.
Gestos Exclusivos
Use quando: Apenas um gesto deve vencer, não ambos
var body: some View {
Rectangle()
.gesture(
TapGesture(count: 2) // Toque duplo
.onEnded { _ in
zoom()
}
.exclusively(before:
TapGesture(count: 1) // Toque único
.onEnded { _ in
select()
}
)
)
}
Por quê: Sem .exclusively, o toque duplo aciona ambos os manipuladores de toque único e duplo.
Como funciona: SwiftUI espera para ver se o segundo toque vem. Se sim → toque duplo vence. Se não → toque único vence.
Padrão 3: GestureState vs State
Quando Usar Cada Um
| Caso de Uso | Tipo de Estado | Por quê |
|---|---|---|
| Feedback temporário durante o gesto | @GestureState | Redefine automaticamente quando o gesto termina |
| Valor final confirmado | @State | Persiste após o gesto |
| Animação durante o gesto | @GestureState | Transições suaves |
| Persistência de dados | @State | Sobrevive a atualizações de visualização |
Exemplo Completo: Cartão Arrastável
struct DraggableCard: View {
@GestureState private var dragOffset = CGSize.zero // Temporário
@State private var position = CGSize.zero // Permanente
var body: some View {
RoundedRectangle(cornerRadius: 12)
.fill(.blue)
.frame(width: 300, height: 200)
.offset(
x: position.width + dragOffset.width,
y: position.height + dragOffset.height
)
.gesture(
DragGesture()
.updating($dragOffset) { value, state, transaction in
state = value.translation
// Ativar animação para feedback suave
transaction.animation = .interactiveSpring()
}
.onEnded { value in
// Confirmar posição final com animação
withAnimation(.spring()) {
position.width += value.translation.width
position.height += value.translation.height
}
}
)
}
}
Insight chave: O terceiro parâmetro do GestureState transaction permite personalizar a animação durante o gesto.
Padrão 4: Gestos Personalizados
Quando Criar Gestos Personalizados
- Necessitar de comportamento de gesto não fornecido pelos gestos internos
- Querer encapsular lógica complexa de gestos
- Reutilizar gesto em múltiplas visualizações
Exemplo: Gesto de Deslizar com Direção
struct SwipeGesture: Gesture {
enum Direction {
case left, right, up, down
}
let minimumDistance: CGFloat
let coordinateSpace: CoordinateSpace
init(minimumDistance: CGFloat = 50, coordinateSpace: CoordinateSpace = .local) {
self.minimumDistance = minimumDistance
self.coordinateSpace = coordinateSpace
}
// Valor é a direção
typealias Value = Direction
// Corpo é construído sobre DragGesture
var body: AnyGesture<Direction> {
DragGesture(minimumDistance: minimumDistance, coordinateSpace: coordinateSpace)
.map { value in
let horizontal = value.translation.width
let vertical = value.translation.height
if abs(horizontal) > abs(vertical) {
return horizontal < 0 ? .left : .right
} else {
return vertical < 0 ? .up : .down
}
}
.eraseToAnyGesture()
}
}
// Uso
Text("Deslize-me")
.gesture(
SwipeGesture()
.onEnded { direction in
switch direction {
case .left: deleteItem()
case .right: archiveItem()
default: break
}
}
)
Padrão 5: Velocidade e Previsão de Gesto
Acessando Velocidade
@State private var velocity: CGSize = .zero
var body: some View {
Circle()
.gesture(
DragGesture()
.onEnded { value in
// value.velocity está obsoleto no iOS 18+
// Use value.predictedEndLocation e time
let timeDelta = value.time.timeIntervalSince(value.startLocation.time)
let distance = value.translation
velocity = CGSize(
width: distance.width / timeDelta,
height: distance.height / timeDelta
)
// Animar com momentum
withAnimation(.interpolatingSpring(stiffness: 100, damping: 15)) {
applyMomentum(velocity: velocity)
}
}
)
}
Localização Final Prevista (iOS 16+)
DragGesture()
.onChanged { value in
// Onde o gesto provavelmente terminará com base na velocidade
let predicted = value.predictedEndLocation
// Mostrar pré-visualização de onde o item irá parar
showPreview(at: predicted)
}
Caso de uso: Física elástica, rolagem com momentum, animações de arremesso.
Padrão 6: Integração de Acessibilidade
Tornando Gestos Personalizados Acessíveis
❌ ERRADO (Apenas gesto, sem suporte VoiceOver)
Image("controle")
.gesture(
DragGesture()
.onChanged { value in
updateVolume(value.translation.width)
}
)
Problema: Usuários do VoiceOver não podem ajustar o controle deslizante.
✅ CORRETO (Adicionar ações de acessibilidade)
@State private var volume: Double = 50
var body: some View {
Image("controle")
.gesture(
DragGesture()
.onChanged { value in
volume = calculateVolume(from: value.translation.width)
}
)
.accessibilityElement()
.accessibilityLabel("Volume")
.accessibilityValue("\(Int(volume))%")
.accessibilityAdjustableAction { direction in
switch direction {
case .increment:
volume = min(100, volume + 5)
case .decrement:
volume = max(0, volume - 5)
@unknown default:
break
}
}
}
Por quê: Usuários do VoiceOver agora podem deslizar para cima/baixo para ajustar o volume sem ver ou usar o gesto.
Alternativas de Teclado (macOS)
Rectangle()
.gesture(
DragGesture()
.onChanged { value in
move(by: value.translation)
}
)
.onKeyPress(.upArrow) {
move(by: CGSize(width: 0, height: -10))
return .handled
}
.onKeyPress(.downArrow) {
move(by: CGSize(width: 0, height: 10))
return .handled
}
.onKeyPress(.leftArrow) {
move(by: CGSize(width: -10, height: 0))
return .handled
}
.onKeyPress(.rightArrow) {
move(by: CGSize(width: 10, height: 0))
return .handled
}
Padrão 7: Gestos Entre Plataformas
iOS vs macOS vs visionOS
| Gesto | iOS | macOS | visionOS |
|---|---|---|---|
| TapGesture | Toque na tela | Clique do mouse | Toque no ar |
| DragGesture | Arrastar com dedo | Arrastar com mouse/trackpad | Arrastar com movimento da mão |
| LongPressGesture | Pressionar e segurar | Clique e segurar | Pressionar e segurar |
| MagnificationGesture | Pinça com dois dedos | Pinça no trackpad | Pinça no espaço 3D |
| RotationGesture | Rotação com dois dedos | Rotação no trackpad | Rotação com movimento da mão |
Ajustes Específicos de Plataforma
#if os(iOS)
// Toque no iOS para comportamento específico
.gesture(
LongPressGesture(minimumDuration: 0.3) // Resposta mais rápida
)
#elseif os(macOS)
.onHover { hovering in
cursorStyle = hovering ? .openHand : .arrow
}
.gesture(
DragGesture(minimumDistance: 0) // Responder imediatamente no macOS
)
#elseif os(visionOS)
.gesture(
SpatialTapGesture()
.onEnded { value in
handleTap(at: value.location3D)
}
)
#endif
Padrão 8: Depuração de Gestos
Conflitos Comuns
Sintoma: Gesto não responde quando outro está presente.
Causa: Prioridade de gesto não intencional ou conflito de estado.
Estratégias de depuração:
- Isolar o gesto: Comente outros gestos para confirmar se o gesto visado funciona sozinho
- Simplificar estado: Substitua @State por @GestureState para ver se o reset automático resolve
- Verificar limites: Garanta que minimumDistance / maximumDistance não estão bloqueando o reconhecimento
- Usar a visualização da hierarquia do Xcode: Verifique qual visualização está recebendo o gesto
- Adicionar impressões de depuração: Anexe
onChangedeonEndedcom prints para ver se os callbacks estão sendo disparados - Testar em simulador: Às vezes, gestos se comportam de forma diferente no simulador vs. dispositivo real
Técnica de Sobreposição de Gestos
Rectangle()
.fill(.blue)
.frame(width: 100, height: 100)
.overlay(
Text("Arraste-me")
.foregroundColor(.white)
)
.gesture( // Gesto na visualização externa
DragGesture()
.onChanged { print("Arrasto: \(value.translation)") }
)
.onTapGesture { // Gesto na visualização interna
print("Toque")
}
Nota: Visões internas podem interceptar gestos antes das externas. Use .highPriorityGesture() se necessário.
Padrão 9: Gestos com ScrollView e Listas
Desafio: Arrastar em uma ScrollView
ScrollView {
VStack {
CardView()
.gesture(
DragGesture()
.onChanged { value in
// Este gesto compete com a rolagem da ScrollView
}
)
}
}
Solução: Use .simultaneousGesture() em vez de .gesture() para permitir que ambos os gestos funcionem.
CardView()
.simultaneousGesture(
DragGesture()
.onChanged { value in
// Agora funciona simultaneamente com a rolagem
}
)
Opção de Prioridade: highPriorityGesture
CardView()
.highPriorityGesture(
DragGesture()
.onEnded { value in
// Impede a ScrollView de receber este evento de arrasto
}
)
Próximos Passos
- Explore o guia oficial da Apple: Adicionando gestos a visualizações SwiftUI
- Experimente exemplos: Use o pré-visualizador do Xcode para testar composições de gestos com diferentes visualizações
- Teste em dispositivos reais: Simuladores às vezes perdem comportamentos de gestos multitoque avançados
Licença
MIT