SwiftUI-Gesten
Umfassender Leitfaden zur Gestenerkennung in SwiftUI mit Kompositionsmustern, Zustandsverwaltung und Barrierefreiheitsintegration.
Wann sollte dieser Skill verwendet werden
- Implementierung von Tipp-, Zieh-, Langdruck-, Vergrößerungs- oder Drehgesten
- Komposition mehrerer Gesten (gleichzeitig, nacheinander, exklusiv)
- Verwaltung des Gestenzustands mit @GestureState
- Erstellung benutzerdefinierter Gestenerkenner
- Fehlersuche bei Gestenkonflikten oder nicht reagierenden Gesten
- Barrierefreiheit von Gesten mit VoiceOver
- Plattformübergreifende Gestenbehandlung (iOS, macOS, visionOS)
Beispielanfragen
Dies sind echte Fragen von Entwicklern, die dieser Skill beantworten soll:
1. „Meine Ziehgeste funktioniert nicht – die Ansicht bewegt sich nicht, wenn ich sie ziehe. Wie kann ich das debuggen?“
→ Der Skill behandelt DragGesture-Zustandsverwaltungsmuster und zeigt, wie man den Ansatz-Offset mit @GestureState korrekt aktualisiert.
2. „Ich habe sowohl eine Tippgeste als auch eine Ziehgeste auf derselben Ansicht. Der Tipp funktioniert, aber das Ziehen nicht. Wie behebe ich das?“
→ Der Skill demonstriert Gestenkomposition mit .simultaneously, .sequenced und .exclusively, um Gestenkonflikte zu lösen.
3. „Ich möchte, dass Benutzer lange drücken, bevor sie ein Element ziehen können. Wie verketten ich Gesten?“
→ Der Skill zeigt das .sequenced-Muster zur Kombination von LongPressGesture mit DragGesture in der richtigen Reihenfolge.
4. „Mein Gestenzustand wird nicht zurückgesetzt, wenn die Geste endet. Die Ansicht bleibt in der falschen Position.“
→ Der Skill behandelt das automatische Zurücksetzverhalten von @GestureState und den Aktualisierungsparameter für eine korrekte Zustandsverwaltung.
5. „VoiceOver-Benutzer können nicht auf Funktionen zugreifen, die Gesten erfordern. Wie mache ich Gesten barrierefrei?“
→ Der Skill demonstriert .accessibilityAction-Muster und die Bereitstellung alternativer Interaktionen für VoiceOver-Benutzer.
Auswahl der richtigen Geste (Entscheidungsbaum)
Welche Interaktion wird benötigt?
├─ Einfaches Tippen/Klicken?
│ └─ Verwende Button (bevorzugt) oder TapGesture
│
├─ Zieh-/Schwenkbewegung?
│ └─ Verwende DragGesture
│
├─ Halten vor einer Aktion?
│ └─ Verwende LongPressGesture
│
├─ Zusammenziehen zum Zoomen?
│ └─ Verwende MagnificationGesture
│
├─ Zweifinger-Drehung?
│ └─ Verwende RotationGesture
│
├─ Mehrere Gesten zusammen?
│ ├─ Beide gleichzeitig? → .simultaneously
│ ├─ Eine nach der anderen? → .sequenced
│ └─ Eine ODER die andere? → .exclusively
│
└─ Komplexes benutzerdefiniertes Verhalten?
└─ Erstelle benutzerdefinierte Geste, die dem Gesture-Protokoll entspricht
Muster 1: Grundlegende Gestenerkennung
TapGesture
❌ FALSCH (Benutzerdefiniertes Tippen auf nicht-semantischer Ansicht)
Text("Absenden")
.onTapGesture {
absenden()
}
Probleme:
- Wird VoiceOver nicht als Schaltfläche angekündigt
- Kein visuelles Drück-Feedback
- Beachtet Barrierefreiheitseinstellungen nicht
✅ RICHTIG (Button für Tipp-Aktionen verwenden)
Button("Absenden") {
absenden()
}
.buttonStyle(.bordered)
Wann TapGesture verwenden: Nur wenn Tipp-Daten (Position, Anzahl) oder nicht standardmäßiges Tippverhalten benötigt werden:
Image("karte")
.onTapGesture(count: 2) { // Doppeltippen für Details
detailsAnzeigen()
}
.onTapGesture { position in // Einfacher Tipp zum Setzen einer Markierung
markierungHinzufügen(at: position)
}
DragGesture
❌ FALSCH (Direkte Zustandsmutation in der Geste)
@State private var offset = CGSize.zero
var body: some View {
Kreis()
.offset(offset)
.gesture(
DragGesture()
.onChanged { value in
offset = value.translation // ❌ Aktualisiert jeden Frame, verursacht Ruckeln
}
)
}
Probleme:
- Ansicht wird bei jedem Zieh-Ereignis aktualisiert (60-120 Mal pro Sekunde)
- Keine Möglichkeit, in die ursprüngliche Position zurückzukehren
- Zwischenzustand geht bei Abbruch der Ziehbewegung verloren
✅ RICHTIG (@GestureState für temporären Zustand verwenden)
@GestureState private var dragOffset = CGSize.zero
@State private var position = CGSize.zero
var body: some View {
Kreis()
.offset(x: position.width + dragOffset.width,
y: position.height + dragOffset.height)
.gesture(
DragGesture()
.updating($dragOffset) { value, state, _ in
state = value.translation // Temporär während des Ziehens
}
.onEnded { value in
position.width += value.translation.width // Endgültig übernehmen
position.height += value.translation.height
}
)
}
Warum: @GestureState setzt automatisch auf den Anfangswert zurück, wenn die Geste endet, und verhindert so Zustandsverfälschungen.
LongPressGesture
@GestureState private var isDetectingLongPress = false
@State private var completedLongPress = false
var body: some View {
Text("Drücken und halten")
.foregroundStyle(isDetectingLongPress ? .red : .blau)
.gesture(
LongPressGesture(minimumDuration: 1.0)
.updating($isDetectingLongPress) { currentState, gestureState, _ in
gestureState = currentState // Visuelles Feedback während des Drückens
}
.onEnded { _ in
completedLongPress = true // Aktion nach dem Halten
}
)
}
Wichtige Parameter:
minimumDuration: Wie lange gehalten werden muss (Standard 0,5 Sekunden)maximumDistance: Wie weit der Finger sich bewegen kann, bevor abgebrochen wird (Standard 10 Punkte)
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
}
)
}
Plattformhinweise:
- iOS: Zwei-Finger-Zoom-Geste
- macOS: Trackpad-Zoom
- visionOS: Zoom-Geste im 3D-Raum
RotationGesture
@GestureState private var rotationAngle = Angle.zero
@State private var currentRotation = Angle.zero
var body: some View {
Rechteck()
.fill(.blau)
.frame(width: 200, height: 200)
.rotationEffect(currentRotation + rotationAngle)
.gesture(
RotationGesture()
.updating($rotationAngle) { value, state, _ in
state = value.rotation
}
.onEnded { value in
currentRotation += value.rotation
}
)
}
Muster 2: Gestenkomposition
Gleichzeitige Gesten
Verwende, wenn: Zwei Gesten gleichzeitig funktionieren sollen
@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
}
)
)
}
Anwendungsfall: Fotobetrachter, in dem man gleichzeitig ziehen UND mit zwei Fingern zoomen kann.
Nacheinander ausgeführte Gesten
Verwende, wenn: Eine Geste abgeschlossen sein muss, bevor die nächste beginnt
@State private var isLongPressing = false
@GestureState private var dragOffset = CGSize.zero
var body: some View {
Kreis()
.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
}
)
)
}
Anwendungsfall: iOS-Startbildschirm — langes Drücken, um in den Bearbeitungsmodus zu gelangen, dann Ziehen, um die Reihenfolge zu ändern.
Exklusive Gesten
Verwende, wenn: Nur eine Geste gewinnen soll, nicht beide
var body: some View {
Rechteck()
.gesture(
TapGesture(count: 2) // Doppeltippen
.onEnded { _ in
zoom()
}
.exclusively(before:
TapGesture(count: 1) // Einzeltippen
.onEnded { _ in
auswählen()
}
)
)
}
Warum: Ohne .exclusively löst Doppeltippen beide Behandlungsroutinen für Einzel- und Doppeltippen aus.
Funktionsweise: SwiftUI wartet, ob ein zweiter Tipp kommt. Wenn ja → Doppeltippen gewinnt. Wenn nein → Einzeltippen gewinnt.
Muster 3: @GestureState vs. @State
Wann was verwenden
| Anwendungsfall | Zustandstyp | Warum |
|---|---|---|
| Temporäres Feedback während der Geste | @GestureState | Wird automatisch zurückgesetzt, wenn die Geste endet |
| Endgültig übernommener Wert | @State | Bleibt nach der Geste bestehen |
| Animation während der Geste | @GestureState | Sanfte Übergänge |
| Datenpersistenz | @State | Überlebt Ansichtsaktualisierungen |
Vollständiges Beispiel: Ziehbare Karte
struct DraggableCard: View {
@GestureState private var dragOffset = CGSize.zero // Temporär
@State private var position = CGSize.zero // Dauerhaft
var body: some View {
AbgerundetesRechteck(cornerRadius: 12)
.fill(.blau)
.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
// Animation für sanftes Feedback aktivieren
transaction.animation = .interactiveSpring()
}
.onEnded { value in
// Endposition mit Animation übernehmen
withAnimation(.spring()) {
position.width += value.translation.width
position.height += value.translation.height
}
}
)
}
}
Wichtige Erkenntnis: Der dritte Parameter von @GestureState, transaction, ermöglicht die Anpassung der Animation während der Geste.
Muster 4: Benutzerdefinierte Gesten
Wann benutzerdefinierte Gesten erstellt werden sollten
- Wenn das Verhalten der integrierten Gesten nicht ausreicht
- Kapselung komplexer Gestenlogik
- Wiederverwendung von Gesten in mehreren Ansichten
Beispiel: Wischgeste mit Richtung
struct WischGeste: Gesture {
enum Richtung {
case links, rechts, oben, unten
}
let mindestAbstand: CGFloat
let koordinatenRaum: CoordinateSpace
init(mindestAbstand: CGFloat = 50, koordinatenRaum: CoordinateSpace = .local) {
self.mindestAbstand = mindestAbstand
self.koordinatenRaum = koordinatenRaum
}
// Wert ist die Richtung
typealias Value = Richtung
// Körper baut auf DragGesture auf
var body: AnyGesture<Richtung> {
DragGesture(minimumDistance: mindestAbstand, coordinateSpace: koordinatenRaum)
.map { value in
let horizontal = value.translation.width
let vertikal = value.translation.height
if abs(horizontal) > abs(vertikal) {
return horizontal < 0 ? .links : .rechts
} else {
return vertikal < 0 ? .oben : .unten
}
}
.eraseToAnyGesture()
}
}
// Verwendung
Text(\