从入门小白到精通，玩转 React Native 鸿蒙跨平台开发：Image 图片加载组件核心使用

RN 的 Image 组件，是对鸿蒙原生 Image 组件在页面中加载并展示各类图片资源。

哈__

459人浏览 · 2026-01-11 12:33:43

哈__ · 2026-01-11 12:33:43 发布

在 React Native 鸿蒙（RN-OH）跨平台开发中，Image 图片加载组件是仅次于 View、Text 的三大核心基础组件，也是新手开发中使用频率最高的组件之一。无论是做商品展示、头像加载、banner 轮播，还是普通配图，都离不开 Image 组件。

本文专为零基础新手打造，全程精简干货、无冗余进阶内容、无复杂代码，只讲「新手必学、必用、必掌握」的核心知识点，所有示例代码均可直接复制运行，鸿蒙真机 / 模拟器完美适配，吃透本文就能搞定 RN 鸿蒙开发中 99% 的图片加载需求。

前置说明：本文基于 React Native 鸿蒙适配版 react-native-ohos 开发，和原生 RN 的 Image 组件用法99% 一致，学会即能跨鸿蒙、安卓、iOS 三端使用，无额外学习成本。

一、新手须知：Image 组件核心概念

1.1 什么是 RN 鸿蒙的 Image 组件？

RN 的 Image 组件，是对鸿蒙原生 Image 组件的一层轻量封装，本质是跨平台的图片渲染容器，作用只有一个：在页面中加载并展示各类图片资源。

1.2 Image 组件核心能力

✅ 加载本地项目内的静态图片（本地资源）

✅ 加载网络地址的远程图片（网络资源）

✅ 适配鸿蒙系统的内置资源图片

✅ 支持基础的图片样式调整（宽高、圆角、拉伸、裁剪）

✅ 提供加载成功 / 加载失败的基础回调

✅ 鸿蒙端无兼容性差异，写法和 RN 原生完全一致

二、新手必备：3 种核心图片加载方式

这是本文的核心重点！RN 鸿蒙开发中，图片加载只有三种最常用的方式，没有多余复杂用法，新手按顺序掌握，从易到难，全部是极简可运行代码，复制即用，无需修改。

通用前置：所有 Image 组件，必须设置宽高样式，否则图片无法显示（新手第一大坑，重点记）

2.1 方式一：加载【本地静态图片】

本地图片指的是：放在我们 RN 鸿蒙项目内的图片文件（png/jpg/jpeg 等格式），比如项目的 logo、默认头像、本地配图等，是新手最先接触的加载方式。

核心用法

本地图片需要先导入再使用，语法：import 图片名 from '图片路径'
Image 组件通过 source={导入的图片名} 加载

完整可运行代码

import React from 'react';
import { View, Image, StyleSheet } from 'react-native';

// 导入本地图片 - 新手注意：路径写自己项目的实际图片路径即可
import logoImg from './images/logo.png';

const LocalImageDemo = () => {
  return (
    <View style={styles.container}>
      {/* 本地图片加载核心写法 */}
      <Image 
        source={logoImg} 
        style={styles.imgStyle} 
      />
    </View>
  );
};

// 样式 - 必写宽高！新手重点
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#f5f5f5'
  },
  imgStyle: {
    width: 150, // 图片宽度
    height: 150, // 图片高度
    margin: 10
  }
});

export default LocalImageDemo;

2.2 方式二：加载【网络远程图片】

网络图片指的是：存放在服务器上、有完整 http/https 网络地址的图片，比如商品图、banner 图、用户头像（后端返回）等，是实际项目中使用最多的加载方式，新手必须吃透！

核心用法

无需导入，直接通过 source={{ uri: '图片的网络地址' }} 加载
鸿蒙端特别注意：必须给 Image 设置宽高，无宽高必不显示
网络地址必须是完整的，以 http/https 开头

import React from 'react';
import { View, Image, StyleSheet } from 'react-native';

const NetImageDemo = () => {
  return (
    <View style={styles.container}>
      {/* 网络图片加载核心写法 - 复制即用 */}
      <Image
        source={{ uri: 'https://img1.baidu.com/it/u=3802229236,3867673209&fm=253&fmt=auto&app=138&f=JPEG?w=500&h=500' }}
        style={styles.netImgStyle}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#f5f5f5'
  },
  netImgStyle: {
    width: 200,
    height: 200,
    borderRadius: 10 // 圆角样式，新手入门必学
  }
});

export default NetImageDemo;

2.3 方式三：加载【鸿蒙项目资源图片】（鸿蒙专属，适配必学）

这是 RN 鸿蒙跨平台开发的专属用法，加载的是鸿蒙原生项目内的资源图片（放在 DevEco Studio 的 resources 目录），适合做鸿蒙端的专属适配，用法简单，新手只需了解并会用即可。

核心用法

直接通过 source={{ uri: '鸿蒙资源图片名' }} 加载，无需写完整路径，RN 鸿蒙框架会自动匹配鸿蒙原生资源。

<Image
  source={{ uri: 'ic_harmony_logo' }}
  style={{ width: 180, height: 180 }}
/>

三、Image 核心属性

为新手量身整理，只保留高频、必用、零基础能看懂的属性 + 样式，剔除所有进阶、冷门、无用的配置项，鸿蒙端完美适配，无兼容性问题，建议新手收藏对照，这是开发中最常用的「速查手册」。

区分说明：属性是 Image 组件的独立配置，样式是写在 style 里的样式配置，新手不用纠结区别，会用即可。

类型	名称	取值 / 写法	核心说明	鸿蒙适配注意点
核心属性	source	本地：{导入的图片名} 网络：{{uri:' 图片地址 '}}	图片加载的「数据源」，必写属性	鸿蒙无差异，写法完全一致
核心属性	resizeMode	cover / contain / stretch / center	图片的「拉伸 / 裁剪 / 居中」模式，新手必学	鸿蒙端完美兼容，无显示差异
基础属性	onLoad	() => {}	图片「加载成功」时触发的回调	可做加载完成提示，极简好用
基础属性	onError	() => {}	图片「加载失败」时触发的回调	网络图片加载失败必用，新手入门必备
基础属性	fadeDuration	数字（如：300）	图片加载完成的「渐入动画时长」(ms)	鸿蒙端支持，默认无动画
核心样式	width	数字（如：100）	图片宽度，必须设置	鸿蒙端单位为 px，无需转换
核心样式	height	数字（如：100）	图片高度，必须设置	同上，无单位，直接写数字
常用样式	borderRadius	数字（如：8）	图片圆角，开发高频使用	圆角值越大，图片越圆润
常用样式	borderWidth	数字（如：1）	图片边框宽度	配合 borderColor 使用
常用样式	borderColor	色值（如：#ccc）	图片边框颜色	鸿蒙端支持所有 css 色值
常用样式	backgroundColor	色值	图片加载前的占位背景色	解决网络图片加载慢的留白问题

resizeMode 四种取值详解

这是 Image 组件最重要的一个属性，新手 90% 的图片变形问题，都是因为没用对这个属性，4 个取值全部是基础用法，无进阶，记牢即可：

resizeMode='cover' 【开发最常用】：保持图片比例，填满容器，超出部分裁剪，不变形
resizeMode='contain'：保持图片比例，完整显示图片，容器留白，不变形
resizeMode='stretch'：不保持比例，拉伸填满容器，图片会变形，尽量少用
resizeMode='center'：图片居中显示，不拉伸不裁剪，容器留白

四、Image 基础综合示例

import React from 'react';
import { View, Image, StyleSheet, Text } from 'react-native';

const ImageAllDemo = () => {
  const localImg = require('./images/avatar.png');

  // 图片加载成功回调
  const imgLoadSuccess = () => {
    console.log('图片加载完成啦～');
  }
  // 图片加载失败回调
  const imgLoadError = () => {
    console.log('图片加载失败了');
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>本地图片展示</Text>
      <Image 
        source={localImg} 
        style={styles.imgItem}
        resizeMode='cover'
      />

      <Text style={styles.title}>网络图片展示</Text>
      <Image
        source={{ uri: 'https://b0.bdstatic.com/ugc/personal_page_creator/XhX0eZQTnozuXvK9fn8yxg54506daa3b81bbfe357836109b11e3f4.jpg' }}
        style={styles.imgItem}
        resizeMode='cover'
        onLoad={imgLoadSuccess}
        onError={imgLoadError}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 20,
    backgroundColor: '#f5f5f5'
  },
  title: {
    fontSize: 16,
    margin: 10,
    color: '#333'
  },
  imgItem: {
    width: 180,
    height: 180,
    borderRadius: 90,
    marginBottom: 20
  }
});

export default ImageAllDemo;