Image 图片 ¶

此组件为 uni-app 的image组件的加强版，在继承了原有功能外，还支持淡入动画、加载中、加载失败提示、圆角值和形状等。
我们推荐您在任何使用图片场景的地方，都优先考虑使用这个小巧，精致而实用的组件。

注意：

由于在nvue下，u-image名称被 uni-app 官方占用，在nvue页面中请使用up-image名称，在vue页面中使用up-image或者up-image均可。

平台差异说明 ¶

App（vue）	App（nvue）	H5	小程序
√	√	√	√

基本使用 ¶

配置图片的width宽和height高，以及src路径即可使用。

html

<template>
  <up-image
    :showLoading="true"
    :src="src"
    width="80px"
    height="80px"
    @click="click"
  ></up-image>
</template>

<script>
  export default {
    data() {
      return {
        src: "https://xxx.com/album/1.jpg",
      };
    },
  };
</script>

裁剪模式 ¶

通过mode参数配置填充模式，此模式用法与 uni-app 的image组件的mode参数完全一致，详见：Image

html

<up-image src="https://xxx.com/album/1.jpg" mode="widthFix"></up-image>

图片形状 ¶

通过shape参数设置图片的形状，circle为圆形，square为方形
如果为方形时，还可以通过radius属性设置圆角值

html

<up-image src="https://xxx.com/album/1.jpg" shape="circle"></up-image>

懒加载 ¶

注意：此功能只对微信小程序、App、百度小程序、字节跳动小程序有效，默认开启。

html

<up-image src="https://xxx.com/album/1.jpg" :lazy-load="true"></up-image>

加载中提示 ¶

图片加载过程中，为加载中状态(默认显示一个小图标)，可以通过loading自定义插槽，结合 uView 的u-loading组件，实现加载的动画效果。

html

<up-image src="https://xxx.com/album/1.jpg">
  <template v-slot:loading>
    <up-loading-icon color="red"></up-loading-icon>
  </template>
</up-image>

加载错误提示 ¶

图片加载失败时，默认显示一个错误提示图标，可以通过error自定义插槽，实现个性化的提示方式。

html

<up-image src="https://xxx.com/album/1.jpg">
  <view slot="error" style="font-size: 24rpx;">加载失败</view>
</up-image>

淡入动画 ¶

组件自带了加载完成时的淡入动画效果：

通过fade参数配置是否开启动画效果
通过duration参数配置动画的过渡时间，单位 ms

html

<up-image
  src="https://xxx.com/album/1.jpg"
  :fade="true"
  duration="450"
></up-image>

事件冒泡 ¶

默认情况下，组件是允许内部向外事件冒泡的，因为很多情况下，我们都希望点击图片，同时图片所在的父元素的点击事件也能触发。
如果您想避免事件冒泡，那么您可以在组件外面嵌套一个view，同时给它加上@tap.stop即可。

html

<!-- 点击图片将不会触发clickHandler -->
<view @tap="clickHandler">
  <view @tap.stop>
    <up-image src="https://xxx.com/album/1.jpg"></up-image>
  </view>
</view>

此页面源代码地址 ¶

页面源码地址

github

gitee

API ¶

Props ¶

参数	说明	类型	默认值	可选值
src	图片地址，强烈建议使用绝对或者网络路径	String	-	-
mode	裁剪模式，见上方说明	String	aspectFill	-
width	宽度，单位任意，如果为数值，默认单位 px	String \| Number	300	-
height	高度，单位任意，如果为数值，默认单位 px	String \| Number	225	-
shape	图片形状，circle-圆形，square-方形	String	square	square
radius	圆角，默认单位 px	String \| Number	0	-
lazyLoad	是否懒加载，仅微信小程序、App、百度小程序、字节跳动小程序有效	Boolean	true	-
showMenuByLongpress	是否开启长按图片显示识别小程序码菜单，仅微信小程序有效	Boolean	true	-
loadingIcon	加载中的图标，或者小图片	String	photo	-
errorIcon	加载失败的图标，或者小图片	String	error-circle	-
showLoading	是否显示加载中的图标或者自定义的 slot	Boolean	true	false
showError	是否显示加载错误的图标或者自定义的 slot	Boolean	true	false
fade	是否需要淡入效果	Boolean	true	false
webp	只支持网络资源，只对微信小程序有效	Boolean	false	true
duration	搭配`fade`参数的过渡时间，单位 ms	String \| Number	500	-
bgColor	背景颜色，用于深色页面加载图片时，为了和背景色融合	String	#f3f4f6	-

Slot ¶

名称	说明
loading	自定义加载中的提示内容
error	自定义失败的提示内容

CellItem Events ¶

事件名	说明	回调参数
click	点击图片时触发	-
error	图片加载失败时触发	err: 错误信息
load	图片加载成功时触发	-