image | uni-app-x

展示全部

# image

组件类型：UniImageElement

图片

# 兼容性

Web	Android	iOS
4.0	3.9	4.11

# 属性

名称

类型

默认值

兼容性

描述

src

string(string.ImageURIString)

图片资源地址

mode

string

"scaleToFill"

图片裁剪、缩放的模式

合法值

兼容性

描述

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

图片显示动画效果

webp

boolean

true

是否支持 webP 格式

show-menu-by-longpress

boolean

false

开启长按图片显示识别小程序码菜单

draggable

boolean

false

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

@error

(event: UniImageErrorEvent) => void

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

@load

(event: UniImageLoadEvent) => void

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

# 事件

# UniImageErrorEvent

# UniImageErrorEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniImageErrorEventDetail

是

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

# UniImageLoadEvent

# UniImageLoadEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniImageLoadEventDetail

是

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

# 图片格式

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

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

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

注意：webp在不同小程序平台策略不同，有的需要打开 webp 属性，有的仅支持来自服务器的webp。

# src路径支持说明

本地路径/static方式
由于uni-app/uni-app x编译时，只把/static目录下的静态资源copy到app中，所以src均需指向/static目录下。
其他目录的图片由于不会被打包进去，所以无法访问。
app平台文件路径会存在大小写敏感问题，为了有更好的兼容性，建议统一按大小写敏感原则处理详情
本地绝对路径file:///方式
app-android平台形如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天缓存，缓存过期后会自动清理。

# 子组件

不可以嵌套组件

# 示例

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>

# 参见

# tips

image组件默认宽度为320px、高度为240px
在error事件里监听报错，并重新设置image组件的src，可实现自定义错误图。详见示例代码
图片文件需在static目录（项目下或uni_modules下都支持static目录）下，或者import导入文件，否则文件不会被copy到最终的包中，导致无法访问
app-android平台由于默认启用了图片缩放（即根据组件实际宽高加载图片，以节省内存），所以可能导致load事件返回的图片尺寸并非图片原始尺寸
app-ios平台 iOS14 版本开始系统原生支持 WebP 图片格式，iOS14以下的版本使用三方解码器软解码实现对 WebP 的支持，性能存在一定损耗。如果在iOS14以下同一页面中大量使用WebP图片，会增加性能损耗
app-android平台不支持CMYK色彩的图片，详见