Appearance
image
图片组件。
| 属性名 | 类型 | 默认值 | 说明 | 平台差异说明 |
|---|---|---|---|---|
| src | String | 图片资源地址 | ||
| mode | String | 'scaleToFill' | 图片裁剪、缩放的模式 | <div style="width:68px;"></div> |
| lazy-load | Boolean | false | 图片懒加载。只针对 page 与 scroll-view 下的 image 有效 | 微信小程序、抖音小程序 |
| webp | boolean | false | 在系统不支持 webp 的情况下是否单独启用 webp 。默认 false ，只支持网络资源。webp支持详见下面说明 | 微信小程序2.9.0 |
| show-menu-by-longpress | boolean | false | 开启长按图片显示识别小程序码菜单 | 微信小程序 2.7.0 |
| draggable | boolean | true | 是否能拖动图片 | H5 |
| @error | HandleEvent | 当错误发生时，发布到 AppService 的事件名，事件对象 event.detail = {errMsg: 'something wrong'} | ||
| @load | HandleEvent | 当图片载入完毕时，发布到 AppService 的事件名，事件对象 event.detail = {height:'图片高度px', width:'图片宽度px'} |
图片格式说明：
- 当使用浏览器
/webview渲染时，支持哪些图片格式由 webview 决定，详见 - 小程序上只支持网络地址的 svg 图
- webp图片支持详解
- Android4 以上（含）、 iOS14 以上（含）系统内置支持webp，此时，不管 h5 还是小程序都可以直接使用webp；
- 微信小程序 2.9.0 起，配置属性webp为true时iOS支持；
- pc浏览器上， webp 在不同浏览器的支持详见
Tips
<image>组件未设置宽高时，默认宽度 320px 、高度 240px 。尤其注意当图片加载失败时，widthFix模式指定宽度的图片，虽然图片空白，但其高度会变成 240px ；src仅支持相对路径、绝对路径，支持 base64 码；- 页面结构复杂，css样式太多的情况，使用 image 可能导致样式生效较慢，出现 “闪一下” 的情况，此时设置
image{will-change: transform}，可优化此问题。 - 自定义组件里面使用
<image>时，若src使用相对路径可能出现路径查找失败的情况，故建议使用绝对路径。
mode 有效值
mode 有 14 种模式，其中 5 种是缩放模式，9 种是裁剪模式。
| 模式 | 值 | 说明 |
|---|---|---|
| 缩放 | scaleToFill | 不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素 |
| 缩放 | aspectFit | 保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。 |
| 缩放 | aspectFill | 保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。 |
| 缩放 | widthFix | 宽度不变，高度自动变化，保持原图宽高比不变 |
| 缩放 | heightFix | 高度不变，宽度自动变化，保持原图宽高比不变 微信小程序需要基础库 2.10.3 |
| 裁剪 | top | 不缩放图片，只显示图片的顶部区域 |
| 裁剪 | bottom | 不缩放图片，只显示图片的底部区域 |
| 裁剪 | center | 不缩放图片，只显示图片的中间区域 |
| 裁剪 | left | 不缩放图片，只显示图片的左边区域 |
| 裁剪 | right | 不缩放图片，只显示图片的右边区域 |
| 裁剪 | top left | 不缩放图片，只显示图片的左上边区域 |
| 裁剪 | top right | 不缩放图片，只显示图片的右上边区域 |
| 裁剪 | bottom left | 不缩放图片，只显示图片的左下边区域 |
| 裁剪 | bottom right | 不缩放图片，只显示图片的右下边区域 |
示例
vue
<template>
<view class="page">
<view class="image-list">
<view
class="image-item"
v-for="(item,index) in theImages"
:key="index"
>
<view class="image-content">
<image
style="width: 200px; height: 200px; background-color: #eeeeee;"
:mode="item.mode"
:src="src"
@error="imageError"
/>
</view>
<view class="image-title">{{item.text}}</view>
</view>
</view>
</view>
</template><template>
<view class="page">
<view class="image-list">
<view
class="image-item"
v-for="(item,index) in theImages"
:key="index"
>
<view class="image-content">
<image
style="width: 200px; height: 200px; background-color: #eeeeee;"
:mode="item.mode"
:src="src"
@error="imageError"
/>
</view>
<view class="image-title">{{item.text}}</view>
</view>
</view>
</view>
</template>js
<script>
export default {
data() {
return {
theImages: [
{
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：不缩放图片，只显示图片的右边边区域',
},
{
mode: 'top left',
text: 'top left：不缩放图片，只显示图片的左上边区域',
},
{
mode: 'top right',
text: 'top right：不缩放图片，只显示图片的右上边区域',
},
{
mode: 'bottom left',
text: 'bottom left：不缩放图片，只显示图片的左下边区域',
},
{
mode: 'bottom right',
text: 'bottom right：不缩放图片，只显示图片的右下边区域',
},
],
src: 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/shuijiao.jpg',
};
},
methods: {
imageError: function(e) {
console.error('image发生error事件，携带值为' + e.detail.errMsg);
},
},
};
</script><script>
export default {
data() {
return {
theImages: [
{
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：不缩放图片，只显示图片的右边边区域',
},
{
mode: 'top left',
text: 'top left：不缩放图片，只显示图片的左上边区域',
},
{
mode: 'top right',
text: 'top right：不缩放图片，只显示图片的右上边区域',
},
{
mode: 'bottom left',
text: 'bottom left：不缩放图片，只显示图片的左下边区域',
},
{
mode: 'bottom right',
text: 'bottom right：不缩放图片，只显示图片的右下边区域',
},
],
src: 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/shuijiao.jpg',
};
},
methods: {
imageError: function(e) {
console.error('image发生error事件，携带值为' + e.detail.errMsg);
},
},
};
</script>原图
scaleToFill：不保持纵横比缩放图片，使图片完全适应
aspectFit：保持纵横比缩放图片，使图片的长边能完全显示出来
aspectFill：保持纵横比缩放图片，只保证图片的短边能完全显示出来
top：不缩放图片，只显示图片的顶部区域
bottom：不缩放图片，只显示图片的底部区域
center：不缩放图片，只显示图片的中间区域
left：不缩放图片，只显示图片的左边区域
right：不缩放图片，只显示图片的右边边区域
top left：不缩放图片，只显示图片的左上边区域
top right：不缩放图片，只显示图片的右上边区域
bottom left：不缩放图片，只显示图片的左下边区域
bottom right：不缩放图片，只显示图片的右下边区域
- 默认的图片加载失败，是空白。如需自定义，可监听error事件进行重定义，如下
vue
<template>
<!-- 当图片加载失败时，会触发error事件 -->
<image
src="https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/cat-12.png"
@error="imageErrorEvent"
/>
</template><template>
<!-- 当图片加载失败时，会触发error事件 -->
<image
src="https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/cat-12.png"
@error="imageErrorEvent"
/>
</template>js
<script>
export default {
methods: {
imageErrorEvent(e : ImageErrorEvent) { //本示例为uts，如使用js则无需通过冒号定义类型
console.log("图片加载错误", e.detail);
// 图片加载失败，加载本地占位图
// 本示例为uts，如使用js则无需加问号
e.target?.setAttribute('src', '/static/404.png');
},
},
};
</script><script>
export default {
methods: {
imageErrorEvent(e : ImageErrorEvent) { //本示例为uts，如使用js则无需通过冒号定义类型
console.log("图片加载错误", e.detail);
// 图片加载失败，加载本地占位图
// 本示例为uts，如使用js则无需加问号
e.target?.setAttribute('src', '/static/404.png');
},
},
};
</script>