1# ImageSpan 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @xiangyuan6--> 5<!--Designer: @pssea--> 6<!--Tester: @jiaoaozihao--> 7<!--Adviser: @HelloCrease--> 8 9[Text](ts-basic-components-text.md)、[ContainerSpan](ts-basic-components-containerspan.md)组件的子组件，用于显示行内图片。 10 11> **说明：** 12> 13> 该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15 16## 子组件 17 18无 19 20 21## 接口 22 23ImageSpan(value: ResourceStr | PixelMap) 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| -------- | -------- | -------- | -------- | 33| value | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md) | 是 | 图片的数据源，支持本地图片和网络图片。<br/>当使用相对路径引用图片资源时，例如`ImageSpan("common/test.jpg")`，不支持跨包/跨模块调用该ImageSpan组件，建议使用`$r`方式来管理需全局使用的图片资源。<br/>\- 支持的图片格式包括png、jpg、bmp、svg、gif和heif。<br/>\- 支持`Base64`字符串。格式`data:image/[png\|jpeg\|bmp\|webp\|heif];base64,[base64 data]`，其中`[base64 data]`为`Base64`字符串数据。<br/>\- 支持file://data/storage路径前缀的字符串，用于读取本应用安装目录下file文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。 | 34 35 36## 属性 37 38属性继承自[BaseSpan](ts-basic-components-span.md#basespan)，通用属性方法支持[尺寸设置](ts-universal-attributes-size.md)、[背景设置](ts-universal-attributes-background.md)、[边框设置](ts-universal-attributes-border.md)。 39 40### verticalAlign 41 42verticalAlign(value: ImageSpanAlignment) 43 44设置图片基于行高的对齐方式。 45 46**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 47 48**系统能力：** SystemCapability.ArkUI.ArkUI.Full 49 50**参数：** 51 52| 参数名 | 类型 | 必填 | 说明 | 53| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 54| value | [ImageSpanAlignment](ts-appendix-enums.md#imagespanalignment10) | 是 | 图片基于行高的对齐方式。<br />默认值：ImageSpanAlignment.BOTTOM | 55 56### objectFit 57 58objectFit(value: ImageFit) 59 60设置图片的缩放类型。 61 62**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 63 64**系统能力：** SystemCapability.ArkUI.ArkUI.Full 65 66**参数：** 67 68| 参数名 | 类型 | 必填 | 说明 | 69| ------ | ----------------------------------------- | ---- | ------------------------------------------- | 70| value | [ImageFit](ts-appendix-enums.md#imagefit) | 是 | 图片的缩放类型。<br/>默认值：ImageFit.Cover | 71 72### alt<sup>12+</sup> 73 74alt(value: PixelMap) 75 76设置图片加载过程中显示的占位图。 77 78**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 79 80**系统能力：** SystemCapability.ArkUI.ArkUI.Full 81 82**参数：** 83 84| 参数名 | 类型 | 必填 | 说明 | 85| ------ | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 86| value | [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md) | 是 | 设置图片加载过程中显示的占位图，支持[PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md)类型。<br/>默认值：null | 87 88### colorFilter<sup>14+</sup> 89 90colorFilter(filter: ColorFilter | DrawingColorFilter) 91 92为图像设置颜色滤镜效果。 93 94**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 95 96**系统能力：** SystemCapability.ArkUI.ArkUI.Full 97 98**参数：** 99 100| 参数名 | 类型 | 必填 | 说明 | 101| ------ | --------------------------------------- | ---- | ------------------------------------------------------------ | 102| filter | [ColorFilter](ts-types.md#colorfilter9) \| [DrawingColorFilter](ts-basic-components-image.md#drawingcolorfilter12) | 是 | 1. 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。<br/>矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。<br/>当矩阵对角线值为1，其余值为0时，保持图片原有色彩。<br/> **计算规则：**<br/>如果输入的滤镜矩阵为：<br/><br/>像素点为[R, G, B, A]，色值的范围[0, 255]<br/>则过滤后的颜色为 [R’, G’, B’, A’]<br/><br/>2. 支持@ohos.graphics.drawing的ColorFilter类型作为入参。<br/>**说明：** <br/>该接口中的DrawingColorFilter类型支持在原子化服务中使用。其中，svg类型的图源只对stroke属性生效。| 103 104## 事件 105 106通用事件仅支持[点击事件](ts-universal-attributes-click.md)。还支持以下事件： 107 108### onComplete<sup>12+</sup> 109 110onComplete(callback: ImageCompleteCallback) 111 112图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。 113 114**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 115 116**系统能力：** SystemCapability.ArkUI.ArkUI.Full 117 118**参数：** 119 120| 参数名 | 类型 | 必填 | 说明 | 121| -------- | ------------------------------------------ | ---- | -------------------------- | 122| callback | [ImageCompleteCallback](#imagecompletecallback12) | 是 | 图片数据加载成功和解码成功时触发的回调。 | 123 124### onError<sup>12+</sup> 125 126onError(callback: ImageErrorCallback) 127 128图片加载异常时触发该回调。 129 130**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 131 132**系统能力：** SystemCapability.ArkUI.ArkUI.Full 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| -------- | ------------------------------------------ | ---- | -------------------------- | 138| callback | [ImageErrorCallback](ts-basic-components-image.md#imageerrorcallback9) | 是 | 图片加载异常时触发的回调。 | 139 140## ImageCompleteCallback<sup>12+</sup> 141 142type ImageCompleteCallback = (result: ImageLoadResult) => void 143 144图片加载成功和解码成功时触发的回调。 145 146**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 147 148**系统能力：** SystemCapability.ArkUI.ArkUI.Full 149 150**参数：** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| ------ | -------------------------- | ---- | ---------------------------------- | 154| result | [ImageLoadResult](#imageloadresult12对象说明) | 是 | 图片数据加载成功和解码成功触发回调时返回的对象。 | 155 156## ImageLoadResult<sup>12+</sup>对象说明 157 158图片数据加载成功和解码成功触发回调时返回的对象。 159 160**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.ArkUI.ArkUI.Full 163 164| 名称 | 类型 | 只读 | 可选 | 说明 | 165| ---------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 166| width | number | 否 | 否 | 图片的宽。<br/>单位：[px](ts-pixel-units.md) | 167| height | number | 否 | 否 | 图片的高。<br/>单位：[px](ts-pixel-units.md) | 168| componentWidth | number | 否 | 否 | 组件的宽。<br/>单位：[px](ts-pixel-units.md) | 169| componentHeight | number | 否 | 否 | 组件的高。<br/>单位：[px](ts-pixel-units.md) | 170| loadingStatus | number | 否 | 否 | 图片加载成功的状态值。<br/>**说明：**<br/>返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 | 171| contentWidth | number | 否 | 否 | 图片实际绘制的宽度。<br/>单位：[px](ts-pixel-units.md)<br>**说明：**<br/>仅在loadingStatus返回1时有效。 | 172| contentHeight | number | 否 | 否 | 图片实际绘制的高度。<br/>单位：[px](ts-pixel-units.md)<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 173| contentOffsetX | number | 否 | 否 | 实际绘制内容相对于组件自身的x轴偏移。<br/>单位：[px](ts-pixel-units.md)<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 174| contentOffsetY | number | 否 | 否 | 实际绘制内容相对于组件自身的y轴偏移。<br/>单位：[px](ts-pixel-units.md)<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 175 176 177 178## 示例 179 180### 示例1（设置对齐方式） 181 182从API version 10开始，该示例通过[verticalAlign](#verticalalign)、[objectFit](#objectfit)属性展示了ImageSpan组件的对齐方式以及缩放效果。 183 184```ts 185// xxx.ets 186@Entry 187@Component 188struct SpanExample { 189 build() { 190 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 191 Text() { 192 Span('This is the Span and ImageSpan component').fontSize(25).textCase(TextCase.Normal) 193 .decoration({ type: TextDecorationType.None, color: Color.Pink }) 194 }.width('100%').textAlign(TextAlign.Center) 195 196 Text() { 197 // $r('app.media.app_icon')需要替换为开发者所需的图像资源文件。 198 ImageSpan($r('app.media.app_icon')) 199 .width('200px') 200 .height('200px') 201 .objectFit(ImageFit.Fill) 202 .verticalAlign(ImageSpanAlignment.CENTER) 203 Span('I am LineThrough-span') 204 .decoration({ type: TextDecorationType.LineThrough, color: Color.Red }).fontSize(25) 205 ImageSpan($r('app.media.app_icon')) 206 .width('50px') 207 .height('50px') 208 .verticalAlign(ImageSpanAlignment.TOP) 209 Span('I am Underline-span') 210 .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(25) 211 ImageSpan($r('app.media.app_icon')) 212 .size({ width: '100px', height: '100px' }) 213 .verticalAlign(ImageSpanAlignment.BASELINE) 214 Span('I am Underline-span') 215 .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(25) 216 ImageSpan($r('app.media.app_icon')) 217 .width('70px') 218 .height('70px') 219 .verticalAlign(ImageSpanAlignment.BOTTOM) 220 Span('I am Underline-span') 221 .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(50) 222 } 223 .width('100%') 224 .textIndent(50) 225 }.width('100%').height('100%').padding({ left: 0, right: 0, top: 0 }) 226 } 227} 228``` 229 230 231 232### 示例2（设置背景样式） 233 234从API version 11开始，该示例通过[textBackgroundStyle](ts-basic-components-span.md#textbackgroundstyle11)属性展示了文本设置背景样式的效果。 235 236```ts 237// xxx.ets 238@Component 239@Entry 240struct Index { 241 build() { 242 Row() { 243 Column() { 244 Text() { 245 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 246 ImageSpan($r('app.media.sky')) 247 .width('60vp') 248 .height('60vp') 249 .verticalAlign(ImageSpanAlignment.CENTER) 250 .borderRadius(20) 251 .textBackgroundStyle({ color: '#7F007DFF', radius: "5vp" }) 252 } 253 }.width('100%') 254 }.height('100%') 255 } 256} 257``` 258 259 260### 示例3（为图片添加事件） 261 262从API version 12开始，该示例通过[onComplete](#oncomplete12)、[onError](#onerror12)为图片添加加载成功和加载异常的事件。 263 264```ts 265// xxx.ets 266@Entry 267@Component 268struct Index { 269 // $r('app.media.app_icon')需要替换为开发者所需的图像资源文件。 270 @State src: ResourceStr = $r('app.media.app_icon'); 271 272 build() { 273 Column() { 274 Text() { 275 ImageSpan(this.src) 276 .width(100).height(100) 277 .onError((err) => { 278 console.info("onError: " + err.message); 279 }) 280 .onComplete((event) => { 281 console.info("onComplete: " + event.loadingStatus); 282 }) 283 } 284 }.width('100%').height('100%') 285 } 286} 287``` 288### 示例4（设置颜色滤镜） 289 290从API version 14开始，该示例通过[colorFilter](#colorfilter14)属性展示了给ImageSpan图像设置颜色滤镜的效果。 291 292```ts 293// xxx.ets 294import { drawing } from '@kit.ArkGraphics2D'; 295 296@Entry 297@Component 298struct SpanExample { 299 private ColorFilterMatrix: number[] = [0.239, 0, 0, 0, 0, 0, 0.616, 0, 0, 0, 0, 0, 0.706, 0, 0, 0, 0, 0, 1, 0]; 300 @State DrawingColorFilterFirst: ColorFilter | undefined = new ColorFilter(this.ColorFilterMatrix); 301 302 build() { 303 Row() { 304 Column({ space: 10 }) { 305 //创建ColorFilter对象的方式为图片设置颜色滤镜 306 Text() { 307 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 308 ImageSpan($r('app.media.sky')) 309 .width('60vp') 310 .height('60vp') 311 .colorFilter(this.DrawingColorFilterFirst) 312 } 313 314 //通过drawing.ColorFilter的方式为图片设置颜色滤镜 315 Text() { 316 // $r('app.media.sky')需要替换为开发者所需的图像资源文件。 317 ImageSpan($r('app.media.sky')) 318 .width('60vp') 319 .height('60vp') 320 .colorFilter(drawing.ColorFilter.createBlendModeColorFilter({ 321 alpha: 255, 322 red: 112, 323 green: 112, 324 blue: 112 325 }, drawing.BlendMode.SRC)) 326 } 327 }.width('100%') 328 }.height('100%') 329 } 330} 331``` 332 333 334### 示例5（设置加载占位图） 335 336从API version 12开始，该示例[alt](#alt12)属性展示了ImageSpan设置加载网络图片时占位图的效果。 337 338```ts 339// xxx.ets 340import { http } from '@kit.NetworkKit'; 341import { image } from '@kit.ImageKit'; 342import { BusinessError } from '@kit.BasicServicesKit'; 343 344@Entry 345@Component 346struct SpanExample { 347 @State imageAlt: PixelMap | undefined = undefined; 348 349 httpRequest() { 350 // 直接加载网络地址，请填写一个具体的网络图片地址 351 http.createHttp().request("https://www.example.com/xxx.png", (error: BusinessError, data: http.HttpResponse) => { 352 if (error) { 353 console.error(`http request failed with. Code: ${error.code}, message: ${error.message}`); 354 } else { 355 console.info(`http request success.`); 356 let imageData: ArrayBuffer = data.result as ArrayBuffer; 357 let imageSource: image.ImageSource = image.createImageSource(imageData); 358 359 class tmp { 360 height: number = 100; 361 width: number = 100; 362 } 363 364 let option: Record<string, number | boolean | tmp> = { 365 'alphaType': 0, // 透明度 366 'editable': false, // 是否可编辑 367 'pixelFormat': 3, // 像素格式 368 'scaleMode': 1, // 缩略值 369 'size': { height: 100, width: 100 } 370 }; 371 //创建图片大小 372 imageSource.createPixelMap(option).then((pixelMap: PixelMap) => { 373 this.imageAlt = pixelMap; 374 }) 375 } 376 }) 377 } 378 379 build() { 380 Column() { 381 Button("获取网络图片") 382 .onClick(() => { 383 this.httpRequest(); 384 }) 385 386 Text() { 387 // 直接加载网络地址，请填写一个具体的网络图片地址 388 ImageSpan('https://www.example.com/xxx.png') 389 .alt(this.imageAlt) 390 .width(300) 391 .height(300) 392 } 393 394 }.width('100%').height(250).padding({ left: 35, right: 35, top: 35 }) 395 } 396} 397``` 398 399 400
){kind=link}
