鸿蒙HarmonyOS NEXT开发：ImageSpan（基础组件）

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，通用属性方法支持尺寸设置、背景设置、边框设置

alt12+

alt(value: PixelMap)

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

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

参数：

参数名	类型	必填	说明
value	PixelMap	是	加载时显示的占位图，支持PixelMap类型。 默认值：null

verticalAlign

verticalAlign(value: ImageSpanAlignment)

设置图片基于文本的对齐方式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	ImageSpanAlignment	是	图片基于文本的对齐方式。 默认值：ImageSpanAlignment.BOTTOM

objectFit

objectFit(value: ImageFit)

设置图片的缩放类型。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	ImageFit	是	图片的缩放类型。 默认值：ImageFit.Cover

ImageSpanAlignment

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

名称	描述
TOP	图片上边沿与行上边沿对齐。
CENTER	图片中间与行中间对齐。
BOTTOM	图片下边沿与行下边沿对齐。
BASELINE	图片下边沿与文本BaseLine对齐。

事件

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

onComplete12+

onComplete(callback: ImageCompleteCallback)

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

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

参数：

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

onError12+

onError(callback: ImageErrorCallback)

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

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

参数：

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

ImageCompleteCallback12+

type ImageCompleteCallback = (result: ImageLoadResult) => void

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

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

ImageLoadResult12+

图片数据加载成功和解码成功触发回调时返回的对象。

参数名	类型	必填	说明
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

该示例实现了设置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.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 })
  }
}
ts

示例2

该示例实现了如何设置ImageSpan图片的背景样式。

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

示例3

ImageSpan设置图片成功加载解码和图片加载异常事件回调。

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

写在最后

• 如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：
• 点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。
• 关注小编，同时可以期待后续文章ing ，不定期分享原创知识。