SwiftUI 제스처
제스처 인식, 구성 패턴, 상태 관리 및 접근성 통합을 위한 SwiftUI 제스처 가이드입니다.
이 스킬을 사용해야 할 때
- 탭, 드래그, 길게 누르기, 확대 또는 회전 제스처 구현
- 여러 제스처 구성 (동시, 순차, 배타적)
- GestureState로 제스처 상태 관리
- 사용자 지정 제스처 인식기 생성
- 제스처 충돌 또는 응답 없는 제스처 디버깅
- VoiceOver를 사용한 접근성 있는 제스처 만들기
- 크로스 플랫폼 제스처 처리 (iOS, macOS, visionOS)
예제 프롬프트
이 스킬이 답변하도록 설계된 실제 개발자 질문입니다.
1. "드래그 제스처가 작동하지 않습니다. 뷰를 드래그해도 이동하지 않습니다. 어떻게 디버깅해야 하나요?"
→ 이 스킬은 DragGesture 상태 관리 패턴을 다루고 @GestureState로 뷰 오프셋을 올바르게 업데이트하는 방법을 보여줍니다.
2. "같은 뷰에 탭 제스처와 드래그 제스처가 모두 있습니다. 탭은 작동하지만 드래그는 작동하지 않습니다. 어떻게 수정하나요?"
→ 이 스킬은 .simultaneously, .sequenced, .exclusively를 사용한 제스처 구성을 통해 제스처 충돌을 해결하는 방법을 보여줍니다.
3. "사용자가 항목을 드래그하기 전에 길게 누르도록 하고 싶습니다. 제스처를 어떻게 연결하나요?"
→ 이 스킬은 올바른 순서로 LongPressGesture와 DragGesture를 결합하는 .sequenced 패턴을 보여줍니다.
4. "제스처가 끝나도 제스처 상태가 재설정되지 않습니다. 뷰가 잘못된 위치에 남아 있습니다."
→ 이 스킬은 @GestureState의 자동 재설정 동작과 적절한 상태 관리를 위한 업데이트 매개변수를 다룹니다.
5. "VoiceOver 사용자가 제스처가 필요한 기능에 접근할 수 없습니다. 제스처를 접근 가능하게 만들려면 어떻게 해야 하나요?"
→ 이 스킬은 .accessibilityAction 패턴과 VoiceOver 사용자를 위한 대체 상호 작용 제공 방법을 보여줍니다.
올바른 제스처 선택 (의사 결정 트리)
어떤 상호 작용이 필요하십니까?
├─ 한 번 탭/클릭?
│ └─ Button (권장) 또는 TapGesture 사용
│
├─ 드래그/팬 이동?
│ └─ DragGesture 사용
│
├─ 작업 전에 누르고 있기?
│ └─ LongPressGesture 사용
│
├─ 핀치하여 확대/축소?
│ └─ MagnificationGesture 사용
│
├─ 두 손가락 회전?
│ └─ RotationGesture 사용
│
├─ 여러 제스처 함께?
│ ├─ 동시에? → .simultaneously
│ ├─ 순차적으로? → .sequenced
│ └─ 하나만? → .exclusively
│
└─ 복잡한 사용자 지정 동작?
└─ Gesture 프로토콜을 준수하는 사용자 지정 Gesture 생성
패턴 1: 기본 제스처 인식
TapGesture
❌ 잘못된 예 (의미 없는 뷰에 사용자 지정 탭)
Text("제출")
.onTapGesture {
submitForm()
}
문제점:
- VoiceOver에 버튼으로 알리지 않음
- 시각적 누름 피드백 없음
- 접근성 설정을 존중하지 않음
✅ 올바른 예 (탭 동작에는 Button 사용)
Button("제출") {
submitForm()
}
.buttonStyle(.bordered)
TapGesture를 사용해야 할 때: 탭 데이터(위치, 횟수) 또는 비표준 탭 동작이 필요할 때만 사용:
Image("map")
.onTapGesture(count: 2) { // 세부 정보를 위한 더블 탭
showDetails()
}
.onTapGesture { location in // 핀을 위한 단일 탭
addPin(at: location)
}
DragGesture
❌ 잘못된 예 (제스처에서 직접 상태 변이)
@State private var offset = CGSize.zero
var body: some View {
Circle()
.offset(offset)
.gesture(
DragGesture()
.onChanged { value in
offset = value.translation // ❌ 매 프레임 업데이트, 버벅거림 유발
}
)
}
문제점:
- 모든 드래그 이벤트에서 뷰 업데이트 (초당 60-120회)
- 원래 위치로 재설정할 방법 없음
- 드래그가 취소되면 중간 상태 손실
✅ 올바른 예 (임시 상태에는 GestureState 사용)
@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 // 드래그 중 임시
}
.onEnded { value in
position.width += value.translation.width // 최종 커밋
position.height += value.translation.height
}
)
}
이유: GestureState는 제스처가 끝나면 자동으로 초기 값으로 재설정되어 상태 손상을 방지합니다.
LongPressGesture
@GestureState private var isDetectingLongPress = false
@State private var completedLongPress = false
var body: some View {
Text("길게 누르세요")
.foregroundStyle(isDetectingLongPress ? .red : .blue)
.gesture(
LongPressGesture(minimumDuration: 1.0)
.updating($isDetectingLongPress) { currentState, gestureState, _ in
gestureState = currentState // 누르는 동안 시각적 피드백
}
.onEnded { _ in
completedLongPress = true // 누른 후 동작
}
)
}
주요 매개변수:
minimumDuration: 유지 시간 (기본값 0.5초)maximumDistance: 취소 전 손가락 이동 거리 (기본값 10포인트)
MagnificationGesture
@GestureState private var magnificationAmount = 1.0
@State private var currentZoom = 1.0
var body: some View {
Image("photo")
.scaleEffect(currentZoom * magnificationAmount)
.gesture(
MagnificationGesture()
.updating($magnificationAmount) { value, state, _ in
state = value.magnification
}
.onEnded { value in
currentZoom *= value.magnification
}
)
}
플랫폼 참고 사항:
- iOS: 두 손가락 핀치 제스처
- macOS: 트랙패드 핀치
- visionOS: 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
}
)
}
패턴 2: 제스처 구성
동시 제스처
다음 경우에 사용: 두 제스처가 동시에 작동해야 할 때
@GestureState private var dragOffset = CGSize.zero
@GestureState private var magnificationAmount = 1.0
var body: some View {
Image("photo")
.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
}
)
)
}
사용 사례: 드래그와 핀치 확대/축소를 동시에 할 수 있는 사진 뷰어.
순차 제스처
다음 경우에 사용: 한 제스처가 완료된 후에 다음 제스처가 시작되어야 할 때
@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
}
)
)
}
사용 사례: iOS 홈 화면 — 길게 누르면 편집 모드로 진입하고, 그런 다음 드래그하여 재정렬합니다.
배타적 제스처
다음 경우에 사용: 하나의 제스처만 실행되어야 할 때
var body: some View {
Rectangle()
.gesture(
TapGesture(count: 2) // 더블 탭
.onEnded { _ in
zoom()
}
.exclusively(before:
TapGesture(count: 1) // 단일 탭
.onEnded { _ in
select()
}
)
)
}
이유: .exclusively 없이 더블 탭은 단일 탭과 더블 탭 핸들러를 모두 트리거합니다.
작동 방식: SwiftUI는 두 번째 탭이 오는지 기다립니다. 오면 → 더블 탭이 실행됩니다. 오지 않으면 → 단일 탭이 실행됩니다.
패턴 3: GestureState vs State
각각 사용해야 할 때
| 사용 사례 | 상태 유형 | 이유 |
|---|---|---|
| 제스처 중 임시 피드백 | @GestureState | 제스처 종료 시 자동 재설정 |
| 최종 커밋된 값 | @State | 제스처 후에도 유지 |
| 제스처 중 애니메이션 | @GestureState | 부드러운 전환 |
| 데이터 지속성 | @State | 뷰 업데이트에도 유지 |
전체 예제: 드래그 가능한 카드
struct DraggableCard: View {
@GestureState private var dragOffset = CGSize.zero // 임시
@State private var position = CGSize.zero // 영구
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
// 부드러운 피드백을 위한 애니메이션 활성화
transaction.animation = .interactiveSpring()
}
.onEnded { value in
// 최종 위치를 애니메이션과 함께 커밋
withAnimation(.spring()) {
position.width += value.translation.width
position.height += value.translation.height
}
}
)
}
}
핵심 인사이트: GestureState의 세 번째 매개변수 transaction을 사용하면 제스처 중 애니메이션을 사용자 지정할 수 있습니다.
패턴 4: 사용자 지정 제스처
사용자 지정 제스처를 만들어야 할 때
- 기본 제공 제스처로는 제공되지 않는 제스처 동작이 필요할 때
- 복잡한 제스처 로직을 캡슐화하고 싶을 때
- 여러 뷰에서 제스처를 재사용할 때
예제: 방향이 있는 스와이프 제스처
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
}
// Value는 방향입니다
typealias Value = Direction
// Body는 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()
}
}
// 사용법
Text("스와이프하세요")
.gesture(
SwipeGesture()
.onEnded { direction in
switch direction {
case .left: deleteItem()
case .right: archiveItem()
default: break
}
}
)
패턴 5: 제스처 속도 및 예측
속도 접근
@State private var velocity: CGSize = .zero
var body: some View {
Circle()
.gesture(
DragGesture()
.onEnded { value in
// value.velocity는 iOS 18+에서 더 이상 사용되지 않음
// value.predictedEndLocation 및 시간 사용
let timeDelta = value.time.timeIntervalSince(value.startLocation.time)
let distance = value.translation
velocity = CGSize(
width: distance.width / timeDelta,
height: distance.height / timeDelta
)
// 모멘텀으로 애니메이션
withAnimation(.interpolatingSpring(stiffness: 100, damping: 15)) {
applyMomentum(velocity: velocity)
}
}
)
}
예측된 종료 위치 (iOS 16+)
DragGesture()
.onChanged { value in
// 속도를 기반으로 제스처가 종료될 가능성이 있는 위치
let predicted = value.predictedEndLocation
// 항목이 놓일 위치 미리보기 표시
showPreview(at: predicted)
}
사용 사례: 스프링 물리, 모멘텀 스크롤, 던지기 애니메이션.
패턴 6: 접근성 통합
사용자 지정 제스처를 접근 가능하게 만들기
❌ 잘못된 예 (제스처 전용, VoiceOver 지원 없음)
Image("slider")
.gesture(
DragGesture()
.onChanged { value in
updateVolume(value.translation.width)
}
)
문제점: VoiceOver 사용자가 슬라이더를 조정할 수 없습니다.
✅ 올바른 예 (접근성 동작 추가)
@State private var volume: Double = 50
var body: some View {
Image("slider")
.gesture(
DragGesture()
.onChanged { value in
volume = calculateVolume(from: value.translation.width)
}
)
.accessibilityElement()
.accessibilityLabel("볼륨")
.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
}
}
}
이유: VoiceOver 사용자는 이제 제스처를 보거나 사용하지 않고 위/아래로 스와이프하여 볼륨을 조정할 수 있습니다.
키보드 대안 (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
}
패턴 7: 크로스 플랫폼 제스처
iOS vs macOS vs visionOS
| 제스처 | iOS | macOS | visionOS |
|---|---|---|---|
| 탭 | 손가락 탭 | 마우스 클릭 | 공중 탭 |
| 드래그 | 손가락 드래그 | 트랙패드/마우스 드래그 | 손가락 핀치 및 당기기 |
| 길게 누르기 | 길게 터치 | 길게 클릭 | 길게 핀치 |
| 확대 | 두 손가락 핀치 | 트랙패드 핀치 | 두 손가락 핀치 |
| 회전 | 두 손가락 회전 | 트랙패드 회전 | 손목 회전 |
복합 구성 (iOS, macOS, visionOS)
다음 코드는 모든 Apple 플랫폼에서 작동합니다:
struct PlatformGestureView: View {
@State private var scale: CGFloat = 1.0
@State private var offset: CGSize = .zero
@GestureState private var dragState = CGSize.zero
@GestureState private var magnifyState = 1.0
var body: some View {
Circle()
.fill(.green)
.frame(width: 150, height: 150)
.scaleEffect(scale * magnifyState)
.offset(dragState)
.gesture(
DragGesture()
.updating($dragState) { value, state, _ in
state = value.translation
}
.simultaneously(with:
MagnificationGesture()
.updating($magnifyState) { value, state, _ in
state = value.magnification
}
.onEnded { value in
scale *= value.magnification
}
)
)
}
}
차이점:
- iOS: 보기에서 직접 상호 작용
- macOS: 트랙패드 또는 마우스로 상호 작용 (Magic Mouse는 확대/축소와 같은 특정 제스처가 제한될 수 있음)
- visionOS: 공간 제스처를 사용하며, SwiftUI가 자동으로 3D 상호 작용을 처리
패턴 8: 디버깅 제스처
일반적인 문제 및 해결 방법
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
| 제스처가 트리거되지 않음 | 뷰가 hitTest를 차단함 | .contentShape(Rectangle()) 추가 |
| 잘못된 제스처가 실행됨 | 제스처 구성 누락 | .exclusively 또는 .simultaneously 사용 |
| 제스처 후 상태가 재설정됨 | @GestureState 잘못 사용 | @State 및 onEnded 사용 |
| 애니메이션이 끊김 | 직접 상태 변이 | transaction.animation 사용 |
| VoiceOver가 제스처를 무시함 | 접근성 누락 | .accessibilityAction 추가 |
.contentShape() 로 디버깅
// 탭 가능 영역이 뷰 경계와 일치하도록 보장
Rectangle()
.fill(.clear)
.frame(width: 50, height: 50)
.contentShape(Rectangle()) // ← 없으면 투명 뷰가 탭을 차단함
.onTapGesture {
print("탭됨!")
}
제스처 충돌 디버깅
Text("안녕하세요, 세계!")
.onTapGesture { print("텍스트 탭") }
.background(
Color.red
.frame(width: 200, height: 200)
.onTapGesture { print("배경 탭") }
)
문제: 텍스트를 탭하면 배경 탭이 트리거되지 않지만, 텍스트 외부를 탭하면 트리거됩니다.
해결 방법: .simultaneously를 사용하여 두 제스처를 동시에 실행하거나, ZStack 재정렬하여 한 제스처가 다른 제스처보다 우선하도록 합니다.
요약
| 패턴 | 핵심 개념 | API |
|---|---|---|
| 기본 제스처 | 탭, 드래그, 길게 누르기, 확대, 회전 | TapGesture, DragGesture, LongPressGesture, MagnificationGesture, RotationGesture |
| 구성 | 동시, 순차, 배타적 | .simultaneously(with:), .sequenced(before:), .exclusively(before:) |
| 상태 | 임시 vs 영구 | @GestureState, .updating() |
| 사용자 지정 | 재사용 가능한 제스처 로직 | Gesture 프로토콜, .map(), .eraseToAnyGesture() |
| 접근성 | VoiceOver 및 키보드 | .accessibilityAction, .accessibilityAdjustableAction, .onKeyPress() |
| 크로스 플랫폼 | iOS, macOS, visionOS | 동일한 API, 플랫폼별 입력 차이점 |