harmony 鸿蒙PanGesture

2025-06-12
浏览 (4)

PanGesture

滑动手势事件，当滑动的最小距离达到设定的最小值时触发滑动手势事件。

以下场景可以触发滑动手势：

触发方式	输入源类型	输入设备类型	备注
手指按下滑动。	SourceTool.Finger	SourceType.TouchScreen	axisVertical和axisHorizontal均为0。
鼠标左键按下滑动。	SourceTool.Mouse	SourceType.Mouse	axisVertical和axisHorizontal均为0。
鼠标滚轮滚动。	SourceTool.Mouse	SourceType.Mouse	axisVertical或axisHorizontal不为0。
触摸板按下左键后滑动。	SourceTool.TouchPad	SourceType.Unknown	axisVertical和axisHorizontal均为0。
触摸板双指滑动。	SourceTool.TouchPad	SourceType.Unknown	axisVertical或axisHorizontal不为0。

说明：

从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

接口

PanGesture(value?: { fingers?: number, direction?: PanDirection, distance?: number }|PanGestureOptions)

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名称	参数类型	必填	参数描述
fingers	number	否	用于指定触发滑动的最少手指数，最小为1指， 最大取值为10指。默认值：1 取值范围：[1,10] 说明：当设置的值小于1或不设置时，会被转化为默认值。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
direction	PanDirection	否	用于指定触发滑动的手势方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。默认值：PanDirection.All。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
distance	number	否	用于指定触发滑动手势事件的最小滑动距离，单位为vp。取值范围：[0, +∞) 手写笔默认值：8，其余输入源默认值：5 说明： Tabs组件滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。当设定的值小于0时，按默认值处理。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。从API version 19开始，手写笔默认值为8，单位为vp。
isFingerCountLimited¹⁵⁺	boolean	否	是否检查触摸屏幕的手指数量。若触摸屏幕的手指数量不等于设置的触发滑动的最少手指数（即上述fingers参数），手势将不会被识别。只有当触摸屏幕的手指数等于设置的触发滑动的最少手指数，并且滑动距离达到阈值时，手势才能被成功识别。对于已成功识别的手势，后续改变触摸屏幕的手指数量不会引发onActionUpdate事件，但可以触发onActionEnd事件。 true：检查触摸屏幕的手指数量。 false：不检查触摸屏幕的手指数量。默认值：false 原子化服务API：从API version 15开始，该接口支持在原子化服务中使用。
distanceMap¹⁹⁺	Map<SourceTool, number>	否	用于指定不同输入源触发拖动手势事件的最小拖动距离，单位为vp。手写笔默认值：8，其余输入源默认值：5 取值范围：[0, +∞)，当设定的值小于0时，按默认值处理。原子化服务API：从API version 19开始，该接口支持在原子化服务中使用。

PanDirection枚举说明

与SwipeDirection不同，PanDirection没有角度限制。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	描述
All	所有方向。
Horizontal	水平方向。
Vertical	竖直方向。
Left	向左滑动。
Right	向右滑动。
Up	向上滑动。
Down	向下滑动。
None	任何方向都不可触发滑动手势事件。

PanGestureOptions

通过PanGestureOptions对象接口可以动态修改平移手势识别器的属性，从而避免通过状态变量修改属性（状态变量修改会导致UI刷新）。

PanGestureOptions(value?: { fingers?: number, direction?: PanDirection, distance?: number })

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名称	参数类型	必填	参数描述
fingers	number	否	用于指定触发滑动的最少手指数，最小为1指， 最大取值为10指。默认值：1
direction	PanDirection	否	用于指定设置滑动方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。默认值：PanDirection.All
distance	number	否	用于指定触发滑动手势事件的最小滑动距离，单位为vp。手写笔默认值：8，其余输入源默认值：5 说明： Tabs组件滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。当设定的值小于0时，按默认值处理。建议设置合理的滑动距离，滑动距离设置过大时会导致滑动不跟手（响应时延慢）的问题。

接口

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	功能描述
setDirection(value: PanDirection)	设置滑动方向。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
setDistance(value: number)	设置触发滑动手势事件的最小滑动距离，单位为vp。取值范围：[0, +∞) 原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
setFingers(value: number)	设置触发滑动的最少手指数。取值范围：[1, 10]，整数。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
getDirection()¹²⁺: PanDirection	获取滑动方向。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
getDistance()¹⁸⁺: (value: number)	获取触发滑动手势事件的最小滑动距离。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

事件

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	功能描述
onActionStart(event: (event: GestureEvent) => void)	Pan手势识别成功回调。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
onActionUpdate(event: (event: GestureEvent) => void)	Pan手势移动过程中回调。 fingerList为多根手指时，该回调监听每次只会更新一根手指的位置信息。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
onActionEnd(event: (event: GestureEvent) => void)	Pan手势识别成功，手指抬起后触发回调。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
onActionCancel(event: () => void)	Pan手势识别成功，接收到触摸取消事件触发回调。不返回手势事件信息。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
onActionCancel(event: Callback<GestureEvent>)¹⁸⁺	Pan手势识别成功，接收到触摸取消事件触发回调。返回手势事件信息。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

属性

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	描述
tag¹¹⁺	string	设置Pan手势标志，用于自定义手势判定时区分绑定的手势。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
allowedTypes¹⁴⁺	Array<SourceTool>	设置Pan手势支持的事件输入源。原子化服务API：从API version 14开始，该接口支持在原子化服务中使用。

示例

该示例通过PanGesture实现了单指/双指滑动手势的识别。

// xxx.ets
@Entry
@Component
struct PanGestureExample {
  @State offsetX: number = 0;
  @State offsetY: number = 0;
  @State positionX: number = 0;
  @State positionY: number = 0;
  private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Left|PanDirection.Right });

  build() {
    Column() {
      Column() {
        Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY)
      }
      .height(200)
      .width(300)
      .padding(20)
      .border({ width: 3 })
      .margin(50)
      .translate({ x: this.offsetX, y: this.offsetY, z: 0 }) // 以组件左上角为坐标原点进行移动
      // 左右滑动触发该手势事件
      .gesture(
      PanGesture(this.panOption)
        .onActionStart((event: GestureEvent) => {
          console.info('Pan start');
          console.info('Pan start timeStamp is: ' + event.timestamp);
        })
        .onActionUpdate((event: GestureEvent) => {
          if (event) {
            this.offsetX = this.positionX + event.offsetX;
            this.offsetY = this.positionY + event.offsetY;
          }
        })
        .onActionEnd((event: GestureEvent) => {
          this.positionX = this.offsetX;
          this.positionY = this.offsetY;
          console.info('Pan end');
          console.info('Pan end timeStamp is: ' + event.timestamp);
        })
      )

      Button('修改PanGesture触发条件')
        .onClick(() => {
          // 将PanGesture手势事件触发条件改为双指以任意方向滑动
          this.panOption.setDirection(PanDirection.All);
          this.panOption.setFingers(2);
        })
    }
  }
}

示意图：

向左滑动：

zh-cn_image_0000001174264374

点击按钮修改PanGesture触发条件，双指向左下方滑动：

zh-cn_image1_0000001174264374

你可能感兴趣的鸿蒙文章

harmony 鸿蒙图像AI分析错误码

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙弹出框 (Dialog)

harmony 鸿蒙DialogV2

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/z0k7T5

热门推荐

1、直接访问google.com
2、 - 优质文章
3、 gate.io
4、 harmony 鸿蒙hdc使用指导
5、 harmony 鸿蒙ArkUI组件（ArkTS）开发常见问题
6、 harmony 鸿蒙初识ArkTS语言
7、 flink kafka connector scan.startup.mode 的几个选项
8、 golang
9、 openharmony
10、 Vue中input框自动聚焦

Loading...