image | uni-app-x

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

lazy-load

boolean

false

图片懒加载。只针对page与scroll-view下的image有效

fade-show

boolean

false

图片显示动画效果

draggable

boolean

false

鼠标长按是否能拖动图片(仅H5平台)

@error

(event: UniImageErrorEvent) => void

图片加载错误时触发，event.detail = { errMsg }

@load

(event: UniImageLoadEvent) => void

图片加载完成时触发，event.detail = { width: '图片宽度px', height: '图片高度px' }

# mode 兼容性

	Android	iOS	web
scaleToFill	3.9	4.11	4.0
aspectFit	3.9	4.11	4.0
aspectFill	3.9	4.11	4.0
widthFix	3.9	4.11	4.0
heightFix	3.9	4.11	4.0
top	3.9	4.11	4.0
bottom	3.9	4.11	4.0
center	3.9	4.11	4.0
left	3.9	4.11	4.0
right	3.9	4.11	4.0
top left	3.9	4.11	4.0
top right	3.9	4.11	4.0
bottom left	3.9	4.11	4.0
bottom right	3.9	4.11	4.0

# 事件

# UniImageErrorEvent

# UniImageErrorEvent 的属性值

名称

类型

必填

默认值

描述

detail

UniImageErrorEventDetail

是

名称	类型	必备	默认值	描述
errMsg	string	是	-	错误信息

bubbles

boolean

是

是否冒泡

cancelable

boolean

是

是否可以取消

type

string

是

事件类型

target

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

currentTarget

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

timeStamp

number

是

事件发生时的时间戳

# UniImageErrorEvent 的方法

名称	类型	必填	默认值	描述
stopPropagation	() => void	是	-	阻止当前事件的进一步传播
preventDefault	() => void	是	-	阻止当前事件的默认行为

# UniImageLoadEvent

# UniImageLoadEvent 的属性值

名称

类型

必填

默认值

描述

detail

UniImageLoadEventDetail

是

名称	类型	必备	默认值	描述
width	number	是	-	图片宽度
height	number	是	-	图片高度

bubbles

boolean

是

是否冒泡

cancelable

boolean

是

是否可以取消

type

string

是

事件类型

target

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

currentTarget

UniElement | null

否

UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。

timeStamp

number

是

事件发生时的时间戳

# UniImageLoadEvent 的方法

名称	类型	必填	默认值	描述
stopPropagation	() => void	是	-	阻止当前事件的进一步传播
preventDefault	() => void	是	-	阻止当前事件的默认行为

# 图片格式

web端支持的图片格式，不同浏览器有差异，可查询caniuse。

app端支持的图片格式如下：

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

# src路径支持说明

本地路径/static方式

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

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

本地路径的大小写，安卓端在真机运行时由于运行在sd卡上所以不敏感，但在打包后整合到apk中由于Android系统的要求是大小写敏感的。iOS端始终是大小写敏感的。
本地绝对路径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)，自带缓存策略，也会自动清理缓存。 iOS端image组件内部使用SDWebImage库(5.10.0)，自带缓存策略，默认7天缓存，缓存过期后会自动清理。

# image 属性兼容性

	Android	iOS	web
src	3.9	4.11	4.0
mode	3.9	4.11	4.0
lazy-load	x	4.11	x
fade-show	3.9	x	x
draggable	x	x	4.0
@error	3.9	4.11	4.0
@load	3.9	4.11	4.0

# App平台

App-Android平台由于默认启用了图片缩放（即根据组件实际宽高加载图片，以节省内存），所以可能导致load事件返回的图片尺寸并非图片原始尺寸。

# 子组件

不可以嵌套组件

# 示例

hello uni-app x

Template

Script

<template>
  <view style="flex: 1;">
    <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 v-if="autoTest">
      <image :src="setCookieImage"></image>
      <image :src="verifyCookieImage" @error="error"></image>
    </view>
  </view>
</template>

<style>
  .image {
    margin: 20px auto;
    width: 100px;
  }
</style>