1# RotationGesture 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9**RotationGesture** is used to trigger a rotation gesture, which requires two to five fingers with a minimum 1-degree rotation angle. This gesture cannot be triggered using a two-finger rotation operation on a trackpad. 10 11> **NOTE** 12> 13> This gesture is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 14 15 16## APIs 17 18### RotationGesture 19 20RotationGesture(value?: { fingers?: number, angle?: number }) 21 22Sets the parameters for the rotation gesture. 23 24**Atomic service API**: This API can be used in atomic services since API version 11. 25 26**System capability**: SystemCapability.ArkUI.ArkUI.Full 27 28**Parameters** 29 30| Name| Type| Mandatory| Description| 31| -------- | -------- | -------- | -------- | 32| value | { fingers?: number, angle?: number } | No| Parameters for the rotation gesture.<br> - **fingers**: minimum number of fingers to trigger a rotation. The value ranges from 2 to 5.<br>Default value: **2**<br>While more fingers than the minimum number can be pressed to trigger the gesture, only the first two fingers participate in gesture calculation.<br> - **angle**: minimum angle change required to trigger the rotation gesture, in degrees (deg).<br>Default value: **1**<br>**NOTE**<br>If the value is less than or equal to 0 or greater than 360, it will be converted to the default value.| 33 34### RotationGesture<sup>15+</sup> 35 36RotationGesture(options?: RotationGestureHandlerOptions) 37 38Sets the parameters for the rotation gesture. Compared with [RotationGesture](#rotationgesture-1), this API adds the **isFingerCountLimited** parameter to **options**, which determines whether to enforce the exact number of fingers touching the screen. 39 40**Atomic service API**: This API can be used in atomic services since API version 15. 41 42**System capability**: SystemCapability.ArkUI.ArkUI.Full 43 44**Parameters** 45 46| Name| Type| Mandatory| Description| 47| -------- | -------- | -------- | -------- | 48| options | [RotationGestureHandlerOptions](./ts-uigestureevent.md#rotationgesturehandleroptions) | No|Parameters of the rotation gesture handler.| 49 50 51## Events 52 53> **NOTE** 54> 55> In **fingerList** of [GestureEvent](ts-gesture-settings.md#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. 56 57### onActionStart 58 59onActionStart(event: (event: GestureEvent) => void) 60 61Triggered when a rotation gesture is recognized. 62 63**Atomic service API**: This API can be used in atomic services since API version 11. 64 65**System capability**: SystemCapability.ArkUI.ArkUI.Full 66 67**Parameters** 68 69| Name| Type | Mandatory| Description | 70| ------ | ------------------------------------------ | ---- | ---------------------------- | 71| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the gesture event.| 72 73### onActionUpdate 74 75onActionUpdate(event: (event: GestureEvent) => void) 76 77Triggered when the user moves the finger in a rotation gesture on the screen. 78 79**Atomic service API**: This API can be used in atomic services since API version 11. 80 81**System capability**: SystemCapability.ArkUI.ArkUI.Full 82 83**Parameters** 84 85| Name| Type | Mandatory| Description | 86| ------ | ------------------------------------------ | ---- | ---------------------------- | 87| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the gesture event.| 88 89### onActionEnd 90 91onActionEnd(event: (event: GestureEvent) => void) 92 93Triggered when the finger used for the rotation gesture is lifted. 94 95**Atomic service API**: This API can be used in atomic services since API version 11. 96 97**System capability**: SystemCapability.ArkUI.ArkUI.Full 98 99**Parameters** 100 101| Name| Type | Mandatory| Description | 102| ------ | ------------------------------------------ | ---- | ---------------------------- | 103| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the gesture event.| 104 105### onActionCancel 106 107onActionCancel(event: () => void) 108 109Triggered when a tap cancellation event is received after the rotation gesture is recognized. No gesture event information is returned. 110 111**Atomic service API**: This API can be used in atomic services since API version 11. 112 113**System capability**: SystemCapability.ArkUI.ArkUI.Full 114 115**Parameters** 116 117| Name| Type | Mandatory| Description | 118| ------ | ------------------------------------------ | ---- | ---------------------------- | 119| event | () => void | Yes | Callback for the gesture event.| 120 121### onActionCancel<sup>18+</sup> 122 123onActionCancel(event: Callback\<GestureEvent\>) 124 125Triggered when a tap cancellation event is received after the rotation gesture is recognized. Gesture event information is returned. 126 127**Atomic service API**: This API can be used in atomic services since API version 18. 128 129**System capability**: SystemCapability.ArkUI.ArkUI.Full 130 131**Parameters** 132 133| Name| Type | Mandatory| Description | 134| ------ | ------------------------------------------ | ---- | ---------------------------- | 135| event | Callback\<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes | Callback for the gesture event.| 136 137## Attributes 138 139**System capability**: SystemCapability.ArkUI.ArkUI.Full 140 141| Name| Type | Read-Only| Optional| Description | 142| ---- | ------ | --- | ----- | -------------------------------- | 143| tag<sup>11+</sup> | string | No| No| Tag for the rotation gesture. It is used to distinguish the gesture during custom gesture recognition.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 144| allowedTypes<sup>14+</sup> | Array\<[SourceTool](ts-gesture-settings.md#sourcetool9)> | No| No| Allowed event input types for the rotation gesture.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 145 146## Example 147 148This example demonstrates the recognition of a two-finger rotation gesture using **RotationGesture**. 149 150```ts 151// xxx.ets 152@Entry 153@Component 154struct RotationGestureExample { 155 @State angle: number = 0; 156 @State rotateValue: number = 0; 157 158 build() { 159 Column() { 160 Column() { 161 Text('RotationGesture angle:' + this.angle) 162 } 163 .height(200) 164 .width(300) 165 .padding(20) 166 .border({ width: 3 }) 167 .margin(80) 168 .rotate({ angle: this.angle }) 169 // The gesture event is triggered by rotating with two fingers. 170 .gesture( 171 RotationGesture() 172 .onActionStart((event: GestureEvent) => { 173 console.info('Rotation start') 174 }) 175 .onActionUpdate((event: GestureEvent) => { 176 if (event) { 177 this.angle = this.rotateValue + event.angle 178 } 179 }) 180 .onActionEnd((event: GestureEvent) => { 181 this.rotateValue = this.angle 182 console.info('Rotation end') 183 }) 184 ) 185 }.width('100%') 186 } 187} 188``` 189 190  191
