1# @ohos.animator (Animator) 2 3The **Animator** module provides APIs for applying animation effects, including defining animations, starting animations, and playing animations in reverse order. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12```js 13import animator from '@ohos.animator'; 14``` 15## create<sup>9+</sup> 16 17create(options: AnimatorOptions): AnimatorResult 18 19Creates an **Animator** object. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name | Type | Mandatory | Description | 26| ------- | ----------------------------------- | ---- | ------- | 27| options | [AnimatorOptions](#animatoroptions) | Yes | Animator options.| 28 29**Return value** 30 31| Type | Description | 32| --------------------------------- | ------------- | 33| [AnimatorResult](#animatorresult) | Animator result.| 34 35**Example** 36 37 ```js 38 let options = { 39 duration: 1500, 40 easing: "friction", 41 delay: 0, 42 fill: "forwards", 43 direction: "normal", 44 iterations: 3, 45 begin: 200.0, 46 end: 400.0 47 }; 48 animator.create(options); 49 ``` 50 51## AnimatorResult 52 53Defines the animator result. 54 55### reset<sup>9+</sup> 56 57reset(options: AnimatorOptions): void 58 59Updates this animator. 60 61**System capability**: SystemCapability.ArkUI.ArkUI.Full 62 63**Parameters** 64 65| Name | Type | Mandatory | Description | 66| ------- | ----------------------------------- | ---- | ------- | 67| options | [AnimatorOptions](#animatoroptions) | Yes | Animator options.| 68 69**Error codes** 70 71For details about the error codes, see [Animator Error Codes](../errorcodes/errorcode-animator.md). 72 73| ID | Error Message| 74| --------- | ------- | 75| 100001 | if no page is found for pageId or fail to get object property list. | 76 77 78**Example** 79 80```js 81let options = { 82 duration: 1500, 83 easing: "friction", 84 delay: 0, 85 fill: "forwards", 86 direction: "normal", 87 iterations: 3, 88 begin: 200.0, 89 end: 400.0 90}; 91try { 92 animator.reset(options); 93} catch(error) { 94 console.error(`Animator reset failed, error code: ${error.code}, message: ${error.message}.`); 95} 96``` 97 98### play 99 100play(): void 101 102Plays this animation. The animation retains the previous playback state. For example, if the animation is set to **reverse** and paused, it will remain in **reverse** when resumed. 103 104**System capability**: SystemCapability.ArkUI.ArkUI.Full 105 106**Example** 107 108```js 109animator.play(); 110``` 111 112### finish 113 114finish(): void 115 116Ends this animation. 117 118**System capability**: SystemCapability.ArkUI.ArkUI.Full 119 120**Example** 121 122```js 123animator.finish(); 124``` 125 126### pause 127 128pause(): void 129 130Pauses this animation. 131 132**System capability**: SystemCapability.ArkUI.ArkUI.Full 133 134**Example** 135 136```js 137animator.pause(); 138``` 139 140### cancel 141 142cancel(): void 143 144Cancels this animation. 145 146**System capability**: SystemCapability.ArkUI.ArkUI.Full 147 148**Example** 149 150```js 151animator.cancel(); 152``` 153 154### reverse 155 156reverse(): void 157 158Plays this animation in reverse order. 159 160**System capability**: SystemCapability.ArkUI.ArkUI.Full 161 162**Example** 163 164```js 165animator.reverse(); 166``` 167 168### onframe 169 170onframe: (progress: number) => void 171 172Called when a frame is received. 173 174**System capability**: SystemCapability.ArkUI.ArkUI.Full 175 176**Parameters** 177 178| Name | Type | Mandatory | Description | 179| -------- | ------ | ---- | -------- | 180| progress | number | Yes | Current progress of the animation.| 181 182**Example** 183 184```js 185let animatorResult = animator.create(options) 186animatorResult.onframe = function(value) { 187 console.info("onframe callback") 188} 189``` 190 191### onfinish 192 193onfinish: () => void 194 195Called when this animation is finished. 196 197**System capability**: SystemCapability.ArkUI.ArkUI.Full 198 199**Example** 200 201```js 202let animatorResult = animator.create(options) 203animatorResult.onfinish = function() { 204 console.info("onfinish callback") 205} 206``` 207 208### oncancel 209 210oncancel: () => void 211 212Called when this animation is canceled. 213 214**System capability**: SystemCapability.ArkUI.ArkUI.Full 215 216**Example** 217 218```js 219let animatorResult = animator.create(options) 220animatorResult.oncancel = function() { 221 console.info("oncancel callback") 222} 223``` 224 225### onrepeat 226 227onrepeat: () => void 228 229Called when this animation repeats. 230 231**System capability**: SystemCapability.ArkUI.ArkUI.Full 232 233**Example** 234 235```js 236let animatorResult = animator.create(options) 237animatorResult.onrepeat = function() { 238 console.info("onrepeat callback") 239} 240``` 241 242 243 244## AnimatorOptions 245 246Defines animator options. 247 248**System capability**: SystemCapability.ArkUI.ArkUI.Full 249 250| Name | Type | Mandatory| Description | 251| ---------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 252| duration | number | Yes | Duration for playing the animation, in milliseconds. | 253| easing | string | Yes | Animation interpolation curve. Only the following values are supported:<br>**"linear"**: The animation speed keeps unchanged.<br>**"ease"**: The animation starts slowly, accelerates, and then slows down towards the end. The cubic-bezier curve (0.25, 0.1, 0.25, 1.0) is used.<br>**"ease-in"**: The animation starts at a low speed and then picks up speed until the end. The cubic-bezier curve (0.42, 0.0, 1.0, 1.0) is used.<br>**"ease-out"**: The animation ends at a low speed. The cubic-bezier curve (0.0, 0.0, 0.58, 1.0) is used.<br>**"ease-in-out"**: The animation starts and ends at a low speed. The cubic-bezier curve (0.42, 0.0, 0.58, 1.0) is used.<br>**"fast-out-slow-in"**: The animation uses the standard cubic-bezier curve (0.4, 0.0, 0.2, 1.0).<br>**"linear-out-slow-in"**: The animation uses the deceleration cubic-bezier curve (0.0, 0.0, 0.2, 1.0).<br>**"friction"**: The animation uses the damping cubic-bezier curve (0.2, 0.0, 0.2, 1.0).<br>**"extreme-deceleration"**: The animation uses the extreme deceleration cubic-bezier curve (0.0, 0.0, 0.0, 1.0).<br>**"rhythm"**: The animation uses the rhythm cubic-bezier curve (0.7, 0.0, 0.2, 1.0).<br>**"sharp"**: The animation uses the sharp cubic-bezier curve (0.33, 0.0, 0.67, 1.0).<br>**"smooth"**: The animation uses the smooth cubic-bezier curve (0.4, 0.0, 0.4, 1.0).<br>**cubic-bezier(x1, y1, x2, y2)**: The animation uses the defined cubic-bezier curve, where the value of the input parameters must range from 0 to 1.<br>**steps(number, step-position)**: The animation uses a step curve. The **number** must be set and only an integer is supported. **step-position** is optional. It can be set to **start** or **end**. The default value is **end**.| 254| delay | number | Yes | Animation delay duration, in milliseconds. Value **0** means that there is no delay. | 255| fill | "none" \| "forwards" \| "backwards" \| "both" | Yes | State of the animated target after the animation is executed.<br>**"none"**: No style is applied to the target before or after the animation is executed.<br>**"forwards"**: The target keeps the state at the end of the animation (defined in the last key frame) after the animation is executed.<br>**"backwards"**: The animation uses the value defined in the first key frame during the **animation-delay**. When **animation-direction** is set to **normal** or **alternate**, the value in the **from** key frame is used. When **animation-direction** is set to **reverse** or **alternate-reverse**, the value in the **to** key frame is used.<br>**"both"**: The animation follows the **forwards** and **backwards** rules.| 256| direction | "normal" \| "reverse" \| "alternate" \| "alternate-reverse" | Yes | Animation playback mode.<br>**"normal"**: plays the animation in forward loop mode.<br>**"reverse"**: plays the animation in reverse loop mode.<br>**"alternate"**: plays the animation in alternating loop mode. When the animation is played for an odd number of times, the playback is in forward direction. When the animation is played for an even number of times, the playback is in reverse direction.<br>**"alternate-reverse"**: plays the animation in reverse alternating loop mode. When the animation is played for an odd number of times, the playback is in reverse direction. When the animation is played for an even number of times, the playback is in forward direction.| 257| iterations | number | Yes | Number of times that the animation is played. The value **0** means not to play the animation, and **-1** means to play the animation for an unlimited number of times.<br>**NOTE**<br>If this parameter is set to a negative value other than **-1**, the value is invalid. In this case, the animation is played once.| 258| begin | number | Yes | Start point of the animation interpolation. | 259| end | number | Yes | End point of animation interpolation. | 260 261 262## Example 263### JavaScript-compatible Web-like Development Paradigm 264 265```html 266<!-- hml --> 267<div class="container"> 268 <div class="Animation" style="height: {{divHeight}}px; width: {{divWidth}}px; background-color: red;" onclick="Show"> 269 </div> 270</div> 271``` 272 273```js 274export default { 275 data: { 276 divWidth: 200, 277 divHeight: 200, 278 animator: null 279 }, 280 onInit() { 281 let options = { 282 duration: 1500, 283 easing: "friction", 284 delay: 0, 285 fill: "forwards", 286 direction: "normal", 287 iterations: 2, 288 begin: 200.0, 289 end: 400.0 290 }; 291 this.animator = animator.create(options); 292 }, 293 Show() { 294 let options1 = { 295 duration: 1500, 296 easing: "friction", 297 delay: 0, 298 fill: "forwards", 299 direction: "normal", 300 iterations: 2, 301 begin: 0, 302 end: 400.0 303 }; 304 try { 305 this.animator.reset(options1); 306 } catch(error) { 307 console.error(`Animator reset failed, error code: ${error.code}, message: ${error.message}.`); 308 } 309 let _this = this; 310 this.animator.onframe = function(value) { 311 _this.divWidth = value; 312 _this.divHeight = value; 313 }; 314 this.animator.play(); 315 } 316} 317``` 318 319  320 321### ArkTS-based Declarative Development Paradigm 322 323```ts 324import animator from '@ohos.animator'; 325 326@Entry 327@Component 328struct AnimatorTest { 329 private TAG: string = '[AnimatorTest]' 330 private backAnimator: any = undefined 331 private flag: boolean = false 332 @State wid: number = 100 333 @State hei: number = 100 334 335 create() { 336 let _this = this 337 this.backAnimator = animator.create({ 338 duration: 2000, 339 easing: "ease", 340 delay: 0, 341 fill: "none", 342 direction: "normal", 343 iterations: 1, 344 begin: 100, 345 end: 200 346 }) 347 this.backAnimator.onfinish = function () { 348 _this.flag = true 349 console.info(_this.TAG, 'backAnimator onfinish') 350 } 351 this.backAnimator.onrepeat = function () { 352 console.info(_this.TAG, 'backAnimator repeat') 353 } 354 this.backAnimator.oncancel = function () { 355 console.info(_this.TAG, 'backAnimator cancel') 356 } 357 this.backAnimator.onframe = function (value) { 358 _this.wid = value 359 _this.hei = value 360 } 361 } 362 363 build() { 364 Column() { 365 Column() { 366 Column() 367 .width(this.wid) 368 .height(this.hei) 369 .backgroundColor(Color.Red) 370 } 371 .width('100%') 372 .height(300) 373 374 Column() { 375 Row() { 376 Button('create') 377 .fontSize(30) 378 .fontColor(Color.Black) 379 .onClick(() => { 380 this.create() 381 }) 382 } 383 .padding(10) 384 385 Row() { 386 Button('play') 387 .fontSize(30) 388 .fontColor(Color.Black) 389 .onClick(() => { 390 this.flag = false 391 this.backAnimator.play() 392 }) 393 } 394 .padding(10) 395 396 Row() { 397 Button('pause') 398 .fontSize(30) 399 .fontColor(Color.Black) 400 .onClick(() => { 401 this.backAnimator.pause() 402 }) 403 } 404 .padding(10) 405 406 Row() { 407 Button('finish') 408 .fontSize(30) 409 .fontColor(Color.Black) 410 .onClick(() => { 411 this.flag = true 412 this.backAnimator.finish() 413 }) 414 } 415 .padding(10) 416 417 Row() { 418 Button('reverse') 419 .fontSize(30) 420 .fontColor(Color.Black) 421 .onClick(() => { 422 this.flag = false 423 this.backAnimator.reverse() 424 }) 425 } 426 .padding(10) 427 428 Row() { 429 Button('cancel') 430 .fontSize(30) 431 .fontColor(Color.Black) 432 .onClick(() => { 433 this.backAnimator.cancel() 434 }) 435 } 436 .padding(10) 437 438 Row() { 439 Button('reset') 440 .fontSize(30) 441 .fontColor(Color.Black) 442 .onClick(() => { 443 if (this.flag) { 444 this.flag = false 445 this.backAnimator.reset({ 446 duration: 5000, 447 easing: "ease-in", 448 delay: 0, 449 fill: "none", 450 direction: "normal", 451 iterations: 4, 452 begin: 100, 453 end: 300 454 }) 455 } else { 456 console.info(this.TAG, 'Animation not ended') 457 } 458 }) 459 } 460 .padding(10) 461 } 462 } 463 } 464} 465``` 466 467## update<sup>(deprecated)</sup> 468 469update(options: AnimatorOptions): void 470 471Updates this animator. 472 473This API is deprecated since API version 9. You are advised to use [reset<sup>9+</sup>](#reset9) instead. 474 475**System capability**: SystemCapability.ArkUI.ArkUI.Full 476 477**Parameters** 478 479| Name | Type | Mandatory | Description | 480| ------- | ----------------------------------- | ---- | ------- | 481| options | [AnimatorOptions](#animatoroptions) | Yes | Animator options.| 482 483**Example** 484 485```js 486animator.update(options); 487``` 488 489## createAnimator<sup>(deprecated)</sup> 490 491createAnimator(options: AnimatorOptions): AnimatorResult 492 493Creates an **Animator** object. 494 495This API is deprecated since API version 9. You are advised to use [create<sup>9+</sup>](#create9) instead. 496 497**System capability**: SystemCapability.ArkUI.ArkUI.Full 498 499**Parameters** 500 501| Name | Type | Mandatory | Description | 502| ------- | ----------------------------------- | ---- | ------- | 503| options | [AnimatorOptions](#animatoroptions) | Yes | Animator options.| 504 505**Return value** 506 507| Type | Description | 508| --------------------------------- | ------------- | 509| [AnimatorResult](#animatorresult) | Animator result.| 510 511**Example** 512 513```js 514let options = { 515 duration: 1500, 516 easing: "friction", 517 delay: 0, 518 fill: "forwards", 519 direction: "normal", 520 iterations: 3, 521 begin: 200.0, 522 end: 400.0 523}; 524this.animator = animator.createAnimator(options); 525``` 526
