Gestos individuales en ArkUI

Los gestos en aplicaciones móviles permiten la interacción del usuario con la interfaz mediante toques, deslizamientos, pellizcos y otras acciones sobre la pantalla táctil. HarmonyOS proporciona un conjunto completo de reconocedores de gestos dentro del framework ArkUI.

1. TapGesture

El gesto de toque detecta cuando el usuario presiona y libera rápidamente la pantalla. Se puede configurar para reconocer múltiples toques consecutivos o múltiples dedos.

Parámetros del constructor:

• count: Número de toques consecutivos requeridos. Por defecto 1. El intervalo máximo entre toques es de 300ms.
• fingers: Cantidad de dedos necesarios. Rango 1-10, por defecto 1.

// archivo: MainApp.ets
@Entry
@Component
struct MainApp {
  @State lastTapInfo: string = "Sin eventos";

  build() {
    Column() {
      Text('Doble toque para activar')
        .fontSize(26)
        .gesture(
          TapGesture({ count: 2 })
            .onAction((evt: GestureEvent) => {
              this.lastTapInfo = `Toque detectado en X:${evt.fingerList[0].localX.toFixed(0)}`;
            })
        )
      Text(this.lastTapInfo)
        .fontSize(18)
        .margin({ top: 12 })
    }
    .width(280)
    .height(220)
    .padding(16)
    .border({ width: 2 })
    .margin(24)
  }
}

2. LongPressGesture

Este gesto se activa cuando el usuario mantiene presionado un elemento durante un período determinado. Es útil para mostrar menús contextuales, iniciar modos de edición o habilitar arrastre.

Parámetros del constructor:

• fingers: Dedos mínimos requeridos (1-10), por defecto 1.
• repeat: Si es true, dispara el callback continuamente mientras se mantiene la presión.
• duration: Tiempo mínimo de presión en ms. Por defecto 500.

// archivo: LongPressDemo.ets
@Entry
@Component
struct LongPressDemo {
  @State pressCounter: number = 0;

  build() {
    Column() {
      Text(`Pulsaciones repetidas: ${this.pressCounter}`)
        .fontSize(26)
        .gesture(
          LongPressGesture({ repeat: true, duration: 400 })
            .onAction((evt: GestureEvent) => {
              if (evt.repeat) {
                this.pressCounter += 1;
              }
            })
            .onActionEnd(() => {
              this.pressCounter = 0;
            })
        )
    }
    .width(260)
    .height(180)
    .padding(18)
    .border({ width: 2 })
    .margin(24)
  }
}

3. PanGesture

El gesto de arrastre detecta el movimiento del dedo sobre la pantalla después de un toque inicial. Permite desplazar elementos, hacer scroll de contenido o reorganizar componentes visuales.

Parámetros de PanGestureOptions:

• fingers: Cantidad mínima de dedos (1-10), por defecto 1.
• direction: Dirección del desplazamiento mediante PanDirection, soporta operadores bit a bit.
• distance: Distancia mínima de reconocimiento en vp, por defecto 5.

// archivo: DragDemo.ets
@Entry
@Component
struct DragDemo {
  @State deltaX: number = 0;
  @State deltaY: number = 0;
  @State savedX: number = 0;
  @State savedY: number = 0;

  build() {
    Column() {
      Text(`Desplazamiento - X: ${this.deltaX.toFixed(0)} | Y: ${this.deltaY.toFixed(0)}`)
        .fontSize(22)
        .height(180)
        .width(280)
        .padding(16)
        .border({ width: 2 })
        .translate({ x: this.deltaX, y: this.deltaY, z: 0 })
        .gesture(
          PanGesture()
            .onActionStart(() => {
              console.info('Inicio de arrastre');
            })
            .onActionUpdate((evt: GestureEvent) => {
              this.deltaX = this.savedX + evt.offsetX;
              this.deltaY = this.savedY + evt.offsetY;
            })
            .onActionEnd(() => {
              this.savedX = this.deltaX;
              this.savedY = this.deltaY;
            })
        )
    }
    .width('100%')
    .height(240)
  }
}

4. PinchGesture

El gesto de pellizco utiliza dos o más dedos que se acercan o separan simultáneamente. Se emplea comúnmente para escalar imágenes, mapas y otros contenidos visuales.

Parámetros del constructor:

• fingers: Dedos mínimos requeridos (2-5), por defecto 2.
• distance: Distancia mínima de reconocimiento en vp, por defecto 5.

// archivo: PinchDemo.ets
@Entry
@Component
struct PinchDemo {
  @State currentScale: number = 1;
  @State baseScale: number = 1;
  @State centerX: number = 0;
  @State centerY: number = 0;

  build() {
    Column() {
      Column() {
        Text(`Escala actual: ${this.currentScale.toFixed(2)}`)
        Text(`Centro: (${this.centerX.toFixed(0)}, ${this.centerY.toFixed(0)})`)
      }
      .height(180)
      .width(280)
      .border({ width: 2 })
      .margin({ top: 80 })
      .scale({ x: this.currentScale, y: this.currentScale, z: 1 })
      .gesture(
        PinchGesture({ fingers: 3 })
          .onActionStart(() => {
            console.info('Inicio de pellizco');
          })
          .onActionUpdate((evt: GestureEvent) => {
            this.currentScale = this.baseScale * evt.scale;
            this.centerX = evt.pinchCenterX;
            this.centerY = evt.pinchCenterY;
          })
          .onActionEnd(() => {
            this.baseScale = this.currentScale;
            console.info('Fin de pellizco');
          })
      )
    }
  }
}

5. RotationGesture

El gesto de rotación reconoce cuando el usuario coloca dos dedos sobre la pantalla y los mueve describiendo un arco. Es ideal para rotar imágenes, mapas u otros objetos visuales.

Parámetros del constructor:

• fingers: Dedos mínimos requeridos (2-5), por defecto 2.
• angle: Cambio angular mínimo en grados para activar el gesto, por defecto 1.

// archivo: RotationDemo.ets
@Entry
@Component
struct RotationDemo {
  @State visualAngle: number = 0;
  @State storedAngle: number = 0;

  build() {
    Column() {
      Text(`Ángulo de rotación: ${this.visualAngle.toFixed(1)}°`)
        .fontSize(26)
        .rotate({ angle: this.visualAngle })
        .gesture(
          RotationGesture()
            .onActionStart(() => {
              console.info('Rotación iniciada');
            })
            .onActionUpdate((evt: GestureEvent) => {
              this.visualAngle = this.storedAngle + evt.angle;
            })
            .onActionEnd(() => {
              this.storedAngle = this.visualAngle;
              console.info('Rotación finalizada');
            })
            .onActionCancel(() => {
              console.info('Rotación cancelada');
            })
        )
    }
    .width(280)
    .height(220)
  }
}

6. SwipeGesture

El gesto de deslizamiento detecta movimientos rápidos del dedo en una dirección específica. Se utiliza para navegación entre páginas, cambio de imágenes o acciones de eliminación.

Parámetros del constructor:

• fingers: Dedos mínimos requeridos (1-10), por defecto 1.
• direction: Dirección del deslizamiento mediante SwipeDirection, soporta operadores bit a bit.
• speed: Velocidad mínima de reconocimiento en vp/s, por defecto 100.

// archivo: SwipeDemo.ets
@Entry
@Component
struct SwipeDemo {
  @State swipeSpeed: number = 0;
  @State swipeAngle: number = 0;

  build() {
    Column() {
      Column() {
        Text(`Velocidad: ${this.swipeSpeed.toFixed(0)} vp/s`)
        Text(`Ángulo: ${this.swipeAngle.toFixed(0)}°`)
      }
      .border({ width: 2 })
      .width(280)
      .height(180)
      .margin(80)
      .rotate({ angle: this.swipeAngle })
      .gesture(
        SwipeGesture({ direction: SwipeDirection.Vertical })
          .onAction((evt: GestureEvent) => {
            this.swipeSpeed = evt.speed;
            this.swipeAngle = evt.angle;
          })
      )
    }
  }
}