登录/ 注册
 找回密码
 立即注册
关闭

CSDN热搜

程序园 精品问答 技术交流 资源下载
返回列表 发新帖
首页 › 业界区 › 业界 ›第十六节：图片展示组件Image核心讲解与实战（基础篇） ...

第十六节：图片展示组件Image核心讲解与实战（基础篇）

磁呃泵 2 小时前
猛犸象科技工作室:网站开发，备案域名，渗透，服务器出租，DDOS/CC攻击，TG加粉引流
第十六节：图片展示组件Image核心讲解与实战（基础篇）

【学习目标】


  • 理解Image组件的核心定位，掌握png/jpg/svg/gif等主流格式的支持特性，明确各类格式的适配场景；
  • 精通本地资源、网络图片、媒体库、Base64等基础数据源的加载方式与权限配置；
  • 掌握objectFit、interpolation、renderMode等核心属性的用法，能根据业务需求自定义基础图片展示效果。
一、Image组件核心认知

1.1 组件定义与定位

Image是鸿蒙图片展示的核心基础组件，负责将不同来源、不同格式的图片资源渲染到界面上，是应用开发中高频使用的组件之一。它承接了从图片加载、解码到渲染展示的全流程能力，同时支持丰富的属性配置和进阶扩展，可满足日常静态展示、动态效果呈现、性能优化等多场景需求。
1.2 支持图片格式与适配说明

支持格式格式后缀适用场景特殊说明位图基础格式png、jpg、bmp、jpeg日常静态图片展示（图标、背景、内容图）png支持透明通道，适合图标/按钮；jpg压缩率高，适合大尺寸内容图矢量图格式svg自适应缩放场景（LOGO、简易图标、插画）无像素失真，支持动态修改颜色，无原始尺寸时需手动设置宽高动态图片格式gif、heif短动态效果展示（表情包、简易动画）支持多帧播放，ArkTS卡片中gif仅播放一次不支持格式apng、svga-如需实现复杂动态效果，可通过AnimatedDrawableDescriptor1.3 典型适用场景

场景类型具体示例核心实现要点基础静态展示页面图标、背景图、商品图片本地资源/Resource加载 + objectFit适配 + 基础样式配置网络图片展示新闻配图、头像、远程资源图网络路径加载 + INTERNET权限 + 缓存优化 + 加载/失败占位自适应矢量展示应用LOGO、功能图标、导航栏图标SVG格式 + fillColor动态改色 + 固定宽高配置动态效果展示表情包、操作反馈动画、轮播小动画GIF/HEIF格式 + AnimatedDrawableDescriptor + 循环/时长配置复杂定制展示圆形头像、带徽章图片、分层背景objectFit(Cover) + 裁剪 + LayeredDrawableDescriptor分层叠加性能优化场景长列表图片、大尺寸图片展示sourceSize解码降分辨率 + 异步加载 + 缓存策略二、工程结构与环境准备

2.1 工程基础配置


  • 基础环境：鸿蒙API 12+、Stage模型
  • 权限声明：网络图片需在module.json5中添加ohos.permission.INTERNET；媒体库访问需申请ohos.permission.READ_MEDIA_IMAGES权限（PhotoViewPicker安全控件方式无需声明）
2.2 工程目录结构
  1. ImageApplication/
  2. ├── AppScope/
  3. │   └── app.json5  // 应用全局配置
  4. ├── entry/
  5. │   ├── src/
  6. │   │   ├── main/
  7. │   │   │   ├── ets/
  8. │   │   │   │   ├── entryability/
  9. │   │   │   │   │   └── EntryAbility.ets  // 应用入口
  10. │   │   │   │   ├── pages/  // 功能演示页面
  11. │   │   │   │   │   ├── Index.ets  // 导航主页面
  12. │   │   │   │   │   ├── ImageBasicPage.ets  // 基础用法&核心属性
  13. │   │   │   │   │   ├── ImageSourcePage.ets // 多数据源加载
  14. │   │   │   │   │   ├── Base64ImagePage.ets // Base64图片加载
  15. │   │   │   │   │   ├── ImageMediaLibrary.ets // 媒体库加载
  16. │   │   │   ├── resources/
  17. │   │   │   │   ├── media/  // $r引用资源
  18. │   │   │   │   └── rawfile/ // $rawfile引用原生资源
  19. │   │   │   └── module.json5  // 权限声明
复制代码
2.3 导航主页面（Index.ets）
  1. import { router } from '@kit.ArkUI';
  3. interface RouterButton {
  4.   title: string;
  5.   url: string;
  6. }
  8. @Entry
  9. @Component
  10. struct Index {
  11.   private buttonList: RouterButton[] = [
  12.     { title: "Image基础用法&核心属性", url: 'pages/ImageBasicPage' },
  13.     { title: "Image多数据源加载", url: 'pages/ImageSourcePage' },
  14.     { title: "Base64图片加载", url: 'pages/Base64ImagePage' },
  15.     { title: "MediaLibrary图片加载", url: 'pages/ImageMediaLibrary' },
  16.   ];
  18.   build() {
  19.     Column({ space: 15 }) {
  20.       Text("Image组件实战教程")
  21.         .fontSize(30)
  22.         .fontWeight(FontWeight.Bold)
  23.         .margin({ bottom: 40 })
  24.         .textAlign(TextAlign.Center);
  26.       ForEach(
  27.         this.buttonList,
  28.         (item: RouterButton) => {
  29.           Button(item.title)
  30.             .width('80%')
  31.             .height(45)
  32.             .backgroundColor($r('sys.color.brand'))
  33.             .fontColor(Color.White)
  34.             .fontSize(16)
  35.             .borderRadius(8)
  36.             .onClick(() => {
  37.               router.pushUrl({
  38.                 url: item.url,
  39.                 params: { title: item.title }
  40.               });
  41.             })
  42.         },
  43.         (item:RouterButton) => item.url
  44.       );
  45.     }
  46.     .width('100%')
  47.     .height('100%')
  48.     .justifyContent(FlexAlign.Center)
  49.     .backgroundColor('#F5F5F5')
  50.     .padding(20);
  51.   }
  52. }
复制代码
三、核心属性与实战用法

3.1 必配属性（避免布局异常）
  1. Image(数据源)
  2.   .width(数值)
  3.   .height(数值)
  4.   .objectFit(ImageFit.Contain)
复制代码
3.2 objectFit（最核心）

枚举值通俗描述视觉效果适用场景Contain完整显示图片完整，容器可能留白图标、LOGO、需完整展示的内容Cover填充裁剪容器无空白，图片裁剪头像、背景图、填满容器的图片Auto自适应同Contain默认场景Fill拉伸填充图片变形慎用ScaleDown缩小不放大小图不变，大图缩小小图防模糊3.3 其他核心属性


  • interpolation：图片放大插值，抗锯齿
  • objectRepeat：图片重复平铺
  • renderMode + fillColor：SVG图标改色
  • borderRadius：圆角、圆形头像
  • alt：加载失败/加载中占位图
3.4 基础属性实战页面（ImageBasicPage.ets）
  1. import { LengthMetrics } from '@kit.ArkUI';
  3. // 1. 定义ImageFit配置项的接口
  4. interface ImageFitItem {
  5.   name: string;        // 枚举名称（用于展示）
  6.   desc: string;        // 枚举说明（用于展示）
  7.   value: ImageFit;     // ImageFit枚举值
  8. }
  10. @Entry
  11. @Component
  12. struct ImageBasicPage {
  13.   private imageFitList: ImageFitItem[] = [
  14.     { name: 'Contain', desc: '完整显示', value: ImageFit.Contain },
  15.     { name: 'Cover', desc: '填充裁剪', value: ImageFit.Cover },
  16.     { name: 'Auto', desc: '自适应', value: ImageFit.Auto },
  17.     { name: 'Fill', desc: '拉伸填充', value: ImageFit.Fill },
  18.     { name: 'ScaleDown', desc: '缩小不放大', value: ImageFit.ScaleDown }
  19.   ];
  21.   build() {
  22.     Scroll() {
  23.       Column({ space: 25 }) {
  24.         // 页面标题
  25.         Text("Image核心属性演示")
  26.           .fontSize(24)
  27.           .fontWeight(FontWeight.Bold)
  28.           .width('100%')
  29.           .textAlign(TextAlign.Center);
  31.         // 1. objectFit枚举演示
  32.         Text("1. objectFit核心缩放枚举")
  33.           .fontSize(16)
  34.           .fontWeight(FontWeight.Medium)
  35.           .width('90%')
  36.           .textAlign(TextAlign.Start);
  38.         // Flex布局：自动换行，统一间距
  39.         Flex({
  40.           wrap: FlexWrap.Wrap,
  41.           justifyContent: FlexAlign.Center,
  42.           alignItems: ItemAlign.Center,
  43.           space:{
  44.             main:LengthMetrics.vp(10),
  45.             cross:LengthMetrics.vp(10)
  46.           }
  47.         }) {
  48.           // ForEach批量渲染
  49.           ForEach(
  50.             this.imageFitList,
  51.             (item: ImageFitItem) => { // 显式指定类型，提升可读性
  52.               Column({ space: 8 }) {
  53.                 Text(`${item.name}\n（${item.desc}）`)
  54.                   .fontSize(16)
  55.                   .fontColor('#666')
  56.                   .textAlign(TextAlign.Center)
  58.                 Image($r('app.media.banner'))
  59.                   .width(160)
  60.                   .height(120)
  61.                   .objectFit(item.value) // 类型安全：只能传ImageFit枚举值
  62.                   .backgroundColor(Color.Pink)
  63.                   .border({ width: 1, color: '#eee' });
  64.               }
  65.               .flexGrow(1)
  66.               .flexShrink(1);
  67.             },
  68.             (item:ImageFitItem) => item.name // 唯一标识
  69.           );
  70.         }
  71.         .width('100%')
  72.         .padding({ left: 10, right: 10 });
  74.         // 2. 圆角图片
  75.         Text("2. 圆角头像（borderRadius + Cover）")
  76.           .fontSize(16)
  77.           .width('90%')
  78.           .textAlign(TextAlign.Start);
  80.         Image($r('app.media.avatar'))
  81.           .width(120)
  82.           .height(120)
  83.           .objectFit(ImageFit.Cover)
  84.           .borderRadius(20)
  85.           .backgroundColor('#f5f5f5');
  87.         // 3. 图标动态改色
  88.         Text("3. 图标改色（Template + fillColor）")
  89.           .fontSize(16)
  90.           .width('90%')
  91.           .textAlign(TextAlign.Start);
  93.         Row(){
  94.           Image($r('app.media.icon_setting'))
  95.             .width(40)
  96.             .height(40)
  97.             .backgroundColor('#999');
  99.           Image($r('app.media.icon_setting'))
  100.             .width(40)
  101.             .height(40)
  102.             .renderMode(ImageRenderMode.Template)
  103.             .fillColor(Color.Blue)
  104.             .backgroundColor('#999');
  105.         }.width('100%')
  106.         .justifyContent(FlexAlign.Center)
  108.         // 4. 图片重复
  109.         Text("4. objectRepeat：XY（双向重复）")
  110.           .fontSize(16)
  111.           .width('90%')
  112.           .textAlign(TextAlign.Start);
  113.         Image($r('app.media.love'))
  114.           .width(200)
  115.           .height(200)
  116.           .objectRepeat(ImageRepeat.XY)
  117.           .objectFit(ImageFit.ScaleDown)
  118.           .backgroundColor(Color.Pink)
  119.           .overlay('ImageRepeat.XY', { align: Alignment.Bottom, offset: { x: 0, y: 20 } });
  121.         // 5. 放大抗锯齿
  122.         Text("5. interpolation：High（放大抗锯齿）")
  123.           .fontSize(16)
  124.           .width('90%')
  125.           .textAlign(TextAlign.Start);
  126.         Row(){
  127.           Image($r('app.media.love'))
  128.             .width(100)
  129.             .height(100)
  130.             .interpolation(ImageInterpolation.None)
  131.             .backgroundColor('#f5f5f5');
  132.           Image($r('app.media.love'))
  133.             .width(100)
  134.             .height(100)
  135.             .interpolation(ImageInterpolation.High)
  136.             .backgroundColor('#f5f5f5');
  137.         }.width('100%')
  138.         .justifyContent(FlexAlign.Center)
  140.       }
  141.       .backgroundColor('#F5F5F5')
  142.       .width('100%')
  143.     }
  144.     .width('100%')
  145.     .height('100%')
  146.   }
  147. }
复制代码
运行效果

1.gif

四、多数据源加载

4.1 本地资源加载

（1）media 目录（$r）
  1. Image($r('app.media.harmonyOS'))
复制代码
（2）rawfile 目录（$rawfile）
  1. Image($rawfile('development.webp'))
复制代码
4.2 网络图片加载

步骤1：声明权限（module.json5）
  1. {
  2.   "module": {
  3.     "requestPermissions": [
  4.       { "name": "ohos.permission.INTERNET" }
  5.     ]
  6.   }
  7. }
复制代码
步骤2：加载网络图片
  1. Image('https://res.vmallres.com/FssCdnProxy/vmall_product_uom/pmsCdn/09EFE73EA18A31D59FF3D60F7F54566A.jpg')
  2.   .width(300)
  3.   .objectFit(ImageFit.Contain)
复制代码
4.3 多数据源页面（ImageSourcePage.ets）
  1. @Entry
  2. @Component
  3. struct ImageSourcePage {
  4.   build() {
  5.     Column({ space: 15 }) {
  6.       // 1. Resource资源
  7.       Text("1. Resource资源（$r）")
  8.         .fontSize(16)
  9.         .width('90%')
  10.         .textAlign(TextAlign.Start);
  11.       Image($r('app.media.harmonyOS'))
  12.         .width(300)
  13.         .aspectRatio(16/9)
  14.         .objectFit(ImageFit.Contain)
  15.         .backgroundColor('#f5f5f5');
  17.       // 2. rawfile资源
  18.       Text("2. rawfile资源（$rawfile）")
  19.         .fontSize(16)
  20.         .width('90%')
  21.         .textAlign(TextAlign.Start);
  22.       Image($rawfile('development.webp'))
  23.         .width(300)
  24.         .aspectRatio(16/9)
  25.         .objectFit(ImageFit.Cover)
  26.         .backgroundColor('#f5f5f5');
  28.       // 3. 网络资源
  29.       Text("3. 网络资源（URL）")
  30.         .fontSize(16)
  31.         .width('90%')
  32.         .textAlign(TextAlign.Start);
  33.       Image('https://res.vmallres.com/FssCdnProxy/vmall_product_uom/pmsCdn/09EFE73EA18A31D59FF3D60F7F54566A.jpg')
  34.         .width(300)
  35.         .syncLoad(false) // 异步加载（默认值，避免阻塞UI）
  36.         .objectFit(ImageFit.Contain)
  37.         .backgroundColor('#f5f5f5');
  39.     }
  40.     .width('100%')
  41.     .height('100%')
  42.     .backgroundColor('#F5F5F5')
  43.     .justifyContent(FlexAlign.Center);
  44.   }
  45. }
复制代码
运行效果

2.jpeg

4.4 媒体库图片加载（ImageMediaLibrary.ets）
  1. import { photoAccessHelper } from '@kit.MediaLibraryKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  4. @Entry
  5. @Component
  6. struct ImageMediaLibrary {
  7.   @State imgUris: string[] = [];
  9.   // 获取图库图片URI
  10.   getAllImages() {
  11.     try {
  12.       const selectOptions = new photoAccessHelper.PhotoSelectOptions();
  13.       selectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
  14.       selectOptions.maxSelectNumber = 3; // 最多选择3张
  15.       const photoPicker = new photoAccessHelper.PhotoViewPicker();
  17.       photoPicker.select(selectOptions)
  18.         .then((result) => {
  19.           this.imgUris = result.photoUris; // 存储图片URI
  20.         })
  21.         .catch((err: BusinessError) => {
  22.           console.error(`图库选择失败：${err.code} - ${err.message}`);
  23.         });
  24.     } catch (err) {
  25.       console.error(`图库访问异常：${err.message}`);
  26.     }
  27.   }
  29.   build() {
  30.     Column({ space: 20 }) {
  31.       Button("选择图库图片")
  32.         .onClick(() => this.getAllImages())
  33.         .margin({ top: 20 });
  35.       // 展示选中的图片
  36.       ForEach(
  37.         this.imgUris,
  38.         (uri: string) => {
  39.           Image(uri)
  40.             .width(120)
  41.             .height(120)
  42.             .objectFit(ImageFit.Cover)
  43.             .borderRadius(8)
  44.             .backgroundColor('#f5f5f5');
  45.         },
  46.         (uri: string) => uri
  47.       );
  48.     }
  49.     .width('100%')
  50.     .height('100%')
  51.     .backgroundColor('#F5F5F5');
  52.   }
  53. }
复制代码
运行效果

3.gif

4.5 Base64 图片加载（Base64ImagePage.ets）
  1. import util from '@ohos.util';
  3. @Entry
  4. @Component
  5. struct Base64ImagePage {
  6.   @State base64image: string = ''
  8.   aboutToAppear(): void {
  9.     // base64 字符串由于很长，所以我们将图片并转换为Base64字符串并加载
  10.     this.base64image = this.imageToBase64('harmonyOSCar.jpeg')
  11.   }
  13.   /**
  14.    * 读取rawfile图片并转换为Base64字符串
  15.    * @param imageName rawfile下的图片文件名（含后缀）
  16.    * @returns 标准Base64图片字符串
  17.    */
  18.   imageToBase64(imageName: string): string {
  19.     try {
  20.       // 1. 获取资源管理器
  21.       const uiContext = this.getUIContext();
  22.       const hostContext = uiContext.getHostContext();
  23.       const resMgr = hostContext?.resourceManager;
  24.       if (!resMgr) {
  25.         console.error('获取resourceManager失败');
  26.         return '';
  27.       }
  29.       // 2. 同步读取rawfile文件内容
  30.       const imageData = resMgr.getRawFileContentSync(imageName)
  31.       if (!imageData || imageData.length === 0) {
  32.         console.error('读取图片数据为空');
  33.         return '';
  34.       }
  36.       // 3. 转换为Base64字符串（确保入参类型正确）
  37.       const base64Helper = new util.Base64Helper();
  38.       const base64Str = base64Helper.encodeToStringSync(imageData);
  39.       if (!base64Str) {
  40.         console.error('Base64编码失败');
  41.         return '';
  42.       }
  44.       // 4. 动态生成正确的MIME前缀（根据文件后缀匹配）
  45.       const ext = imageName.split('.').pop()?.toLowerCase() || 'png';
  46.       // 映射常见图片格式的MIME类型
  47.       const mimeMap: Record<string, string> = {
  48.         'png': 'image/png',
  49.         'jpg': 'image/jpeg',
  50.         'jpeg': 'image/jpeg',
  51.         'webp': 'image/webp',
  52.         'gif': 'image/gif'
  53.       };
  54.       const mimeType = mimeMap[ext] || 'image/png';
  55.       // 5. 拼接标准Base64图片格式
  56.       const base64ImageStr = `data:${mimeType};base64,${base64Str}`;
  57.       console.log('生成的Base64字符串：', base64ImageStr.substring(0, 50) + '...'); // 打印前50位验证
  58.       return base64ImageStr;
  59.     } catch (error) {
  60.       console.error('图片转Base64失败：', error);
  61.       return '';
  62.     }
  63.   }
  65.   build() {
  66.     Column({ space: 15 }) {
  67.       Text("Base64格式图片展示")
  68.         .fontSize(16)
  69.         .width('90%')
  70.         .textAlign(TextAlign.Start);
  71.       Image(this.base64image)
  72.         .width(200)
  73.         .height(200)
  74.         .objectFit(ImageFit.Contain)
  75.         .backgroundColor('#f5f5f5');
  76.     }
  77.     .width('100%')
  78.     .height('100%')
  79.     .backgroundColor('#F5F5F5')
  80.     .justifyContent(FlexAlign.Center);
  81.   }
  82. }
复制代码
运行效果

4.png

4.6 数据源选型建议

数据源类型适用场景优势$r本地图标、常规图片适配强、使用简单$rawfile特殊格式、原始文件保留原始结构网络URL远程图片、头像、内容图动态更新、无需打包进应用媒体库URI相册选择图片安全、无需权限Base64小图标、内嵌图片无网络请求、加载快五、内容总结


  • 核心定位：Image是鸿蒙系统最常用的图片展示组件，支持png、jpg、svg、gif等主流格式，可满足静态展示、圆角头像、图标改色等日常开发需求。
  • 必掌握属性：width/height必须显式设置；objectFit是图片缩放核心，优先使用Contain和Cover；borderRadius实现圆角/圆形效果；renderMode+fillColor用于SVG图标改色。
  • 多数据源加载：本地资源用$r/$rawfile；网络图片需配置INTERNET权限；媒体库图片使用PhotoViewPicker无需申请权限；Base64适合小型图标内嵌展示。
  • 开发规范：网络图片建议配置alt占位图，媒体库选择优先使用系统控件，避免权限风险与异常崩溃。
六、代码仓库


  • 工程名称：ImageApplication
  • 仓库地址：https://gitee.com/HarmonyOS-UI-Basics/harmony-os-ui-basics.git
七、下节预告

下一节我们将学习 第十七节：Image组件进阶实战，内容包括：

  • PixelMap 像素级图片处理
  • 图片加载事件与异常兜底
  • 分层图片、GIF 动画合成与播放
  • 图片性能优化与内存管理

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！
第十六图片展示组件Image

使用道具 举报

相关推荐
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册
发帖
磁呃泵
2 小时前

0

粉丝关注

13

主题发布

板块介绍填写区域，请于后台编辑
微信扫一扫