1# @ohos.animator (动画) 2 3本模块提供组件动画效果，包括定义动画、启动动画和以相反的顺序播放动画等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 该模块不支持在[UIAbility](./js-apis-app-ability-uiAbility.md)的文件声明处使用，即不能在UIAbility的生命周期中调用，需要在创建组件实例后使用。 10 11 12## 导入模块 13 14```js 15import animator from '@ohos.animator'; 16``` 17## create<sup>9+</sup> 18 19create(options: AnimatorOptions): AnimatorResult 20 21定义Animator类。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------- | ----------------------------------- | ---- | ------- | 29| options | [AnimatorOptions](#animatoroptions) | 是 | 定义动画选项。 | 30 31**返回值：** 32 33| 类型 | 说明 | 34| --------------------------------- | ------------- | 35| [AnimatorResult](#animatorresult) | Animator结果接口。 | 36 37**示例：** 38 39 ```js 40import animator, { AnimatorOptions } from '@ohos.animator'; 41 42let options: AnimatorOptions = { // xxx.js文件中不需要强调显式类型AnimatorOptions 43 duration: 1500, 44 easing: "friction", 45 delay: 0, 46 fill: "forwards", 47 direction: "normal", 48 iterations: 3, 49 begin: 200.0, 50 end: 400.0 51}; 52animator.create(options); 53 ``` 54 55## AnimatorResult 56 57定义Animator结果接口。 58 59### reset<sup>9+</sup> 60 61reset(options: AnimatorOptions): void 62 63更新当前动画器。 64 65**系统能力：** SystemCapability.ArkUI.ArkUI.Full 66 67**参数：** 68 69| 参数名 | 类型 | 必填 | 说明 | 70| ------- | ----------------------------------- | ---- | ------- | 71| options | [AnimatorOptions](#animatoroptions) | 是 | 定义动画选项。 | 72 73**错误码：** 74 75以下错误码的详细介绍请参见[ohos.animator(动画)](../errorcodes/errorcode-animator.md)错误码。 76 77| 错误码ID | 错误信息 | 78| --------- | ------- | 79| 100001 | if no page is found for pageId or fail to get object property list. | 80 81 82**示例：** 83 84```js 85let options: AnimatorOptions = { // xxx.js文件中不需要强调显式类型AnimatorOptions 86 duration: 1500, 87 easing: "friction", 88 delay: 0, 89 fill: "forwards", 90 direction: "normal", 91 iterations: 3, 92 begin: 200.0, 93 end: 400.0 94}; 95try { 96 animator.reset(options); 97} catch(error) { 98 console.error(`Animator reset failed, error code: ${error.code}, message: ${error.message}.`); 99} 100``` 101 102### play 103 104play(): void 105 106启动动画。动画会保留上一次的播放状态，比如播放状态设置reverse后，再次播放会保留reverse的播放状态。 107 108**系统能力：** SystemCapability.ArkUI.ArkUI.Full 109 110**示例：** 111 112```js 113animator.play(); 114``` 115 116### finish 117 118finish(): void 119 120结束动画。 121 122**系统能力：** SystemCapability.ArkUI.ArkUI.Full 123 124**示例：** 125 126```js 127animator.finish(); 128``` 129 130### pause 131 132pause(): void 133 134暂停动画。 135 136**系统能力：** SystemCapability.ArkUI.ArkUI.Full 137 138**示例：** 139 140```js 141animator.pause(); 142``` 143 144### cancel 145 146cancel(): void 147 148删除动画。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152**示例：** 153 154```js 155animator.cancel(); 156``` 157 158### reverse 159 160reverse(): void 161 162以相反的顺序播放动画。 163 164**系统能力：** SystemCapability.ArkUI.ArkUI.Full 165 166**示例：** 167 168```js 169animator.reverse(); 170``` 171 172### onframe 173 174onframe: (progress: number) => void 175 176接收到帧时回调。 177 178**系统能力：** SystemCapability.ArkUI.ArkUI.Full 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| -------- | ------ | ---- | -------- | 184| progress | number | 是 | 动画的当前进度。 | 185 186**示例：** 187 188```js 189let animatorResult = animator.create(options) 190animatorResult.onframe = function(value) { 191 console.info("onframe callback") 192} 193``` 194 195### onfinish 196 197onfinish: () => void 198 199动画完成时回调。 200 201**系统能力：** SystemCapability.ArkUI.ArkUI.Full 202 203**示例：** 204 205```js 206let animatorResult = animator.create(options) 207animatorResult.onfinish = function() { 208 console.info("onfinish callback") 209} 210``` 211 212### oncancel 213 214oncancel: () => void 215 216动画被取消时回调。 217 218**系统能力：** SystemCapability.ArkUI.ArkUI.Full 219 220**示例：** 221 222```js 223let animatorResult = animator.create(options) 224animatorResult.oncancel = function() { 225 console.info("oncancel callback") 226} 227``` 228 229### onrepeat 230 231onrepeat: () => void 232 233动画重复时回调。 234 235**系统能力：** SystemCapability.ArkUI.ArkUI.Full 236 237**示例：** 238 239```js 240let animatorResult = animator.create(options) 241animatorResult.onrepeat = function() { 242 console.info("onrepeat callback") 243} 244``` 245 246 247 248## AnimatorOptions 249 250定义动画选项。 251 252**系统能力：** SystemCapability.ArkUI.ArkUI.Full 253 254| 名称 | 类型 | 必填 | 说明 | 255| ---------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 256| duration | number | 是 | 动画播放的时长，单位毫秒。 | 257| 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/>"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)"。 | 258| delay | number | 是 | 动画延时播放时长，单位毫秒，设置为0时，表示不延时。 | 259| fill | "none" \| "forwards" \| "backwards" \| "both" | 是 | 动画执行后是否恢复到初始状态，动画执行后，动画结束时的状态（在最后一个关键帧中定义）将保留。<br/>"none"：在动画执行之前和之后都不会应用任何样式到目标上。<br/>"forwards"：在动画结束后，目标将保留动画结束时的状态（在最后一个关键帧中定义）。<br/>"backwards"：动画将在animation-delay期间应用第一个关键帧中定义的值。当animation-direction为"normal"或"alternate"时应用from关键帧中的值，当animation-direction为"reverse"或"alternate-reverse"时应用to关键帧中的值。<br/>"both"：动画将遵循forwards和backwards的规则，从而在两个方向上扩展动画属性。 | 260| direction | "normal" \| "reverse" \| "alternate" \| "alternate-reverse" | 是 | 动画播放模式。<br/>"normal"： 动画正向循环播放。<br/>"reverse"： 动画反向循环播放。<br/>"alternate"：动画交替循环播放，奇数次正向播放，偶数次反向播放。<br/>"alternate-reverse"：动画反向交替循环播放，奇数次反向播放，偶数次正向播放。 | 261| iterations | number | 是 | 动画播放次数。设置为0时不播放，设置为-1时无限次播放。<br/>**说明:** 设置为除-1外其他负数视为无效取值，无效取值动画默认播放1次。 | 262| begin | number | 是 | 动画插值起点。 | 263| end | number | 是 | 动画插值终点。 | 264 265 266## 完整示例 267### 基于JS扩展的类Web开发范式 268 269```html 270<!-- hml --> 271<div class="container"> 272 <div class="Animation" style="height: {{divHeight}}px; width: {{divWidth}}px; background-color: red;" onclick="Show"> 273 </div> 274</div> 275``` 276 277```js 278export default { 279 data: { 280 divWidth: 200, 281 divHeight: 200, 282 animator: null 283 }, 284 onInit() { 285 let options = { 286 duration: 1500, 287 easing: "friction", 288 delay: 0, 289 fill: "forwards", 290 direction: "normal", 291 iterations: 2, 292 begin: 200.0, 293 end: 400.0 294 }; 295 this.animator = animator.create(options); 296 }, 297 Show() { 298 let options1 = { 299 duration: 1500, 300 easing: "friction", 301 delay: 0, 302 fill: "forwards", 303 direction: "normal", 304 iterations: 2, 305 begin: 0, 306 end: 400.0 307 }; 308 try { 309 this.animator.reset(options1); 310 } catch(error) { 311 console.error(`Animator reset failed, error code: ${error.code}, message: ${error.message}.`); 312 } 313 let _this = this; 314 this.animator.onframe = function(value) { 315 _this.divWidth = value; 316 _this.divHeight = value; 317 }; 318 this.animator.play(); 319 } 320} 321``` 322 323  324 325### 基于TS扩展的声明式开发范式 326 327```ts 328import animator from '@ohos.animator'; 329 330@Entry 331@Component 332struct AnimatorTest { 333 private TAG: string = '[AnimatorTest]' 334 private backAnimator: any = undefined 335 private flag: boolean = false 336 @State wid: number = 100 337 @State hei: number = 100 338 339 create() { 340 let _this = this 341 this.backAnimator = animator.create({ 342 duration: 2000, 343 easing: "ease", 344 delay: 0, 345 fill: "none", 346 direction: "normal", 347 iterations: 1, 348 begin: 100, 349 end: 200 350 }) 351 this.backAnimator.onfinish = function () { 352 _this.flag = true 353 console.info(_this.TAG, 'backAnimator onfinish') 354 } 355 this.backAnimator.onrepeat = function () { 356 console.info(_this.TAG, 'backAnimator repeat') 357 } 358 this.backAnimator.oncancel = function () { 359 console.info(_this.TAG, 'backAnimator cancel') 360 } 361 this.backAnimator.onframe = function (value) { 362 _this.wid = value 363 _this.hei = value 364 } 365 } 366 367 build() { 368 Column() { 369 Column() { 370 Column() 371 .width(this.wid) 372 .height(this.hei) 373 .backgroundColor(Color.Red) 374 } 375 .width('100%') 376 .height(300) 377 378 Column() { 379 Row() { 380 Button('create') 381 .fontSize(30) 382 .fontColor(Color.Black) 383 .onClick(() => { 384 this.create() 385 }) 386 } 387 .padding(10) 388 389 Row() { 390 Button('play') 391 .fontSize(30) 392 .fontColor(Color.Black) 393 .onClick(() => { 394 this.flag = false 395 this.backAnimator.play() 396 }) 397 } 398 .padding(10) 399 400 Row() { 401 Button('pause') 402 .fontSize(30) 403 .fontColor(Color.Black) 404 .onClick(() => { 405 this.backAnimator.pause() 406 }) 407 } 408 .padding(10) 409 410 Row() { 411 Button('finish') 412 .fontSize(30) 413 .fontColor(Color.Black) 414 .onClick(() => { 415 this.flag = true 416 this.backAnimator.finish() 417 }) 418 } 419 .padding(10) 420 421 Row() { 422 Button('reverse') 423 .fontSize(30) 424 .fontColor(Color.Black) 425 .onClick(() => { 426 this.flag = false 427 this.backAnimator.reverse() 428 }) 429 } 430 .padding(10) 431 432 Row() { 433 Button('cancel') 434 .fontSize(30) 435 .fontColor(Color.Black) 436 .onClick(() => { 437 this.backAnimator.cancel() 438 }) 439 } 440 .padding(10) 441 442 Row() { 443 Button('reset') 444 .fontSize(30) 445 .fontColor(Color.Black) 446 .onClick(() => { 447 if (this.flag) { 448 this.flag = false 449 this.backAnimator.reset({ 450 duration: 5000, 451 easing: "ease-in", 452 delay: 0, 453 fill: "none", 454 direction: "normal", 455 iterations: 4, 456 begin: 100, 457 end: 300 458 }) 459 } else { 460 console.info(this.TAG, 'Animation not ended') 461 } 462 }) 463 } 464 .padding(10) 465 } 466 } 467 } 468} 469``` 470 471## update<sup>(deprecated)</sup> 472 473update(options: AnimatorOptions): void 474 475更新当前动画器。 476 477从API version9开始不再维护，建议使用[reset<sup>9+</sup>](#reset9) 478 479**系统能力：** SystemCapability.ArkUI.ArkUI.Full 480 481**参数：** 482 483| 参数名 | 类型 | 必填 | 说明 | 484| ------- | ----------------------------------- | ---- | ------- | 485| options | [AnimatorOptions](#animatoroptions) | 是 | 定义动画选项。 | 486 487**示例：** 488 489```js 490animator.update(options); 491``` 492 493## createAnimator<sup>(deprecated)</sup> 494 495createAnimator(options: AnimatorOptions): AnimatorResult 496 497定义Animator类。 498 499从API version9开始不再维护，建议使用[create<sup>9+</sup>](#create9) 500 501**系统能力：** SystemCapability.ArkUI.ArkUI.Full 502 503**参数：** 504 505| 参数名 | 类型 | 必填 | 说明 | 506| ------- | ----------------------------------- | ---- | ------- | 507| options | [AnimatorOptions](#animatoroptions) | 是 | 定义动画选项。 | 508 509**返回值：** 510 511| 类型 | 说明 | 512| --------------------------------- | ------------- | 513| [AnimatorResult](#animatorresult) | Animator结果接口。 | 514 515**示例：** 516 517```js 518let options: AnimatorOptions = { // xxx.js文件中不需要强调显式类型AnimatorOptions 519 duration: 1500, 520 easing: "friction", 521 delay: 0, 522 fill: "forwards", 523 direction: "normal", 524 iterations: 3, 525 begin: 200.0, 526 end: 400.0 527}; 528this.animator = animator.createAnimator(options); 529```
