目录

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开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

接口

[h2]PanGesture

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

创建滑动手势对象。继承自GestureInterface<T>

元服务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,使滑动更灵敏,避免滑动手势与Tabs组件滑动事件的响应结果不符合预期。

当设定的值小于0时,按默认值处理。

当组件应用了scale缩放变换时,distance的实际识别距离会按照scale比例进行缩放。

[h2]PanGesture15+

PanGesture(options?: PanGestureHandlerOptions)

创建滑动手势对象。与PanGesture相比,options参数新增了isFingerCountLimited参数,表示是否检查触摸屏幕的手指数量;distanceMap参数从API version 19开始支持,用于指定不同输入源触发滑动手势事件的最小滑动距离,单位为vp。

元服务API: 从API version 15开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

参数:

参数名 类型 必填 说明
options PanGestureHandlerOptions 否 滑动手势处理器配置参数,用于配置触发滑动手势事件的条件,包括是否检查触摸屏幕的手指数量(isFingerCountLimited)以及为不同输入源指定触发滑动手势事件的最小滑动距离(distanceMap,API version 19开始支持,单位为vp)。当需要配置是否检查触摸屏幕的手指数量,或需要为不同输入源分别指定触发滑动手势事件的最小滑动距离时,传入该参数;不传入时,使用默认滑动手势处理器配置。

PanDirection枚举说明

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

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

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

PanGestureOptions

[h2]constructor

constructor(value?: { fingers?: number; direction?: PanDirection; distance?: number })

创建滑动手势配置参数对象。通过PanGestureOptions对象可以动态修改滑动手势的属性,从而避免通过状态变量修改属性导致UI刷新。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

参数:

参数名 类型 必填 说明
value { fingers?: number; direction?: PanDirection; distance?: number } 否

滑动手势配置参数对象。

fingers用于指定触发滑动的最少手指数,最小为1指, 最大取值为10指。

默认值:1

direction用于指定触发滑动的手势方向,此枚举值支持逻辑与(&)和逻辑或(|)运算。

默认值:PanDirection.All

distance用于指定触发滑动手势事件的最小滑动距离,单位为vp。

取值范围:[0, +∞)

手写笔默认值:8,其余输入源默认值:5

说明:

Tabs组件滑动与该滑动手势事件同时存在时,可将distance值设为1,使滑动更灵敏,避免造成事件错乱。

当设定的值小于0时,按默认值处理。

建议设置合理的滑动距离,滑动距离设置过大时会导致滑动不跟手(响应时延增加)的问题。

当组件应用了scale缩放变换时,distance的实际识别距离会按照scale比例进行缩放。

[h2]setDirection

setDirection(value: PanDirection)

设置滑动方向。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

参数:

参数名 类型 必填 说明
value PanDirection 是

用于指定触发滑动的手势方向,此枚举值支持逻辑与(&)和逻辑或(|)运算。

默认值:PanDirection.All

[h2]setDistance

setDistance(value: number)

设置触发滑动手势事件的最小滑动距离,单位为vp。建议以手写笔8vp、其余输入源5vp为初始值,根据实际交互场景调整滑动距离;滑动距离增大时,可能出现手势跟随效果变差、响应时延增加等问题,导致性能劣化,最佳实践请参考:减小拖动识别距离。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

参数:

参数名 类型 必填 说明
value number 是

触发滑动手势事件的最小滑动距离,单位为vp。

取值范围:[0, +∞)

手写笔默认值:8,其余输入源默认值:5

说明:

Tabs组件滑动与该滑动手势事件同时存在时,可将distance值设为1,使滑动更灵敏,避免滑动手势与Tabs组件滑动事件的响应结果不符合预期。

当设定的值小于0时,按默认值处理。

建议设置合理的滑动距离,滑动距离设置过大时会导致滑动不跟手(响应时延慢)的问题。

当组件应用了scale缩放变换时,distance的实际识别距离会按照scale比例进行缩放。

[h2]setFingers

setFingers(value: number)

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

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

参数:

参数名 类型 必填 说明
value number 是

触发滑动的最少手指数,最小为1指, 最大取值为10指。

默认值:1

[h2]getDirection12+

getDirection(): PanDirection

获取滑动方向。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
PanDirection 当前PanGestureOptions对象中配置的滑动触发方向。

[h2]getDistance18+

getDistance(): number

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

元服务API: 从API version 18开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 当前PanGestureOptions对象中配置的触发滑动手势事件的最小滑动距离,单位为vp。

事件

在GestureEvent的fingerList元素中,手指索引编号与位置相对应,即fingerList[index]的id为index。对于先按下但未参与当前手势触发的手指,fingerList中对应的位置为undefined。建议优先使用fingerInfos。

[h2]onActionStart

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

设置滑动手势识别成功回调。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

参数:

参数名 类型 必填 说明
event (event: GestureEvent) => void 是 滑动手势识别成功时触发的回调函数,回调参数event为GestureEvent对象,用于获取本次滑动手势的事件信息。

[h2]onActionUpdate

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

设置滑动手势更新回调。fingerList包含多根手指时,每次触发该回调仅更新一根手指的位置信息。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

参数:

参数名 类型 必填 说明
event (event: GestureEvent) => void 是 滑动手势更新时触发的回调函数,回调参数event为GestureEvent对象,用于获取滑动过程中的手势事件信息。

[h2]onActionEnd

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

设置滑动手势结束回调。滑动手势识别成功后,手指抬起时触发回调。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

参数:

参数名 类型 必填 说明
event (event: GestureEvent) => void 是 滑动手势结束时触发的回调函数,回调参数event为GestureEvent对象,用于获取滑动结束时的手势事件信息。

[h2]onActionCancel

onActionCancel(event: () => void)

设置滑动手势取消回调。滑动手势识别成功后,接收到触摸取消事件时触发回调。不返回手势事件信息。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

参数:

参数名 类型 必填 说明
event () => void 是 滑动手势取消回调。

[h2]onActionCancel18+

onActionCancel(event: Callback<GestureEvent>)

设置滑动手势取消回调。滑动手势识别成功后,接收到触摸取消事件时触发回调。返回手势事件信息。

元服务API: 从API version 18开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

参数:

参数名 类型 必填 说明
event Callback<GestureEvent> 是 滑动手势取消时触发的回调函数,回调参数为GestureEvent对象,用于获取滑动取消时的手势事件信息。

示例

该示例通过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);
        })
    }
  }
}

示意图:

向左滑动:

点击按钮时,修改PanGesture触发条件为双指向任意方向滑动: