# image

Component Type:UniImageElement

图片

# # Attributes

name type default description
src string.ImageURIString - 图片资源地址
mode string scaleToFill 图片裁剪、缩放的模式 mode
fade-show boolean false 图片显示动画效果
@error (event: ImageErrorEvent) => void - 图片加载错误时触发,event.detail = { errMsg }
@load (event: ImageLoadEvent) => void - 图片加载完成时触发,event.detail = { width: '图片宽度px', height: '图片高度px' }

# # mode

name description
scaleToFill 不保持纵横比缩放图片,使图片的宽高完全拉伸至填满 image 元素
aspectFit 保持纵横比缩放图片,使图片的长边能完全显示出来。也就是说,可以完整地将图片显示出来。
aspectFill 保持纵横比缩放图片,只保证图片的短边能完全显示出来。也就是说,图片通常只在水平或垂直方向是完整的,另一个方向将会发生截取
widthFix 宽度不变,高度自动变化,保持原图宽高比不变
heightFix 高度不变,宽度自动变化,保持原图宽高比不变
top 不缩放图片,只显示图片的顶部区域
bottom 不缩放图片,只显示图片的底部区域
center 不缩放图片,只显示图片的中间区域
left 不缩放图片,只显示图片的左边区域
right 不缩放图片,只显示图片的右边区域
top left 不缩放图片,只显示图片的左上边区域
top right 不缩放图片,只显示图片的右上边区域
bottom left 不缩放图片,只显示图片的左下边区域
bottom right 不缩放图片,只显示图片的右下边区域

# # Event

# # ImageErrorEvent

# # ImageErrorEvent Values
name type required default description
detail ImageErrorEventDetail YES - -
type string YES - 事件类型
target Element YES - 触发事件的组件
currentTarget Element YES - 当前组件
timeStamp number YES - 事件发生时的时间戳
# # ImageErrorEventDetail Values
name type optinal default description
errMsg string YES - 错误信息
# # ImageErrorEvent Methods
name type required default description
stopPropagation () => void YES - 阻止当前事件的进一步传播
preventDefault () => void YES - 阻止当前事件的默认行为

# # ImageLoadEvent

# # ImageLoadEvent Values
name type required default description
detail ImageLoadEventDetail YES - -
type string YES - 事件类型
target Element YES - 触发事件的组件
currentTarget Element YES - 当前组件
timeStamp number YES - 事件发生时的时间戳
# # ImageLoadEventDetail Values
name type optinal default description
width number YES - 图片宽度
height number YES - 图片高度
# # ImageLoadEvent Methods
name type required default description
stopPropagation () => void YES - 阻止当前事件的进一步传播
preventDefault () => void YES - 阻止当前事件的默认行为

# 图片格式

  • bmp
  • gif
  • ico
  • jpg
  • png
  • webp
  • heic(Android10+支持)

如需其他图片格式,可自行开发uts组件插件或搜索插件市场,如

# src路径支持说明

  • 本地路径/static方式

    由于uni-app编译时,只把/static目录下的静态资源copy到app中,所以src均需指向/static目录下。

    其他目录的图片由于不会被打包进去,所以无法访问。

    本地路径的大小写,在真机运行时由于运行在sd卡上所以不敏感,但在打包后整合到apk中由于Android系统的要求是大小写敏感的。

  • 本地绝对路径file:///方式

    形如file:///storage/emulated/0/Android/data/io.dcloud.uniappx/apps/__UNI__4517034/www/static/test-image/logo.png

    访问本应用内的资源时无需使用本方式,推荐使用/static方式。上述地址受包名、appid影响。

    file:///方式一般用于download等公共目录。使用前需确保拥有相关权限。

  • 支持网络路径

    支持http、https。

    image组件内部使用facebook的fresco库(2.5.0),自带缓存策略,也会自动清理缓存。

# # Example

hello uni-app x

<template>
   <view>
   	<page-head :title="title"></page-head>
   	<view class="uni-padding-wrap uni-common-mt">
   		<view class="uni-center" style="background:#FFFFFF;">
   			<image class="image" :fade-show="true" mode="widthFix" :src="imageSrc" @error="error"
   				@load="load"></image>
   		</view>
   		<view class="uni-btn-v">
   			<button type="primary" @tap="imageFormat">图片格式示例</button>
   		</view>
   		<view class="uni-btn-v">
   			<button type="primary" @tap="imageMode">图片缩放模式示例</button>
   		</view>
   		<view class="uni-btn-v">
   			<button type="primary" @tap="imagePath">图片路径示例</button>
   		</view>
   		<view class="uni-btn-v">
   			<button type="primary" @tap="imageLarge">大图示例</button>
   		</view>
   	</view>
   </view>
</template>
<script>
   export default {
   	data() {
   		return {
   			title: 'image',
   			imageSrc: "/static/test-image/logo.png",
   			loadError: false
   		}
   	},
   	methods: {
   		error(event : ImageErrorEvent) {
   			this.loadError = true
   			console.log(event.type, event.detail);
   		},
   		load(event : ImageLoadEvent) {
   			console.log(event.type, event.detail);
   		},
   		imageFormat() {
   			uni.navigateTo({
   				url: '/pages/component/image/image-format'
   			});
   		},
   		imageMode() {
   			uni.navigateTo({
   				url: '/pages/component/image/image-mode'
   			});
   		},
   		imagePath() {
   			uni.navigateTo({
   				url: '/pages/component/image/image-path'
   			});
   		},
   		imageLarge() {
   			uni.navigateTo({
   				url: '/pages/component/image/image-large'
   			});
   		}
   	}
   }
</script>
<style>
   .image {
   	margin: 40rpx auto;
   	width: 200rpx;
   }
</style>

# # Compatibility

Android version Android uni-app Android uni-app-x iOS version iOS uni-app iOS uni-app-x
image 5.0 3.9+ 9.0 -
src 5.0 3.9+ 9.0 x
mode 5.0 3.9+ 9.0 x
fade-show 5.0 3.9+ 9.0 x x

# # Children Components

Can't nest components

# # See also

# tips

  • 在error事件里监听报错,并重新设置image组件的src,可实现自定义错误图。详见示例代码
  • 图片文件需在static目录(项目下或uni_modules下都支持static目录)下,或者import导入文件,否则文件不会被copy到最终的包中,导致无法访问。