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