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路径前缀的字符串，用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。 | 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### alt<sup>12+</sup> 35 36alt(value: PixelMap) 37 38设置图片加载时显示的占位图。 39 40**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 41 42**系统能力：** SystemCapability.ArkUI.ArkUI.Full 43 44**参数：** 45 46| 参数名 | 类型 | 必填 | 说明 | 47| ------ | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 48| value | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) | 是 | 加载时显示的占位图，支持[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)类型。<br/>默认值：null | 49 50### verticalAlign 51 52verticalAlign(value: ImageSpanAlignment) 53 54设置图片基于行高的对齐方式。 55 56**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 57 58**系统能力：** SystemCapability.ArkUI.ArkUI.Full 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 64| value | [ImageSpanAlignment](ts-appendix-enums.md#imagespanalignment10) | 是 | 图片基于行高的对齐方式。<br />默认值：ImageSpanAlignment.BOTTOM | 65 66### objectFit 67 68objectFit(value: ImageFit) 69 70设置图片的缩放类型。 71 72**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.ArkUI.ArkUI.Full 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| ------ | ----------------------------------------- | ---- | ------------------------------------------- | 80| value | [ImageFit](ts-appendix-enums.md#imagefit) | 是 | 图片的缩放类型。<br/>默认值：ImageFit.Cover | 81 82## 事件 83 84通用事件仅支持[点击事件](ts-universal-attributes-click.md)。还支持以下事件： 85 86### onComplete<sup>12+</sup> 87 88onComplete(callback: ImageCompleteCallback) 89 90图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。 91 92**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 93 94**系统能力：** SystemCapability.ArkUI.ArkUI.Full 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| -------- | ------------------------------------------ | ---- | -------------------------- | 100| callback | [ImageCompleteCallback](#imagecompletecallback12) | 是 | 图片数据加载成功和解码成功时触发的回调。 | 101 102### onError<sup>12+</sup> 103 104onError(callback: ImageErrorCallback) 105 106图片加载异常时触发该回调。 107 108**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112**参数：** 113 114| 参数名 | 类型 | 必填 | 说明 | 115| -------- | ------------------------------------------ | ---- | -------------------------- | 116| callback | [ImageErrorCallback](ts-basic-components-image.md#imageerrorcallback9) | 是 | 图片加载异常时触发的回调。 | 117 118## ImageCompleteCallback<sup>12+</sup> 119 120type ImageCompleteCallback = (result: ImageLoadResult) => void 121 122图片加载异常时触发的回调。 123 124**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 125 126**系统能力：** SystemCapability.ArkUI.ArkUI.Full 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | -------------------------- | ---- | ---------------------------------- | 130| result | [ImageLoadResult](#imageloadresult12对象说明) | 是 | 图片数据加载成功和解码成功触发回调时返回的对象。 | 131 132## ImageLoadResult<sup>12+</sup>对象说明 133 134图片数据加载成功和解码成功触发回调时返回的对象。 135 136**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 137 138**系统能力：** SystemCapability.ArkUI.ArkUI.Full 139 140| 名称 | 类型 | 必填 | 说明 | 141| ---------------------------- | ------ | ---- | ------------------------------------------------------------ | 142| width | number | 是 | 图片的宽。<br/>单位：像素 | 143| height | number | 是 | 图片的高。<br/>单位：像素 | 144| componentWidth | number | 是 | 组件的宽。<br/>单位：像素 | 145| componentHeight | number | 是 | 组件的高。<br/>单位：像素 | 146| loadingStatus | number | 是 | 图片加载成功的状态值。<br/>**说明：**<br/>返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 | 147| contentWidth | number | 是 | 图片实际绘制的宽度。<br/>单位：像素<br>**说明：**<br/>仅在loadingStatus返回1时有效。 | 148| contentHeight | number | 是 | 图片实际绘制的高度。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 149| contentOffsetX | number | 是 | 实际绘制内容相对于组件自身的x轴偏移。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 150| contentOffsetY | number | 是 | 实际绘制内容相对于组件自身的y轴偏移。<br/>单位：像素<br/>**说明：**<br/>仅在loadingStatus返回1时有效。 | 151 152 153 154## 示例 155 156### 示例1 157 158该示例实现了设置ImageSpan的基本属性和图片基于文本的对齐方式。 159 160```ts 161// xxx.ets 162@Entry 163@Component 164struct SpanExample { 165 build() { 166 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 167 Text() { 168 Span('This is the Span and ImageSpan component').fontSize(25).textCase(TextCase.Normal) 169 .decoration({ type: TextDecorationType.None, color: Color.Pink }) 170 }.width('100%').textAlign(TextAlign.Center) 171 172 Text() { 173 ImageSpan($r('app.media.icon')) 174 .width('200px') 175 .height('200px') 176 .objectFit(ImageFit.Fill) 177 .verticalAlign(ImageSpanAlignment.CENTER) 178 Span('I am LineThrough-span') 179 .decoration({ type: TextDecorationType.LineThrough, color: Color.Red }).fontSize(25) 180 ImageSpan($r('app.media.icon')) 181 .width('50px') 182 .height('50px') 183 .verticalAlign(ImageSpanAlignment.TOP) 184 Span('I am Underline-span') 185 .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(25) 186 ImageSpan($r('app.media.icon')) 187 .size({ width: '100px', height: '100px' }) 188 .verticalAlign(ImageSpanAlignment.BASELINE) 189 Span('I am Underline-span') 190 .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(25) 191 ImageSpan($r('app.media.icon')) 192 .width('70px') 193 .height('70px') 194 .verticalAlign(ImageSpanAlignment.BOTTOM) 195 Span('I am Underline-span') 196 .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(50) 197 } 198 .width('100%') 199 .textIndent(50) 200 }.width('100%').height('100%').padding({ left: 0, right: 0, top: 0 }) 201 } 202} 203``` 204 205 206 207### 示例2 208 209该示例实现了如何设置ImageSpan图片的背景样式。 210 211```ts 212// xxx.ets 213@Component 214@Entry 215struct Index { 216 build() { 217 Column() { 218 Text() { 219 ImageSpan($r('app.media.app_icon')) 220 .width('60vp') 221 .height('60vp') 222 .verticalAlign(ImageSpanAlignment.CENTER) 223 .textBackgroundStyle({color: Color.Green, radius: "5vp"}) 224 } 225 }.width('100%').alignItems(HorizontalAlign.Center) 226 } 227} 228``` 229 230 231### 示例3 232ImageSpan设置图片成功加载解码和图片加载异常事件回调。 233```ts 234// xxx.ets 235@Entry 236@Component 237struct Index { 238 @State src: ResourceStr = $r('app.media.icon'); 239 build(){ 240 Column(){ 241 Text(){ 242 ImageSpan(this.src) 243 .width(100).height(100) 244 .onError((err)=>{ 245 console.log("onError:" + err.message) 246 }) 247 .onComplete((event)=>{ 248 console.log("onComplete: " + event.loadingStatus) 249 }) 250 } 251 }.width('100%').height('100%') 252 } 253} 254``` 255 256### 示例4 257 258该示例实现了ImageSpan设置加载网络图片时占位图的效果。 259 260```ts 261// xxx.ets 262import { http } from '@kit.NetworkKit' 263import { image } from '@kit.ImageKit' 264import { BusinessError } from '@kit.BasicServicesKit' 265 266@Entry 267@Component 268struct SpanExample { 269 @State imageAlt: PixelMap | undefined = undefined 270 271 httpRequest() { 272 // 直接加载网络地址，请填写一个具体的网络图片地址 273 http.createHttp().request("https://www.example.com/xxx.png", (error: BusinessError, data: http.HttpResponse) => { 274 if (error) { 275 console.error(`http request failed with. Code: ${error.code}, message: ${error.message}`) 276 } else { 277 console.log(`http request success.`) 278 let imageData: ArrayBuffer = data.result as ArrayBuffer 279 let imageSource: image.ImageSource = image.createImageSource(imageData) 280 281 class tmp { 282 height: number = 100 283 width: number = 100 284 } 285 286 let option: Record<string, number | boolean | tmp> = { 287 'alphaType': 0, // 透明度 288 'editable': false, // 是否可编辑 289 'pixelFormat': 3, // 像素格式 290 'scaleMode': 1, // 缩略值 291 'size': { height: 100, width: 100 } 292 } 293 //创建图片大小 294 imageSource.createPixelMap(option).then((pixelMap: PixelMap) => { 295 this.imageAlt = pixelMap 296 }) 297 } 298 }) 299 } 300 301 build() { 302 Column() { 303 Button("获取网络图片") 304 .onClick(() => { 305 this.httpRequest() 306 }) 307 308 Text() { 309 // 直接加载网络地址，请填写一个具体的网络图片地址 310 ImageSpan('https://www.example.com/xxx.png') 311 .alt(this.imageAlt) 312 .width(300) 313 .height(300) 314 } 315 316 }.width('100%').height(250).padding({ left: 35, right: 35, top: 35 }) 317 } 318} 319``` 320 321 322
){kind=link}
