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## Attributes
25
26In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
27
28### images
29
30images(value: Array<ImageFrameInfo>)
31
32Sets the image frame information. Dynamic update is not supported.
33
34**Widget capability**: This API can be used in ArkTS widgets since API version 10.
35
36**Atomic service API**: This API can be used in atomic services since API version 11.
37
38**System capability**: SystemCapability.ArkUI.ArkUI.Full
39
40**Parameters**
41
42| Name | Type                                                  | Mandatory | Description                                                        |
43| ------ | ------------------------------------------------------ | ---- | ------------------------------------------------------------ |
44| value  | Array&lt;[ImageFrameInfo](#imageframeinfo)&gt;  | 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: **[]** |
45
46### state
47
48state(value: AnimationStatus)
49
50Sets the playback state of the animation.
51
52**Widget capability**: This API can be used in ArkTS widgets since API version 10.
53
54**Atomic service API**: This API can be used in atomic services since API version 11.
55
56**System capability**: SystemCapability.ArkUI.ArkUI.Full
57
58**Parameters**
59
60| Name | Type                                                   | Mandatory | Description                                                        |
61| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
62| value  | [AnimationStatus](ts-appendix-enums.md#animationstatus) | Yes  | Playback state of the animation. The default state is **Initial**.<br>Default value: **AnimationStatus.Initial** |
63
64### duration
65
66duration(value: number)
67
68Sets the playback duration. This attribute does not take effect when a separate duration is set for any of the image frames.
69
70**Widget capability**: This API can be used in ArkTS widgets since API version 10.
71
72**Atomic service API**: This API can be used in atomic services since API version 11.
73
74**System capability**: SystemCapability.ArkUI.ArkUI.Full
75
76**Parameters**
77
78| Name | Type  | Mandatory | Description                                                        |
79| ------ | ------ | ---- | ------------------------------------------------------------ |
80| 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** |
81
82### reverse
83
84reverse(value: boolean)
85
86Sets the playback direction.
87
88**Widget capability**: This API can be used in ArkTS widgets since API version 10.
89
90**Atomic service API**: This API can be used in atomic services since API version 11.
91
92**System capability**: SystemCapability.ArkUI.ArkUI.Full
93
94**Parameters**
95
96| Name | Type   | Mandatory | Description                                                        |
97| ------ | ------- | ---- | ------------------------------------------------------------ |
98| 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** |
99
100### fixedSize
101
102fixedSize(value: boolean)
103
104Sets whether the image size is fixed at the component size.
105
106**Widget capability**: This API can be used in ArkTS widgets since API version 10.
107
108**Atomic service API**: This API can be used in atomic services since API version 11.
109
110**System capability**: SystemCapability.ArkUI.ArkUI.Full
111
112**Parameters**
113
114| Name | Type   | Mandatory | Description                                                        |
115| ------ | ------- | ---- | ------------------------------------------------------------ |
116| 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** |
117
118### preDecode<sup>(deprecated)</sup>
119
120preDecode(value: number)
121
122Sets the number of images to be pre-decoded.
123
124This API is deprecated since API version 9.
125
126**Widget capability**: This API can be used in ArkTS widgets since API version 10.
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| Name  | Type  | Mandatory | Description |
175| -------- | -------------- | -------- | -------- |
176| 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 .svg, .png, or .jpg. 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.|
177| width    | number \| string | No | Image width.<br>Default value: **0**<br>Since API version 10, this API is supported in ArkTS widgets.      |
178| height   | number \| string | No | Image height.<br>Default value: **0**<br>Since API version 10, this API is supported in ArkTS widgets.       |
179| 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. |
180| 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.  |
181| duration | number          | No    | Playback duration of each image frame, in milliseconds.<br>Default value: **0**        |
182
183## Events
184
185In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
186
187### onStart
188
189onStart(event: () =&gt; void)
190
191Triggered when the animation starts to play.
192
193**Widget capability**: This API can be used in ArkTS widgets since API version 10.
194
195**Atomic service API**: This API can be used in atomic services since API version 11.
196
197**System capability**: SystemCapability.ArkUI.ArkUI.Full
198
199### onPause
200
201onPause(event: () =&gt; void)
202
203Triggered when the animation playback is paused.
204
205**Widget capability**: This API can be used in ArkTS widgets since API version 10.
206
207**Atomic service API**: This API can be used in atomic services since API version 11.
208
209**System capability**: SystemCapability.ArkUI.ArkUI.Full
210
211### onRepeat
212
213onRepeat(event: () =&gt; void)
214
215Triggered when the animation playback is repeated.
216
217**Atomic service API**: This API can be used in atomic services since API version 11.
218
219**System capability**: SystemCapability.ArkUI.ArkUI.Full
220
221### onCancel
222
223onCancel(event: () =&gt; void)
224
225Triggered when the animation playback returns to the initial state.
226
227**Widget capability**: This API can be used in ArkTS widgets since API version 10.
228
229**Atomic service API**: This API can be used in atomic services since API version 11.
230
231**System capability**: SystemCapability.ArkUI.ArkUI.Full
232
233### onFinish
234
235onFinish(event: () =&gt; void)
236
237Triggered when the animation playback is complete or stopped.
238
239**Widget capability**: This API can be used in ArkTS widgets since API version 10.
240
241**Atomic service API**: This API can be used in atomic services since API version 11.
242
243**System capability**: SystemCapability.ArkUI.ArkUI.Full
244
245
246## Example
247
248### Playing an Animation of the Resource Type
249
250```ts
251// xxx.ets
252@Entry
253@Component
254struct ImageAnimatorExample {
255  @State state: AnimationStatus = AnimationStatus.Initial
256  @State reverse: boolean = false
257  @State iterations: number = 1
258
259  build() {
260    Column({ space: 10 }) {
261      ImageAnimator()
262        .images([
263          {
264            src: $r('app.media.img1')
265          },
266          {
267            src: $r('app.media.img2')
268          },
269          {
270            src: $r('app.media.img3')
271          },
272          {
273            src: $r('app.media.img4')
274          }
275        ])
276        .duration(2000)
277        .state(this.state).reverse(this.reverse)
278        .fillMode(FillMode.None).iterations(this.iterations).width(340).height(240)
279        .margin({ top: 100 })
280        .onStart(() => {
281          console.info('Start')
282        })
283        .onPause(() => {
284          console.info('Pause')
285        })
286        .onRepeat(() => {
287          console.info('Repeat')
288        })
289        .onCancel(() => {
290          console.info('Cancel')
291        })
292        .onFinish(() => {
293          console.info('Finish')
294          this.state = AnimationStatus.Stopped
295        })
296      Row() {
297        Button('start').width(100).padding(5).onClick(() => {
298          this.state = AnimationStatus.Running
299        }).margin(5)
300        Button('pause').width(100).padding(5).onClick(() => {
301          this.state = AnimationStatus.Paused     // Display the image of the current frame.
302        }).margin(5)
303        Button('stop').width(100).padding(5).onClick(() => {
304          this.state = AnimationStatus.Stopped    // Display the image of the initial frame.
305        }).margin(5)
306      }
307
308      Row() {
309        Button('reverse').width(100).padding(5).onClick(() => {
310          this.reverse = !this.reverse
311        }).margin(5)
312        Button('once').width(100).padding(5).onClick(() => {
313          this.iterations = 1
314        }).margin(5)
315        Button('infinite').width(100).padding(5).onClick(() => {
316          this.iterations = -1 // The animation is played for an unlimited number of times.
317        }).margin(5)
318      }
319    }.width('100%').height('100%')
320  }
321}
322```
323
324### Playing an Animation of the PixelMap Type
325
326```ts
327import { image } from '@kit.ImageKit'
328
329@Entry
330@Component
331struct ImageAnimatorExample {
332  imagePixelMap: Array<PixelMap> = []
333  @State state: AnimationStatus = AnimationStatus.Initial
334  @State reverse: boolean = false
335  @State iterations: number = 1
336  @State images:Array<ImageFrameInfo> = []
337  async aboutToAppear() {
338    this.imagePixelMap.push(await this.getPixmapFromMedia($r('app.media.icon')))
339    this.images.push({src:this.imagePixelMap[0]})
340  }
341  build() {
342    Column({ space: 10 }) {
343      ImageAnimator()
344        .images(this.images)
345        .duration(2000)
346        .state(this.state).reverse(this.reverse)
347        .fillMode(FillMode.None).iterations(this.iterations).width(340).height(240)
348        .margin({ top: 100 })
349        .onStart(() => {
350          console.info('Start')
351        })
352        .onPause(() => {
353          console.info('Pause')
354        })
355        .onRepeat(() => {
356          console.info('Repeat')
357        })
358        .onCancel(() => {
359          console.info('Cancel')
360        })
361        .onFinish(() => {
362          console.info('Finish')
363          this.state = AnimationStatus.Stopped
364        })
365      Row() {
366        Button('start').width(100).padding(5).onClick(() => {
367          this.state = AnimationStatus.Running
368        }).margin(5)
369        Button('pause').width(100).padding(5).onClick(() => {
370          this.state = AnimationStatus.Paused     // Display the image of the current frame.
371        }).margin(5)
372        Button('stop').width(100).padding(5).onClick(() => {
373          this.state = AnimationStatus.Stopped    // Display the image of the initial frame.
374        }).margin(5)
375      }
376      Row() {
377        Button('reverse').width(100).padding(5).onClick(() => {
378          this.reverse = !this.reverse
379        }).margin(5)
380        Button('once').width(100).padding(5).onClick(() => {
381          this.iterations = 1
382        }).margin(5)
383        Button('infinite').width(100).padding(5).onClick(() => {
384          this.iterations = -1 // The animation is played for an unlimited number of times.
385        }).margin(5)
386      }
387    }.width('100%').height('100%')
388  }
389
390  private async getPixmapFromMedia(resource: Resource) {
391    let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
392      bundleName: resource.bundleName,
393      moduleName: resource.moduleName,
394      id: resource.id
395    })
396    let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
397    let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
398      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
399    })
400    await imageSource.release()
401    return createPixelMap
402  }
403}
404```
405
406![imageAnimator](figures/imageAnimator.gif)
407