1# @ohos.animator (动画) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @CCFFWW--> 5<!--Designer: @yangfan229--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9本模块提供组件动画效果，包括定义动画、启动动画和以相反的顺序播放动画等。 10 11> **说明：** 12> 13> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> 本模块从API version 9开始支持在ArkTS中使用。 16> 17> 该模块不支持在[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)的文件声明处使用，即不能在UIAbility的生命周期中调用，需要在创建组件实例后使用。 18> 19> 本模块功能依赖UI的执行上下文，不可在[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的地方使用，参见[UIContext](arkts-apis-uicontext-uicontext.md)说明。 20> 21> 自定义组件中一般会持有一个[create](#create18)接口返回的[AnimatorResult](#animatorresult)对象，以保证动画对象不在动画过程中析构，而这个对象也通过回调捕获了自定义组件对象。则需要在自定义组件销毁时的[aboutToDisappear](../apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#abouttodisappear)中释放动画对象，来避免因为循环依赖导致内存泄漏，详细示例可参考：[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 22> 23> Animator对象析构或主动调用[cancel](#cancel)都会有一次额外的[onFrame](#onframe12)，返回值是动画终点的值。 24 25## 导入模块 26 27```ts 28import { Animator as animator, AnimatorOptions, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 29``` 30 31## Animator 32 33定义Animator类。 34 35**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39### create<sup>(deprecated)</sup> 40 41create(options: AnimatorOptions): AnimatorResult 42 43创建animator动画结果对象（AnimatorResult）。 44 45> **说明：** 46> 47> 从API version 9开始支持，从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[createAnimator](arkts-apis-uicontext-uicontext.md#createanimator)替代。 48> 49> 从API version 10开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[createAnimator](arkts-apis-uicontext-uicontext.md#createanimator)来明确UI的执行上下文。 50 51**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 52 53**系统能力：** SystemCapability.ArkUI.ArkUI.Full 54 55**参数：** 56 57| 参数名 | 类型 | 必填 | 说明 | 58| ------- | ----------------------------------- | ---- | ------- | 59| options | [AnimatorOptions](#animatoroptions) | 是 | 定义动画选项。 | 60 61**返回值：** 62 63| 类型 | 说明 | 64| --------------------------------- | ------------- | 65| [AnimatorResult](#animatorresult) | Animator结果接口。 | 66 67**错误码**： 68 69以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 70 71| 错误码ID | 错误信息 | 72| ------- | -------- | 73| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 74 75**示例：** 76 77完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 78 79> **说明：** 80> 81> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[createAnimator](arkts-apis-uicontext-uicontext.md#createanimator)接口明确UI上下文。 82 83<!--deprecated_code_no_check--> 84```ts 85import { Animator as animator, AnimatorOptions } from '@kit.ArkUI'; 86 87let options: AnimatorOptions = { 88 duration: 1500, 89 easing: "friction", 90 delay: 0, 91 fill: "forwards", 92 direction: "normal", 93 iterations: 3, 94 begin: 200.0, 95 end: 400.0 96}; 97animator.create(options); // 建议使用 UIContext.createAnimator()接口 98``` 99 100### create<sup>18+</sup> 101 102create(options: AnimatorOptions \| SimpleAnimatorOptions): AnimatorResult 103 104创建animator动画结果对象（AnimatorResult）。与[create](#createdeprecated)相比，新增对[SimpleAnimatorOptions](#simpleanimatoroptions18)类型入参的支持。 105 106**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 107 108**系统能力：** SystemCapability.ArkUI.ArkUI.Full 109 110**参数：** 111 112| 参数名 | 类型 | 必填 | 说明 | 113| ------- | ----------------------------------- | ---- | ------- | 114| options | [AnimatorOptions](#animatoroptions) \| [SimpleAnimatorOptions](#simpleanimatoroptions18) | 是 | 定义动画参数选项。 | 115 116**返回值：** 117 118| 类型 | 说明 | 119| --------------------------------- | ------------- | 120| [AnimatorResult](#animatorresult) | Animator结果接口。 | 121 122**错误码**： 123 124以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 125 126| 错误码ID | 错误信息 | 127| ------- | -------- | 128| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 129 130**示例：** 131 132完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 133 134> **说明：** 135> 136> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[createAnimator](arkts-apis-uicontext-uicontext.md#createanimator)接口明确UI上下文。 137 138<!--deprecated_code_no_check--> 139```ts 140import { Animator as animator, SimpleAnimatorOptions } from '@kit.ArkUI'; 141let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).duration(2000); 142animator.create(options);// 建议使用 UIContext.createAnimator()接口 143``` 144 145### createAnimator<sup>(deprecated)</sup> 146 147createAnimator(options: AnimatorOptions): AnimatorResult 148 149创建动画 150 151从API version 9开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[createAnimator](arkts-apis-uicontext-uicontext.md#createanimator) 152 153**系统能力：** SystemCapability.ArkUI.ArkUI.Full 154 155**参数：** 156 157| 参数名 | 类型 | 必填 | 说明 | 158| ------- | ----------------------------------- | ---- | ------- | 159| options | [AnimatorOptions](#animatoroptions) | 是 | 定义动画选项。 | 160 161**返回值：** 162 163| 类型 | 说明 | 164| --------------------------------- | ------------- | 165| [AnimatorResult](#animatorresult) | Animator结果接口。 | 166 167**示例：** 168 169完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 170 171```ts 172import { Animator as animator } from '@kit.ArkUI'; 173 174let options: AnimatorOptions = { 175 // xxx.js文件中不需要强调显式类型AnimatorOptions 176 duration: 1500, 177 easing: "friction", 178 delay: 0, 179 fill: "forwards", 180 direction: "normal", 181 iterations: 3, 182 begin: 200.0, 183 end: 400.0, 184}; 185this.animator = animator.createAnimator(options); 186``` 187 188## AnimatorResult 189 190定义Animator结果接口。 191 192### reset<sup>9+</sup> 193 194reset(options: AnimatorOptions): void 195 196重置当前animator动画参数。 197 198**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 199 200**系统能力：** SystemCapability.ArkUI.ArkUI.Full 201 202**参数：** 203 204| 参数名 | 类型 | 必填 | 说明 | 205| ------- | ----------------------------------- | ---- | ------- | 206| options | [AnimatorOptions](#animatoroptions) | 是 | 定义动画选项。 | 207 208**错误码：** 209 210以下错误码的详细介绍请参见[ohos.animator(动画)](errorcode-animator.md)错误码。 211 212| 错误码ID | 错误信息 | 213| --------- | ------- | 214| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 215| 100001 | The specified page is not found or the object property list is not obtained.| 216 217 218**示例：** 219 220```ts 221import { AnimatorResult } from '@kit.ArkUI'; 222 223@Entry 224@Component 225struct AnimatorTest { 226 private animatorResult: AnimatorResult | undefined = undefined; 227 228 create() { 229 this.animatorResult = this.getUIContext().createAnimator({ 230 duration: 1500, 231 easing: "friction", 232 delay: 0, 233 fill: "forwards", 234 direction: "normal", 235 iterations: 3, 236 begin: 200.0, 237 end: 400.0 238 }) 239 this.animatorResult.reset({ 240 duration: 1500, 241 easing: "friction", 242 delay: 0, 243 fill: "forwards", 244 direction: "normal", 245 iterations: 5, 246 begin: 200.0, 247 end: 400.0 248 }); 249 } 250 251 build() { 252 // ...... 253 } 254} 255``` 256 257### reset<sup>18+</sup> 258 259reset(options: AnimatorOptions \| SimpleAnimatorOptions): void 260 261重置当前animator动画参数。与[reset](#reset9)相比，新增对[SimpleAnimatorOptions](#simpleanimatoroptions18)类型入参的支持。 262 263**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 264 265**系统能力：** SystemCapability.ArkUI.ArkUI.Full 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| ------- | ----------------------------------- | ---- | ------- | 271| options | [AnimatorOptions](#animatoroptions) \| [SimpleAnimatorOptions](#simpleanimatoroptions18) | 是 | 定义动画选项。 | 272 273**错误码：** 274 275以下错误码的详细介绍请参考[通用错误码](../errorcode-universal.md)和[ohos.animator(动画)](errorcode-animator.md)错误码。 276 277| 错误码ID | 错误信息 | 278| --------- | ------- | 279| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 280| 100001 | The specified page is not found or the object property list is not obtained.| 281 282**示例：** 283 284完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 285 286<!--deprecated_code_no_check--> 287```ts 288import { Animator as animator, AnimatorResult, AnimatorOptions, SimpleAnimatorOptions } from '@kit.ArkUI'; 289let options: AnimatorOptions = { 290 duration: 1500, 291 easing: "ease", 292 delay: 0, 293 fill: "forwards", 294 direction: "normal", 295 iterations: 1, 296 begin: 100, 297 end: 200 298}; 299let optionsNew: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200) 300 .duration(2000) 301 .iterations(3) 302 .delay(1000) 303let animatorResult:AnimatorResult = animator.create(options); 304animatorResult.reset(optionsNew); 305``` 306 307### play 308 309play(): void 310 311启动动画。动画会保留上一次的播放状态，比如播放状态设置reverse后，再次播放会保留reverse的播放状态。 312 313**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 314 315**系统能力：** SystemCapability.ArkUI.ArkUI.Full 316 317**示例：** 318 319完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 320 321```ts 322animator.play(); 323``` 324 325### finish 326 327finish(): void 328 329结束动画，会触发[onFinish](#onfinish12)回调。 330 331**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 332 333**系统能力：** SystemCapability.ArkUI.ArkUI.Full 334 335**示例：** 336 337完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 338 339```ts 340animator.finish(); 341``` 342 343### pause 344 345pause(): void 346 347暂停动画。 348 349**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 350 351**系统能力：** SystemCapability.ArkUI.ArkUI.Full 352 353**示例：** 354 355完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 356 357```ts 358animator.pause(); 359``` 360 361### cancel 362 363cancel(): void 364 365取消动画，会触发[onCancel](#oncancel12)回调。此接口和[finish](#finish)接口功能上没有区别，仅触发的回调不同，建议使用finish接口结束动画。 366 367**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 368 369**系统能力：** SystemCapability.ArkUI.ArkUI.Full 370 371**示例：** 372 373完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 374 375```ts 376animator.cancel(); 377``` 378 379### reverse 380 381reverse(): void 382 383以相反的顺序播放动画。使用interpolating-spring曲线时此接口无效。 384 385**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 386 387**系统能力：** SystemCapability.ArkUI.ArkUI.Full 388 389**示例：** 390 391完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 392 393```ts 394animator.reverse(); 395``` 396 397### onFrame<sup>12+</sup> 398 399onFrame: (progress: number) => void 400 401接收到帧时回调。 402 403**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 404 405**系统能力：** SystemCapability.ArkUI.ArkUI.Full 406 407**参数：** 408 409| 参数名 | 类型 | 必填 | 说明 | 410| -------- | ------ | ---- | -------- | 411| progress | number | 是 | 动画的当前值。<br/>取值范围为[AnimatorOptions](#animatoroptions)定义的[begin, end]，默认取值范围为[0, 1]。 | 412 413**示例：** 414 415```ts 416import { AnimatorResult } from '@kit.ArkUI'; 417 418@Entry 419@Component 420struct AnimatorTest { 421 private backAnimator: AnimatorResult | undefined = undefined 422 423 create() { 424 this.backAnimator = this.getUIContext().createAnimator({ 425 duration: 2000, 426 easing: "ease", 427 delay: 0, 428 fill: "forwards", 429 direction: "normal", 430 iterations: 1, 431 begin: 100, //动画插值起点 432 end: 200 //动画插值终点 433 }) 434 this.backAnimator.onFrame = (value: number) => { 435 console.info("onFrame callback") 436 } 437 } 438 439 build() { 440 // ...... 441 } 442} 443``` 444 445### onFinish<sup>12+</sup> 446 447onFinish: () => void 448 449动画完成时回调。 450 451**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 452 453**系统能力：** SystemCapability.ArkUI.ArkUI.Full 454 455**示例：** 456 457```ts 458import { AnimatorResult } from '@kit.ArkUI'; 459 460@Entry 461@Component 462struct AnimatorTest { 463 private backAnimator: AnimatorResult | undefined = undefined 464 465 create() { 466 this.backAnimator = this.getUIContext().createAnimator({ 467 duration: 2000, 468 easing: "ease", 469 delay: 0, 470 fill: "forwards", 471 direction: "normal", 472 iterations: 1, 473 begin: 100, //动画插值起点 474 end: 200 //动画插值终点 475 }) 476 this.backAnimator.onFinish = ()=> { 477 console.info("onFinish callback") 478 } 479 } 480 481 build() { 482 // ...... 483 } 484} 485``` 486 487### onCancel<sup>12+</sup> 488 489onCancel: () => void 490 491动画被取消时回调。 492 493**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 494 495**系统能力：** SystemCapability.ArkUI.ArkUI.Full 496 497**示例：** 498 499```ts 500import { AnimatorResult } from '@kit.ArkUI'; 501 502@Entry 503@Component 504struct AnimatorTest { 505 private backAnimator: AnimatorResult | undefined = undefined 506 507 create() { 508 this.backAnimator = this.getUIContext().createAnimator({ 509 duration: 2000, 510 easing: "ease", 511 delay: 0, 512 fill: "forwards", 513 direction: "normal", 514 iterations: 1, 515 begin: 100, //动画插值起点 516 end: 200 //动画插值终点 517 }) 518 this.backAnimator.onCancel = () => { 519 console.info("onCancel callback") 520 } 521 } 522 523 build() { 524 // ...... 525 } 526} 527``` 528 529### onRepeat<sup>12+</sup> 530 531onRepeat: () => void 532 533动画重复时回调。 534 535**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 536 537**系统能力：** SystemCapability.ArkUI.ArkUI.Full 538 539**示例：** 540 541```ts 542import { AnimatorResult } from '@kit.ArkUI'; 543 544@Entry 545@Component 546struct AnimatorTest { 547 private backAnimator: AnimatorResult | undefined = undefined 548 549 create() { 550 this.backAnimator = this.getUIContext().createAnimator({ 551 duration: 2000, 552 easing: "ease", 553 delay: 0, 554 fill: "forwards", 555 direction: "normal", 556 iterations: 1, 557 begin: 100, //动画插值起点 558 end: 200 //动画插值终点 559 }) 560 this.backAnimator.onRepeat = () => { 561 console.info("onRepeat callback") 562 } 563 } 564 565 build() { 566 // ...... 567 } 568} 569``` 570 571### onframe<sup>(deprecated)</sup> 572 573> **说明：** 574> 575> 从API version 12开始废弃，推荐使用[onFrame](#onframe12)。 576 577onframe: (progress: number) => void 578 579接收到帧时回调。 580 581**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 582 583**系统能力：** SystemCapability.ArkUI.ArkUI.Full 584 585**参数：** 586 587| 参数名 | 类型 | 必填 | 说明 | 588| -------- | ------ | ---- | -------- | 589| progress | number | 是 | 动画的当前进度。 | 590 591**示例：** 592 593完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 594 595```ts 596import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 597 598let animatorResult: AnimatorResult | undefined = animator.create(options) 599animatorResult.onframe = (value) => { 600 console.info("onframe callback") 601} 602``` 603 604### onfinish<sup>(deprecated)</sup> 605 606> **说明：** 607> 608> 从API version 12开始废弃，推荐使用[onFinish](#onfinish12)。 609 610onfinish: () => void 611 612动画完成时回调。 613 614**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 615 616**系统能力：** SystemCapability.ArkUI.ArkUI.Full 617 618**示例：** 619 620完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 621 622```ts 623import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 624 625let animatorResult: AnimatorResult | undefined = animator.create(options) 626animatorResult.onfinish = () => { 627 console.info("onfinish callback") 628} 629``` 630 631### oncancel<sup>(deprecated)</sup> 632 633> **说明：** 634> 635> 从API version 12开始废弃，推荐使用[onCancel](#oncancel12)。 636 637 638oncancel: () => void 639 640动画被取消时回调。 641 642**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 643 644**系统能力：** SystemCapability.ArkUI.ArkUI.Full 645 646**示例：** 647 648完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 649 650<!--deprecated_code_no_check--> 651```ts 652import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 653 654let animatorResult: AnimatorResult | undefined = animator.create(options) 655animatorResult.oncancel = () => { 656 console.info("oncancel callback") 657} 658``` 659 660### onrepeat<sup>(deprecated)</sup> 661 662> **说明：** 663> 664> 从API version 12开始废弃，推荐使用[onRepeat](#onrepeat12)。 665 666onrepeat: () => void 667 668动画重复时回调。 669 670**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 671 672**系统能力：** SystemCapability.ArkUI.ArkUI.Full 673 674**示例：** 675 676完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 677 678```ts 679import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 680 681let animatorResult: AnimatorResult | undefined = animator.create(options) 682animatorResult.onrepeat = () => { 683 console.info("onrepeat callback") 684} 685``` 686 687### setExpectedFrameRateRange<sup>12+</sup> 688 689setExpectedFrameRateRange(rateRange: ExpectedFrameRateRange): void 690 691设置期望的帧率范围。 692 693**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 694 695**系统能力：** SystemCapability.ArkUI.ArkUI.Full 696 697**参数：** 698 699| 参数名 | 类型 | 必填 | 说明 | 700| --------------- | ------------------------------------------ | ---- | -----------------------------| 701| rateRange | [ExpectedFrameRateRange](../apis-arkui/arkui-ts/ts-explicit-animation.md#expectedframeraterange11)| 是 | 设置期望的帧率范围。| 702 703**示例：** 704 705```ts 706import { AnimatorResult } from '@kit.ArkUI'; 707 708let expectedFrameRate: ExpectedFrameRateRange = { 709 min: 0, 710 max: 120, 711 expected: 30 712} 713 714@Entry 715@Component 716struct AnimatorTest { 717 private backAnimator: AnimatorResult | undefined = undefined 718 719 create() { 720 this.backAnimator = this.getUIContext().createAnimator({ 721 duration: 2000, 722 easing: "ease", 723 delay: 0, 724 fill: "forwards", 725 direction: "normal", 726 iterations: 1, 727 begin: 100, //动画插值起点 728 end: 200 //动画插值终点 729 }) 730 this.backAnimator.setExpectedFrameRateRange(expectedFrameRate); 731 } 732 733 build() { 734 // ...... 735 } 736} 737``` 738 739### update<sup>(deprecated)</sup> 740 741update(options: AnimatorOptions): void 742 743更新当前动画器。 744 745从API version 9开始废弃，建议使用[reset<sup>9+</sup>](#reset9)。 746 747**系统能力：** SystemCapability.ArkUI.ArkUI.Full 748 749**参数：** 750 751| 参数名 | 类型 | 必填 | 说明 | 752| ------- | ----------------------------------- | ---- | ------- | 753| options | [AnimatorOptions](#animatoroptions) | 是 | 定义动画选项。 | 754 755**示例：** 756 757完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 758 759```ts 760animator.update(options); 761``` 762 763## AnimatorOptions 764 765定义动画选项。 766 767**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 768 769**系统能力：** SystemCapability.ArkUI.ArkUI.Full 770 771### 属性 772 773| 名称 | 类型 | 只读 | 可选 | 说明 | 774| ---------- | ----------------------------------------------------------- | ---- | ------- | ----------------------------------------------------- | 775| duration | number | 否 | 否 | 动画播放的时长，单位毫秒。<br/> 取值范围：[0, +∞) <br/>默认值：0 | 776| easing | string | 否 | 否 | 动画插值曲线，仅支持以下可选值：<br/>"linear"：动画线性变化。<br/>"ease"：动画开始和结束时的速度较慢，cubic-bezier(0.25、0.1、0.25、1.0)。<br/>"ease-in"：动画播放速度先慢后快，cubic-bezier(0.42, 0.0, 1.0, 1.0)。<br/>"ease-out"：动画播放速度先快后慢，cubic-bezier(0.0, 0.0, 0.58, 1.0)。<br/>"ease-in-out"：动画播放速度先加速后减速，cubic-bezier(0.42, 0.0, 0.58, 1.0)。<br/>"fast-out-slow-in"：标准曲线，cubic-bezier(0.4，0.0，0.2，1.0)。<br/>"linear-out-slow-in"：减速曲线，cubic-bezier(0.0，0.0，0.2，1.0)。<br>"fast-out-linear-in"：加速曲线，cubic-bezier(0.4, 0.0, 1.0, 1.0)。<br/>"friction"：阻尼曲线，cubic-bezier(0.2, 0.0, 0.2, 1.0)。<br/>"extreme-deceleration"：急缓曲线，cubic-bezier(0.0, 0.0, 0.0, 1.0)。<br/>"rhythm"：节奏曲线，cubic-bezier(0.7, 0.0, 0.2, 1.0)。<br/>"sharp"：锐利曲线，cubic-bezier(0.33, 0.0, 0.67, 1.0)。<br/>"smooth"：平滑曲线，cubic-bezier(0.4, 0.0, 0.4, 1.0)。<br/>"cubic-bezier(x1,y1,x2,y2)"：三次贝塞尔曲线，x1、x2的值必须处于0-1之间。例如"cubic-bezier(0.42,0.0,0.58,1.0)"。<br/>"steps(number,step-position)"：阶梯曲线，number必须设置，为正整数，step-position参数可选，支持设置start或end，默认值为end。例如"steps(3,start)"。<br/>"interpolating-spring(velocity,mass,stiffness,damping)"：插值弹簧曲线，从API version 11开始支持且仅在ArkTS中支持使用。velocity、mass、stiffness、damping都是数值类型，且mass、stiffness、damping参数均应该大于0，具体参数含义参考[插值弹簧曲线](./js-apis-curve.md#curvesinterpolatingspring10)。使用interpolating-spring时，duration不生效，由弹簧参数决定；fill、direction、iterations设置无效，fill固定设置为"forwards"，direction固定设置为"normal"，iterations固定设置为1，且对animator的[reverse](#reverse)函数调用无效。即animator使用interpolating-spring时只能正向播放1次。<br/>非法字符串时取:"ease"。 | 777| delay | number | 否 | 否 | 动画延时播放时长，单位毫秒，设置为0时，表示不延时。设置为负数时动画提前播放，如果提前播放的时长大于动画总时长，动画直接过渡到终点。 <br/>默认值：0 | 778| fill | 'none' \| 'forwards' \| 'backwards' \| 'both' | 否 | 否 | 动画执行后是否恢复到初始状态，动画执行后，动画结束时的状态（在最后一个关键帧中定义）将保留。<br/>'none'：在动画执行之前和之后都不会应用任何样式到目标上。<br/>'forwards'：在动画结束后，目标将保留动画结束时的状态（在最后一个关键帧中定义）。<br/>'backwards'：动画将在[AnimatorOptions](#animatoroptions)中的delay期间应用第一个关键帧中定义的值。当[AnimatorOptions](#animatoroptions)中的direction为'normal'或'alternate'时应用from关键帧中的值，当[AnimatorOptions](#animatoroptions)中的direction为'reverse'或'alternate-reverse'时应用to关键帧中的值。<br/>'both'：动画将遵循forwards和backwards的规则，从而在两个方向上扩展动画属性。 | 779| direction | 'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse' | 否 | 否 | 动画播放模式。<br/>'normal'： 动画正向循环播放。<br/>'reverse'： 动画反向循环播放。<br/>'alternate'：动画交替循环播放，奇数次正向播放，偶数次反向播放。<br/>'alternate-reverse'：动画反向交替循环播放，奇数次反向播放，偶数次正向播放。<br/>默认值：'normal' | 780| iterations | number | 否 | 否 | 动画播放次数。设置为0时不播放，设置为-1时无限次播放，设置大于0时为播放次数。<br/>**说明:** 设置为除-1外其他负数视为无效取值，无效取值动画默认播放1次。 | 781| begin | number | 否 | 否 | 动画插值起点。<br/>**说明:** 会影响[onFrame](#onframe12)回调的入参值。<br/>默认值：0 | 782| end | number | 否 | 否 | 动画插值终点。<br/>**说明:** 会影响[onFrame](#onframe12)回调的入参值。 <br/>默认值：1 | 783 784## SimpleAnimatorOptions<sup>18+</sup> 785 786animator简易动画参数对象。与AnimatorOptions相比，部分动画参数有默认值，可不设置。 787 788### constructor<sup>18+</sup> 789 790constructor(begin: number, end: number) 791 792SimpleAnimatorOptions的构造函数。 793 794**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 795 796**系统能力：** SystemCapability.ArkUI.ArkUI.Full 797 798**参数：** 799 800| 参数名 | 类型 | 必填 | 说明 | 801| ---------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 802| begin | number | 是 | 动画插值起点。 | 803| end | number | 是 | 动画插值终点。 804 805**示例：** 806 807完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 808 809```ts 810import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 811 812let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200); // 动画插值过程从100到200，其余动画参数使用默认值。 813let animatorResult:AnimatorResult = animator.create(options); 814``` 815 816### duration<sup>18+</sup> 817 818duration(duration: number): SimpleAnimatorOptions 819 820设置animator动画时长。 821 822**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 823 824**系统能力：** SystemCapability.ArkUI.ArkUI.Full 825 826**参数：** 827 828| 参数名 | 类型 | 必填 | 说明 | 829| ------- | ----------------------------------- | ---- | ------- | 830| duration | number | 是 | 设置动画时长，单位毫秒。<br/>默认值：1000 | 831 832**返回值：** 833 834| 类型 | 说明 | 835| --------------------------------- | ------------- | 836| [SimpleAnimatorOptions](#simpleanimatoroptions18) | Animator简易动画参数对象。 | 837 838**示例：** 839 840完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 841 842```ts 843import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 844 845let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).duration(500); 846let animatorResult:AnimatorResult = animator.create(options); 847``` 848 849### easing<sup>18+</sup> 850 851easing(curve: string): SimpleAnimatorOptions 852 853设置animator动画插值曲线。 854 855**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 856 857**系统能力：** SystemCapability.ArkUI.ArkUI.Full 858 859**参数：** 860 861| 参数名 | 类型 | 必填 | 说明 | 862| ------- | ----------------------------------- | ---- | ------- | 863| curve | string | 是 | 设置animator动画插值曲线，具体说明参考[AnimatorOptions](#animatoroptions)。<br/>默认值：“ease” | 864 865**返回值：** 866 867| 类型 | 说明 | 868| --------------------------------- | ------------- | 869| [SimpleAnimatorOptions](#simpleanimatoroptions18) | Animator简易动画参数对象。 | 870 871**示例：** 872 873完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 874 875```ts 876import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 877 878let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).easing("ease-in"); 879let animatorResult:AnimatorResult = animator.create(options); 880``` 881 882### delay<sup>18+</sup> 883 884delay(delay: number): SimpleAnimatorOptions 885 886设置animator动画播放时延。 887 888**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 889 890**系统能力：** SystemCapability.ArkUI.ArkUI.Full 891 892**参数：** 893 894| 参数名 | 类型 | 必填 | 说明 | 895| ------- | ----------------------------------- | ---- | ------- | 896| delay | number | 是 | 设置animator动画播放时延，单位毫秒，设置为0时，表示不延时。设置为负数时动画提前播放，如果提前播放的时长大于动画总时长，动画直接过渡到终点。<br/>默认值：0 | 897 898**返回值：** 899 900| 类型 | 说明 | 901| --------------------------------- | ------------- | 902| [SimpleAnimatorOptions](#simpleanimatoroptions18) | Animator简易动画参数对象。 | 903 904**示例：** 905 906完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 907 908```ts 909import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 910 911let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).delay(500); 912let animatorResult:AnimatorResult = animator.create(options); 913``` 914 915### fill<sup>18+</sup> 916 917fill(fillMode: [FillMode](./arkui-ts/ts-appendix-enums.md#fillmode)): SimpleAnimatorOptions 918 919设置animator动画填充方式。 920 921**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 922 923**系统能力：** SystemCapability.ArkUI.ArkUI.Full 924 925**参数：** 926 927| 参数名 | 类型 | 必填 | 说明 | 928| ------- | ----------------------------------- | ---- | ------- | 929| fillMode | [FillMode](./arkui-ts/ts-appendix-enums.md#fillmode) | 是 | 设置animator动画填充方式，影响动画delay期间和结束时的表现。<br/>默认值：FillMode.Forwards | 930 931**返回值：** 932 933| 类型 | 说明 | 934| --------------------------------- | ------------- | 935| [SimpleAnimatorOptions](#simpleanimatoroptions18) | Animator简易动画参数对象。 | 936 937**示例：** 938 939完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 940 941```ts 942import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 943 944let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).fill(FillMode.Forwards); 945let animatorResult:AnimatorResult = animator.create(options); 946``` 947 948### direction<sup>18+</sup> 949 950direction(direction: [PlayMode](./arkui-ts/ts-appendix-enums.md#playmode)): SimpleAnimatorOptions 951 952设置animator动画播放方向。 953 954**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 955 956**系统能力：** SystemCapability.ArkUI.ArkUI.Full 957 958**参数：** 959 960| 参数名 | 类型 | 必填 | 说明 | 961| ------- | ----------------------------------- | ---- | ------- | 962| direction | [PlayMode](./arkui-ts/ts-appendix-enums.md#playmode) | 是 | 设置animator动画播放方向。<br/>默认值：PlayMode.Normal | 963 964**返回值：** 965 966| 类型 | 说明 | 967| --------------------------------- | ------------- | 968| [SimpleAnimatorOptions](#simpleanimatoroptions18) | Animator简易动画参数对象。 | 969 970**示例：** 971 972完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 973 974```ts 975import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 976 977let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).direction(PlayMode.Alternate); 978let animatorResult:AnimatorResult = animator.create(options); 979``` 980 981### iterations<sup>18+</sup> 982 983iterations(iterations: number): SimpleAnimatorOptions 984 985设置animator动画播放次数。 986 987**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 988 989**系统能力：** SystemCapability.ArkUI.ArkUI.Full 990 991**参数：** 992 993| 参数名 | 类型 | 必填 | 说明 | 994| ------- | ----------------------------------- | ---- | ------- | 995| iterations | number | 是 | 设置animator动画播放次数，设置为0时不播放，设置为-1时无限次播放。<br/>默认值：1 | 996 997**返回值：** 998 999| 类型 | 说明 | 1000| --------------------------------- | ------------- | 1001| [SimpleAnimatorOptions](#simpleanimatoroptions18) | Animator简易动画参数对象。 | 1002 1003**示例：** 1004 1005完整示例请参考[基于ArkTS扩展的声明式开发范式](#基于arkts扩展的声明式开发范式)。 1006 1007```ts 1008import { Animator as animator, AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 1009 1010let options: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).iterations(3); 1011let animatorResult:AnimatorResult = animator.create(options); 1012``` 1013 1014## 完整示例 1015### 基于JS扩展的类Web开发范式 1016 1017```html 1018<!-- hml --> 1019<div class="container"> 1020 <div class="Animation" style="height: {{divHeight}}px; width: {{divWidth}}px; background-color: red;" onclick="Show"> 1021 </div> 1022</div> 1023``` 1024 1025<!--code_no_check--> 1026<!--deprecated_code_no_check--> 1027```ts 1028import { Animator as animator, AnimatorResult } from '@kit.ArkUI'; 1029import { BusinessError } from '@kit.BasicServicesKit'; 1030 1031let DataTmp: Record<string, Animator> = { 1032 'divWidth': 200, 1033 'divHeight': 200, 1034 'animator': animator 1035} 1036 1037class Tmp { 1038 data: animator = DataTmp 1039 onInit: Function = () => { 1040 } 1041 Show: Function = () => { 1042 } 1043} 1044 1045class DateT { 1046 divWidth: number = 0 1047 divHeight: number = 0 1048 animator: AnimatorResult | null = null 1049} 1050 1051(Fn: (v: Tmp) => void) => { 1052 Fn({ 1053 data: DataTmp, 1054 onInit() { 1055 let options: AnimatorOptions = { 1056 duration: 1500, 1057 easing: "friction", 1058 delay: 0, 1059 fill: "forwards", 1060 direction: "normal", 1061 iterations: 2, 1062 begin: 200.0, 1063 end: 400.0 1064 }; 1065 let DataTmp: DateT = { 1066 divWidth: 200, 1067 divHeight: 200, 1068 animator: null 1069 } 1070 DataTmp.animator = animator.create(options); 1071 }, 1072 Show() { 1073 let options1: AnimatorOptions = { 1074 duration: 1500, 1075 easing: "friction", 1076 delay: 0, 1077 fill: "forwards", 1078 direction: "normal", 1079 iterations: 2, 1080 begin: 0, 1081 end: 400.0, 1082 }; 1083 let DataTmp: DateT = { 1084 divWidth: 200, 1085 divHeight: 200, 1086 animator: null 1087 } 1088 try { 1089 DataTmp.animator = animator.create(options1); 1090 DataTmp.animator.reset(options1); 1091 } catch (error) { 1092 let message = (error as BusinessError).message 1093 let code = (error as BusinessError).code 1094 console.error(`Animator reset failed, error code: ${code}, message: ${message}.`); 1095 } 1096 let _this = DataTmp; 1097 if (DataTmp.animator) { 1098 DataTmp.animator.onFrame = (value: number) => { 1099 _this.divWidth = value; 1100 _this.divHeight = value; 1101 }; 1102 DataTmp.animator.play(); 1103 } 1104 } 1105 }) 1106} 1107``` 1108 1109  1110 1111### 基于ArkTS扩展的声明式开发范式 1112 1113> **说明：** 1114> 1115> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[createAnimator](arkts-apis-uicontext-uicontext.md#createanimator)接口明确UI上下文。 1116 1117<!--deprecated_code_no_check--> 1118```ts 1119import { AnimatorResult } from '@kit.ArkUI'; 1120 1121@Entry 1122@Component 1123struct AnimatorTest { 1124 private TAG: string = '[AnimatorTest]' 1125 private backAnimator: AnimatorResult | undefined = undefined 1126 private flag: boolean = false 1127 @State columnWidth: number = 100 1128 @State columnHeight: number = 100 1129 1130 create() { 1131 this.backAnimator = this.getUIContext().createAnimator({ 1132 // 建议使用 this.getUIContext().createAnimator()接口 1133 duration: 2000, 1134 easing: "ease", 1135 delay: 0, 1136 fill: "forwards", 1137 direction: "normal", 1138 iterations: 1, 1139 begin: 100, //动画插值起点 1140 end: 200 //动画插值终点 1141 }) 1142 this.backAnimator.onFinish = () => { 1143 this.flag = true 1144 console.info(this.TAG, 'backAnimator onFinish') 1145 } 1146 this.backAnimator.onRepeat = () => { 1147 console.info(this.TAG, 'backAnimator repeat') 1148 } 1149 this.backAnimator.onCancel = () => { 1150 console.info(this.TAG, 'backAnimator cancel') 1151 } 1152 this.backAnimator.onFrame = (value: number) => { 1153 this.columnWidth = value 1154 this.columnHeight = value 1155 } 1156 } 1157 1158 aboutToDisappear() { 1159 // 自定义组件消失时调用finish使未完成的动画结束，避免动画继续运行。 1160 // 由于backAnimator在onframe中引用了this, this中保存了backAnimator， 1161 // 在自定义组件消失时应该将保存在组件中的backAnimator置空，避免内存泄漏 1162 this.backAnimator?.finish(); 1163 this.backAnimator = undefined; 1164 } 1165 1166 build() { 1167 Column() { 1168 Column() { 1169 Column() 1170 .width(this.columnWidth) 1171 .height(this.columnHeight) 1172 .backgroundColor(Color.Red) 1173 } 1174 .width('100%') 1175 .height(300) 1176 1177 Column() { 1178 Row() { 1179 Button('create') 1180 .fontSize(30) 1181 .fontColor(Color.Black) 1182 .onClick(() => { 1183 this.create() 1184 }) 1185 } 1186 .padding(10) 1187 1188 Row() { 1189 Button('play') 1190 .fontSize(30) 1191 .fontColor(Color.Black) 1192 .onClick(() => { 1193 this.flag = false 1194 if (this.backAnimator) { 1195 this.backAnimator.play() 1196 } 1197 }) 1198 } 1199 .padding(10) 1200 1201 Row() { 1202 Button('pause') 1203 .fontSize(30) 1204 .fontColor(Color.Black) 1205 .onClick(() => { 1206 if (this.backAnimator) { 1207 this.backAnimator.pause() 1208 } 1209 }) 1210 } 1211 .padding(10) 1212 1213 Row() { 1214 Button('finish') 1215 .fontSize(30) 1216 .fontColor(Color.Black) 1217 .onClick(() => { 1218 this.flag = true 1219 if (this.backAnimator) { 1220 this.backAnimator.finish() 1221 } 1222 }) 1223 } 1224 .padding(10) 1225 1226 Row() { 1227 Button('reverse') 1228 .fontSize(30) 1229 .fontColor(Color.Black) 1230 .onClick(() => { 1231 this.flag = false 1232 if (this.backAnimator) { 1233 this.backAnimator.reverse() 1234 } 1235 }) 1236 } 1237 .padding(10) 1238 1239 Row() { 1240 Button('cancel') 1241 .fontSize(30) 1242 .fontColor(Color.Black) 1243 .onClick(() => { 1244 if (this.backAnimator) { 1245 this.backAnimator.cancel() 1246 } 1247 }) 1248 } 1249 .padding(10) 1250 1251 Row() { 1252 Button('reset') 1253 .fontSize(30) 1254 .fontColor(Color.Black) 1255 .onClick(() => { 1256 if (this.flag) { 1257 this.flag = false 1258 if (this.backAnimator) { 1259 this.backAnimator.reset({ 1260 duration: 3000, 1261 easing: "ease-in", 1262 delay: 0, 1263 fill: "forwards", 1264 direction: "alternate", 1265 iterations: 3, 1266 begin: 100, 1267 end: 300 1268 }) 1269 } 1270 } else { 1271 console.info(this.TAG, 'Animation not ended') 1272 } 1273 }) 1274 } 1275 .padding(10) 1276 } 1277 } 1278 } 1279} 1280``` 1281 1282### 位移动画示例（简易入参） 1283 1284```ts 1285import { AnimatorResult, SimpleAnimatorOptions } from '@kit.ArkUI'; 1286 1287@Entry 1288@Component 1289struct AnimatorTest { 1290 private TAG: string = '[AnimatorTest]' 1291 private backAnimator: AnimatorResult | undefined = undefined 1292 private flag: boolean = false 1293 @State translate_: number = 0 1294 1295 create() { 1296 this.backAnimator = this.getUIContext()?.createAnimator( 1297 new SimpleAnimatorOptions(0, 100) 1298 ) 1299 this.backAnimator.onFinish = ()=> { 1300 this.flag = true 1301 console.info(this.TAG, 'backAnimator onFinish') 1302 } 1303 this.backAnimator.onFrame = (value:number)=> { 1304 this.translate_ = value 1305 } 1306 } 1307 1308 aboutToDisappear() { 1309 // 自定义组件消失时调用finish使未完成的动画结束，避免动画继续运行。 1310 // 由于backAnimator在onframe中引用了this, this中保存了backAnimator， 1311 // 在自定义组件消失时应该将保存在组件中的backAnimator置空，避免内存泄漏 1312 this.backAnimator?.finish(); 1313 this.backAnimator = undefined; 1314 } 1315 1316 build() { 1317 Column() { 1318 Column() { 1319 Column() 1320 .width(100) 1321 .height(100) 1322 .translate({x: this.translate_}) 1323 .backgroundColor(Color.Green) 1324 } 1325 .width('100%') 1326 .height(300) 1327 1328 Column() { 1329 Column() { 1330 Button('create') 1331 .fontSize(30) 1332 .fontColor(Color.White) 1333 .onClick(() => { 1334 this.create() 1335 }) 1336 } 1337 .padding(10) 1338 1339 Column() { 1340 Button('play') 1341 .fontSize(30) 1342 .fontColor(Color.White) 1343 .onClick(() => { 1344 this.flag = false 1345 if(this.backAnimator){ 1346 this.backAnimator.play() 1347 } 1348 }) 1349 } 1350 .padding(10) 1351 1352 Column() { 1353 Button('reset') 1354 .fontSize(30) 1355 .fontColor(Color.White) 1356 .onClick(() => { 1357 if (this.flag) { 1358 this.flag = false 1359 if(this.backAnimator){ 1360 this.backAnimator.reset( 1361 new SimpleAnimatorOptions(0, -100) 1362 .duration(2000) 1363 .easing("ease-in") 1364 .fill(FillMode.Forwards) 1365 .direction(PlayMode.Alternate) 1366 .iterations(2) 1367 ) 1368 } 1369 } else { 1370 console.info(this.TAG, 'Animation not ended') 1371 } 1372 }) 1373 } 1374 .padding(10) 1375 } 1376 } 1377 } 1378} 1379``` 1380 1381 1382
