SwiftUI 手势识别 是做什么的?
涵盖手势识别、组合模式、状态管理及无障碍集成的全面指南。
何时使用本技能
- 实现轻点、拖拽、长按、缩放或旋转手势
- 组合多个手势(同时、顺序、独占)
- 使用
GestureState管理手势状态 - 创建自定义手势识别器
- 调试手势冲突或无响应手势
- 为 VoiceOver 实现手势的无障碍访问
- 跨平台手势处理(iOS, macOS, visionOS)
示例提示
以下是开发者提出的真实问题,本技能旨在解答它们:
1. "我的拖拽手势不起作用——拖拽时视图不动。如何调试?"
→ 该技能涵盖了 DragGesture 状态管理模式,并展示了如何正确使用 @GestureState 更新视图偏移量
2. "我在同一个视图上同时有轻点手势和拖拽手势。轻点有效,但拖拽无效。如何修复?"
→ 该技能演示了使用 .simultaneously、.sequenced 和 .exclusively 进行手势组合以解决手势冲突
3. "我希望用户先长按才能拖拽项目。如何链接手势?"
→ 该技能展示了按正确顺序将 LongPressGesture 与 DragGesture 结合使用的 .sequenced 模式
4. "手势结束时我的手势状态没有重置。视图停留在错误位置。"
→ 该技能介绍了 @GestureState 的自动重置行为以及用于正确状态管理的 updating 参数
5. "使用 VoiceOver 的用户无法访问需要手势的功能。如何使手势变得无障碍?"
→ 该技能演示了 .accessibilityAction 模式以及为 VoiceOver 用户提供替代交互的方法
选择正确的手势(决策树)
你需要什么交互?
├─ 单次轻点/点击?
│ └─ 使用 Button(推荐)或 TapGesture
│
├─ 拖拽/平移移动?
│ └─ 使用 DragGesture
│
├─ 按住后执行操作?
│ └─ 使用 LongPressGesture
│
├─ 捏合缩放?
│ └─ 使用 MagnificationGesture
│
├─ 双指旋转?
│ └─ 使用 RotationGesture
│
├─ 多个手势一起使用?
│ ├─ 同时进行?→ .simultaneously
│ ├─ 一个接一个?→ .sequenced
│ └─ 要么这个要么那个?→ .exclusively
│
└─ 复杂的自定义行为?
└─ 创建符合 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(\