目录

ImageSpan

Text、ContainerSpan组件的子组件,用于显示行内图片。

该组件从API Version 10开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

子组件

无

接口

ImageSpan(value: ResourceStr | PixelMap)

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value ResourceStr | PixelMap 是

图片的数据源,支持本地图片和网络图片。

当使用相对路径引用图片资源时,例如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,通用属性方法支持尺寸设置、背景设置、边框设置

[h2]verticalAlign

verticalAlign(value: ImageSpanAlignment)

设置图片基于行高的对齐方式。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value ImageSpanAlignment 是

图片基于行高的对齐方式。

默认值:ImageSpanAlignment.BOTTOM

[h2]objectFit

objectFit(value: ImageFit)

设置图片的缩放类型。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value ImageFit 是

图片的缩放类型。

默认值:ImageFit.Cover

[h2]alt12+

alt(value: PixelMap)

设置图片加载时显示的占位图。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value PixelMap 是

加载时显示的占位图,支持PixelMap类型。

默认值:null

事件

通用事件仅支持点击事件。还支持以下事件:

[h2]onComplete12+

onComplete(callback: ImageCompleteCallback)

图片数据加载成功和解码成功时均触发该回调,返回成功加载的图片尺寸。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
callback ImageCompleteCallback 是 图片数据加载成功和解码成功时触发的回调。

[h2]onError12+

onError(callback: ImageErrorCallback)

图片加载异常时触发该回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
callback ImageErrorCallback 是 图片加载异常时触发的回调。

ImageCompleteCallback12+

type ImageCompleteCallback = (result: ImageLoadResult) => void

图片加载异常时触发的回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数名 类型 必填 说明
result ImageLoadResult 是 图片数据加载成功和解码成功触发回调时返回的对象。

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时有效。

示例

[h2]示例1(设置对齐方式)

该示例通过verticalAlign、objectFit属性展示了ImageSpan的对齐方式以及缩放效果。

// 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.app_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.app_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.app_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.app_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]示例2(设置背景样式)

该示例通过textBackgroundStyle属性展示了文本设置背景样式的效果。

// xxx.ets
@Component
@Entry
struct Index {
  build() {
    Row() {
      Column() {
        Text() {
          ImageSpan($r('app.media.sky'))//建议使用自定义的本地图片
            .width('60vp')
            .height('60vp')
            .verticalAlign(ImageSpanAlignment.CENTER)
            .borderRadius(20)
            .textBackgroundStyle({ color: '#7F007DFF', radius: "5vp" })
        }
      }.width('100%')
    }.height('100%')
  }
}

[h2]示例3(为图片添加事件)

该示例通过onComplete、onError为图片添加加载成功和加载异常的事件。

// xxx.ets
@Entry
@Component
struct Index {
  @State src: ResourceStr = $r('app.media.app_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]示例4(设置加载占位图)

该示例alt属性展示了ImageSpan设置加载网络图片时占位图的效果。

// 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<string, number | boolean | tmp> = {
          '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 })
  }
}