HarmonyOS7 手势系统：Tap/LongPress/Pan 组合拳

文章目录

前言

手势是触屏 app 的灵魂。点一下、长按、拖动------这些"手势"背后是 HarmonyOS 一套统一的手势系统。

这篇文章我把最基础也最常用的三种手势------点击(Tap)、长按(LongPress)、拖拽(Pan)------拆开讲，再告诉你它们怎么组合到一个组件上。学会这三个，大部分交互都能搞定。

Tap：点一下

最简单的点击，用 .onClick 其实也是 Tap 的一种。但要用更细的手势控制（比如双击），用 TapGesture：

代码实现

typescript 复制代码

Text('点我')
  .gesture(
    TapGesture({ count: 1 })    // count=1 单击，=2 双击
      .onAction(() => {
        console.info('被点击了')
      })
  )

count: 1 是单击，count: 2 是双击。
.onAction 在手势识别成功时触发。

小知识：普通 .onClick() 底层就是 TapGesture，日常点击用 onClick 更直观；需要双击/多击才上 TapGesture。

LongPress：长按

长按常用于"弹出菜单""拖拽启动"。用 LongPressGesture：

核心代码

typescript 复制代码

Image($r('app.media.icon'))
  .gesture(
    LongPressGesture({ duration: 500 })   // 按住 500ms 触发
      .onAction(() => {
        this.showMenu()                   // 弹出操作菜单
      })
  )

duration: 500：默认按住 500 毫秒算长按，可调。
常用于"长按删除""长按预览"等场景。

Pan：拖动

拖拽要用 PanGesture，前面拖拽回弹那篇详细讲过，这里复习骨架：

完整示例

typescript 复制代码

.gesture(
  PanGesture()
    .onActionUpdate((e: GestureEvent) => {
      this.offsetX = e.offsetX   // 实时跟手
    })
    .onActionEnd(() => { /* 松手处理 */ })
)

onActionUpdate 里拿 offsetX/offsetY 实时位移，配合 animateTo 做跟手和回弹。

组合多个手势

一个组件上能同时绑多个手势，用 GestureGroup 或链式 .gesture()：

代码解析

typescript 复制代码

.gesture(
  TapGesture({ count: 2 })
    .onAction(() => { this.like() })        // 双击点赞
)
.gesture(
  LongPressGesture({ duration: 600 })
    .onAction(() => { this.showMenu() })    // 长按菜单
)

两个 .gesture() 链式调用，组件既能双击又能长按，互不冲突。系统会按手势特征自动识别用户想做哪个。

手势冲突怎么办

当父子组件都有手势（比如外层可滚动、内层可拖动），可能抢。用 priority 指定优先级：

实现拆解

typescript 复制代码

.gesture(
  PanGesture().onActionUpdate(...),
  GesturePriority.High       // 高优先级，优先识别这个
)

GesturePriority.High/low 控制谁先抢到手势。
复杂嵌套场景才需要，普通页面用默认的就行。

常见误区（小白必踩）

误区	说明
`onClick` 和 `TapGesture` 混用混乱	日常点击用 `onClick` 最直观，需要双击/多击才上 `TapGesture`，别滥用。
手势冲突不 `priority`	父子都有手势时可能抢，用 `GesturePriority` 指定谁优先。
长按 `duration` 不对	默认 500ms，想要"更灵敏"或"更迟钝"自己调。

下面这段代码可以直接复制到 DevEco Studio 里运行。建议你边读边敲，改一改文末「动手改一改」里的参数，亲眼看看效果。

完整可运行示例：三种基础手势

Tap / LongPress / Pan 组合响应。

代码清单

typescript 复制代码

// 组合 Tap / LongPress / Pan
@Entry
@Component
struct Gestures {
  @State info: string = '试试手势'
  build() {
    Column() {
      Text(this.info)
        .padding(40)
        .backgroundColor('#E8F0FE')
        .gesture(
          TapGesture().onAction(() => { this.info = '单击了' })
        )
        .gesture(
          LongPressGesture({ repeat: false })
            .onAction(() => { this.info = '长按了' })
        )
    }.padding(20)
  }
}

你会看到什么 ：点一下文字变「单击了」，长按变「长按了」。gesture 可以链式叠加多个手势识别器。

动手改一改：

加 PanGesture().onActionUpdate 让文字跟手移动。
给 LongPressGesture 设 repeat: true，体验长按连续触发。
用 PriorityGesture 设置手势优先级，解决冲突。

写在最后

三种基础手势：Tap 点、LongPress 按、Pan 拖 。日常 90% 的交互都是它们的组合。记忆法：单击 .onClick、双击/多击 TapGesture、长按 LongPressGesture、拖动 PanGesture、多个手势链式 .gesture() 叠加。

你现在的任务：找个项目里"只有点击"的组件，给加个长按弹出菜单------这一下子就让交互丰富起来了。