d552b223创建于 2025年8月15日历史提交

PanGesture

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

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

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

说明：

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

接口

PanGesture

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

设置滑动手势事件。

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

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

参数：

参数名	类型	必填	说明
value	{ fingers?: number; direction?: PanDirection; distance?: number } \| PanGestureOptions	否	设置拖动手势事件参数。 - fingers：用于指定触发滑动的最少手指数，最小为1指，最大取值为10指。默认值：1 取值范围：[1, 10] 说明：当设置的值小于1或不设置时，会被转化为默认值。 - direction：用于指定触发滑动的手势方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。默认值：PanDirection.All - distance：用于指定触发滑动手势事件的最小滑动距离，单位为vp。取值范围：[0, +∞) 手写笔默认值：8，其余输入源默认值：5 说明： Tabs组件滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。当设定的值小于0时，按默认值处理。

PanGesture¹⁵⁺

PanGesture(options?: PanGestureHandlerOptions)

设置拖动手势事件。与PanGesture相比，options参数新增了对isFingerCountLimited和distanceMap参数，分别表示是否检查触摸屏幕的手指数量以及指定不同输入源触发拖动手势事件的最小拖动距离。

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

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

参数：

参数名	类型	必填	说明
options	PanGestureHandlerOptions	否	拖动手势处理器配置参数。

PanDirection枚举说明

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

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

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

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

PanGestureOptions

constructor

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

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

原子化服务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时，按默认值处理。建议设置合理的滑动距离，滑动距离设置过大时会导致滑动不跟手（响应时延慢）的问题。

constructor²⁰⁺

constructor(value?: PanGestureHandlerOptions)

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

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

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

参数：

参数名	类型	必填	说明
value	PanGestureHandlerOptions	否	拖动手势处理器配置参数。

setDirection

setDirection(value: PanDirection)

设置滑动方向。

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

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

参数：

参数名	类型	必填	说明
value	PanDirection	是	用于指定设置滑动方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。默认值：PanDirection.All

setDirection²⁰⁺

setDirection(value: PanDirection): void

设置滑动方向。

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

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

参数：

参数名	类型	必填	说明
value	PanDirection	是	用于指定设置滑动方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。默认值：PanDirection.All

setDistance

setDistance(value: number)

设置触发滑动手势事件的最小滑动距离，单位为vp。距离值不宜设置过大，避免因滑动脱手，响应时延过大等问题导致性能劣化，最佳实践请参考：减小拖动识别距离。

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

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

参数：

参数名	类型	必填	说明
value	number	是	用于指定触发滑动手势事件的最小滑动距离，单位为vp。手写笔默认值：8，其余输入源默认值：5 说明： Tabs组件滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。当设定的值小于0时，按默认值处理。建议设置合理的滑动距离，滑动距离设置过大时会导致滑动不跟手（响应时延慢）的问题。

setDistance²⁰⁺

setDistance(value: number): void

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

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

参数：

参数名	类型	必填	说明
value	number	是	用于指定触发滑动手势事件的最小滑动距离，单位为vp。手写笔默认值：8，其余输入源默认值：5 说明： Tabs组件滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。当设定的值小于0时，按默认值处理。建议设置合理的滑动距离，滑动距离设置过大时会导致滑动不跟手（响应时延慢）的问题。

setFingers

setFingers(value: number)

设置触发滑动的最少手指数。

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

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

参数：

参数名	类型	必填	说明
value	number	是	用于指定触发滑动的最少手指数，最小为1指，最大取值为10指。默认值：1

setFingers²⁰⁺

setFingers(value: number): void

设置触发滑动的最少手指数。

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

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

参数：

参数名	类型	必填	说明
value	number	是	用于指定触发滑动的最少手指数，最小为1指，最大取值为10指。默认值：1

getDirection¹²⁺

getDirection(): PanDirection

获取滑动方向。

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

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

返回值：

类型	说明
PanDirection	返回滑动方向。

getDistance¹⁸⁺

getDistance(): number

获取触发滑动手势事件的最小滑动距离。

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

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

返回值：

类型	说明
number	返回滑动手势事件的最小滑动距离。

事件

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

onActionStart

onActionStart(event: (event: GestureEvent) => void)

Pan手势识别成功回调。

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

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

参数：

参数名	类型	必填	说明
event	(event: GestureEvent) => void	是	手势事件回调函数。

onActionUpdate

onActionUpdate(event: (event: GestureEvent) => void)

Pan手势移动过程中回调。fingerList为多根手指时，该回调监听每次只会更新一根手指的位置信息。

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

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

参数：

参数名	类型	必填	说明
event	(event: GestureEvent) => void	是	手势事件回调函数。

onActionEnd

onActionEnd(event: (event: GestureEvent) => void)

Pan手势识别成功，手指抬起后触发回调。

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

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

参数：

参数名	类型	必填	说明
event	(event: GestureEvent) => void	是	手势事件回调函数。

onActionCancel

onActionCancel(event: () => void)

Pan手势识别成功，接收到触摸取消事件触发回调。不返回手势事件信息。

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

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

参数：

参数名	类型	必填	说明
event	() => void	是	手势事件回调函数。

onActionCancel¹⁸⁺

onActionCancel(event: Callback<GestureEvent>)

Pan手势识别成功，接收到触摸取消事件触发回调。返回手势事件信息。

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

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

参数：

参数名	类型	必填	说明
event	Callback<GestureEvent>	是	手势信息回调函数。

属性

系统能力： 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

PanGesture

接口

PanGesture

PanGesture15+

PanDirection枚举说明

PanGestureOptions

constructor

constructor20+

setDirection

setDirection20+

setDistance

setDistance20+

setFingers

setFingers20+

getDirection12+

getDistance18+

事件

onActionStart

onActionUpdate

onActionEnd

onActionCancel

onActionCancel18+

属性

示例

PanGesture¹⁵⁺

constructor²⁰⁺

setDirection²⁰⁺

setDistance²⁰⁺

setFingers²⁰⁺

getDirection¹²⁺

getDistance¹⁸⁺

onActionCancel¹⁸⁺