目录

ImageSpan

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.

Child Components

Not supported

APIs

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.

Attributes

The attributes inherit from BaseSpan. Among the universal attributes, size, background, and border are supported.

[h2]alt12+

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

Name Type Mandatory Description
value PixelMap Yes

Placeholder image displayed during loading. The PixelMap type is supported.

Default value: null

[h2]verticalAlign

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

[h2]objectFit

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

Events

Among all the universal events, only the click event is supported. The following events are also supported.

[h2]onComplete12+

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.

[h2]onError12+

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.

ImageCompleteCallback12+

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.

ImageLoadResult12+

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.

Example

[h2]Example 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 })
  }
}

[h2]Example 2

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)
  }
}

[h2]Example 3

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%')
  }
}

[h2]Example 4

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 })
  }
}