鸿蒙应用开发从入门到实战（十）：ArkUI 图片组件 Image

作者：程序员潘Sir

2025-09-21
四川
本文字数：5808 字
阅读完需：约 19 分钟

大家好，我是潘 Sir，持续分享 IT 技术，帮你少走弯路。《鸿蒙应用开发从入门到项目实战》系列文章持续更新中，陆续更新 AI+编程、企业级项目实战等原创内容、欢迎关注！

ArkUI 提供了丰富的系统组件，用于制作鸿蒙原生应用 APP 的 UI，本文主要讲解 Image 图片组件的使用。

一、Image 图片组件

1.1 概述

Image为图片组件，用于在应用中显示图片。

1.2 图片参数

Image 组件的参数类型为string | Resource | media.PixelMap，下面对三种参数类型逐一进行介绍。

1.2.1 string 类型

string类型的参数用于通过路径的方式引用图片，包括本地图片和网络图片。

本地图片

Image('images/demo.jpg')

复制代码

注意：使用这种方式引入本地图片，需要将图片置于ets目录下，并且需要为Image组件提供图片相对于ets目录的路径。

网络图片

Image('http://xxx/xxx.jpg')

复制代码

**注意：**真机中运行的鸿蒙应用，访问网络图片需要配置网络访问权限，不过在预览器和模拟器中测试时不受限制。权限配置相关的内容在后续章节会系统介绍。

1.2.2 Resource 类型

Resource类型的参数用于引入 resources 目录下的图片。

resources 目录用于统一存放应用所需的各种资源，包括图片、音频、视频、文本等等。下面简要介绍 resources 目录的用法，首先需要了解 resources 的目录结构，如下

resources 目录下，用于存放资源的子目录有（element、media、profile）和 rawfile。下面分别介绍：

（1）element、media、profile

（element、media、profile）可存在多种版本，用于适配不同的环境，例如语言环境（zh_CN 和 en_US）、系统主题（dark 和 light）、设备类型（phone 和 tablet）等等。我们可以为上述每种环境各自准备一套资源文件，每种环境对应 resources 下的一个目录，例如上述的 zh_CN 和 en_US。我们在使用 resources 下的资源时，无需指定具体的环境版本，系统会根据设备所处的环境自动选择匹配的版本，例如当设备系统语言为中文时，则会使用 zh_CN 目录下的资源，为英文时，则会使用 en_US 目录下的资源。若没有与当前所处环境相对应的版本，则使用 base 目录下资源**。**

各目录存储的具体资源如下

media

存放媒体资源，包括图片、音频、视频等文件。

element

存放用于描述页面元素的尺寸、颜色、样式等的各种类型的值，每种类型的值都定义在一个相应的 JSON 文件中。

profile

存放自定义配置文件。

（2）rawfile

用于存储任意格式的原始文件，需要注意的是 rawfile 不会根据设备所处的环境去匹配不同的资源。

总结：

resources 目录下可用于存放图片的目录有**resources/*/**media 以及 **resources/**rawfile，两个目录下图片的使用方式有所不同，下面逐一介绍

media 目录
该目录下的资源，需要使用$r('app.media.<filename>')的方式引用。
注意：无需指定具体版本，系统会自动根据所处环境选择相应版本
例如上图中的 img.png 图片，可通过$r('app.media.img')引用。需要注意的是$r()的返回值即为 Resource 类型，因此可以直接将$r('app.media.img')作为 Image 组件的参数，例如Image($r('app.media.img'))。
rawfile 目录
该目录下的资源，可通过$rawfile('path/to/your/file')的方式引用，文件的路径为相对于 rawfile 的路径。例如上图中的 icon.png，须使用$rawfile('icon.png)引用。需要注意的是，$rawfile()的返回值也是 Resource 类型，因此其也可以直接作为 Image 组件的参数，如Image($rawfile('icon.png))。

1.2.3 media.PixelMap

PixelMap 指的是图片的像素位图，其通常是一个二维数组，数组中的每个元素对应着图片中的一个像素，其包含了该像素的颜色等信息。像素位图主要用于图片编辑的场景。

示例代码：

在 pages 目录下新建 component 目录，通过并把对应的代码放到对应的组件目录下。新建 image 目录，在该目录下创建 ImageParamenter.ets 和 images 目录。

素材准备：将 img_phone.png 拷贝到 images 目录，将 img_harmony.png 拷贝到 resources/base/media 目录下，将 img_phone.png 拷贝到 rawfile 目录下。

ImageParamenter.ets 代码

@Entry@Component// 图片参数struct ImageParamenter {
  build() {    Column({ space: 40 }) {      // 1、string类型      //本地图片,位于ets目录      Image('pages/component/image/images/img_phone.png')        .width(150)        .height(150)
      //网络图片      Image('https://developer.harmonyos.com/resource/image/new/home/img_DLP_jiazhi_2.png')        .width(150)        .height(150)
      // 2、Resource类型      //本地图片,位于resource/*/media目录      Image($r('app.media.img_harmony'))        .width(150)        .height(150)
      //本地图片,位于resource/rawfile目录      Image($rawfile('img_phone.png'))        .width(150)        .height(150)
    }    .width('100%')    .height('100%')    .justifyContent(FlexAlign.Center)  }}

复制代码

1.3 常用属性

1.3.1 图片尺寸

图片尺寸可通过width()方法和height()方法进行设置。例如

Image($r('app.media.img'))  .width(100)  .height(100)

复制代码

两个方法可接收的参数类型均为string | number | Resource，下面对三种参数类型逐一进行介绍。

（1）string 类型

string类型的参数可为百分比，例如'100%'，或者为具体尺寸，例如'100px'。

具体尺寸的单位，常用的有两个，分别是px和vp，下面逐个介绍

px(Pixel)

物理像素，以像素个数来定义图像尺寸。这种方式的弊端是，在不同像素密度的屏幕上，相同的像素个数对应的物理尺寸是不同的。这样一来就会导致我们的应用在不同设备上显示的尺寸可能不同。如下图所示

vp(Virtual Pixel)

为了保证一致的观感，我们可以使用虚拟像素作为单位。虚拟像素是一种可根据屏幕像素密度灵活缩放的单位。1vp 相当于像素密度为 160ppi 的屏幕上的 1px。在不同像素密度的屏幕上，HarmonyOS 会根据如下公式将虚拟像素换算为对应的物理像素

根据上述公式，不难看出，使用虚拟像素作为单位时，同一尺寸，在像素密度低的屏幕上（单个像素的物理尺寸大），对应的物理像素会更少，相反在像素密度高的屏幕上（单个像素的物理尺寸小），对应的物理像素会更多。因此就能在不同像素密度的屏幕上，获得基本一致的观感了。如下图所示

（2）number类型

number类型的参数，默认以vp作为单位。

（3）Resource类型

Resource类型参数用于引用 resources 下的 element 目录中定义的数值。

引用 element 目录中的数值，同样需要使用$r()函数。要了解具体语法，需要先熟悉 element 目录下的文件内容。

前文提到过，element 目录中可保存各种类型的数值，且每种类型的值分别定义在一个 JSON 文件中。文件中的内容为键值对(name-value)的形式。具体内容如下

element/string.json

{  "string": [    {      "name": "module_desc",      "value": "模块描述"    },    {      "name": "greeting",      "value": "你好"    }  ]}

复制代码

element/integer.json

{  "integer": [    {      "name": "width",      "value": 150    },    {      "name": "height",      "value": 150    }  ]}

复制代码

我们可以通过 name 引用相应的 value。具体语法为$r('app..')。

注意：无需指定具体版本，系统会自动根据所处环境选择相应版本

例如上述的 greeting 的值，可通过$r('app.string.greeting')引用，width的值可通过$r('app.integer.width')。

示例代码：

在 resources/base/element 目录下新增 integer.json 文件

在 pages/component/image 目录下新增 ImageSizePage.ets 文件

@Entry@Component  // 图片尺寸struct ImageSizePage {  @State message: string = 'Hello World'
  build() {    Column({ space: 20 }) {
      // 1、属性方法参数为string类型      //1.1 单位为px      Row({ space: 20 }) {        Column() {          Image($r('app.media.img_harmony'))            .width('450px')            .height('450px')          Text('宽高:450px')        }
        //1.2 单位为vp        Column() {          Image($r('app.media.img_harmony'))            .width('150vp')            .height('150vp')          Text('宽高:150vp')        }      }
      // 2、属性方法参数为number类型，默认单位为vp      Row({ space: 20 }) {        Column() {          Image($r('app.media.img_harmony'))            .width(150)            .height(150)          Text('宽高:150')        }
        // 3、属性方法参数为Resource类型,读取integer.json文件        Column() {          Image($r('app.media.img_harmony'))            .width($r('app.integer.width'))            .height($r('app.integer.height'))          Text('宽高:150')        }      }
    }.width('100%')    .height('100%')    .justifyContent(FlexAlign.Center)  }}

复制代码

1.3.2 图片缩放

当图片的原始大小与 Image 组件不同时，可通过objectFit()方法来设置图片的显示效果。该方法的参数类型为ImageFit枚举类型，可选的枚举值如下

各选项的效果如下图所示

代码示例：

在 pages/component/image 目录下新增 ImageObjectFit.ets 文件

@Entry@Component// 图片缩放struct ImageObjectFit {
  build() {    Column({ space: 20 }) {
      Column() {        Image($r('app.media.img_harmony'))          .width('720px')          .height('334px')        Text('原图')      }
      Row({ space: 20 }) {        Column() {          Image($r('app.media.img_harmony'))            .width('450px')            .height('450px')            .borderWidth(1)            .objectFit(ImageFit.None)          Text('None')        }
        Column() {          Image($r('app.media.img_harmony'))            .width('450px')            .height('450px')            .borderWidth(1)            .objectFit(ImageFit.Contain)          Text('Contain')        }      }
      Row({ space: 20 }) {        Column() {          Image($r('app.media.img_harmony'))            .width('450px')            .height('450px')            .borderWidth(1)            .objectFit(ImageFit.Cover)          Text('Cover')        }
        Column() {          Image($r('app.media.img_harmony'))            .width('450px')            .height('450px')            .borderWidth(1)            .objectFit(ImageFit.Fill)          Text('Fill')        }      }
      Row({ space: 20 }) {        Column() {          Image($r('app.media.img_harmony'))            .width('450px')            .height('450px')            .borderWidth(1)            .objectFit(ImageFit.ScaleDown)          Text('ScaleDown')        }
        Column() {          Image($r('app.media.img_harmony'))            .width('450px')            .height('450px')            .borderWidth(1)            .objectFit(ImageFit.Auto)          Text('Auto')        }      }    }    .justifyContent(FlexAlign.Center)    .width('100%')    .height('100%')  }}

复制代码

1.3.3 图片插值

当原图分辨率较低并且需要放大显示时，图片会模糊并出现锯齿。如下图所示

这时可以使用interpolation()方法对图片进行插值，使图片显示得更清晰。该方法的参数为ImageInterpolation枚举类型，可选的值有

各选项效果如下图所示

代码示例：

将 img_flower.png 拷贝到 resources/base/media 目录下

在 pages/component/image 目录下新增 ImageInterpolationPage.ets 文件

@Entry@Component// 图片插值struct ImageInterpolationPage {
  build() {    Column({ space: 50 }) {      Row({ space: 20 }) {        Column() {          Image($r('app.media.img_flower'))            .width('500px')            .height('500px')            .interpolation(ImageInterpolation.None)          Text('None')        }
        Column() {          Image($r('app.media.img_flower'))            .width('500px')            .height('500px')            .interpolation(ImageInterpolation.Low)          Text('Low')        }      }

      Row({ space: 20 }) {        Column() {          Image($r('app.media.img_flower'))            .width('500px')            .height('500px')            .interpolation(ImageInterpolation.Medium)          Text('Medium')
        }
        Column() {          Image($r('app.media.img_flower'))            .width('500px')            .height('500px')            .interpolation(ImageInterpolation.High)          Text('High')        }      }    }    .width('100%')    .height('100%')    .justifyContent(FlexAlign.Center)  }}

复制代码

二、权限申请

真机或模拟器查看网络图片，需要申请网络访问权限：ohos.permission.INTERNET

为了方便测试，在 EntryAbility.ts 文件中修改启动页为：pages/component/image/ImageParamenter

页面路径可以在 resources/base/profile/main_pages.json 文件中查看

在 module.json5 文件的 module 下添加：

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

复制代码

具体参见官网说明

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V2/accesstoken-guidelines-0000001493744016-V2

附录：屏幕参数

想要理解 px 和 vp 尺寸单位，需要大家先掌握屏幕相关的几个参数

像素

屏幕显示的最小单位，屏幕上的一个小亮点称为一个像素。

分辨率

屏幕上横向和纵向的像素数量。

尺寸

屏幕对角线的长度，以英寸(inches)为单位。

像素密度

像素密度是每英寸屏幕上的像素数量，通常以PPI（Pixels Per Inch）表示，计算公式如下。较高的像素密度意味着在相同尺寸的屏幕上有更多的像素，从而提供更加清晰和细腻的图像。

如下图所示

《鸿蒙应用开发从入门到项目实战》系列文章持续更新中，陆续更新 AI+编程、企业级项目实战等原创内容，防止迷路，欢迎关注！

发布于: 1 小时前阅读数: 7

原文链接:【http://xie.infoq.cn/article/789fa6d24246f3f19919cd462】。文章转载请联系作者。

程序员潘Sir

关注

网名：黑马腾云 2020-06-22 加入

80后创业者、高级架构师，带你轻松学编程！著有《Node.js全栈开发从入门到项目实战》、《Java企业级软件开发》、《HarmonyOS应用开发实战》等书籍。“自学帮”公众号主。

发布

暂无评论

创作场景

鸿蒙应用开发从入门到实战（十）：ArkUI 图片组件 Image

一、Image 图片组件

1.1 概述

1.2 图片参数

1.2.1 string 类型

1.2.2 Resource 类型

1.2.3 media.PixelMap

1.3 常用属性

1.3.1 图片尺寸

1.3.2 图片缩放

1.3.3 图片插值

二、权限申请

附录：屏幕参数

程序员潘Sir

评论