微信小程序 TDesign Image 图片组件实战:模式裁切、加载状态与源码级 API 详解

原创2026-10-14 10:49:191,345 阅读
文章标签:示例工程小程序前端

微信小程序 TDesign Image 图片组件实战:模式裁切、加载状态与源码级 API 详解

在微信小程序项目中,图片是最高频的 UI 元素之一,而 t-image(TDesign Image 图片组件)为开发者封装了居中裁切、拉伸、平铺等多种展示模式,并内置了加载中/加载失败两种占位状态。本篇文章以 miniprogram-demo 仓库中 image/README.md 为骨架,结合该组件的真实源码(image.js、image.wxml、image.wxss),完整讲解组件的引入方式、全部 Props、事件、External Classes、CSS 变量,并给出可直接复用的实战示例。读完本文,你将能够熟练地在业务页面中配置任意图片展示形态,并理解底层实现原理与低版本兼容细节。

组件定位:一个带完整状态机的高可用图片封装

从源码结构看,t-image 并不是对小程序的 <image> 标签做简单透传,而是一个自带状态机的复合组件。image.js 中维护了三个核心内部状态:

  • isLoading:是否处于加载中;
  • isFailed:是否加载失败;
  • innerStyle:由 width / height 属性计算出的内联样式字符串。

在 image.wxml 中,这三个状态驱动了三段式渲染逻辑:

  1. wx:if="{{isLoading}}":渲染"加载中"占位层(默认是 TDesign 的 dots 风格 loading,配合 t-loading 子组件实现);
  2. wx:elif="{{isFailed}}":渲染"加载失败"占位层(默认是关闭图标,配合 t-icon 子组件实现);
  3. 图片本身:wx:if="{{ !isFailed }}",即失败时不再渲染 <image>,避免继续请求无效资源。

也就是说,组件内部替你完成了"加载态 → 成功态 / 失败态"的完整切换,页面开发者只需要传入 src,剩下的占位处理交给组件即可。

引入方式:全局与局部两种配置

组件支持全局引入与局部引入两种方式,与官方文档 README.md 描述一致:

  • 全局引入:在 miniprogram 根目录下的 app.json 的 usingComponents 中配置;
  • 局部引入:在需要使用该组件的页面或组件的 index.json 中配置。

配置代码如下:

{
  "usingComponents": {
    "t-image": "tdesign-miniprogram/image/image"
  }
}

注意:文档中的路径写法对应的是通过 npm 安装 tdesign-miniprogram 后的引用路径。而本仓库(miniprogram-demo)将组件源码直接内置在 miniprogram/packageChatTool/components/ 目录下,因此实际页面中的引入路径是相对路径。例如 activity_create/index.json:

{
  "usingComponents": {
    "t-image": "../../components/tdesign-miniprogram/image/image"
  }
}

同样地,activity_detail/index.json 也采用了相同的相对路径引入方式。从组件自身的 image.json 可以看到,t-image 内部还依赖 t-loading 与 t-icon 两个兄弟组件("styleIsolation": "apply-shared" 表示共享页面样式,便于通过 External Classes 自定义外观),因此引入时需保证整个 tdesign-miniprogram 组件目录完整可用。

代码演示与开发者工具预览

文档中的代码演示区提供了"在开发者工具中预览效果"的入口(对应 README.md 中的预览链接),覆盖两个典型场景:

  • 裁切样式:演示 mode 属性在不同取值下的图片裁切与缩放表现;
  • 加载状态:演示 loading / error 属性在加载中和加载失败时的表现。

预览前请确保微信开发者工具处于打开状态,导入项目后依次执行:npm i → 构建 npm 包 → 勾选 "将 JS 编译成 ES5",即可正常跑通 TDesign 组件依赖。

Image Props 全参数详解

以下参数表完整继承自 README.md,并补充了从 props.js 与 type.d.ts 中确认的默认值与类型约束:

名称 类型 默认值 描述 必传
style Object - 样式 N
custom-style Object - 样式,一般用于开启虚拟化组件节点场景 N
error String / Slot 'default' 加载失败时显示的内容:值为 default 使用默认失败风格;值为空或 slot 使用 error 插槽渲染;其他值则按普通文本展示(如"加载失败") N
height String / Number - 高度,默认单位为 px N
lazy Boolean false 是否开启图片懒加载 N
loading String / Slot 'default' 加载态内容:值为 default 使用默认加载中风格;其他值按普通文本展示(如"加载中") N
mode String scaleToFill 图片裁剪、缩放模式(详见下文) N
shape String square 图片圆角类型:circle / round / square N
show-menu-by-longpress Boolean false 长按图片是否弹出"发送给朋友、收藏、保存图片、搜一搜、打开名片/前往群聊/打开小程序"菜单 N
src String '' 图片链接 N
t-id String '' 图片标签 id(1.2.10 版本新增) N
webp Boolean false 是否解析 webP 格式(仅支持网络资源) N
width String / Number - 宽度,默认单位为 px N

源码级解读:几个容易被忽略的实现细节

1. width / height 与 addUnit 单位处理。 文档标注"默认单位为 px",其底层逻辑位于 common/utils.js 的 addUnit 函数:组件通过 observers 监听 width, height 变化(见 image.js),调用 calcSize 拼装 innerStyle,而 addUnit 会判断传入值是否为纯数字——纯数字自动补上 px 单位,带单位(如 50%、200rpx)则原样保留。这解释了"默认单位为 px"的准确含义:传 width="48" 等效于 width: 48px,传 width="50%" 则按百分比生效。

2. src 变化的重新加载逻辑。 observers 中还监听 src(image.js):仅当 src 与上一次的 preSrc 不同时才调用 update() 重置加载状态,避免同一链接重复刷新。且当 src 为空字符串时,会直接走 onLoadError({ errMsg: '图片链接为空' }) 进入失败态——这是 src 必传性的一个隐含约束。

3. heightFix 模式的低版本 SDK 兼容处理。 在 onLoaded 回调中(image.js),组件会通过 compareVersion 对比当前基础库版本与 2.10.3(实现见 common/version.js)。若使用 heightFix 模式且 SDK 版本低于 2.10.3,原生 image 的 binderror 详情可能拿不到完整尺寸信息,组件会主动通过 getRect 获取实际渲染区域,并依据 (rect.height / picHeight) * picWidth 反算图片宽度后写回 innerStyle,保证低版本下高度自适应仍可用。

4. t-id 的用途。 t-id 用于给内部 <image> 节点指定 id(默认回退为 image),在上述 getRect 测量流程中承担选择器定位的作用。

mode 属性:裁剪与缩放模式速查

mode 直接透传给小程序原生 <image> 组件(见 image.wxml),可选值在 type.d.ts 中有完整定义:

mode 取值 行为
scaleToFill 默认值。不保持纵横比缩放图片,使图片的宽高完全拉伸至填满元素
aspectFit 保持纵横比缩放,使图片完整显示(可能有留白)
aspectFill 保持纵横比缩放,填满元素,多余部分被裁切(可能不完整显示)
widthFix 宽度不变,高度自动变化,保持原图宽高比
heightFix 高度不变,宽度自动变化,保持原图宽高比
top / bottom / center 不缩放图片,只显示图片的顶部 / 底部 / 居中部分
left / right 不缩放图片,只显示图片的左侧 / 右侧部分
top left / top right / bottom left / bottom right 不缩放图片,只显示对应角落区域

实战选型建议:头像、商品缩略图这类"需要占满且不怕裁边"的场景,推荐 aspectFill;需要完整预览大图的场景,推荐 aspectFit;宽度确定、高度随内容变化的场景,推荐 widthFix(如资讯列表封面图)。

加载状态与失败状态的自定义

组件默认内置两种占位:加载中为 dots 动画,加载失败为关闭图标(t-icon name="close",见 image.wxml)。通过 loading 与 error 属性可切换三种形态:

  1. 默认风格:属性值为 'default'(默认值),渲染内置 loading / error 组件;
  2. 文本内容:属性传任意非空字符串,如 loading="加载中"、error="加载失败",占位层直接展示该文本;
  3. 自定义插槽:属性值为空字符串或 'slot' 时,使用同名插槽 name="loading" / name="error" 渲染自定义内容。

组件在 image.js 中开启了 multipleSlots: true,因此两个具名插槽可以同时使用。示例:

<t-image src="{{imgUrl}}" error="slot" loading="slot">
  <view slot="error">😢 图片走丢了,请重试</view>
  <view slot="loading">努力加载中...</view>
</t-image>

Image Events:load 与 error

组件对外暴露两个事件(对应文档 README.md 的 Events 表):

名称 参数 描述
error 原生 error 事件详情 图片加载失败时触发
load 原生 load 事件详情 图片加载完成时触发

这两个事件在 image.wxml 中通过 bind:load="onLoaded"、bind:error="onLoadError" 绑定,并在 image.js 与 image.js 中经由 triggerEvent 向外转发。注意:onLoaded 额外做了 heightFix 低版本兼容处理(见上文),这是直接使用原生 <image> 所没有的。

业务侧监听示例:

<t-image
  src="{{imgUrl}}"
  bind:load="onImgLoad"
  bind:error="onImgError"
/>
Page({
  onImgLoad(e) {
    console.log('图片加载完成', e.detail);
  },
  onImgError(e) {
    console.log('图片加载失败', e.detail);
  },
});

External Classes:外部样式类

为了让业务页面在不改组件内部结构的前提下定制样式,组件开放了 4 个外部样式类(定义于 image.js):

类名 描述
t-class 根节点样式类
t-class-load 加载样式类(同时作用于加载中与加载失败占位)
t-class-image 图片样式类
t-class-error 加载失败样式类

在 common/template/image.wxml 中可以看到,这些类名对应模板属性 tClass、tClassLoad、tClassImage、tClassError。使用方式:

<t-image
  src="{{imgUrl}}"
  t-class="custom-img-root"
  t-class-image="custom-img"
  t-class-load="custom-img-load"
  t-class-error="custom-img-error"
/>

CSS Variables:主题化定制

组件在 image.wxss 中提供了 4 个 CSS 变量,默认值来自 TDesign 设计令牌(@font-gray-3、@bg-color-secondarycontainer、@radius-default),并逐级携带 fallback 值,便于在无令牌环境降级:

变量名 默认值 描述
--td-image-color @font-gray-3 占位图标 / 文本的前景色
--td-image-loading-bg-color @bg-color-secondarycontainer 加载中占位背景色
--td-image-loading-color @font-gray-3 加载中图标 / 文本颜色
--td-image-round-radius @radius-default round 圆角类型的圆角大小

从 image.wxss 的 fallback 链可以看到真实降级顺序,例如加载背景色最终兜底为 #f3f3f3,round 圆角最终兜底为 12rpx。可在页面级或组件级覆盖,实现全局主题统一:

/* page.wxss */
page {
  --td-image-round-radius: 16rpx;
  --td-image-loading-bg-color: #fafafa;
  --td-image-loading-color: #999;
}

常见问题与避坑指南

1. 本地图片无法正确引用? 这是文档"常见问题"中明确指出的一类高频问题。解决办法是使用绝对路径而非相对路径,且绝对路径以 app.json 所在位置为基准。例如 src="/images/logo.png",而不是 src="../../images/logo.png"。在分包场景下,还要注意路径基准是否变化。

2. 空 src 会导致失败态。 从 image.js 的 update() 可知,src 为空会直接触发加载失败回调并展示错误占位。如果业务中存在"先占位后赋值"的需求,建议初始不渲染 t-image,或传入一个透明占位图。

3. webp 仅对网络资源生效。 webp 属性默认 false,开启后可解析 webP 格式,但文档与源码均明确该能力只支持网络资源(src 为 https 链接),本地图片不支持。

4. 长按菜单需要 show-menu-by-longpress。 默认 false,需要支持长按弹出保存 / 识别小程序码等菜单时,显式开启该属性。

5. 懒加载使用场景。 lazy 默认 false,在长列表(如消息流、商品瀑布流)中开启可显著减少首屏网络请求,结合小程序原生 lazy-load 实现(见 image.wxml)。

实战:在 miniprogram-demo 中落地一个裁剪头像

以仓库内真实的 activity_create/index.wxml 为例,创建活动页在选择自定义分享图后,用 t-image 展示所选图片的缩略预览:

<t-cell bind:tap="chooseShareImage" title="自定义分享图" hover>
  <view slot="note">
    <t-icon wx:if="{{!shareImage}}" name="image-add" size="48rpx" />
    <t-image
      wx:else
      src="{{shareImage}}"
      mode="aspectFill"
      width="48"
      height="48"
    />
  </view>
</t-cell>

这段代码展示了三个最常用的组合技巧:

  • mode="aspectFill":48px 见方的缩略框内居中裁切,不产生变形;
  • width="48" height="48":纯数字自动补 px 单位,固定尺寸;
  • 结合 wx:if / wx:else:未选图时显示图标占位,选图后切换为图片预览——正好呼应了组件"失败/空态占位"的设计思路。

若需进一步定制展示效果(如圆角头像、加载失败重试提示、长按保存菜单等),组合使用上文所述的 shape、error / loading 插槽、show-menu-by-longpress 属性即可,无需为每种形态重复封装原生 <image>。

相关资源

登录后查看全文
miniprogram-demo