1# ImageAnimator 2 3The **\<ImageAnimator>** component enables images to be played frame by frame. 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 20Since API version 10, this API is supported in ArkTS widgets. 21 22## Attributes 23 24In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 25 26| Name | Type |Description | 27| ---------- | ----------------------- |-------- | 28| images | Array<[ImageFrameInfo](#imageframeinfo)> | 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: **[]**<br>**NOTE**<br>Dynamic update is not supported.<br>Since API version 10, this API is supported in ArkTS widgets.| 29| state | [AnimationStatus](ts-appendix-enums.md#animationstatus) | Playback status of the animation. The default status is **Initial**.<br>Default value: **AnimationStatus.Initial**<br>Since API version 10, this API is supported in ArkTS widgets.| 30| duration | number | Playback duration, in ms. The default duration is 1000 ms. When the duration is **0**, no image is played. The value change takes effect only at the beginning of the next cycle. When a separate duration is set in **images**, the setting of this attribute is invalid.<br>Default value: **1000**<br>Since API version 10, this API is supported in ArkTS widgets.| 31| reverse | boolean | Playback direction. 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**<br>Since API version 10, this API is supported in ArkTS widgets.| 32| fixedSize | boolean | Whether the image size is the same as the component size.<br> **true**: The image size is the same as 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**<br>Since API version 10, this API is supported in ArkTS widgets.| 33| preDecode<sup>(deprecated)</sup> | number | Number of pre-decoded images. The value **2** indicates that two images following the currently playing page will be pre-decoded to improve performance.<br>This API is deprecated since API version 9.<br>Default value: **0** | 34| fillMode | [FillMode](ts-appendix-enums.md#fillmode) | Status before and after execution of the animation in the current playback direction. For details about the options, see **FillMode**. 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.<br>Default value: **FillMode.Forwards**<br>Since API version 10, this API is supported in ArkTS widgets.| 35| iterations | number | 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** | 36 37## ImageFrameInfo 38 39| Name | Type | Mandatory| Description| 40| -------- | -------------- | -------- | -------- | 41| src | string \| [Resource](ts-types.md#resource)<sup>9+</sup> | Yes | Image path. The image format can be .svg, .png, or .jpg. Since API version 9, this attribute accepts paths of the [Resource](ts-types.md#resource) type.<br>Since API version 10, this API is supported in ArkTS widgets.| 42| width | number \| string | No | Image width.<br>Default value: **0**<br>Since API version 10, this API is supported in ArkTS widgets. | 43| height | number \| string | No | Image height.<br>Default value: **0**<br>Since API version 10, this API is supported in ArkTS widgets. | 44| top | number \| string | No | Vertical coordinate of the image relative to the upper left corner of the widget<br>Default value: **0**<br>Since API version 10, this API is supported in ArkTS widgets. | 45| left | number \| string | No | Horizontal coordinate of the image relative to the upper left corner of the widget<br>Default value: **0**<br>Since API version 10, this API is supported in ArkTS widgets. | 46| duration | number | No | Playback duration of each image frame, in milliseconds.<br>Default value: **0** | 47 48## Events 49 50In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 51 52| Name| Description| 53| -------- | -------- | 54| onStart(event: () => void) | Triggered when the animation starts to play.<br>Since API version 10, this API is supported in ArkTS widgets.| 55| onPause(event: () => void) | Triggered when the animation playback is paused.<br>Since API version 10, this API is supported in ArkTS widgets.| 56| onRepeat(event: () => void) | Triggered when the animation playback is repeated. | 57| onCancel(event: () => void) | Triggered when the animation playback is canceled.<br>Since API version 10, this API is supported in ArkTS widgets.| 58| onFinish(event: () => void) | Triggered when the animation playback is complete.<br>Since API version 10, this API is supported in ArkTS widgets.| 59 60 61## Example 62 63```ts 64// xxx.ets 65@Entry 66@Component 67struct ImageAnimatorExample { 68 @State state: AnimationStatus = AnimationStatus.Initial 69 @State reverse: boolean = false 70 @State iterations: number = 1 71 72 build() { 73 Column({ space: 10 }) { 74 ImageAnimator() 75 .images([ 76 { 77 src: $r('app.media.img1') 78 }, 79 { 80 src: $r('app.media.img2') 81 }, 82 { 83 src: $r('app.media.img3') 84 }, 85 { 86 src: $r('app.media.img4') 87 } 88 ]) 89 .duration(2000) 90 .state(this.state).reverse(this.reverse) 91 .fillMode(FillMode.None).iterations(this.iterations).width(340).height(240) 92 .margin({ top: 100 }) 93 .onStart(() => { 94 console.info('Start') 95 }) 96 .onPause(() => { 97 console.info('Pause') 98 }) 99 .onRepeat(() => { 100 console.info('Repeat') 101 }) 102 .onCancel(() => { 103 console.info('Cancel') 104 }) 105 .onFinish(() => { 106 console.info('Finish') 107 this.state = AnimationStatus.Stopped 108 }) 109 Row() { 110 Button('start').width(100).padding(5).onClick(() => { 111 this.state = AnimationStatus.Running 112 }).margin(5) 113 Button('pause').width(100).padding(5).onClick(() => { 114 this.state = AnimationStatus.Paused // Display the image of the current frame. 115 }).margin(5) 116 Button('stop').width(100).padding(5).onClick(() => { 117 this.state = AnimationStatus.Stopped // Display the image of the initial frame. 118 }).margin(5) 119 } 120 121 Row() { 122 Button('reverse').width(100).padding(5).onClick(() => { 123 this.reverse = !this.reverse 124 }).margin(5) 125 Button('once').width(100).padding(5).onClick(() => { 126 this.iterations = 1 127 }).margin(5) 128 Button('infinite').width(100).padding(5).onClick(() => { 129 this.iterations = -1 // The animation is played for an unlimited number of times. 130 }).margin(5) 131 } 132 }.width('100%').height('100%') 133 } 134} 135``` 136 137 138
