# ImageSpan [Text](ts-basic-components-text.md)、[ContainerSpan](ts-basic-components-containerspan.md)组件的子组件，用于显示行内图片。 > **说明：** > > 该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 ## 子组件 无 ## 接口 ImageSpan(value: ResourceStr | PixelMap) **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | value | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)  | 是 | 图片的数据源，支持本地图片和网络图片。
当使用相对路径引用图片资源时，例如`ImageSpan("common/test.jpg")`，不支持跨包/跨模块调用该ImageSpan组件，建议使用`$r`方式来管理需全局使用的图片资源。
\- 支持的图片格式包括png、jpg、bmp、svg、gif和heif。
\- 支持`Base64`字符串。格式`data:image/[png\|jpeg\|bmp\|webp\|heif];base64,[base64 data]`, 其中`[base64 data]`为`Base64`字符串数据。
\- 支持file:///data/storage路径前缀的字符串，用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。 | ## 属性 属性继承自[BaseSpan](ts-basic-components-span.md#basespan)，通用属性方法支持[尺寸设置](ts-universal-attributes-size.md#尺寸设置)、[背景设置](ts-universal-attributes-background.md#背景设置)、[边框设置](ts-universal-attributes-border.md#边框设置) ### alt12+ alt(value: PixelMap) 设置图片加载时显示的占位图。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | | value | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) | 是 | 加载时显示的占位图，支持[PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7)类型。
默认值：null | ### verticalAlign verticalAlign(value: ImageSpanAlignment) 设置图片基于行高的对齐方式。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | | value | [ImageSpanAlignment](ts-appendix-enums.md#imagespanalignment10) | 是 | 图片基于行高的对齐方式。
默认值：ImageSpanAlignment.BOTTOM | ### objectFit objectFit(value: ImageFit) 设置图片的缩放类型。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ----------------------------------------- | ---- | ------------------------------------------- | | value | [ImageFit](ts-appendix-enums.md#imagefit) | 是 | 图片的缩放类型。
默认值：ImageFit.Cover | ### colorFilter14+ colorFilter(filter: ColorFilter | DrawingColorFilter) 为图像设置颜色滤镜效果。 **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | --------------------------------------- | ---- | ------------------------------------------------------------ | | filter | [ColorFilter](ts-types.md#colorfilter9) \| [DrawingColorFilter](ts-basic-components-image.md#drawingcolorfilter12) | 是 | 1. 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。
矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。
当矩阵对角线值为1，其余值为0时，保持图片原有色彩。
**计算规则：**
如果输入的滤镜矩阵为：
![image-matrix-1](figures/image-matrix-1.jpg)
像素点为[R, G, B, A]
则过滤后的颜色为 [R’, G’, B’, A’]
![image-matrix-2](figures/image-matrix-2.jpg)
2. 支持@ohos.graphics.drawing的ColorFilter类型作为入参。
**说明：**
该接口中的DrawingColorfilter类型支持在原子化服务中使用。其中，svg类型的图源需具有stroke属性。| ## 事件 通用事件仅支持[点击事件](ts-universal-attributes-click.md)。还支持以下事件： ### onComplete12+ onComplete(callback: ImageCompleteCallback) 图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------ | ---- | -------------------------- | | callback | [ImageCompleteCallback](#imagecompletecallback12) | 是 | 图片数据加载成功和解码成功时触发的回调。 | ### onError12+ onError(callback: ImageErrorCallback) 图片加载异常时触发该回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------ | ---- | -------------------------- | | callback | [ImageErrorCallback](ts-basic-components-image.md#imageerrorcallback9) | 是 | 图片加载异常时触发的回调。 | ## ImageCompleteCallback12+ type ImageCompleteCallback = (result: ImageLoadResult) => void 图片加载异常时触发的回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 参数名 | 类型 | 必填 | 说明 | | ------ | -------------------------- | ---- | ---------------------------------- | | result | [ImageLoadResult](#imageloadresult12对象说明) | 是 | 图片数据加载成功和解码成功触发回调时返回的对象。 | ## ImageLoadResult12+对象说明 图片数据加载成功和解码成功触发回调时返回的对象。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | ---------------------------- | ------ | ---- | ------------------------------------------------------------ | | width | number | 是 | 图片的宽。
单位：像素 | | height | number | 是 | 图片的高。
单位：像素 | | componentWidth | number | 是 | 组件的宽。
单位：像素 | | componentHeight | number | 是 | 组件的高。
单位：像素 | | loadingStatus | number | 是 | 图片加载成功的状态值。
**说明：**
返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 | | contentWidth | number | 是 | 图片实际绘制的宽度。
单位：像素
**说明：**
仅在loadingStatus返回1时有效。 | | contentHeight | number | 是 | 图片实际绘制的高度。
单位：像素
**说明：**
仅在loadingStatus返回1时有效。 | | contentOffsetX | number | 是 | 实际绘制内容相对于组件自身的x轴偏移。
单位：像素
**说明：**
仅在loadingStatus返回1时有效。 | | contentOffsetY | number | 是 | 实际绘制内容相对于组件自身的y轴偏移。
单位：像素
**说明：**
仅在loadingStatus返回1时有效。 | ## 示例 ### 示例1（设置对齐方式） 该示例通过verticalAlign、objectFit属性展示了ImageSpan的对齐方式以及缩放效果。 ```ts // xxx.ets @Entry @Component struct SpanExample { build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Text() { Span('This is the Span and ImageSpan component').fontSize(25).textCase(TextCase.Normal) .decoration({ type: TextDecorationType.None, color: Color.Pink }) }.width('100%').textAlign(TextAlign.Center) Text() { ImageSpan($r('app.media.icon')) .width('200px') .height('200px') .objectFit(ImageFit.Fill) .verticalAlign(ImageSpanAlignment.CENTER) Span('I am LineThrough-span') .decoration({ type: TextDecorationType.LineThrough, color: Color.Red }).fontSize(25) ImageSpan($r('app.media.icon')) .width('50px') .height('50px') .verticalAlign(ImageSpanAlignment.TOP) Span('I am Underline-span') .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(25) ImageSpan($r('app.media.icon')) .size({ width: '100px', height: '100px' }) .verticalAlign(ImageSpanAlignment.BASELINE) Span('I am Underline-span') .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(25) ImageSpan($r('app.media.icon')) .width('70px') .height('70px') .verticalAlign(ImageSpanAlignment.BOTTOM) Span('I am Underline-span') .decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(50) } .width('100%') .textIndent(50) }.width('100%').height('100%').padding({ left: 0, right: 0, top: 0 }) } } ``` ![imagespan](figures/imagespan.png) ### 示例2（设置背景样式） 该示例通过textBackgroundStyle属性展示了文本设置背景样式的效果。 ```ts // xxx.ets @Component @Entry struct Index { build() { Column() { Text() { ImageSpan($r('app.media.app_icon')) .width('60vp') .height('60vp') .verticalAlign(ImageSpanAlignment.CENTER) .textBackgroundStyle({color: Color.Green, radius: "5vp"}) } }.width('100%').alignItems(HorizontalAlign.Center) } } ``` ![imagespan](figures/image_span_textbackgroundstyle.png) ### 示例3（为图片添加事件） 该示例通过onComplete、onError为图片添加加载成功和加载异常的事件。 ```ts // xxx.ets @Entry @Component struct Index { @State src: ResourceStr = $r('app.media.icon'); build(){ Column(){ Text(){ ImageSpan(this.src) .width(100).height(100) .onError((err)=>{ console.log("onError:" + err.message) }) .onComplete((event)=>{ console.log("onComplete: " + event.loadingStatus) }) } }.width('100%').height('100%') } } ``` ### 示例4（设置颜色滤镜） 该示例通过colorFilter属性展示了给ImageSpan图像设置颜色滤镜的效果。 ```ts // xxx.ets import { drawing, common2D } from '@kit.ArkGraphics2D'; @Entry @Component struct SpanExample { 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]; @State DrawingColorFilterFirst: ColorFilter | undefined = new ColorFilter(this.ColorFilterMatrix) build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Text() { ImageSpan($r('app.media.icon')) .width('50px') .height('50px') .colorFilter(this.DrawingColorFilterFirst) } .width('50%') Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Text() { ImageSpan($r('app.media.icon')) .width('50px') .height('50px') .colorFilter(drawing.ColorFilter.createBlendModeColorFilter({ alpha: 255, red: 112, green: 112, blue: 112 }, drawing.BlendMode.SRC)) } .width('50%') }.width('100%').height('10%') }.width('200%').height('100%') } } ``` ![imagespan](figures/image_span_colorfilter.gif) ### 示例5（设置加载占位图） 该示例alt属性展示了ImageSpan设置加载网络图片时占位图的效果。 ```ts // xxx.ets import { http } from '@kit.NetworkKit' import { image } from '@kit.ImageKit' import { BusinessError } from '@kit.BasicServicesKit' @Entry @Component struct SpanExample { @State imageAlt: PixelMap | undefined = undefined httpRequest() { // 直接加载网络地址，请填写一个具体的网络图片地址 http.createHttp().request("https://www.example.com/xxx.png", (error: BusinessError, data: http.HttpResponse) => { if (error) { console.error(`http request failed with. Code: ${error.code}, message: ${error.message}`) } else { console.log(`http request success.`) let imageData: ArrayBuffer = data.result as ArrayBuffer let imageSource: image.ImageSource = image.createImageSource(imageData) class tmp { height: number = 100 width: number = 100 } let option: Record = { 'alphaType': 0, // 透明度 'editable': false, // 是否可编辑 'pixelFormat': 3, // 像素格式 'scaleMode': 1, // 缩略值 'size': { height: 100, width: 100 } } //创建图片大小 imageSource.createPixelMap(option).then((pixelMap: PixelMap) => { this.imageAlt = pixelMap }) } }) } build() { Column() { Button("获取网络图片") .onClick(() => { this.httpRequest() }) Text() { // 直接加载网络地址，请填写一个具体的网络图片地址 ImageSpan('https://www.example.com/xxx.png') .alt(this.imageAlt) .width(300) .height(300) } }.width('100%').height(250).padding({ left: 35, right: 35, top: 35 }) } } ``` ![imagespan](figures/image_span_alt.gif)