图片组件

image 组件是 Uniapp 中用于展示图片的基础组件，支持多种图片格式及显示模式，适用于在页面中展示静态图片、网络图片或本地资源图片。它提供了丰富的属性，帮助开发者控制图片的加载、显示效果、裁剪模式等功能。

1. 什么是 image 组件？

image 组件用于在页面中显示图片，支持本地图片、网络图片以及 Base64 编码的图片资源。通过该组件，开发者可以方便地控制图片的尺寸、缩放、裁剪、懒加载等功能。此外，它还提供了错误处理和加载完成的事件，用于增强图片的交互体验。

使用场景

• 展示产品图片：在电商应用中，用于展示商品的图片信息。
• 轮播图：结合 swiper 组件，用于展示轮播图片或广告图片。
• 用户头像：在个人中心或聊天应用中，展示用户的头像。
• 图片加载占位：在图片加载时使用占位图，提升页面加载体验。

2. image 组件的常用属性

image 组件提供了多种属性，用于控制图片的资源、显示模式、懒加载等。以下是常用属性的详细说明及使用示例。

属性名	类型	默认值	说明	平台差异说明
src	String	无	图片资源的地址，支持本地路径、网络路径和 Base64 编码	无
mode	String	scaleToFill	图片的裁剪、缩放模式	无
lazy-load	Boolean	false	是否开启懒加载功能，只在 page 或 scroll-view 下有效	部分平台支持
webp	Boolean	false	是否在不支持 webp 格式的设备上单独启用 webp 图片格式	微信小程序 2.9.0+ 支持
draggable	Boolean	true	是否允许图片拖动	H5 3.1.1+，App(iOS 15+ 支持)
@error	EventHandle	无	当图片加载失败时触发	无
@load	EventHandle	无	当图片加载完成时触发，返回图片的宽度和高度	无

2.1 图片资源 src

• 说明：指定要显示的图片资源路径，支持本地路径、网络路径或 Base64 编码的图片资源。
• 类型：String
• 默认值：无

<template>
  <view>
    <!-- 显示网络图片 -->
    <image :src="imageSrc" style="width: 100%; height: 200px;" />
  </view>
</template>

<script setup>
const imageSrc = 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/shuijiao.jpg';
</script>

2.2 图片裁剪与缩放模式 mode

• 说明：指定图片的裁剪或缩放模式，共有 14 种模式，具体模式详见下表。
• 类型：String
• 默认值：scaleToFill

模式	值	说明
缩放	scaleToFill	不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素
缩放	aspectFit	保持纵横比缩放图片，使图片的长边能完全显示出来
缩放	aspectFill	保持纵横比缩放图片，只保证图片的短边能完全显示出来
缩放	widthFix	宽度不变，高度自动变化，保持原图宽高比不变
缩放	heightFix	高度不变，宽度自动变化，保持原图宽高比不变
裁剪	top	不缩放图片，只显示图片的顶部区域
裁剪	bottom	不缩放图片，只显示图片的底部区域
裁剪	center	不缩放图片，只显示图片的中间区域
裁剪	left	不缩放图片，只显示图片的左边区域
裁剪	right	不缩放图片，只显示图片的右边区域
裁剪	top left	不缩放图片，只显示图片的左上边区域
裁剪	top right	不缩放图片，只显示图片的右上边区域
裁剪	bottom left	不缩放图片，只显示图片的左下边区域
裁剪	bottom right	不缩放图片，只显示图片的右下边区域

<template>
  <view>
    <!-- 使用 aspectFill 模式 -->
    <image :src="imageSrc" mode="aspectFill" style="width: 100%; height: 200px;" />
  </view>
</template>

<script setup>
const imageSrc = 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/shuijiao.jpg';
</script>

2.3 图片懒加载 lazy-load

• 说明：是否启用图片懒加载功能，适用于长页面或 scroll-view 中的图片。
• 类型：Boolean
• 默认值：false

<template>
  <view>
    <!-- 开启懒加载 -->
    <image :src="imageSrc" :lazy-load="true" style="width: 100%; height: 200px;" />
  </view>
</template>

<script setup>
const imageSrc = 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/shuijiao.jpg';
</script>

2.4 图片加载错误处理 @error

• 说明：当图片加载失败时触发 @error 事件，可以在事件回调中处理加载失败逻辑，例如显示占位图。
• 类型：EventHandle

<template>
  <view>
    <!-- 监听图片加载错误 -->
    <image :src="imageSrc" @error="handleImageError" style="width: 100%; height: 200px;" />
  </view>
</template>

<script setup>
import { ref } from 'vue';

const imageSrc = ref('https://invalid-url.com/invalid.jpg');

const handleImageError = () => {
  console.log('图片加载失败，显示占位图');
  imageSrc.value = '/static/placeholder.png';
};
</script>

3. 多种裁剪与缩放模式展示

以下案例展示了 image 组件的多种 mode 模式，包括裁剪和缩放模式。通过不同的 mode 设置，可以实现多种图片显示效果。

<template>
  <view class="image-list">
    <view class="image-item" v-for="(item, index) in modes" :key="index">
      <view class="image-content">
        <image :src="imageSrc" :mode="item.mode" style="width: 200px; height: 200px; background-color: #eeeeee;" />
      </view>
      <view class="image-title">{{ item.text }}</view>
    </view>
  </view>
</template>

<script setup>
const imageSrc = 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/shuijiao.jpg';

const modes = [
  { mode: 'scaleToFill', text: 'scaleToFill：不保持纵横比缩放图片，使图片完全适应' },
  { mode: 'aspectFit', text: 'aspectFit：保持纵横比缩放图片，使图片的长边能完全显示出来' },
  { mode: 'aspectFill', text: 'aspectFill：保持纵横比缩放图片，只保证图片的短边能完全显示出来' },
  { mode: 'top', text: 'top：不缩放图片，只显示图片的顶部区域' },
  { mode: 'bottom', text: 'bottom：不缩放图片，只显示图片的底部区域' },
  { mode: 'center', text: 'center：不缩放图片，只显示图片的中间区域' },
  { mode: 'left', text: 'left：不缩放图片，只显示图片的左边区域' },
  { mode: 'right', text: 'right：不缩放图片，只显示图片的右边边区域' },
];
</script>

<style scoped>
.image-list {
  display: flex;
  flex-wrap: wrap;
}

.image-item {
  margin: 10px;
  text-align: center;
}

.image-content {
  margin-bottom: 5px;
}

.image-title {
  font-size: 14px;
  color: #333;
}
</style>