swiftUI 手势完全指南：让你的界面学会“倾听”

如果你对手势的认知还停留在 .onTapGesture，那么你只打开了手势世界的门缝。本文带你走进 SwiftUI 手势引擎的核心地带，从"听懂"一次触碰，到指挥一整个手势交响乐团。读完你会明白，原来一个拖拽、一次缩放，背后是优雅的状态机设计，而不是一堆回调的堆砌。

---

一、 全景地图：本篇讲什么？

我们不会逐条罗列 API------那是文档的事。本篇要帮你勾勒出 SwiftUI 手势系统的骨架与灵魂，核心就三板斧：

1. 理解"状态驱动" ：为什么手势的状态最适合用 @GestureState，而不是 @State。
2. 掌握组合法则：如何让拖动和缩放同时发生？如何让长按之后才允许拖拽？这全靠三种组合运算符。
3. 驯服手势冲突：当父视图与子视图都想抢触摸事件时，谁赢？如何控制优先级？

掌握了这些核心概念，剩下的 TapGesture、DragGesture 不过是积木块，你完全可以自由拼装出任何交互效果。

---

二、 第一性原理：手势是一台微型状态机

想象你的手指按在屏幕上：系统在飞快地记录 began → changed → ended 这一连串事件。SwiftUI 把这些事件抽象成了手势识别器，并根据你绑定的状态实时刷新视图。

但问题来了：如果我们在 onChanged 里手动修改 @State var offset，手指抬起时还要记得在 onEnded 里复原它，非常容易出错。于是 SwiftUI 提供了一个为手势而生的属性包装器：

@GestureState ------ 会"自愈"的手势状态

@GestureState private var offset = CGSize.zero

• 它在手势进行中可变。
• 手势结束（或取消）时，自动恢复到初始值。
• 不需要你写任何复原代码。

配合 updating(_:body:) 方法，代码立刻清爽：

Circle()
    .offset(offset)
    .gesture(
        DragGesture()
            .updating($offset) { value, state, _ in
                state = value.translation
            }
    )

手指抬起的瞬间，圆自动弹回原位------没有任何手动 withAnimation 或 = .zero。这就是 SwiftUI 手势的状态哲学：让状态与手势生命周期自动绑定。

---

三、 基础手势速览：蓄满你的"武器库"

这些是基础识别器，你应该像熟悉数字一样熟悉它们：

手势	类型	典型用途
TapGesture(count:)	离散	点击（或双击、三击）
LongPressGesture(minimumDuration:)	离散/连续	长按弹出菜单、进入编辑
DragGesture(minimumDistance:)	连续	拖拽、滑动解锁、卡片平移
MagnificationGesture()	连续	缩放图片、地图
RotationGesture()	连续	旋转图片、游戏对象

两条铁律：

• 离散手势用 onEnded 监听。
• 连续手势用 updating 配合 @GestureState 监听，除非你需要累积历史值（如累积缩放倍数），才启用 @State 存储基础值并在 onChanged 中累加。

---

四、 进阶：指挥手势的"三重奏"

单个手势只是独奏。真正的交互往往需要几个手势协同工作。SwiftUI 提供了三种组合操作符，就像三个指挥棒：

4.1 同时进行：simultaneously(with:)

让拖拽和旋转同时发生，像这样：

DragGesture()
    .updating($offset) { ... }
    .simultaneously(with:
        RotationGesture()
            .updating($angle) { ... }
    )

想象用两根手指同时移动和旋转一张照片：它们是平等的，互不干扰。

4.2 顺序进行：sequenced(before:)

"先长按，再拖动"用来实现列表重新排序：

LongPressGesture(minimumDuration: 0.5)
    .sequenced(before: DragGesture())
    .onEnded { value in
        switch value {
        case .second(true, let drag):
            // 长按成功，现在可以取到拖拽位移
        default: break
        }
    }

注意：sequenced 返回的类型是 SequenceGesture，它的 .onEnded 接收的是一个枚举值，你要判断第一阶段是否成功，再拆出第二阶段的值。

4.3 互斥进行：exclusively(before:)

"先试试点击，如果失效再试试长按"，防止按钮长按时触发点击：

TapGesture()
    .exclusively(before: LongPressGesture(minimumDuration: 1.0))
    .onEnded { result in
        switch result {
        case .first(_): print("普通点击")
        case .second(true): print("长按")
        }
    }

这样在同一个视图上双击和单机可以共存，系统会根据你的组合规则决定最终触发哪一个。

组合心法 ：当你觉得手势"打架"时，别急着加标志位，看看能不能用 simultaneously、sequenced、exclusively 直接表达关系。声明式地描述手势关系，代码会少很多 Bug。

---

五、 手势冲突调解：谁才是真正的"触摸之王"？

当父视图是 ScrollView，子视图是一个可拖拽的卡片，会发生什么？ ScrollView 会"吃掉"你的拖拽，卡片纹丝不动。

SwiftUI 默认优先把事件交给最深的子视图，但你可以显式改变优先级：

• .highPriorityGesture()：把这个手势提升到最高优先级，其他同层或父层手势识别失败才会轮到它。用它给子视图开"绿色通道"。
• .simultaneousGesture()：告诉系统这个手势可以和你的其他手势一起识别，别二选一。

示例：在滚动列表中给每一行附加一个横向轻扫手势：

List {
    ForEach(items) { item in
        ItemRow(item: item)
            .highPriorityGesture(
                DragGesture(minimumDistance: 20)
                    .onEnded { value in
                        if value.translation.width < -50 {
                            // 左滑删除
                        }
                    }
            )
    }
}

这行代码让轻扫手势优先于列表的垂直滚动识别，完美解决了冲突。

---

六、 实战锦囊：增色手势体验的三个细节

6.1 触觉反馈：让界面"有触感"

let feedback = UIImpactFeedbackGenerator(style: .medium)

Circle()
    .gesture(
        DragGesture()
            .onChanged { value in
                if abs(value.translation.width) > 100 {
                    feedback.impactOccurred()
                }
            }
    )

超过阈值时给一个轻微震动，立刻有了物理感。轻量级震动 (selectionChanged) 适合吸附操作。

6.2 惯性动画：松手后也不"死板"

手指划得快时，我们希望视图带着惯性继续滑动一段再停止。利用 predictedEndTranslation 配合弹簧动画：

.onEnded { value in
    withAnimation(.spring(duration: 0.6, bounce: 0.2)) {
        offset = value.predictedEndTranslation
    }
}

如果再结合边界限制，就会得到像 iOS 相册一样的平滑拖拽体验。

6.3 边界钳制：画地为牢也优雅

用 GeometryReader 获取容器尺寸，在手势更新中计算合法区间。注意使用 value.location（绝对位置）而不是 translation 做边界判断更准确。

.onChanged { value in
    let newX = min(max(value.location.x, minX), maxX)
    let newY = min(max(value.location.y, minY), maxY)
    position = CGPoint(x: newX, y: newY)
}

---

七、 无障碍与性能：高级开发者的必修课

无障碍

所有手势操作都应提供非手势的替代方式 （按钮、菜单）。使用 .accessibilityAction 和 .accessibilityHint 描述自定义手势，并尊重系统的"减弱动态效果"设置：

@Environment(\.accessibilityReduceMotion) var reduceMotion
if reduceMotion { /* 跳过动画或使用极简效果 */ }

性能

• onChanged / updating 每帧调用，避免复杂计算。
• 多用 @GestureState 而非 @State，减少不必要的重绘。
• 复杂视图在手势驱动时，考虑启用 drawingGroup() 提升渲染效率。

---

八、 总结：建立你的手势心智模型

SwiftUI 手势系统的本质是声明式状态机：

• 你的手势定义了状态如何变化。
• @GestureState 管理临时状态，保证自愈。
• 组合操作符 (simultaneously, sequenced, exclusively) 定义状态机之间的转换关系。
• 优先级修饰符 (highPriorityGesture) 决定状态机的触发顺序。

带着这个模型去写代码，你就不会在 onChanged 里迷失方向，也不会在手势冲突时束手无策。