属性详解

mode 16种显示模式（最常用5种重点）

容器固定宽高时，控制图片适配逻辑：

1. scaleToFill（默认）

不保持比例，拉伸填满容器，图片会变形
适用：纯色背景占位图

2. aspectFit（最常用预览）

保持比例，完整显示整张图，长边贴合容器，会留白
适用：商品详情、图片预览

3. aspectFill（头像/封面首选）

保持比例，短边填满容器，超出部分裁剪，无留白不变形
适用：头像、轮播封面、商品列表图

4. widthFix（自适应宽度）

宽度等于容器宽度，高度自动等比例缩放，无需手动设height

<image src="xxx.jpg" mode="widthFix" style="width:100%;"></image>

适用：图文详情、信息流大图

5. heightFix

高度等于容器高度，宽度自适应

其余裁剪定位模式（按需使用）

top/center/bottom/left/right/top left/top right/bottom left/bottom right
作用：等比例放大填满容器，按对应方位裁剪多余部分

事件监听：加载成功/失败

WXML

<image 
  src="{{imgUrl}}"
  style="width:300rpx;height:300rpx"
  bindload="onImgLoad"
  binderror="onImgError"
>
</image>

JS

Page({
  data: { imgUrl: "https://xxx/test.jpg" },
  // 加载成功
  onImgLoad(e) {
    console.log("图片宽高", e.detail.width, e.detail.height)
  },
  // 加载失败（404/域名错误）
  onImgError(e) {
    console.log("加载失败", e.detail.errMsg)
    // 替换默认兜底图
    this.setData({ imgUrl: "/images/default.png" })
  }
})

实用高级功能

1. 懒加载 lazy-load

页面长列表大量图片时开启，不在屏幕内不请求，优化性能

<image src="{{list.img}}" lazy-load="true"></image>

2. 长按保存/识别小程序码

<image src="/ewm.png" show-menu-by-longpress="true"></image>

3. 圆形头像（圆角）

<image 
  src="{{avatar}}" 
  mode="aspectFill"
  style="width:120rpx;height:120rpx;border-radius:50%;"
></image>

4. 轮播图搭配 image

<swiper style="width:100%;height:400rpx" autoplay circular>
  <swiper-item>
    <image src="img1.jpg" mode="aspectFill" style="width:100%;height:100%"></image>
  </swiper-item>
  <swiper-item>
    <image src="img2.jpg" mode="aspectFill" style="width:100%;height:100%"></image>
  </swiper-item>
</swiper>

5. 图片点击预览（wx.previewImage）

<image src="{{img}}" bindtap="previewImg"></image>

previewImg() {
  wx.previewImage({
    current: this.data.img, // 当前预览图
    urls: [this.data.img] // 图片数组，支持多图滑动
  })
}

常见踩坑与解决方案

1. 图片空白不显示

   • 没设置宽高：必须加 style="width:xx;height:xx"
   • 网络图域名未添加到后台 request 合法域名
   • 路径写错：本地图用绝对路径 /images/xxx

2. 图片拉伸变形

   • 头像/封面改用 mode="aspectFill"
   • 详情大图改用 mode="widthFix"

3. 本地背景图不生效
   WXSS background-image:url(本地图) 不支持，改用 image 组件模拟背景。

4. 长列表页面卡顿
   全部添加 lazy-load="true"，图片压缩到 200kb 以内。

5. 真机无法长按保存
   加上 show-menu-by-longpress="true"。

性能优化建议

1. 图片压缩：线上图控制在 200kb 以内，优先 WebP；
2. 列表开启懒加载 lazy-load；
3. 列表图片统一尺寸，避免频繁重绘；
4. 失败统一兜底默认图，提升体验；
5. 首屏大图可在 onShow 预加载。

原文出处：/show_1GW3XL9oYFR2.html