1# ImageAnimator 2 3提供帧动画组件来实现逐帧播放图片的能力，可以配置需要播放的图片列表，每张图片可以配置时长。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10 11## 子组件 12 13无 14 15 16## 接口 17 18ImageAnimator() 19 20**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 21 22**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 23 24**系统能力：** SystemCapability.ArkUI.ArkUI.Full 25 26## 属性 27 28除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 29 30### images 31 32images(value: Array<ImageFrameInfo>) 33 34设置图片帧信息集合。不支持动态更新。 35 36**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 37 38**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 39 40**系统能力：** SystemCapability.ArkUI.ArkUI.Full 41 42**参数：** 43 44| 参数名 | 类型 | 必填 | 说明 | 45| ------ | ------------------------------------------------------ | ---- | ------------------------------------------------------------ | 46| value | Array<[ImageFrameInfo](#imageframeinfo对象说明)> | 是 | 设置图片帧信息集合。每一帧的帧信息(ImageFrameInfo)包含图片路径、图片大小、图片位置和图片播放时长信息，详见ImageFrameInfo属性说明。<br/>默认值：[] | 47 48### state 49 50state(value: AnimationStatus) 51 52控制播放状态。 53 54**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 55 56**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 57 58**系统能力：** SystemCapability.ArkUI.ArkUI.Full 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 64| value | [AnimationStatus](ts-appendix-enums.md#animationstatus) | 是 | 默认为初始状态，用于控制播放状态。<br/>默认值：AnimationStatus.Initial | 65 66### duration 67 68duration(value: number) 69 70设置播放时长。当Images中任意一帧图片设置了单独的duration后，该属性设置无效。 71 72**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 73 74**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 75 76**系统能力：** SystemCapability.ArkUI.ArkUI.Full 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| ------ | ------ | ---- | ------------------------------------------------------------ | 82| value | number | 是 | 播放时长。<br/>value为0时，不播放图片。<br/>value的改变只会在下一次循环开始时生效。<br/>单位：毫秒<br/>默认值：1000ms | 83 84### reverse 85 86reverse(value: boolean) 87 88设置播放方向。 89 90**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 91 92**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 93 94**系统能力：** SystemCapability.ArkUI.ArkUI.Full 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| ------ | ------- | ---- | ------------------------------------------------------------ | 100| value | boolean | 是 | 播放方向。<br/>false表示从第1张图片播放到最后1张图片，true表示从最后1张图片播放到第1张图片。<br/>默认值：false | 101 102### fixedSize 103 104fixedSize(value: boolean) 105 106设置图片大小是否固定为组件大小。 107 108**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 109 110**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 111 112**系统能力：** SystemCapability.ArkUI.ArkUI.Full 113 114**参数：** 115 116| 参数名 | 类型 | 必填 | 说明 | 117| ------ | ------- | ---- | ------------------------------------------------------------ | 118| value | boolean | 是 | 设置图片大小是否固定为组件大小。 true表示图片大小与组件大小一致，此时设置图片的width 、height 、top 和left属性是无效的。false表示每一张图片的width 、height 、top和left属性都要单独设置。<br/>默认值：true | 119 120### preDecode<sup>(deprecated)</sup> 121 122preDecode(value: number) 123 124设置预解码的图片数量。 125 126从API version 9开始废弃。 127 128**系统能力：** SystemCapability.ArkUI.ArkUI.Full 129 130**参数：** 131 132| 参数名 | 类型 | 必填 | 说明 | 133| ------ | ------ | ---- | ------------------------------------------------------------ | 134| value | number | 是 | 预解码的图片数量。例如该值设为2，则播放当前页时会提前加载后面两张图片至缓存以提升性能。<br/>默认值：0 | 135 136### fillMode 137 138fillMode(value: FillMode) 139 140设置当前播放方向下，动画开始前和结束后的状态。动画结束后的状态由fillMode和reverse属性共同决定。例如，fillMode为Forwards表示停止时维持动画最后一个关键帧的状态，若reverse为false则维持正播的最后一帧，即最后一张图，若reverse为true则维持逆播的最后一帧，即第一张图。 141 142**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 143 144**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 145 146**系统能力：** SystemCapability.ArkUI.ArkUI.Full 147 148**参数：** 149 150| 参数名 | 类型 | 必填 | 说明 | 151| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 152| value | [FillMode](ts-appendix-enums.md#fillmode) | 是 | 当前播放方向下，动画开始前和结束后的状态。<br/>默认值：FillMode.Forwards | 153 154### iterations 155 156iterations(value: number) 157 158设置播放次数。 159 160**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.ArkUI.ArkUI.Full 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ------ | ------ | ---- | ------------------------------------------------------ | 168| value | number | 是 | 默认播放一次，设置为-1时表示无限次播放。<br/>默认值：1 | 169 170## ImageFrameInfo对象说明 171 172**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176| 名称 | 类型 | 必填 | 说明 | 177| -------- | -------------- | -------- | -------- | 178| src | string \| [Resource](ts-types.md#resource)<sup>9+</sup> \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)<sup>12+</sup> | 是 | 图片路径，图片格式为jpg、jpeg、svg、png、bmp、webp、ico和heif，从API Version9开始支持[Resource](ts-types.md#resource)类型的路径，从API version 12开始支持[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)类型。 <br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。| 179| width | number \| string | 否 | 图片宽度。<br/>默认值：0 <br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用 | 180| height | number \| string | 否 | 图片高度。<br/>默认值：0 <br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用 | 181| top | number \| string | 否 | 图片相对于组件左上角的纵向坐标。<br/>默认值：0 <br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用 | 182| left | number \| string | 否 | 图片相对于组件左上角的横向坐标。<br/>默认值：0 <br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用 | 183| duration | number | 否 | 每一帧图片的播放时长，单位毫秒。<br/>默认值：0 | 184 185## 事件 186 187除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 188 189### onStart 190 191onStart(event: () => void) 192 193状态回调，动画开始播放时触发。 194 195**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 196 197**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 198 199**系统能力：** SystemCapability.ArkUI.ArkUI.Full 200 201### onPause 202 203onPause(event: () => void) 204 205状态回调，动画暂停播放时触发。 206 207**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 208 209**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 210 211**系统能力：** SystemCapability.ArkUI.ArkUI.Full 212 213### onRepeat 214 215onRepeat(event: () => void) 216 217状态回调，动画重复播放时触发。 218 219**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 220 221**系统能力：** SystemCapability.ArkUI.ArkUI.Full 222 223### onCancel 224 225onCancel(event: () => void) 226 227状态回调，动画返回最初状态时触发。 228 229**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 230 231**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 232 233**系统能力：** SystemCapability.ArkUI.ArkUI.Full 234 235### onFinish 236 237onFinish(event: () => void) 238 239状态回调，动画播放完成时或者停止播放时触发。 240 241**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 242 243**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 244 245**系统能力：** SystemCapability.ArkUI.ArkUI.Full 246 247 248## 示例 249 250### 示例1（播放Resource动画） 251 252通过ImageAnimator组件播放Resource动画。 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 // 显示当前帧图片 306 }).margin(5) 307 Button('stop').width(100).padding(5).onClick(() => { 308 this.state = AnimationStatus.Stopped // 显示动画的起始帧图片 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 // 无限循环播放 321 }).margin(5) 322 } 323 }.width('100%').height('100%') 324 } 325} 326``` 327 328### 示例2（播放PixelMap动画） 329 330通过ImageAnimator组件播放PixelMap动画。 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 // 显示当前帧图片 378 }).margin(5) 379 Button('stop').width(100).padding(5).onClick(() => { 380 this.state = AnimationStatus.Stopped // 显示动画的起始帧图片 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 // 无限循环播放 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
