【鸿蒙开发】系统组件Image

鸿蒙开发arkui组件，image组件

d312697510

1863人浏览 · 2024-04-07 17:18:27

d312697510 · 2024-04-07 17:18:27 发布

Image组件

ImageImage为图片组件，常用于在应用中显示图片。Image支持加载string、PixelMap和Resource类型的数据源，支持png、jpg、bmp、svg和gif类型的图片格式。

使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考权限申请声明。

接口：

Image(src: string | PixelMap | Resource)

参数：

参数名	参数类型	必填	参数描述
src	string \| PixelMap \| Resource	是	图片的数据源，支持本地图片和网络图片，引用方式请参考加载图片资源。 string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image("common/test.jpg")，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。支持Base64字符串。格式data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data], 其中[base64 data]为Base64字符串数据。支持file://路径前缀的字符串。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。 PixelMap格式为像素图，常用于图片编辑的场景。 Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。说明： ArkTS卡片支持gif图片格式动效，但仅在显示时播放一次。 ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。 ArkTS卡片上不支持PixelMap类型。

参数名

参数类型

必填

参数描述

src

string | PixelMap | Resource

是

图片的数据源，支持本地图片和网络图片，引用方式请参考加载图片资源。

string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image("common/test.jpg")，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。
- 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp];base64,[base64 data], 其中[base64 data]为Base64字符串数据。
- 支持file://路径前缀的字符串。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。
PixelMap格式为像素图，常用于图片编辑的场景。
Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。

说明：

ArkTS卡片支持gif图片格式动效，但仅在显示时播放一次。
ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。
ArkTS卡片上不支持PixelMap类型。

属性：

属性的详细使用指导请参考添加属性。除支持通用属性外，还支持以下属性：

名称	参数类型	描述
alt	string \| Resource	加载时显示的占位图，支持本地图片（png、jpg、bmp、svg和gif类型），不支持网络图片。默认值：null 从API version 9开始，该接口支持在ArkTS卡片中使用。
objectFit	ImageFit	设置图片的填充效果。默认值：ImageFit.Cover 从API version 9开始，该接口支持在ArkTS卡片中使用。
objectRepeat	ImageRepeat	设置图片的重复样式。从中心点向两边重复，剩余空间不足放下一张图片时会截断。默认值：ImageRepeat.NoRepeat 从API version 9开始，该接口支持在ArkTS卡片中使用。说明： svg类型图源不支持该属性。
interpolation	ImageInterpolation	设置图片的插值效果，即减轻低清晰度图片在放大显示时出现的锯齿问题。默认值：ImageInterpolation.None 从API version 9开始，该接口支持在ArkTS卡片中使用。说明： svg类型图源不支持该属性。 PixelMap资源不支持该属性。
renderMode	ImageRenderMode	设置图片的渲染模式为原色或黑白。默认值：ImageRenderMode.Original 从API version 9开始，该接口支持在ArkTS卡片中使用。说明： svg类型图源不支持该属性。
sourceSize	{ width: number, height: number }	设置图片解码尺寸，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。单位：px 从API version 9开始，该接口支持在ArkTS卡片中使用。说明：仅在目标尺寸小于图源尺寸时生效。 svg类型图源不支持该属性。 PixelMap资源不支持该属性。
matchTextDirection	boolean	设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。默认值：false 从API version 9开始，该接口支持在ArkTS卡片中使用。
fitOriginalSize	boolean	图片组件尺寸未设置时，显示尺寸是否跟随图源尺寸。组件不设置宽高或仅设置宽/高时，该属性不生效。默认值：false 从API version 9开始，该接口支持在ArkTS卡片中使用。
fillColor	ResourceColor	设置填充颜色，设置后填充颜色会覆盖在图片上。从API version 9开始，该接口支持在ArkTS卡片中使用。说明：仅对svg图源生效，设置后会替换svg图片的填充颜色。
autoResize	boolean	设置图片解码过程中是否对图源自动缩放。设置为true时，组件会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。如原图大小为1920x1080，而显示区域大小为200x200，则图片会自动解码到200x200的尺寸，大幅度节省图片占用的内存。默认值：true 从API version 9开始，该接口支持在ArkTS卡片中使用。
syncLoad8+	boolean	设置是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。默认值：false 从API version 9开始，该接口支持在ArkTS卡片中使用。说明：建议加载尺寸较小的本地图片时将syncLoad设为true，因为耗时较短，在主线程上执行即可。
copyOption9+	CopyOptions	设置图片是否可复制。当copyOption设置为非CopyOptions.None时，支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。默认值：CopyOptions.None 从API version 9开始，该接口支持在ArkTS卡片中使用。说明： svg图片不支持复制。
colorFilter9+	ColorFilter	给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。 RGBA值分别是0和1之间的浮点数字，当矩阵对角线值为1时，保持图片原有色彩。计算规则：如果输入的滤镜矩阵为： [ r_1, r_2, r_3, r_4, r_5, g_1, g_2, g_3, g_4, g_5, b_1, b_2, b_3, b_4, b_5, a_1, a_2, a_3, a_4, a_5 ] 像素点为[R, G, B, A] 则过滤后的颜色为 [R’, G’, B’, A’] R’ = r_1R + r_2G + r_3B + r_4A + r_5 G’ = g_1R + g_2G + g_3B + g_4A + g_5 B’ = b_1R + b_2G + b_3B + b_4A + b_5 A’ = a_1R + a_2G + a_3B + a_4A + a_5 从API version 9开始，该接口支持在ArkTS卡片中使用。
draggable9+	boolean	设置组件默认拖拽效果，设置为true时，组件可拖拽。不能和拖拽事件事件同时使用。默认值：false

开启网络权限

修改src/main/module.json5

添加网络权限配置

    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ],

示例

@Entry
@Component
struct APage {
  build() {
    Column({ space: 20 }) {
      Image($r("app.media.app_icon"))
        .width(80)
        .aspectRatio(1)

      Divider()
        .strokeWidth(20)

      Image($rawfile("cat.jpg"))
        .width(80)
        .aspectRatio(1)

      Divider()
        .strokeWidth(20)

      //前提条件，需要申请网络访问权限
      Image("https://p5.itc.cn/images01/20210415/c5101e7c44044fd0bed287cb1009f063.jpeg")
        .width(80)
        .aspectRatio(1)

      Divider()
        .strokeWidth(20)

      Image("/pages/images/cat.jpg")
        .width(80)
        .aspectRatio(1)

    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Start)

  }
}

HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

HarmonyOS开发者集合！“智问智答挑战月”来袭，边解难题边赢会员+定制周边！

HarmonyOS开发者社区

鸿蒙应用冷启动优化：本地 KV 缓存预热实战指南

友友们，早上好。在鸿蒙（HarmonyOS）应用开发中，冷启动速度直接影响用户的初始体验。许多应用在启动后需要加载大量常用配置（如用户偏好设置、主题配置）或基础数据（如上次登录信息、常用功能参数），若每次都从本地存储中实时读取，会增加 IO 开销，导致界面响应延迟。这里我将分享本地 KV 缓存预热技术，详解如何在应用启动阶段提前加载关键数据，从根源上减少用户等待时间。一、为什么需要 KV 缓存

HarmonyOS开发者社区

鸿蒙深链落地实战：从安全解析到异常兜底的全链路设计

友友们，大家好。在鸿蒙应用的商业化场景中，深链（Deep Link）是连接外部流量与内部页面的关键纽带 —— 无论是活动推广页的直接唤起、第三方 App 跳转至特定功能页，还是带参数的个性化路由，都依赖深链实现 “一步直达”。但实际落地时，开发者常面临三大核心难题：复杂参数易被篡改（如伪造 token 绕过权限校验）、冷 / 热启动场景适配混乱（应用未启动 vs 已启动时参数接收不一致）、异常场景