1# ImageAnimator 2 3The **ImageAnimator** component enables images to be played a frame-by-frame basis. The list of images to be played as well as the duration of each image can be configured. 4 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10 11## Child Components 12 13Not supported 14 15 16## APIs 17 18ImageAnimator() 19 20**Widget capability**: This API can be used in ArkTS widgets since API version 10. 21 22**Atomic service API**: This API can be used in atomic services since API version 11. 23 24**System capability**: SystemCapability.ArkUI.ArkUI.Full 25 26## Attributes 27 28In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 29 30### images 31 32images(value: Array<ImageFrameInfo>) 33 34Sets the image frame information. Dynamic update is not supported. 35 36**Widget capability**: This API can be used in ArkTS widgets since API version 10. 37 38**Atomic service API**: This API can be used in atomic services since API version 11. 39 40**System capability**: SystemCapability.ArkUI.ArkUI.Full 41 42**Parameters** 43 44| Name | Type | Mandatory | Description | 45| ------ | ------------------------------------------------------ | ---- | ------------------------------------------------------------ | 46| value | Array<[ImageFrameInfo](#imageframeinfo)> | Yes | Image frame information. The information of each frame includes the image path, image size, image position, and image playback duration. For details, see **ImageFrameInfo**.<br>Default value: **[]** | 47 48### state 49 50state(value: AnimationStatus) 51 52Sets the playback state of the animation. 53 54**Widget capability**: This API can be used in ArkTS widgets since API version 10. 55 56**Atomic service API**: This API can be used in atomic services since API version 11. 57 58**System capability**: SystemCapability.ArkUI.ArkUI.Full 59 60**Parameters** 61 62| Name | Type | Mandatory | Description | 63| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 64| value | [AnimationStatus](ts-appendix-enums.md#animationstatus) | Yes | Playback state of the animation. The default state is **Initial**.<br>Default value: **AnimationStatus.Initial** | 65 66### duration 67 68duration(value: number) 69 70Sets the playback duration. This attribute does not take effect when a separate duration is set for any of the image frames. 71 72**Widget capability**: This API can be used in ArkTS widgets since API version 10. 73 74**Atomic service API**: This API can be used in atomic services since API version 11. 75 76**System capability**: SystemCapability.ArkUI.ArkUI.Full 77 78**Parameters** 79 80| Name | Type | Mandatory | Description | 81| ------ | ------ | ---- | ------------------------------------------------------------ | 82| value | number | Yes | Playback duration.<br>If the value is **0**, no image is played.<br>The value change takes effect only at the start of the next cycle.<br>Unit: ms<br>Default value: **1000** | 83 84### reverse 85 86reverse(value: boolean) 87 88Sets the playback direction. 89 90**Widget capability**: This API can be used in ArkTS widgets since API version 10. 91 92**Atomic service API**: This API can be used in atomic services since API version 11. 93 94**System capability**: SystemCapability.ArkUI.ArkUI.Full 95 96**Parameters** 97 98| Name | Type | Mandatory | Description | 99| ------ | ------- | ---- | ------------------------------------------------------------ | 100| value | boolean | Yes | Playback direction.<br>The value **false** indicates that images are played from the first one to the last one, and **true** indicates that images are played from the last one to the first one.<br>Default value: **false** | 101 102### fixedSize 103 104fixedSize(value: boolean) 105 106Sets whether the image size is fixed at the component size. 107 108**Widget capability**: This API can be used in ArkTS widgets since API version 10. 109 110**Atomic service API**: This API can be used in atomic services since API version 11. 111 112**System capability**: SystemCapability.ArkUI.ArkUI.Full 113 114**Parameters** 115 116| Name | Type | Mandatory | Description | 117| ------ | ------- | ---- | ------------------------------------------------------------ | 118| value | boolean | Yes | Whether the image size is fixed at the component size.<br> **true**: The image size is fixed at the component size. In this case, the width, height, top, and left attributes of the image are invalid.<br> **false**: The width, height, top, and left attributes of each image must be set separately.<br>Default value: **true** | 119 120### preDecode<sup>(deprecated)</sup> 121 122preDecode(value: number) 123 124Sets the number of images to be pre-decoded. 125 126This API is deprecated since API version 9. 127 128**System capability**: SystemCapability.ArkUI.ArkUI.Full 129 130**Parameters** 131 132| Name | Type | Mandatory | Description | 133| ------ | ------ | ---- | ------------------------------------------------------------ | 134| value | number | Yes | Number of images to be pre-decoded. For example, the value **2** indicates that two images following the currently playing one are pre-decoded.<br>Default value: **0** | 135 136### fillMode 137 138fillMode(value: FillMode) 139 140Sets the status before and after execution of the animation in the current playback direction. The status after execution of the animation is jointly determined by the **fillMode** and **reverse** attributes. For example, if **fillMode** is set to **Forwards**, the target will retain the state defined by the last keyframe encountered during execution. In this case, if **reverse** is set to **false**, the target will retain the state defined by the last keyframe encountered in the forward direction, that is, the last image; if **reverse** is set to **true**, the target will retain the state defined by the last keyframe encountered in the backward direction, that is, the first image. 141 142**Widget capability**: This API can be used in ArkTS widgets since API version 10. 143 144**Atomic service API**: This API can be used in atomic services since API version 11. 145 146**System capability**: SystemCapability.ArkUI.ArkUI.Full 147 148**Parameters** 149 150| Name | Type | Mandatory | Description | 151| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 152| value | [FillMode](ts-appendix-enums.md#fillmode) | Yes | Status before and after execution of the animation in the current playback direction.<br>Default value: **FillMode.Forwards** | 153 154### iterations 155 156iterations(value: number) 157 158Sets the number of times that the animation is played. 159 160**Atomic service API**: This API can be used in atomic services since API version 11. 161 162**System capability**: SystemCapability.ArkUI.ArkUI.Full 163 164**Parameters** 165 166| Name | Type | Mandatory | Description | 167| ------ | ------ | ---- | ------------------------------------------------------ | 168| value | number | Yes | Number of times that the animation is played. By default, the animation is played once. The value **-1** indicates that the animation is played for an unlimited number of times.<br>Default value: **1** | 169 170## ImageFrameInfo 171 172**Atomic service API**: This API can be used in atomic services since API version 11. 173 174**System capability**: SystemCapability.ArkUI.ArkUI.Full 175 176| Name | Type | Mandatory| Description| 177| -------- | -------------- | -------- | -------- | 178| src | string \| [Resource](ts-types.md#resource)<sup>9+</sup> \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)<sup>12+</sup> | Yes | Image path. The image format can be .jpg, .jpeg, .svg, .png, .bmp, .webp, .ico, or .heif. The [Resource](ts-types.md#resource) type is supported since API version 9, and the [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) type is supported since API version 12.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 179| width | number \| string | No | Image width.<br>Default value: **0**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10. | 180| height | number \| string | No | Image height.<br>Default value: **0**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10. | 181| top | number \| string | No | Vertical coordinate of the image relative to the upper left corner of the widget<br>Default value: **0**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10. | 182| left | number \| string | No | Horizontal coordinate of the image relative to the upper left corner of the widget<br>Default value: **0**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10. | 183| duration | number | No | Playback duration of each image frame, in milliseconds.<br>Default value: **0** | 184 185## Events 186 187In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 188 189### onStart 190 191onStart(event: () => void) 192 193Triggered when the animation starts to play. 194 195**Widget capability**: This API can be used in ArkTS widgets since API version 10. 196 197**Atomic service API**: This API can be used in atomic services since API version 11. 198 199**System capability**: SystemCapability.ArkUI.ArkUI.Full 200 201### onPause 202 203onPause(event: () => void) 204 205Triggered when the animation playback is paused. 206 207**Widget capability**: This API can be used in ArkTS widgets since API version 10. 208 209**Atomic service API**: This API can be used in atomic services since API version 11. 210 211**System capability**: SystemCapability.ArkUI.ArkUI.Full 212 213### onRepeat 214 215onRepeat(event: () => void) 216 217Triggered when the animation playback is repeated. 218 219**Atomic service API**: This API can be used in atomic services since API version 11. 220 221**System capability**: SystemCapability.ArkUI.ArkUI.Full 222 223### onCancel 224 225onCancel(event: () => void) 226 227Triggered when the animation playback returns to the initial state. 228 229**Widget capability**: This API can be used in ArkTS widgets since API version 10. 230 231**Atomic service API**: This API can be used in atomic services since API version 11. 232 233**System capability**: SystemCapability.ArkUI.ArkUI.Full 234 235### onFinish 236 237onFinish(event: () => void) 238 239Triggered when the animation playback is complete or stopped. 240 241**Widget capability**: This API can be used in ArkTS widgets since API version 10. 242 243**Atomic service API**: This API can be used in atomic services since API version 11. 244 245**System capability**: SystemCapability.ArkUI.ArkUI.Full 246 247 248## Example 249 250### Example 1: Playing an Animation Using Images of the Resource Type 251 252This example demonstrates how to play an animation using the **ImageAnimator** component with images of the Resource type. 253 254```ts 255// xxx.ets 256@Entry 257@Component 258struct ImageAnimatorExample { 259 @State state: AnimationStatus = AnimationStatus.Initial 260 @State reverse: boolean = false 261 @State iterations: number = 1 262 263 build() { 264 Column({ space: 10 }) { 265 ImageAnimator() 266 .images([ 267 { 268 src: $r('app.media.img1') 269 }, 270 { 271 src: $r('app.media.img2') 272 }, 273 { 274 src: $r('app.media.img3') 275 }, 276 { 277 src: $r('app.media.img4') 278 } 279 ]) 280 .duration(2000) 281 .state(this.state).reverse(this.reverse) 282 .fillMode(FillMode.None).iterations(this.iterations).width(340).height(240) 283 .margin({ top: 100 }) 284 .onStart(() => { 285 console.info('Start') 286 }) 287 .onPause(() => { 288 console.info('Pause') 289 }) 290 .onRepeat(() => { 291 console.info('Repeat') 292 }) 293 .onCancel(() => { 294 console.info('Cancel') 295 }) 296 .onFinish(() => { 297 console.info('Finish') 298 this.state = AnimationStatus.Stopped 299 }) 300 Row() { 301 Button('start').width(100).padding(5).onClick(() => { 302 this.state = AnimationStatus.Running 303 }).margin(5) 304 Button('pause').width(100).padding(5).onClick(() => { 305 this.state = AnimationStatus.Paused // Display the image of the current frame. 306 }).margin(5) 307 Button('stop').width(100).padding(5).onClick(() => { 308 this.state = AnimationStatus.Stopped // Display the image of the initial frame. 309 }).margin(5) 310 } 311 312 Row() { 313 Button('reverse').width(100).padding(5).onClick(() => { 314 this.reverse = !this.reverse 315 }).margin(5) 316 Button('once').width(100).padding(5).onClick(() => { 317 this.iterations = 1 318 }).margin(5) 319 Button('infinite').width(100).padding(5).onClick(() => { 320 this.iterations = -1 // The animation is played for an unlimited number of times. 321 }).margin(5) 322 } 323 }.width('100%').height('100%') 324 } 325} 326``` 327 328### Example 2: Playing an Animation Using Images of the PixelMap Type 329 330This example demonstrates how to play an animation using the **ImageAnimator** component with images of the PixelMap type. 331 332```ts 333// xxx.ets 334import { image } from '@kit.ImageKit' 335 336@Entry 337@Component 338struct ImageAnimatorExample { 339 imagePixelMap: Array<PixelMap> = [] 340 @State state: AnimationStatus = AnimationStatus.Initial 341 @State reverse: boolean = false 342 @State iterations: number = 1 343 @State images:Array<ImageFrameInfo> = [] 344 async aboutToAppear() { 345 this.imagePixelMap.push(await this.getPixmapFromMedia($r('app.media.icon'))) 346 this.images.push({src:this.imagePixelMap[0]}) 347 } 348 build() { 349 Column({ space: 10 }) { 350 ImageAnimator() 351 .images(this.images) 352 .duration(2000) 353 .state(this.state).reverse(this.reverse) 354 .fillMode(FillMode.None).iterations(this.iterations).width(340).height(240) 355 .margin({ top: 100 }) 356 .onStart(() => { 357 console.info('Start') 358 }) 359 .onPause(() => { 360 console.info('Pause') 361 }) 362 .onRepeat(() => { 363 console.info('Repeat') 364 }) 365 .onCancel(() => { 366 console.info('Cancel') 367 }) 368 .onFinish(() => { 369 console.info('Finish') 370 this.state = AnimationStatus.Stopped 371 }) 372 Row() { 373 Button('start').width(100).padding(5).onClick(() => { 374 this.state = AnimationStatus.Running 375 }).margin(5) 376 Button('pause').width(100).padding(5).onClick(() => { 377 this.state = AnimationStatus.Paused // Display the image of the current frame. 378 }).margin(5) 379 Button('stop').width(100).padding(5).onClick(() => { 380 this.state = AnimationStatus.Stopped // Display the image of the initial frame. 381 }).margin(5) 382 } 383 Row() { 384 Button('reverse').width(100).padding(5).onClick(() => { 385 this.reverse = !this.reverse 386 }).margin(5) 387 Button('once').width(100).padding(5).onClick(() => { 388 this.iterations = 1 389 }).margin(5) 390 Button('infinite').width(100).padding(5).onClick(() => { 391 this.iterations = -1 // The animation is played for an unlimited number of times. 392 }).margin(5) 393 } 394 }.width('100%').height('100%') 395 } 396 397 private async getPixmapFromMedia(resource: Resource) { 398 let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({ 399 bundleName: resource.bundleName, 400 moduleName: resource.moduleName, 401 id: resource.id 402 }) 403 let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength)) 404 let createPixelMap: image.PixelMap = await imageSource.createPixelMap({ 405 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 406 }) 407 await imageSource.release() 408 return createPixelMap 409 } 410} 411``` 412 413 414
