PanGesture-Basic Gestures-Gesture Handling-ArkTS Components-ArkUI-Application Framework

PanGesture is used to trigger a pan gesture when the movement distance of a finger on the screen reaches the minimum value.

The table below describes the scenarios that can trigger a pan gesture:

Expand

Trigger Mode	Input Source Type	Input Device Type	Remarks
Swiping with a finger press	SourceTool.Finger	SourceType.TouchScreen	Both axisVertical and axisHorizontal are 0.
Swiping with a left mouse button press	SourceTool.MOUSE	SourceType.Mouse	Both axisVertical and axisHorizontal are 0.
Scrolling with a mouse wheel	SourceTool.MOUSE	SourceType.Mouse	Either axisVertical or axisHorizontal is non-zero.
Swiping after pressing the left button on a touchpad	SourceTool.MOUSE	SourceType.Mouse	Both axisVertical and axisHorizontal are 0.
Swiping with two fingers on a touchpad	SourceTool.TOUCHPAD	SourceType.Mouse	Either axisVertical or axisHorizontal is non-zero.
Swiping with a stylus	SourceTool.Pen	SourceType.TouchScreen	Both axisVertical and axisHorizontal are 0.

NOTE

This API is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

APIs

PanGesture

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

Creates a pan gesture. Inherits from GestureInterface<T>.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
value	{ fingers?: number; direction?: PanDirection; distance?: number } \| PanGestureOptions	No	Parameters for the pan gesture. - fingers: minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10. Default value: 1 Value range: [1, 10] NOTE If the value is less than 1 or is not set, the default value is used. - direction: pan direction. The value supports the AND (&) and OR (\|) operations. Default value: PanDirection.All - distance: minimum pan distance to trigger the gesture, in vp. Value range: [0, +∞) Default value: 8 for the stylus and 5 for other input sources. NOTE If a pan gesture and a tab swipe occur at the same time, set distance to 1 to make the gesture more easily recognizable. If the value specified is less than 0, the default value is used. When the scale attribute is applied to the component, the actual pan distance is adjusted based on the scale ratio.

Name

Type

Mandatory

Description

value

{ fingers?: number; direction?: PanDirection; distance?: number } | PanGestureOptions

Parameters for the pan gesture.

- fingers: minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.

Default value: 1

Value range: [1, 10]

NOTE

If the value is less than 1 or is not set, the default value is used.

- direction: pan direction. The value supports the AND (&) and OR (|) operations.

Default value: PanDirection.All

- distance: minimum pan distance to trigger the gesture, in vp.

Value range: [0, +∞)

Default value: 8 for the stylus and 5 for other input sources.

NOTE

If a pan gesture and a tab swipe occur at the same time, set distance to 1 to make the gesture more easily recognizable.

If the value specified is less than 0, the default value is used.

When the scale attribute is applied to the component, the actual pan distance is adjusted based on the scale ratio.

PanGesture¹⁵⁺

PanGesture(options?: PanGestureHandlerOptions)

Creates a pan gesture. Compared with PanGesture, this API adds the isFingerCountLimited and distanceMap parameters to options, which control whether to enforce the exact number of fingers touching the screen and specify the minimum pan distance required to trigger the gesture for different input sources, respectively.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
options	PanGestureHandlerOptions	No	Parameters of the swipe gesture handler.

PanDirection

Enumerates the pan directions. Unlike SwipeDirection, PanDirection has no angular restrictions.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand

Name	Value	Description
None	0	Panning disabled.
Left	1	Leftward.
Right	2	Rightward.
Horizontal	3	Horizontal direction.
Up	4	Upward.
Down	8	Downward.
Vertical	12	Vertical direction.
All	15	All directions.

PanGestureOptions

constructor

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

Creates a pan gesture configuration object. The PanGestureOptions API enables dynamic updates to pan gesture properties without requiring state variable modifications that would trigger UI re-renders.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
value	{ fingers?: number; direction?: PanDirection; distance?: number }	No	Pan gesture configuration. fingers: minimum number of fingers required. The value ranges from 1 to 10. Default value: 1 direction: pan direction. The value supports the AND (&) and OR (\|) operations. Default value: PanDirection.All distance: minimum pan distance to trigger the gesture, in vp. Default value: 8 for the stylus and 5 for other input sources. NOTE If a pan gesture and a tab swipe occur at the same time, set distance to 1 to make the gesture more easily recognizable. If the value specified is less than 0, the default value is used. To avoid slow response and lagging during scrolling, set a reasonable pan distance. When the scale attribute is applied to the component, the actual pan distance is adjusted based on the scale ratio.

Name

Type

Mandatory

Description

value

{ fingers?: number; direction?: PanDirection; distance?: number }

Pan gesture configuration.

fingers: minimum number of fingers required. The value ranges from 1 to 10.

Default value: 1

direction: pan direction. The value supports the AND (&) and OR (|) operations.

Default value: PanDirection.All

distance: minimum pan distance to trigger the gesture, in vp.

Default value: 8 for the stylus and 5 for other input sources.

NOTE

If a pan gesture and a tab swipe occur at the same time, set distance to 1 to make the gesture more easily recognizable.

If the value specified is less than 0, the default value is used.

To avoid slow response and lagging during scrolling, set a reasonable pan distance.

When the scale attribute is applied to the component, the actual pan distance is adjusted based on the scale ratio.

setDirection

setDirection(value: PanDirection)

Sets the pan direction.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
value	PanDirection	Yes	Pan direction. The value supports the AND (&) and OR (\|) operations. Default value: PanDirection.All

Name

Type

Mandatory

Description

value

PanDirection

Yes

Pan direction. The value supports the AND (&) and OR (|) operations.

Default value: PanDirection.All

setDistance

setDistance(value: number)

Sets the minimum pan distance to trigger the gesture, in vp. An excessively large value can result in delayed responses and accidental gesture releases, which may lead to performance degradation. For best practices, see Reducing the Pan Distance for Gesture Recognition.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
value	number	Yes	Minimum pan distance to trigger the gesture, in vp. Default value: 8 for the stylus and 5 for other input sources. NOTE If a pan gesture and a tab swipe occur at the same time, set distance to 1 to make the gesture more easily recognizable. If the value specified is less than 0, the default value is used. To avoid slow response and lagging during scrolling, set a reasonable pan distance. When the scale attribute is applied to the component, the actual pan distance is adjusted based on the scale ratio.

Name

Type

Mandatory

Description

value

number

Yes

Minimum pan distance to trigger the gesture, in vp.

Default value: 8 for the stylus and 5 for other input sources.

NOTE

If a pan gesture and a tab swipe occur at the same time, set distance to 1 to make the gesture more easily recognizable.

If the value specified is less than 0, the default value is used.

To avoid slow response and lagging during scrolling, set a reasonable pan distance.

When the scale attribute is applied to the component, the actual pan distance is adjusted based on the scale ratio.

setFingers

setFingers(value: number)

Sets the minimum number of fingers to trigger the gesture.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
value	number	Yes	Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10. Default value: 1

Name

Type

Mandatory

Description

value

number

Yes

Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.

Default value: 1

getDirection¹²⁺

getDirection(): PanDirection

Obtains the pan direction.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Expand

Type	Description
PanDirection	Pan direction.

getDistance¹⁸⁺

getDistance(): number

Obtains the minimum pan distance to trigger the gesture.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Expand

Type	Description
number	Minimum pan distance to trigger the gesture.

Events

NOTE

In fingerList of GestureEvent, the index of a finger corresponds to its position, that is, the ID of a finger in fingerList[index] refers to its index. If a finger is pressed first and does not participate in triggering of the current gesture, its position in fingerList is left empty. You are advised to use fingerInfos when possible.

onActionStart

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

Registers the callback for successful pan gesture recognition.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
event	(event: GestureEvent) => void	Yes	Callback for successful pan gesture recognition.

onActionUpdate

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

Registers the callback for pan gesture updates. If fingerList contains multiple fingers, this callback updates the location information of only one finger each time.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
event	(event: GestureEvent) => void	Yes	Callback for pan gesture updates.

onActionEnd

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

Registers the callback for pan gesture completion. This callback is triggered when all fingers are lifted after successful pan gesture recognition.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
event	(event: GestureEvent) => void	Yes	Callback for pan gesture completion.

onActionCancel

onActionCancel(event: () => void)

Registers the callback for pan gesture cancellation. This callback is triggered when a touch cancellation event occurs after successful pan gesture recognition. No gesture event information is returned.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
event	() => void	Yes	Callback for pan gesture cancellation.

onActionCancel¹⁸⁺

onActionCancel(event: Callback<GestureEvent>)

Registers the callback for pan gesture cancellation. This callback is triggered when a touch cancellation event occurs after successful pan gesture recognition. Gesture event information is returned.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand

Name	Type	Mandatory	Description
event	Callback<GestureEvent>	Yes	Callback for pan gesture cancellation.

Example

This example demonstrates the recognition of single-finger and double-finger pan gestures using PanGesture.

Collapse
Word wrap
Dark theme
Copy code
// 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}) // Move the component with its upper left corner as the coordinate origin.
      // Pan left and right to trigger the gesture event
      .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('Set PanGesture Trigger Condition')
        .onClick(() => {
          // Change the trigger condition to double-finger panning in any direction.
          this.panOption.setDirection(PanDirection.All);
          this.panOption.setFingers(2);
        })
    }
  }
}

Diagrams

Panning left:

Click Set PanGesture Trigger Condition to set the pan gesture to be triggered by two fingers moving toward the lower left corner.

PanGesture

APIs

PanGesture

PanGesture15+

PanDirection

PanGestureOptions

constructor

setDirection

setDistance

setFingers

getDirection12+

getDistance18+

Events

onActionStart

onActionUpdate

onActionEnd

onActionCancel

onActionCancel18+

Example

PanGesture¹⁵⁺

getDirection¹²⁺

getDistance¹⁸⁺

onActionCancel¹⁸⁺