一、image 组件基础image 是小程序的图片组件负责把一张图片按指定方式显示在页面里。它支持JPG、PNG、SVG、WEBP、GIF等格式从基础库 2.3.0 起也支持直接使用云文件 ID。它的用法非常简单只有一个必须关心的属性src和一个真正决定效果的属性mode。1.1 最简用法image src/images/helo.jpeg modeaspectFit/src支持本地路径和网络地址。本地路径有两种写法以/开头表示从项目根目录算起不以/开头则表示相对于当前文件。本项目用的是绝对写法/images/helo.jpeg这样无论文件被放在哪一层页面目录里都能正确找到图片。1.2 两个必须先知道的默认值项目默认值含义modescaleToFill不写 mode 时默认拉伸填满图片会变形组件尺寸320px × 240px不写样式时组件就是这个大小图片会被限制在里面这两个默认值一起造成了新手最常见的问题图片要么变形要么只显示一角。所以实际使用时既要显式设置宽高也要显式指定mode。1.3 src 与 mode 的关系src决定显示哪张图mode决定这张图如何塞进组件的框里。组件最终显示的尺寸是由 CSS 决定的mode只控制图片在框内的缩放与裁剪方式——理解这一点后面 14 种模式的差别就都能推出来了。二、两种模式缩放与裁剪14 个 mode 值分成两类这是理解它们的第一个分水岭类别数量是否改变图片大小渲染框架支持缩放模式5 个会缩放图片让它适应组件框Webview 与 Skyline 都支持裁剪模式9 个不缩放图片组件框当作取景窗口仅 Webview 支持2.1 五种缩放模式mode含义scaleToFill不保持纵横比把图片的宽高完全拉伸至填满组件会变形aspectFit保持纵横比让图片的长边完整显示整张图都能看到aspectFill保持纵横比只保证短边完整显示另一个方向会被裁掉widthFix宽度不变高度按原图比例自动变化基础库支持heightFix高度不变宽度按原图比例自动变化2.10.3 起支持2.2 九种裁剪模式mode含义取景位置top只显示图片顶部区域上中bottom只显示图片底部区域下中center只显示图片中间区域正中left只显示图片左边区域左中right只显示图片右边区域右中top left只显示左上区域左上角top right只显示右上区域右上角bottom left只显示左下区域左下角bottom right只显示右下区域右下角以上九个均为裁剪模式官方文档标注「仅 Webview 支持」。2.3 为什么本项目把渲染器改成了 webview这是整个项目里最关键的一处配置。因为九个裁剪模式只在Webview渲染器下生效而微信开发者工具新建项目时默认可能启用 Skyline所以作者在 app.json 里明确写了renderer: webview,如果不写这一行前 5 种缩放模式看起来正常后 9 种裁剪模式则不会按预期工作——这是学习这 14 种模式时最容易被绊住的地方。官方文档把这 9 个裁剪模式都标注为「仅 Webview 支持」也就是说在 Skyline 渲染器下它们不在支持范围内。需要用到这些模式时就要像本项目一样显式指定 renderer。三、本项目做了什么这个项目的思路很干净把一张图片用 14 种不同的mode各显示一次每张上面配上这个模式的说明文字方便一眼对比差别。3.1 目录结构image/ ├── app.js ├── app.json # 关键renderer 设为 webview ├── app.wxss ├── components │ └── navigation-bar │ ├── navigation-bar.js │ ├── navigation-bar.json │ ├── navigation-bar.wxml │ └── navigation-bar.wxss ├── images │ └── helo.jpeg # 被演示的图片1422 x 800 像素 ├── pages │ └── index │ ├── index.js # 14 种模式的数据 │ ├── index.json │ ├── index.wxml │ └── index.wxss # 固定 image 的宽高 ├── project.config.json ├── project.private.config.json └── sitemap.json3.2 页面数据index.js节选页面把所有模式放在一个数组里每项含mode和text两个字段Page({ data: { src:/images/helo.jpeg, imgArray:[{ mode:scaleToFill, text:scaleToFill缩放模式不保持纵横比缩放图片使图片的宽高完全拉伸至填满 image 元素 },{ mode:aspectFit, text:aspectFit缩放模式保持纵横比缩放图片使图片的长边能完全显示出来 },{ mode:aspectFill, text:aspectFill缩放模式保持纵横比缩放图片只保证图片的短边能完全显示出来 }, /* ……中间省略数组共 14 项完整清单见第四章的表格…… */ { mode: bottom right, text: bottom right裁剪模式不缩放图片只显示图片的右下边区域。仅 Webview 支持 } ] })为便于阅读此处省略了中间若干项数组实际共 14 项顺序与第二章表格一致。3.3 页面结构index.wxml!--index.wxml-- navigation-bar titleWeixin back{{false}} colorblack background#FFF/navigation-bar scroll-view classscrollarea scroll-y typelist view classbox view classtitle图片的不同显示模式/view block wx:for{{imgArray}} view显示模式编号{{index1}}/view view{{item.text}}/view view classimg-layout image src{{src}} mode{{item.mode}}/ /view /block /view /scroll-view这里有两个细节值得注意image的 src 是固定的只有mode跟着循环变量走——所以 14 张图其实是同一张图的不同显示方式。外层用block而不是view包循环block不会渲染成真实节点因此不会多出一层容器影响布局。3.4 页面样式index.wxsspage { 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: 400rpx; background-color: #eee; }这段样式做了两件重要的事把image固定成 480rpx × 400rpx给所有模式一个统一的对照框否则组件会用默认的 320px × 240px对照就没有意义了。给image加了background-color: #eee浅灰底。这看着不起眼却让aspectFit的留白一眼可见——这是个很实用的做法。3.5 全局样式app.wxss除了页面自身的样式项目还在app.wxss中定义了一些全局样式供所有页面共用。全局样式通常用来统一字体、间距、背景色等基础视觉规范避免在每个页面里重复书写相同的样式规则。这样既减少了冗余代码也让整个小程序的视觉风格保持一致。/**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; }四、用真实尺寸算一遍上面只是文字描述要真正理解这 14 种模式最有效的办法是拿本项目的真实数字算一次。4.1 两个关键比例对象尺寸宽高比原图 helo.jpeg1422 × 800 像素1422 ÷ 800 1.78组件框wxss 设定480rpx × 400rpx480 ÷ 400 1.20两个比例不相等1.78 比 1.20 更「扁长」所以图片比框更宽。这一个事实就决定了所有缩放模式的表现——这是本节的核心。补充750rpx 等于屏幕宽度。在 375px 宽的手机上480rpx 约等于 240px400rpx 约等于 200px。所以这个组件框实际只有 240 × 200 像素大小。4.2 五种缩放模式的推算结果mode实际显示尺寸怎么来的视觉效果scaleToFill480 × 400 rpx强制拉伸到框的大小变形。原比例 1.78 被压成 1.20图被压扁aspectFit480 × 270 rpx宽贴满480高 480 ÷ 1.78整图完整可见上下各留约 65rpx 灰底aspectFill711 × 400 rpx高贴满400宽 400 × 1.78撑满整个框左右各有约 115rpx 被裁掉widthFix480 × 270 rpx宽度保持 480高度自动算效果同 aspectFit但组件高度不再是 400heightFix711 × 400 rpx高度保持 400宽度自动算效果同 aspectFill但组件宽度超出 480尺寸按原图 1422×800 与组件框 480×400rpx 计算与官方对五种模式的描述一致。4.3 为什么只有 aspectFit 能看见灰底aspectFit是唯一一个让组件框比图片大的模式图片按宽度贴满后只有 270rpx 高而框有 400rpx 高多出来的 130rpx 就露出了background-color: #eee的浅灰底。其余四种模式的图片都会把框填满或撑破所以看不到灰底。反过来说如果你想确认一张图有没有被裁切加一句浅灰底色是最省事的办法。4.4 九种裁剪模式的实际效果裁剪模式与缩放模式有一个本质区别它不缩放图片。图片按原始尺寸渲染组件框只是一个取景窗口框外的一律看不见。按 4.1 的换算组件框约 240 × 200 像素而原图是 1422 × 800 像素于是方向可见比例说明水平240 ÷ 1422 ≈ 17%只能看到图片左右方向约六分之一垂直200 ÷ 800 25%只能看到图片上下方向约四分之一也就是说每种裁剪模式都只露出原图很小的一块。这正好展示了裁剪模式的特点但如果希望每种模式的差别更明显可以换一张更小的原图或者把组件框调大一些。五、完整属性表5.1 通用属性属性类型默认值说明srcstring—图片资源地址支持本地路径、网络地址、云文件 IDmodestringscaleToFill图片裁剪、缩放的模式共 14 个合法值show-menu-by-longpressbooleanfalse长按图片显示菜单发送给朋友、保存图片、识别码等bind:loadeventhandle—图片载入完毕时触发e.detail { height, width }bind:erroreventhandle—错误发生时触发e.detail { errMsg }5.2 分渲染框架的特有属性属性框架默认值说明fade-inSkylinefalse是否渐显preloadSkylinefalse是否预加载图片3.15.0 起lazy-loadWebViewfalse图片懒加载进入上下三屏范围才加载Skyline 默认懒加载webpWebViewfalse是否解析 webP 格式只支持网络资源forceHttpsWebViewfalse自动把 http 链接替换为 https3.9.1 起属性、默认值与说明取自微信官方 image 组件文档。5.3 用 bind:load 拿到图片的真实尺寸bind:load会在图片载入完成时告诉你图片的真实宽高这在需要按原图比例做布局时很有用image src{{src}} bindloadonImageLoad/onImageLoad(e){console.log(e.detail.width, e.detail.height) // 例如 1422 800}六、通读项目后发现的问题6.1 wx:for 缺少 wx:key建议修index.wxml 里的循环没有写wx:keyblock wx:for{{imgArray}}这不会导致报错但微信开发者工具会给出警告。wx:key的作用是帮助框架在数据变化时正确复用节点用法是填一个数据里唯一且不变的字段名。本项目每项的mode正好唯一可以直接用它block wx:for{{imgArray}} wx:keymode6.2 renderer 与 rendererOptions.skyline 同时存在建议清理app.json 里既写了renderer: webview又保留了rendererOptions.skyline配置块renderer: webview, rendererOptions: { skyline: { ... } // 渲染器已是 webview这段配置不会生效 }功能上没有问题——渲染器既然是 webviewskyline 的那段参数就被忽略了但留在文件里会让人误以为当前用的是 Skyline。建议删掉或补一句注释说明。6.3 本地配置里的 skylineRenderEnable 开关project.private.config.json 里有一项skylineRenderEnable: true。这是开发者工具侧的编译开关和 app.json 里显式指定的renderer: webview是两回事真正决定渲染器的是 app.json。不过两者看起来方向相反建议确认一下本地开关是否有意保留。6.4 说明文字的大小写不统一数组中各条text描述里「Webview」出现了三种写法仅webview支持1 处、仅Webview支持3 处、仅 Webview 支持5 处。内容都对但同一份数据里混用三种写法会显得随意建议统一成一种。6.5 其他小问题位置现状建议navigation-bartitleWeixin改成页面实际标题如「图片显示模式」index.wxml文字写成「左上边区域/右下边区域」官方用语是「左上角区域」可统一app.jsApp({}) 空实现保持空即可无需修改组件尺寸固定 480 × 400 rpx建议补一句注释说明这个尺寸与图片比例不同是有意为之七、易错点汇总现象原因解决办法图片变形了没写 mode用了默认的 scaleToFill按需指定 mode如 aspectFit图片只显示一角用了裁剪模式或组件尺寸太小改用缩放模式或放大组件与图片的适配裁剪模式完全没效果渲染器是 Skyline在 app.json 里设置 renderer: webviewaspectFit 上下有空白图片比例与组件比例不一致这是正常现象如不想要留白改用 aspectFill或让组件比例贴近原图组件大小不对没写样式用了默认的 320px × 240px在 wxss 里显式设置宽高widthFix 设置了高度但没生效widthFix 会接管高度按比例自动算用 widthFix 时只设宽度不要设高度列表渲染有警告wx:for 没写 wx:key补上唯一字段作为 wx:key图片加载失败没有提示没有监听 bind:error绑定 bind:error 做兜底提示八、小结image 组件只有src和mode两个核心属性但mode的 14 个取值分属两个体系5 个缩放模式会改变图片大小来适应组件框9 个裁剪模式不缩放图片、把组件框当成取景窗口。使用时记住三件事一要显式设置宽高默认是 320×240二要显式指定mode默认会拉伸变形三要注意裁剪模式仅Webview支持——需要它们时就要像本项目这样把 app.json 的 renderer 设为 webview。理解了原图比例与组件框比例的关系14 种模式的效果其实都能提前推算出来不必逐个去试。