RotationGesture is used to trigger a rotation gesture, which recognizes rotational movements using two to five fingers, with a minimum angular change of 1 degree. This gesture cannot be triggered using a two-finger rotation operation on a trackpad.
The initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
[h2]RotationGesture
RotationGesture(value?: { fingers?: number; angle?: number })
Sets the parameters for the rotation 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
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | { fingers?: number; angle?: number } | No | Parameters for the rotation gesture. - fingers: minimum number of fingers to trigger the rotation gesture. Default value: 2 Value range: [2, 5]. Values less than 2 or greater than 5 are automatically adjusted to the default value. While more fingers than the minimum number can be pressed to trigger the gesture, only the first two fingers participate in gesture calculation. - angle: minimum angular change required to trigger the rotation gesture; unit: deg. Default value: 1 NOTE If the value is less than or equal to 0 or greater than 360, it will be converted to the default value. |
[h2]RotationGesture15+
RotationGesture(options?: RotationGestureHandlerOptions)
Sets the parameters for the rotation gesture. Compared with RotationGesture, this API adds the isFingerCountLimited parameter to options, which determines whether to enforce the exact number of fingers touching the screen.
Atomic service API: This API can be used in atomic services since API version 15.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | RotationGestureHandlerOptions | No | Parameters of the rotation gesture handler. |
Events
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.
[h2]onActionStart
onActionStart(event: (event: GestureEvent) => void)
Triggered when the rotation gesture is recognized successfully.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| event | (event: GestureEvent) => void | Yes | Callback for the gesture event. |
[h2]onActionUpdate
onActionUpdate(event: (event: GestureEvent) => void)
Triggered during the movement of the rotation gesture.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| event | (event: GestureEvent) => void | Yes | Callback for the gesture event. |
[h2]onActionEnd
onActionEnd(event: (event: GestureEvent) => void)
Triggered when the last finger used for the rotation gesture is lifted.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| event | (event: GestureEvent) => void | Yes | Callback for the gesture event. |
[h2]onActionCancel
onActionCancel(event: () => void)
Triggered when a tap cancellation event is received after the rotation gesture is recognized. This callback does not return gesture event information.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| event | () => void | Yes | Callback for the gesture event. |
[h2]onActionCancel18+
onActionCancel(event: Callback<GestureEvent>)
Triggered when a tap cancellation event is received after the rotation gesture is recognized. Compared with onActionCancel, this callback returns gesture event information.
Atomic service API: This API can be used in atomic services since API version 18.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| event | Callback<GestureEvent> | Yes | Callback for the gesture event. |
Example
This example demonstrates the recognition of a two-finger rotation gesture using RotationGesture.
// xxx.ets
@Entry
@Component
struct RotationGestureExample {
@State angle: number = 0;
@State rotateValue: number = 0;
build() {
Column() {
Column() {
Text('RotationGesture angle:' + this.angle)
}
.height(200)
.width(300)
.padding(20)
.border({ width: 3 })
.margin(80)
.rotate({ angle: this.angle })
// The gesture event is triggered by rotating with two fingers.
.gesture(
RotationGesture()
.onActionStart((event: GestureEvent) => {
console.info('Rotation start')
})
.onActionUpdate((event: GestureEvent) => {
if (event) {
this.angle = this.rotateValue + event.angle
}
})
.onActionEnd((event: GestureEvent) => {
this.rotateValue = this.angle
console.info('Rotation end')
})
)
}.width('100%')
}
} 