OpenHarmony/HarmonyOS开发中的基础手势之PanGesture

PanGesture

作者：坚果
团队：坚果派
公众号：“大前端之旅”
润开鸿技术专家，华为HDE，InfoQ签约作者，OpenHarmony布道师，擅长HarmonyOS应用开发、熟悉服务卡片开发，在“战码先锋”活动中作为大队长，累计培养三个小队长，带领100+队员完成Pr的提交合入。
欢迎通过主页或者私信联系我，加入坚果派，一起学习OpenHarmony/HarmonyO应用开发。

今天我们一起来看一下基础手势的拖动手势。用于触发拖动手势事件，滑动的最小距离为5vp时拖动手势识别成功。

适用

语言：ArkTS

版本：API9

OpenHarmony：3.2Release

HarmonyOS：3.1

接口

interface PanGestureInterface {
    /**
     * Set the value.
     * @since 7
     */
    (value?: {
        fingers?: number;
        direction?: PanDirection;
        distance?: number;
    } | PanGestureOptions): PanGestureInterface;
    /**
     * Pan gesture recognition success callback.
     * @since 7
     */
    onActionStart(event: (event?: GestureEvent) => void): PanGestureInterface;
    /**
     * Callback when the Pan gesture is moving.
     * @since 7
     */
    onActionUpdate(event: (event?: GestureEvent) => void): PanGestureInterface;
    /**
     * The Pan gesture is successfully recognized. When the finger is lifted, the callback is triggered.
     * @since 7
     */
    onActionEnd(event: (event?: GestureEvent) => void): PanGestureInterface;
    /**
     * The Pan gesture is successfully recognized and a callback is triggered when the touch cancel event is received.
     * @since 7
     */
    onActionCancel(event: () => void): PanGestureInterface;
}

接下来对以上几个参数进行说明。

• fingers：触发拖动的最少手指数，最小为1指， 最大取值为10指。默认值：1取值范围：[1,10]说明： 当设置的值小于1或不设置时，会被转化为默认值。
• direction：触发拖动的手势方向，此枚举值支持逻辑与(&)和逻辑或（|）运算。默认值：PanDirection.All
• distance：最小拖动识别距离，单位为vp。默认值：5说明： Tabs组件滑动与该拖动手势事件同时存在时，可将distance值设为1，使拖动更灵敏，避免造成事件错乱。

以上就是几个参数的说明

事件

• onActionStart(event: (event?: GestureEvent) => void)：Pan手势识别成功回调。
• onActionUpdate(event: (event?: GestureEvent) => void)：Pan手势移动过程中回调。
• onActionEnd(event: (event?: GestureEvent) => void)：Pan手势识别成功，手指抬起后触发回调。
• onActionCancel(event: () => void)：Pan手势识别成功，接收到触摸取消事件触发回调。

这里我们继续对后面的几个值进行学习。

PanGestureOptions

declare class PanGestureOptions {
    /**
     * Constructor parameters.
     * @since 7
     */
    constructor(value?: {
        fingers?: number;
        direction?: PanDirection;
        distance?: number;
    });
    /**
     * Sets the direction attribute.
     * @since 7
     */
    setDirection(value: PanDirection);
    /**
     * Sets the setDistance attribute.
     * @since 7
     */
    setDistance(value: number);
    /**
     * Sets the setFingers attribute.
     * @since 7
     */
    setFingers(value: number);
}

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

• fingers：触发拖动的最少手指数，最小为1指， 最大取值为10指。默认值：1
• direction：触发拖动的手势方向，此枚举值支持逻辑与(&)和逻辑或（|）运算。默认值：PanDirection.All
• distance：最小拖动识别距离，单位为vp。默认值：5说明：Tabs组件滑动与该拖动手势事件同时存在时，可将distance值设为1，使拖动更灵敏，避免造成事件错乱。

接口

• setDirection(value: PanDirection)：设置direction属性。
• setDistance(value: number)：设置distance属性。
• setFingers(value: number)：设置fingers属性。

最后我们对上面所用到的枚举值进行学习。

anDirection枚举说明

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

以上就是关于拖动手势所有的学习。

最后给大家附上完整的源码。

// xxx.ets
@Entry
@Component
struct PanGesturePage{
  @State offsetX: number = 0
  @State offsetY: number = 0
  @State positionX: number = 0
  @State positionY: number = 0
  private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Up | 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) => {
           // Pan手势识别成功回调。
            console.info('Pan start')
          })
          .onActionUpdate((event: GestureEvent) => {
            //Pan手势移动过程中回调。
            this.offsetX = this.positionX + event.offsetX
            this.offsetY = this.positionY + event.offsetY
          })
          .onActionEnd(() => {
            //Pan手势识别成功，手指抬起后触发回调。
            this.positionX = this.offsetX
            this.positionY = this.offsetY
            console.info('Pan end')
          }).onActionCancel(()=>{

          //Pan手势识别成功，接收到触摸取消事件触发回调。
          // Pan手势识别成功回调。
          console.info('Pan end')
        })
      )

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