微信小程序 image 组件 14 种显示模式详解与实战

一、前言

在微信小程序开发中，image组件是最常用的组件之一，用于展示图片。与 HTML 中的<img>标签不同，小程序的image组件提供了丰富的显示模式（mode属性），可以控制图片的缩放和裁剪方式。本文将通过一个完整的案例，详细演示image组件的14 种显示模式，并通过列表渲染wx:for将所有模式一目了然地展示出来。

二、image 组件简介

image组件默认宽度为 320px、高度为 240px，其核心属性是mode，用于指定图片的裁剪和缩放模式。mode的有效值共有 14 种，分为两大类：

• 缩放模式（5 种）：scaleToFill、aspectFit、aspectFill、widthFix、heightFix
• 裁剪模式（9 种）：top、bottom、center、left、right、top left、top right、bottom left、bottom right

注意：裁剪模式（top、bottom 等）仅在 Webview 渲染引擎下支持，因此需要在app.json中将"renderer"设置为"webview"。

三、项目搭建

3.1 新建项目

新建一个不使用云服务、不使用模板的小程序项目。

3.2 修改 app.json

将渲染引擎改为webview，以支持裁剪模式：

{"pages":["pages/index/index"],"window":{"navigationBarTextStyle":"black","navigationStyle":"custom"},"renderer":"webview","style":"v2","sitemapLocation":"sitemap.json"}

3.3 准备图片

在项目根目录新建images文件夹，放入一张用于测试的图片（如daxinganling.jpg）。

四、核心代码实现

4.1 页面结构 index.wxml

使用自定义导航栏组件navigation-bar，通过scroll-view实现可滚动区域，利用wx:for遍历图片模式数组：

<!--index.wxml--><navigation-bartitle="image组件"back="{{false}}"color="black"background="#FFF"></navigation-bar><scroll-viewclass="scrollarea"scroll-ytype="list"><viewclass="box"><viewclass="title">图片的不同显示模式</view><blockwx:for="{{imgArray}}"><viewclass="mode-no">显示模式编号：{{index + 1}}</view><viewclass="mode-text">{{item.text}}</view><viewclass="img-layout"><imagesrc="{{src}}"mode="{{item.mode}}"/></view></block></view></scroll-view>

代码说明：

• wx:for="{{imgArray}}"：列表渲染，遍历模式数组
• {{item.text}}：绑定图片的说明文字
• {{src}}：绑定图片地址
• {{item.mode}}：绑定图片的显示模式
• {{index + 1}}：列表渲染的索引（从 0 开始），加 1 后作为显示模式的编号

4.2 页面逻辑 index.js

在data中定义图片路径src和模式数组imgArray，数组中每一项包含mode（显示模式）和text（模式说明）：

Page({data:{src:'/images/daxinganling.jpg',imgArray:[{mode:'scaleToFill',text:'scaleToFill: 缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素'},{mode:'aspectFit',text:'aspectFit: 缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来'},{mode:'aspectFill',text:'aspectFill: 缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取'},{mode:'widthFix',text:'widthFix: 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变'},{mode:'heightFix',text:'heightFix: 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变'},{mode:'top',text:'top: 裁剪模式，不缩放图片，只显示图片的顶部区域。仅 Webview 支持'},{mode:'bottom',text:'bottom: 裁剪模式，不缩放图片，只显示图片的底部区域。仅 Webview 支持'},{mode:'center',text:'center: 裁剪模式，不缩放图片，只显示图片的中间区域。仅 Webview 支持'},{mode:'left',text:'left: 裁剪模式，不缩放图片，只显示图片的左边区域。仅 Webview 支持'},{mode:'right',text:'right: 裁剪模式，不缩放图片，只显示图片的右边区域。仅 Webview 支持'},{mode:'top left',text:'top left: 裁剪模式，不缩放图片，只显示图片的左上边区域。仅 Webview 支持'},{mode:'top right',text:'top right: 裁剪模式，不缩放图片，只显示图片的右上边区域。仅 Webview 支持'},{mode:'bottom left',text:'bottom left: 裁剪模式，不缩放图片，只显示图片的左下边区域。仅 Webview 支持'},{mode:'bottom right',text:'bottom right: 裁剪模式，不缩放图片，只显示图片的右下边区域。仅 Webview 支持'}]}})

4.3 页面样式 index.wxss

page{height:100vh;display:flex;flex-direction:column;}.scrollarea{flex:1;overflow-y:hidden;}.img-layout{text-align:center;margin-top:20rpx;margin-bottom:40rpx;}image{width:480rpx;height:480rpx;background-color:#eee;}.mode-no{font-size:28rpx;color:#333;margin-top:20rpx;font-weight:bold;}.mode-text{font-size:28rpx;color:#333;margin-top:10rpx;line-height:1.5;}

4.4 全局样式 app.wxss

.box{margin:20rpx;padding:20rpx;border:2rpx solid silver;}.title{font-size:40rpx;font-weight:bolder;text-align:center;margin-bottom:30rpx;color:red;}

五、功能扩充：添加显示模式编号

在基本功能的基础上，为了更清晰地标识每一种显示模式，在文字说明上方增加了图片显示模式的编号。利用wx:for自带的索引变量index（从 0 开始），通过{{index + 1}}即可显示从 1 开始的编号：

<viewclass="mode-no">显示模式编号：{{index + 1}}</view><viewclass="mode-text">{{item.text}}</view>

效果如下：

显示模式编号：1 scaleToFill: 缩放模式，不保持纵横比缩放图片... [图片] 显示模式编号：2 aspectFit: 缩放模式，保持纵横比缩放图片... [图片] ...

六、14 种显示模式效果对比

七、总结

通过本案例，我们学习了：

1. image 组件的 14 种显示模式：5 种缩放模式 + 9 种裁剪模式，掌握了每种模式的适用场景。
2. 列表渲染 wx:for：通过遍历数组高效地渲染重复结构，避免冗余代码。
3. 数据绑定：使用{{}}语法将src、mode、text等数据动态绑定到视图。
4. 自定义导航栏：通过自定义navigation-bar组件实现个性化导航栏。
5. 渲染引擎配置：裁剪模式需要webview渲染引擎支持，需在app.json中配置。
6. scroll-view 滚动：使用scroll-view组件实现页面区域的滚动。

image组件的显示模式是小程序开发中的基础知识，合理选择显示模式可以让图片在不同尺寸的容器中呈现最佳效果。希望本文能帮助你更好地理解和运用image组件。