As a child of the Text and ContainerSpan components, the ImageSpan component is used to display inline images.
This component is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.
ImageSpan(value: ResourceStr | PixelMap)
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | ResourceStr | PixelMap | Yes | Image source. Both local and online images are supported. When using an image referenced using a relative path, for example, ImageSpan("common/test.jpg"), the ImageSpan component cannot be called across bundles or modules. Therefore, you are advised to use $r to reference image resources that need to be used globally. - The supported formats include PNG, JPG, BMP, SVG, GIF, and HEIF. - Base64 strings are supported. The value format is data:image/[png|jpeg|bmp|webp|heif];base64,[base64 data], where [base64 data] is a Base64 string. - Strings with the file:///data/storage prefix are supported, which are used to read image resources in the files folder in the installation directory of the application. Ensure that the application has the read permission to the files in the specified path. |
The attributes inherit from BaseSpan. Among the universal attributes, size, background, and border are supported.
alt(value: PixelMap)
Sets the placeholder image displayed during loading.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
verticalAlign(value: ImageSpanAlignment)
Sets the alignment mode of the image relative to the line height.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | ImageSpanAlignment | Yes | Alignment mode of the image relative to the line height. Default value: ImageSpanAlignment.BOTTOM |
objectFit(value: ImageFit)
Sets the image scale type.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | ImageFit | Yes | Image scale type. Default value: ImageFit.Cover |
Among all the universal events, only the click event is supported. The following events are also supported.
onComplete(callback: ImageCompleteCallback)
Triggered when the image is successfully loaded or decoded. The size of the loaded image is returned.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| callback | ImageCompleteCallback | Yes | Callback triggered when the image is successfully loaded or decoded. |
onError(callback: ImageErrorCallback)
Triggered when an error occurs during image loading.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| callback | ImageErrorCallback | Yes | Callback triggered when an error occurs during image loading. |
type ImageCompleteCallback = (result: ImageLoadResult) => void
Triggered when the image is successfully loaded.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| result | ImageLoadResult | Yes | Object returned after the callback is triggered when an image is successfully loaded or decoded. |
Object returned after the callback is triggered when an image is successfully loaded or decoded.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| width | number | Yes | Width of the image. Unit: pixel |
| height | number | Yes | Height of the image. Unit: pixel |
| componentWidth | number | Yes | Width of the component. Unit: pixel |
| componentHeight | number | Yes | Height of the component. Unit: pixel |
| loadingStatus | number | Yes | Loading status of the image. NOTE If the return value is 0, the image is successfully loaded. If the return value is 1, the image is successfully decoded. |
| contentWidth | number | Yes | Actual rendered width of the image. Unit: pixel NOTE This parameter is valid only when the return value of loadingStatus is 1. |
| contentHeight | number | Yes | Actual rendered height of the image. Unit: pixel NOTE This parameter is valid only when the return value of loadingStatus is 1. |
| contentOffsetX | number | Yes | Offset of the rendered content relative to the component on the x-axis. Unit: pixel NOTE This parameter is valid only when the return value of loadingStatus is 1. |
| contentOffsetY | number | Yes | Offset of the rendered content relative to the component on the y-axis Unit: pixel NOTE This parameter is valid only when the return value of loadingStatus is 1. |
This example sets the basic attributes of the image span as well as the alignment mode of the image with the text.
// 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 })
}
} 
This example shows how to set the background style of an image span.
// 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)
}
} 
This example implements a callback triggered when the image is successfully loaded or decoded and a callback triggered when an error occurs during image loading.
// 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%')
}
} This example shows how a placeholder image is used in ImageSpan during the process of loading an image from the Internet.
// 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() {
// Enter an image URL.
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<string, number | boolean | tmp> = {
'alphaType': 0, // Alpha type.
'editable': false, // Whether the image is editable.
'pixelFormat': 3, // Pixel format.
'scaleMode': 1, // Scale mode.
'size': { height: 100, width: 100 }
}
// Image size.
imageSource.createPixelMap(option).then((pixelMap: PixelMap) => {
this.imageAlt = pixelMap
})
}
})
}
build() {
Column() {
Button("Get Online Image")
.onClick(() => {
this.httpRequest()
})
Text() {
// Enter an image URL.
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 })
}
} 