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> This module can be used in ArkTS since API version 9. 10> 11> This module cannot be used in the file declaration of the [UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md). In other words, the APIs of this module can be used only after a component instance is created; they cannot be called in the lifecycle of the UIAbility. 12> 13> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](js-apis-arkui-UIContext.md#uicontext). 14> 15> Since API version 10, you can use the [createAnimator](js-apis-arkui-UIContext.md#createanimator) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. 16 17## Modules to Import 18 19```ts 20import { Animator as animator, AnimatorOptions, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 21``` 22 23## Animator 24 25Creates an **Animator** object. 26 27**Atomic service API**: This API can be used in atomic services since API version 11. 28 29**System capability**: SystemCapability.ArkUI.ArkUI.Full 30 31### create<sup>9+</sup> 32 33create(options: AnimatorOptions): AnimatorResult 34 35Creates an **AnimatorResult** object for animations. 36 37**Atomic service API**: This API can be used in atomic services since API version 11. 38 39**System capability**: SystemCapability.ArkUI.ArkUI.Full 40 41**Parameters** 42 43| Name | Type | Mandatory | Description | 44| ------- | ----------------------------------- | ---- | ------- | 45| options | [AnimatorOptions](#animatoroptions) | Yes | Animator options.| 46 47**Return value** 48 49| Type | Description | 50| --------------------------------- | ------------- | 51| [AnimatorResult](#animatorresult) | Animator result.| 52 53**Error codes** 54 55For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 56 57| ID| Error Message| 58| ------- | -------- | 59| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 60 61**Example** 62 63> **NOTE** 64> 65> For precise animation control, use the [createAnimator](js-apis-arkui-UIContext.md#createanimator) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to specify the UI context. 66 67```ts 68import { Animator as animator, AnimatorOptions } from '@kit.ArkUI'; 69 70let options: AnimatorOptions = { 71 duration: 1500, 72 easing: "friction", 73 delay: 0, 74 fill: "forwards", 75 direction: "normal", 76 iterations: 3, 77 begin: 200.0, 78 end: 400.0 79}; 80animator.create(options); // You are advised to use UIContext.creatAnimator(). 81``` 82 83### create<sup>18+</sup> 84 85create(options: AnimatorOptions \| [SimpleAnimatorOptions](#simpleanimatoroptions18)): AnimatorResult 86 87Creates an **AnimatorResult** object for animations. Compared to [create](#create9), this API accepts parameters of the [SimpleAnimatorOptions](#simpleanimatoroptions18) type. 88 89**Atomic service API**: This API can be used in atomic services since API version 18. 90 91**System capability**: SystemCapability.ArkUI.ArkUI.Full 92 93**Parameters** 94 95| Name | Type | Mandatory | Description | 96| ------- | ----------------------------------- | ---- | ------- | 97| options | [AnimatorOptions](#animatoroptions) \| [SimpleAnimatorOptions](#simpleanimatoroptions18) | Yes | Parameters of the animation.| 98 99**Return value** 100 101| Type | Description | 102| --------------------------------- | ------------- | 103| [AnimatorResult](#animatorresult) | Animator result.| 104 105**Error codes** 106 107For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 108 109| ID| Error Message| 110| ------- | -------- | 111| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 112 113**Example** 114 115> **NOTE** 116> 117> For precise animation control, use the [createAnimator](js-apis-arkui-UIContext.md#createanimator) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to specify the UI context. 118 119```ts 120import { Animator as animator, SimpleAnimatorOptions } from '@kit.ArkUI'; 121let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).duration(2000); 122animator.create (options);// You are advised to use UIContext.creatAnimator(). 123``` 124 125### createAnimator<sup>(deprecated)</sup> 126 127createAnimator(options: AnimatorOptions): AnimatorResult 128 129Creates an animation. 130 131This API is deprecated since API version 9. You are advised to use [create<sup>9+</sup>](#create9) instead. 132 133**System capability**: SystemCapability.ArkUI.ArkUI.Full 134 135**Parameters** 136 137| Name | Type | Mandatory | Description | 138| ------- | ----------------------------------- | ---- | ------- | 139| options | [AnimatorOptions](#animatoroptions) | Yes | Animator options.| 140 141**Return value** 142 143| Type | Description | 144| --------------------------------- | ------------- | 145| [AnimatorResult](#animatorresult) | Animator result.| 146 147**Example** 148 149```ts 150import { Animator as animator } from '@kit.ArkUI'; 151 152let options: AnimatorOptions = { 153 // There is no need to explicitly specify the type AnimatorOptions in the xxx.js file. 154 duration: 1500, 155 easing: "friction", 156 delay: 0, 157 fill: "forwards", 158 direction: "normal", 159 iterations: 3, 160 begin: 200.0, 161 end: 400.0, 162}; 163this.animator = animator.createAnimator(options); 164``` 165 166## AnimatorResult 167 168Defines the animator result. 169 170### reset<sup>9+</sup> 171 172reset(options: AnimatorOptions): void 173 174Updates this animation. 175 176**Atomic service API**: This API can be used in atomic services since API version 11. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180**Parameters** 181 182| Name | Type | Mandatory | Description | 183| ------- | ----------------------------------- | ---- | ------- | 184| options | [AnimatorOptions](#animatoroptions) | Yes | Animator options.| 185 186**Error codes** 187 188For details about the error codes, see [Animator Error Codes](errorcode-animator.md). 189 190| ID | Error Message| 191| --------- | ------- | 192| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 193| 100001 | The specified page is not found or the object property list is not obtained.| 194 195 196**Example** 197 198```ts 199import { Animator as animator, AnimatorOptions, AnimatorResult } from '@kit.ArkUI'; 200import { BusinessError } from '@kit.BasicServicesKit'; 201 202let options: AnimatorOptions = { 203 duration: 1500, 204 easing: "friction", 205 delay: 0, 206 fill: "forwards", 207 direction: "normal", 208 iterations: 3, 209 begin: 200.0, 210 end: 400.0 211}; 212let optionsNew: AnimatorOptions = { 213 duration: 1500, 214 easing: "friction", 215 delay: 0, 216 fill: "forwards", 217 direction: "normal", 218 iterations: 5, 219 begin: 200.0, 220 end: 400.0 221}; 222try { 223 let animatorResult: AnimatorResult | undefined = animator.create(options) 224 animatorResult.reset(optionsNew); 225} catch (error) { 226 let message = (error as BusinessError).message 227 let code = (error as BusinessError).code 228 console.error(`Animator reset failed, error code: ${code}, message: ${message}.`); 229} 230``` 231 232### reset<sup>18+</sup> 233 234reset(options: AnimatorOptions \| [SimpleAnimatorOptions](#simpleanimatoroptions18)): void 235 236Updates this animation. Compared to [reset](#reset9), this API accepts parameters of the [SimpleAnimatorOptions](#simpleanimatoroptions18) type. 237 238**Atomic service API**: This API can be used in atomic services since API version 18. 239 240**System capability**: SystemCapability.ArkUI.ArkUI.Full 241 242**Parameters** 243 244| Name | Type | Mandatory | Description | 245| ------- | ----------------------------------- | ---- | ------- | 246| options | [AnimatorOptions](#animatoroptions) \| [SimpleAnimatorOptions](#simpleanimatoroptions18) | Yes | Animator options.| 247 248**Error codes** 249 250For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Animator Error Codes](errorcode-animator.md). 251 252| ID | Error Message| 253| --------- | ------- | 254| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 255| 100001 | The specified page is not found or the object property list is not obtained.| 256 257**Example** 258 259```ts 260import { Animator as animator, AnimatorResult, AnimatorOptions, SimpleAnimatorOptions } from '@kit.ArkUI'; 261let options: AnimatorOptions = { 262 duration: 1500, 263 easing: "ease", 264 delay: 0, 265 fill: "forwards", 266 direction: "normal", 267 iterations: 1, 268 begin: 100, 269 end: 200 270}; 271let optionsNew: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200) 272 .duration(2000) 273 .iterations(3) 274 .delay(1000) 275let animatorResult:AnimatorResult = animator.create(options); 276animatorResult.reset(optionsNew); 277``` 278 279### play 280 281play(): void 282 283Plays 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. 284 285**Atomic service API**: This API can be used in atomic services since API version 11. 286 287**System capability**: SystemCapability.ArkUI.ArkUI.Full 288 289**Example** 290 291```ts 292animator.play(); 293``` 294 295### finish 296 297finish(): void 298 299Ends this animation. 300 301**Atomic service API**: This API can be used in atomic services since API version 11. 302 303**System capability**: SystemCapability.ArkUI.ArkUI.Full 304 305**Example** 306 307```ts 308animator.finish(); 309``` 310 311### pause 312 313pause(): void 314 315Pauses this animation. 316 317**Atomic service API**: This API can be used in atomic services since API version 11. 318 319**System capability**: SystemCapability.ArkUI.ArkUI.Full 320 321**Example** 322 323```ts 324animator.pause(); 325``` 326 327### cancel 328 329cancel(): void 330 331Cancels this animation. 332 333**Atomic service API**: This API can be used in atomic services since API version 11. 334 335**System capability**: SystemCapability.ArkUI.ArkUI.Full 336 337**Example** 338 339```ts 340animator.cancel(); 341``` 342 343### reverse 344 345reverse(): void 346 347Plays this animation in reverse order. This API does not take effect when the interpolating spring curve is used. 348 349**Atomic service API**: This API can be used in atomic services since API version 11. 350 351**System capability**: SystemCapability.ArkUI.ArkUI.Full 352 353**Example** 354 355```ts 356animator.reverse(); 357``` 358 359### onFrame<sup>12+</sup> 360 361onFrame: (progress: number) => void 362 363Called when a frame is received. 364 365**Atomic service API**: This API can be used in atomic services since API version 12. 366 367**System capability**: SystemCapability.ArkUI.ArkUI.Full 368 369**Parameters** 370 371| Name | Type | Mandatory | Description | 372| -------- | ------ | ---- | -------- | 373| progress | number | Yes | Current value of the animation.<br>Value range: [begin, end] defined in [AnimatorOptions](#animatoroptions)<br>Default value range: [0, 1]| 374 375**Example** 376 377```ts 378import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 379 380let animatorResult: AnimatorResult | undefined = animator.create(options) 381animatorResult.onFrame = (value: number) => { 382 console.info("onFrame callback") 383} 384``` 385 386### onFinish<sup>12+</sup> 387 388onFinish: () => void 389 390Called when this animation is finished. 391 392**Atomic service API**: This API can be used in atomic services since API version 12. 393 394**System capability**: SystemCapability.ArkUI.ArkUI.Full 395 396**Example** 397 398```ts 399import {Animator as animator, AnimatorResult } from '@kit.ArkUI'; 400let animatorResult:AnimatorResult|undefined = animator.create(options) 401animatorResult.onFinish = ()=> { 402 console.info("onFinish callback") 403} 404``` 405 406### onCancel<sup>12+</sup> 407 408onCancel: () => void 409 410Called when this animation is canceled. 411 412**Atomic service API**: This API can be used in atomic services since API version 12. 413 414**System capability**: SystemCapability.ArkUI.ArkUI.Full 415 416**Example** 417 418```ts 419import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 420 421let animatorResult: AnimatorResult | undefined = animator.create(options) 422animatorResult.onCancel = () => { 423 console.info("onCancel callback") 424} 425``` 426 427### onRepeat<sup>12+</sup> 428 429onRepeat: () => void 430 431Called when this animation repeats. 432 433**Atomic service API**: This API can be used in atomic services since API version 12. 434 435**System capability**: SystemCapability.ArkUI.ArkUI.Full 436 437**Example** 438 439```ts 440import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 441 442let animatorResult: AnimatorResult | undefined = animator.create(options) 443animatorResult.onRepeat = () => { 444 console.info("onRepeat callback") 445} 446``` 447 448### onframe<sup>(deprecated)</sup> 449 450> **NOTE** 451> 452> This API is deprecated since API version 12. You are advised to use [onFrame](#onframe12) instead. 453 454onframe: (progress: number) => void 455 456Called when a frame is received. 457 458**Atomic service API**: This API can be used in atomic services since API version 11. 459 460**System capability**: SystemCapability.ArkUI.ArkUI.Full 461 462**Parameters** 463 464| Name | Type | Mandatory | Description | 465| -------- | ------ | ---- | -------- | 466| progress | number | Yes | Current progress of the animation.| 467 468**Example** 469 470```ts 471import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 472 473let animatorResult: AnimatorResult | undefined = animator.create(options) 474animatorResult.onframe = (value) => { 475 console.info("onframe callback") 476} 477``` 478 479### onfinish<sup>(deprecated)</sup> 480 481> **NOTE** 482> 483> This API is deprecated since API version 12. You are advised to use [onFinish](#onfinish12) instead. 484 485onfinish: () => void 486 487Called when this animation is finished. 488 489**Atomic service API**: This API can be used in atomic services since API version 11. 490 491**System capability**: SystemCapability.ArkUI.ArkUI.Full 492 493**Example** 494 495```ts 496import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 497 498let animatorResult: AnimatorResult | undefined = animator.create(options) 499animatorResult.onfinish = () => { 500 console.info("onfinish callback") 501} 502``` 503 504### oncancel<sup>(deprecated)</sup> 505 506> **NOTE** 507> 508> This API is deprecated since API version 12. You are advised to use [onCancel](#oncancel12) instead. 509 510 511oncancel: () => void 512 513Called when this animation is canceled. 514 515**Atomic service API**: This API can be used in atomic services since API version 11. 516 517**System capability**: SystemCapability.ArkUI.ArkUI.Full 518 519**Example** 520 521```ts 522import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 523 524let animatorResult: AnimatorResult | undefined = animator.create(options) 525animatorResult.oncancel = () => { 526 console.info("oncancel callback") 527} 528``` 529 530### onrepeat<sup>(deprecated)</sup> 531 532> **NOTE** 533> 534> This API is deprecated since API version 12. You are advised to use [onRepeat](#onrepeat12) instead. 535 536onrepeat: () => void 537 538Called when this animation repeats. 539 540**Atomic service API**: This API can be used in atomic services since API version 11. 541 542**System capability**: SystemCapability.ArkUI.ArkUI.Full 543 544**Example** 545 546```ts 547import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 548 549let animatorResult: AnimatorResult | undefined = animator.create(options) 550animatorResult.onrepeat = () => { 551 console.info("onrepeat callback") 552} 553``` 554 555### setExpectedFrameRateRange<sup>12+</sup> 556 557setExpectedFrameRateRange(rateRange: ExpectedFrameRateRange): void 558 559Sets the expected frame rate range. 560 561**Atomic service API**: This API can be used in atomic services since API version 12. 562 563**System capability**: SystemCapability.ArkUI.ArkUI.Full 564 565**Parameters** 566 567| Name | Type | Mandatory| Description | 568| --------------- | ------------------------------------------ | ---- | -----------------------------| 569| rateRange | [ExpectedFrameRateRange](../apis-arkui/arkui-ts/ts-explicit-animation.md#expectedframeraterange11)| Yes | Expected frame rate range.| 570 571**Example** 572 573```ts 574import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 575 576let animatorResult: AnimatorResult | undefined = animator.create({ 577 duration: 2000, 578 easing: "ease", 579 delay: 0, 580 fill: "forwards", 581 direction: "normal", 582 iterations: 1, 583 begin: 100, 584 end: 200 585}) 586let expectedFrameRate: ExpectedFrameRateRange = { 587 min: 0, 588 max: 120, 589 expected: 30 590} 591animatorResult.setExpectedFrameRateRange(expectedFrameRate); 592``` 593 594### update<sup>(deprecated)</sup> 595 596update(options: AnimatorOptions): void 597 598Updates this animator. 599 600This API is deprecated since API version 9. You are advised to use [reset<sup>9+</sup>](#reset9) instead. 601 602**System capability**: SystemCapability.ArkUI.ArkUI.Full 603 604**Parameters** 605 606| Name | Type | Mandatory | Description | 607| ------- | ----------------------------------- | ---- | ------- | 608| options | [AnimatorOptions](#animatoroptions) | Yes | Animator options.| 609 610**Example** 611 612```ts 613animator.update(options); 614``` 615 616## AnimatorOptions 617 618Animator options. 619 620**Atomic service API**: This API can be used in atomic services since API version 11. 621 622**System capability**: SystemCapability.ArkUI.ArkUI.Full 623 624| Name | Type | Mandatory| Description | 625| ---------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 626| duration | number | Yes | Duration for playing the animation, in milliseconds.<br>Default value: **0** | 627| 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>**"fast-out-linear-in"**: The animation uses acceleration cubic-bezier curve (0.4, 0.0, 1.0, 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 **x1** and **x2** must range from 0 to 1. For example, **"cubic-bezier(0.42,0.0,0.58,1.0)"**.<br>**"steps(number,step-position)"**: The animation uses a step curve. The **number** parameter is mandatory and must be set to a positive integer. The **step-position** parameter is optional and can be set to **start** or **end** (default value). For example, **"steps(3,start)"**.<br>**"interpolating-spring(velocity,mass,stiffness,damping)"**: The animation uses an interpolating spring curve. This API is supported since API version 11 and can be used only in ArkTS. The **velocity**, **mass**, **stiffness**, and **damping** parameters are of the numeric type, and the values of **mass**, **stiffness**, and **damping** must be greater than 0. For details about the parameters, see [Curves.interpolatingSpring](./js-apis-curve.md#curvesinterpolatingspring10). When an interpolating spring curve is used, settings for the **duration**, **fill**, **direction**, and **iterations** do not take effect. Rather, the value of **duration** is subject to the spring settings, **fill** is fixed at **forwards**, **direction** at **normal**, and **iterations** at **1**. In addition, invoking [reverse](#reverse) of **animator** is not effective. In other words, when using an interpolating spring curve, the animation can play only once in forward mode.<br>Default value: **"ease"**| 628| delay | number | Yes | Animation delay duration, in milliseconds. Value **0** means that there is no delay. If the value specified is a negative number, the animation starts playing ahead of its scheduled time. If the amount of time by which the playback is advanced is greater than the total duration of the animation, the animation skips to the end state immediately.<br>Default value: **0** | 629| 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.| 630| 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.<br>Default value: **'normal'**| 631| 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.| 632| begin | number | Yes | Start point of the animation interpolation.<br>Default value: **0** | 633| end | number | Yes | End point of animation interpolation.<br>Default value: **1** | 634 635## SimpleAnimatorOptions<sup>18+</sup> 636 637Defines a simple animation parameter object. Unlike **AnimatorOptions**, this object comes with some default values for certain animation parameters, so you don't have to set them manually. 638 639### constructor<sup>18+</sup> 640 641constructor(begin: number, end: number) 642 643A constructor used to create a **SimpleAnimatorOptions** instance. 644 645**Atomic service API**: This API can be used in atomic services since API version 18. 646 647**System capability**: SystemCapability.ArkUI.ArkUI.Full 648 649**Parameters** 650 651| Name | Type | Mandatory| Description | 652| ---------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 653| begin | number | Yes | Start point of the animation interpolation. | 654| end | number | Yes | End point of animation interpolation. 655 656**Example** 657 658```ts 659import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 660 661let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200); // Animation interpolation from 100 to 200, with other animation parameters set to default values. 662let animatorResult:AnimatorResult = animator.create(options); 663``` 664 665### duration<sup>18+</sup> 666 667duration(duration: number): SimpleAnimatorOptions 668 669Sets the animation duration. 670 671**Atomic service API**: This API can be used in atomic services since API version 18. 672 673**System capability**: SystemCapability.ArkUI.ArkUI.Full 674 675**Parameters** 676 677| Name | Type | Mandatory | Description | 678| ------- | ----------------------------------- | ---- | ------- | 679| duration | number | Yes | Animation duration, in milliseconds.<br>Default value: **1000**| 680 681**Return value** 682 683| Type | Description | 684| --------------------------------- | ------------- | 685| [SimpleAnimatorOptions](#simpleanimatoroptions18) | **SimpleAnimatorOptions** object for animation parameters.| 686 687**Example** 688 689```ts 690import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 691 692let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).duration(500); 693let animatorResult:AnimatorResult = animator.create(options); 694``` 695 696### easing<sup>18+</sup> 697 698easing(curve: string): SimpleAnimatorOptions 699 700Sets the interpolation curve for this animation. 701 702**Atomic service API**: This API can be used in atomic services since API version 18. 703 704**System capability**: SystemCapability.ArkUI.ArkUI.Full 705 706**Parameters** 707 708| Name | Type | Mandatory | Description | 709| ------- | ----------------------------------- | ---- | ------- | 710| curve | string | Yes | Interpolation curve. For details, see [AnimatorOptions](#animatoroptions).<br>Default value: **"ease"**| 711 712**Return value** 713 714| Type | Description | 715| --------------------------------- | ------------- | 716| [SimpleAnimatorOptions](#simpleanimatoroptions18) | **SimpleAnimatorOptions** object for animation parameters.| 717 718**Example** 719 720```ts 721import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 722 723let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).easing("ease-in"); 724let animatorResult:AnimatorResult = animator.create(options); 725``` 726 727### delay<sup>18+</sup> 728 729delay(delay: number): SimpleAnimatorOptions 730 731Sets the playback delay for this animation. 732 733**Atomic service API**: This API can be used in atomic services since API version 18. 734 735**System capability**: SystemCapability.ArkUI.ArkUI.Full 736 737**Parameters** 738 739| Name | Type | Mandatory | Description | 740| ------- | ----------------------------------- | ---- | ------- | 741| delay | number | Yes | Playback delay, in milliseconds. The value **0** indicates no delay. If the value specified is a negative number, the animation starts playing ahead of its scheduled time. If the amount of time by which the playback is advanced is greater than the total duration of the animation, the animation skips to the end state immediately.<br>Default value: **0**| 742 743**Return value** 744 745| Type | Description | 746| --------------------------------- | ------------- | 747| [SimpleAnimatorOptions](#simpleanimatoroptions18) | **SimpleAnimatorOptions** object for animation parameters.| 748 749**Example** 750 751```ts 752import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 753 754let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).delay(500); 755let animatorResult:AnimatorResult = animator.create(options); 756``` 757 758### fill<sup>18+</sup> 759 760fill(fillMode: [FillMode](./arkui-ts/ts-appendix-enums.md#fillmode)): SimpleAnimatorOptions 761 762Sets the fill mode for this animation. 763 764**Atomic service API**: This API can be used in atomic services since API version 18. 765 766**System capability**: SystemCapability.ArkUI.ArkUI.Full 767 768**Parameters** 769 770| Name | Type | Mandatory | Description | 771| ------- | ----------------------------------- | ---- | ------- | 772| fillMode | [FillMode](./arkui-ts/ts-appendix-enums.md#fillmode) | Yes | Fill mode, which affects how the animation behaves during the delay period and after it ends.<br>Default value: **FillMode.Forwards**| 773 774**Return value** 775 776| Type | Description | 777| --------------------------------- | ------------- | 778| [SimpleAnimatorOptions](#simpleanimatoroptions18) | **SimpleAnimatorOptions** object for animation parameters.| 779 780**Example** 781 782```ts 783import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 784 785let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).fill(FillMode.Forwards); 786let animatorResult:AnimatorResult = animator.create(options); 787``` 788 789### direction<sup>18+</sup> 790 791direction(direction: [PlayMode](./arkui-ts/ts-appendix-enums.md#playmode)): SimpleAnimatorOptions 792 793Sets the playback direction for this animation. 794 795**Atomic service API**: This API can be used in atomic services since API version 18. 796 797**System capability**: SystemCapability.ArkUI.ArkUI.Full 798 799**Parameters** 800 801| Name | Type | Mandatory | Description | 802| ------- | ----------------------------------- | ---- | ------- | 803| direction | [PlayMode](./arkui-ts/ts-appendix-enums.md#playmode) | Yes | Playback direction.<br>Default value: **PlayMode.Normal**| 804 805**Return value** 806 807| Type | Description | 808| --------------------------------- | ------------- | 809| [SimpleAnimatorOptions](#simpleanimatoroptions18) | **SimpleAnimatorOptions** object for animation parameters.| 810 811**Example** 812 813```ts 814import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 815 816let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).direction(PlayMode.Alternate); 817let animatorResult:AnimatorResult = animator.create(options); 818``` 819 820### iterations<sup>18+</sup> 821 822iterations(iterations: number): SimpleAnimatorOptions 823 824Sets the number of times that this animation is played. 825 826**Atomic service API**: This API can be used in atomic services since API version 18. 827 828**System capability**: SystemCapability.ArkUI.ArkUI.Full 829 830**Parameters** 831 832| Name | Type | Mandatory | Description | 833| ------- | ----------------------------------- | ---- | ------- | 834| iterations | number | Yes | Number of times that the animation is played. The value **0** means the animation is not played, and **-1** means the animation is played for an unlimited number of times.<br>Default value: **1**| 835 836**Return value** 837 838| Type | Description | 839| --------------------------------- | ------------- | 840| [SimpleAnimatorOptions](#simpleanimatoroptions18) | **SimpleAnimatorOptions** object for animation parameters.| 841 842**Example** 843 844```ts 845import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 846 847let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).iterations(3); 848let animatorResult:AnimatorResult = animator.create(options); 849``` 850 851## Example 852### JavaScript-compatible Web-like Development Paradigm 853 854```html 855<!-- hml --> 856<div class="container"> 857 <div class="Animation" style="height: {{divHeight}}px; width: {{divWidth}}px; background-color: red;" onclick="Show"> 858 </div> 859</div> 860``` 861 862```ts 863import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 864import { BusinessError } from '@kit.BasicServicesKit'; 865 866let DataTmp: Record<string, Animator> = { 867 'divWidth': 200, 868 'divHeight': 200, 869 'animator': animator 870} 871 872class Tmp { 873 data: animator = DataTmp 874 onInit: Function = () => { 875 } 876 Show: Function = () => { 877 } 878} 879 880class DateT { 881 divWidth: number = 0 882 divHeight: number = 0 883 animator: AnimatorResult | null = null 884} 885 886(Fn: (v: Tmp) => void) => { 887 Fn({ 888 data: DataTmp, 889 onInit() { 890 let options: AnimatorOptions = { 891 duration: 1500, 892 easing: "friction", 893 delay: 0, 894 fill: "forwards", 895 direction: "normal", 896 iterations: 2, 897 begin: 200.0, 898 end: 400.0 899 }; 900 let DataTmp: DateT = { 901 divWidth: 200, 902 divHeight: 200, 903 animator: null 904 } 905 DataTmp.animator = animator.create(options); 906 }, 907 Show() { 908 let options1: AnimatorOptions = { 909 duration: 1500, 910 easing: "friction", 911 delay: 0, 912 fill: "forwards", 913 direction: "normal", 914 iterations: 2, 915 begin: 0, 916 end: 400.0, 917 }; 918 let DataTmp: DateT = { 919 divWidth: 200, 920 divHeight: 200, 921 animator: null 922 } 923 try { 924 DataTmp.animator = animator.create(options1); 925 DataTmp.animator.reset(options1); 926 } catch (error) { 927 let message = (error as BusinessError).message 928 let code = (error as BusinessError).code 929 console.error(`Animator reset failed, error code: ${code}, message: ${message}.`); 930 } 931 let _this = DataTmp; 932 if (DataTmp.animator) { 933 DataTmp.animator.onFrame = (value: number) => { 934 _this.divWidth = value; 935 _this.divHeight = value; 936 }; 937 DataTmp.animator.play(); 938 } 939 } 940 }) 941} 942``` 943 944  945 946### ArkTS-based Declarative Development Paradigm 947 948> **NOTE** 949> 950> For precise animation control, use the [createAnimator](js-apis-arkui-UIContext.md#createanimator) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to specify the UI context. 951 952```ts 953import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 954 955@Entry 956@Component 957struct AnimatorTest { 958 private TAG: string = '[AnimatorTest]' 959 private backAnimator: AnimatorResult | undefined = undefined 960 private flag: boolean = false 961 @State wid: number = 100 962 @State hei: number = 100 963 964 create() { 965 this.backAnimator = animator.create({ 966 // You are advised to use this.getUIContext.creatAnimator(). 967 duration: 2000, 968 easing: "ease", 969 delay: 0, 970 fill: "forwards", 971 direction: "normal", 972 iterations: 1, 973 begin: 100, 974 end: 200 975 }) 976 this.backAnimator.onFinish = () => { 977 this.flag = true 978 console.info(this.TAG, 'backAnimator onfinish') 979 } 980 this.backAnimator.onRepeat = () => { 981 console.info(this.TAG, 'backAnimator repeat') 982 } 983 this.backAnimator.onCancel = () => { 984 console.info(this.TAG, 'backAnimator cancel') 985 } 986 this.backAnimator.onFrame = (value: number) => { 987 this.wid = value 988 this.hei = value 989 } 990 } 991 992 aboutToDisappear() { 993 // Because backAnimator references this in onframe, backAnimator is saved in this. 994 // When the custom component disappears, leave backAnimator empty to avoid memory leak. 995 this.backAnimator = undefined; 996 } 997 998 build() { 999 Column() { 1000 Column() { 1001 Column() 1002 .width(this.wid) 1003 .height(this.hei) 1004 .backgroundColor(Color.Red) 1005 } 1006 .width('100%') 1007 .height(300) 1008 1009 Column() { 1010 Row() { 1011 Button('create') 1012 .fontSize(30) 1013 .fontColor(Color.Black) 1014 .onClick(() => { 1015 this.create() 1016 }) 1017 } 1018 .padding(10) 1019 1020 Row() { 1021 Button('play') 1022 .fontSize(30) 1023 .fontColor(Color.Black) 1024 .onClick(() => { 1025 this.flag = false 1026 if (this.backAnimator) { 1027 this.backAnimator.play() 1028 } 1029 }) 1030 } 1031 .padding(10) 1032 1033 Row() { 1034 Button('pause') 1035 .fontSize(30) 1036 .fontColor(Color.Black) 1037 .onClick(() => { 1038 if (this.backAnimator) { 1039 this.backAnimator.pause() 1040 } 1041 }) 1042 } 1043 .padding(10) 1044 1045 Row() { 1046 Button('finish') 1047 .fontSize(30) 1048 .fontColor(Color.Black) 1049 .onClick(() => { 1050 this.flag = true 1051 if (this.backAnimator) { 1052 this.backAnimator.finish() 1053 } 1054 }) 1055 } 1056 .padding(10) 1057 1058 Row() { 1059 Button('reverse') 1060 .fontSize(30) 1061 .fontColor(Color.Black) 1062 .onClick(() => { 1063 this.flag = false 1064 if (this.backAnimator) { 1065 this.backAnimator.reverse() 1066 } 1067 }) 1068 } 1069 .padding(10) 1070 1071 Row() { 1072 Button('cancel') 1073 .fontSize(30) 1074 .fontColor(Color.Black) 1075 .onClick(() => { 1076 if (this.backAnimator) { 1077 this.backAnimator.cancel() 1078 } 1079 }) 1080 } 1081 .padding(10) 1082 1083 Row() { 1084 Button('reset') 1085 .fontSize(30) 1086 .fontColor(Color.Black) 1087 .onClick(() => { 1088 if (this.flag) { 1089 this.flag = false 1090 if (this.backAnimator) { 1091 this.backAnimator.reset({ 1092 duration: 3000, 1093 easing: "ease-in", 1094 delay: 0, 1095 fill: "forwards", 1096 direction: "alternate", 1097 iterations: 3, 1098 begin: 100, 1099 end: 300 1100 }) 1101 } 1102 } else { 1103 console.info(this.TAG, 'Animation not ended') 1104 } 1105 }) 1106 } 1107 .padding(10) 1108 } 1109 } 1110 } 1111} 1112``` 1113 1114### Example: Implementing a Translation Animation with Simple Parameters 1115 1116```ts 1117import { AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 1118 1119@Entry 1120@Component 1121struct AnimatorTest { 1122 private TAG: string = '[AnimatorTest]' 1123 private backAnimator: AnimatorResult | undefined = undefined 1124 private flag: boolean = false 1125 @State translate_: number = 0 1126 1127 create() { 1128 this.backAnimator = this.getUIContext()?.createAnimator( 1129 new SimpleAnimatorOptions(0, 100) 1130 ) 1131 this.backAnimator.onFinish = ()=> { 1132 this.flag = true 1133 console.info(this.TAG, 'backAnimator onfinish') 1134 } 1135 this.backAnimator.onFrame = (value:number)=> { 1136 this.translate_ = value 1137 } 1138 } 1139 1140 aboutToDisappear() { 1141 // Because backAnimator references this in onFrame and is saved in the component, 1142 // it must be set undefined when the custom component disappears to avoid memory leaks. 1143 this.backAnimator = undefined; 1144 } 1145 1146 build() { 1147 Column() { 1148 Column() { 1149 Column() 1150 .width(100) 1151 .height(100) 1152 .translate({x: this.translate_}) 1153 .backgroundColor(Color.Green) 1154 } 1155 .width('100%') 1156 .height(300) 1157 1158 Column() { 1159 Column() { 1160 Button('create') 1161 .fontSize(30) 1162 .fontColor(Color.Black) 1163 .onClick(() => { 1164 this.create() 1165 }) 1166 } 1167 .padding(10) 1168 1169 Column() { 1170 Button('play') 1171 .fontSize(30) 1172 .fontColor(Color.Black) 1173 .onClick(() => { 1174 this.flag = false 1175 if(this.backAnimator){ 1176 this.backAnimator.play() 1177 } 1178 }) 1179 } 1180 .padding(10) 1181 1182 Column() { 1183 Button('reset') 1184 .fontSize(30) 1185 .fontColor(Color.Black) 1186 .onClick(() => { 1187 if (this.flag) { 1188 this.flag = false 1189 if(this.backAnimator){ 1190 this.backAnimator.reset( 1191 new SimpleAnimatorOptions(0, -100) 1192 .duration(2000) 1193 .easing("ease-in") 1194 .fill(FillMode.Forwards) 1195 .direction(PlayMode.Alternate) 1196 .iterations(2) 1197 ) 1198 } 1199 } else { 1200 console.info(this.TAG, 'Animation not ended') 1201 } 1202 }) 1203 } 1204 .padding(10) 1205 } 1206 } 1207 } 1208} 1209``` 1210 1211 1212
