示例工程小程序前端【免费下载链接】miniprogram-demo微信小程序组件 / API / 云开发示例项目地址https://gitcode.com/gh_mirrors/mi/miniprogram-demo点击查看免费下载导读本文以 miniprogram-demo 开源示例项目中内置的 TDesign 微信小程序组件库tdesign-miniprogram/image图片组件为核心系统讲解t-image的引入方式、裁切模式mode、圆角形状shape、加载态与错误态定制、懒加载与 WebP 支持以及底层源码实现原理。读者读完本文后可以在自己的微信小程序页面中快速接入并灵活配置t-image实现居中裁切、等比缩放、圆角头像、自定义加载失败占位等常见图片展示需求并能理解其源码内部的加载状态机与尺寸计算逻辑。该组件位于仓库 miniprogram/packageAPI/components/tdesign-miniprogram/image本示例项目微信小程序组件 / API / 云开发示例的多个页面与组件如 activity_create/index.wxml、cell、empty等都在实际复用该图片组件。一、组件定位与适用场景t-image是对微信小程序原生image组件的封装与增强官方描述为用于展示效果主要为上下左右居中裁切、拉伸、平铺等方式。它继承了小程序原生 image 的裁切缩放能力并额外提供了统一的加载中 / 加载失败占位态默认样式或插槽自定义三种圆角形状圆形 / 圆角 / 方形懒加载、WebP 解析、长按菜单等原生能力透传通过外部样式类external classes与 CSS 变量进行主题定制。从源码结构看组件继承自SuperComponent见 image.js内部维护isLoading、isFailed两个状态配合t-loading加载动画组件与t-icon错误图标组件渲染占位内容是一个典型的状态机 原生能力透传型封装组件。二、组件引入方式与所有 TDesign 小程序组件一致t-image支持全局引入与局部引入两种方式。全局引入在miniprogram根目录下的app.json的usingComponents字段中声明usingComponents: { t-image: tdesign-miniprogram/image/image }局部引入在需要使用的页面或组件对应的index.json中声明路径需要相对该 json 文件计算。以本仓库为例activity_create/index.json 中按相对路径引入{ usingComponents: { t-image: ../../components/tdesign-miniprogram/image/image } }引入后即可在 WXML 中直接使用t-image src{{shareImage}} modeaspectFill width48 height48 /Tips若使用官方开发者工具预览本示例请确保开发者工具为打开状态导入项目后依次执行npm i 构建 npm 包 勾选将 JS 编译成 ES5。三、裁切样式mode详解t-image的mode属性完全透传给原生image组件决定图片的裁剪与缩放方式默认值为scaleToFill。可选项与语义如下| mode 值 | 效果说明 | | -- | -- | |scaleToFill| 默认值。拉伸填满容器不保持宽高比可能变形 | |aspectFit| 保持宽高比缩放完整显示图片可能有留白 | |aspectFill| 保持宽高比缩放并裁切填满容器可能裁掉部分图片 | |widthFix| 宽度不变高度自动变化保持宽高比 | |heightFix| 高度不变宽度自动变化保持宽高比 | |top/bottom/center/left/right| 不缩放按对应方向对齐显示 | |top left/top right/bottom left/bottom right| 不缩放按四个角对齐显示 |实战建议头像、封面图等需要铺满且居中裁切的场景使用aspectFill需要完整展示整张图如商品主图的场景使用aspectFit需要宽度固定、高度自适应的图文列表场景使用widthFix需要注意scaleToFill会拉伸变形一般用于明确知道原始比例的图片。源码对 heightFix 的兼容处理从源码看image.js组件对mode heightFix在低版本基础库下做了特殊兜底通过compareVersion(sdkVersion, 2.10.3)判断基础库版本若低于2.10.3则在图片load事件中通过getRect(this, #image)读取节点实际高度并按照原始宽高比计算展示宽度写入innerStyle。这保证了heightFix模式在旧版本微信上的显示一致性。版本比较逻辑见 common/version.js。四、尺寸设置与单位处理t-image提供width与height两个属性用于控制图片显示尺寸类型为String / Number默认值为-不限制由内容或父容器决定。传入纯数字如48时默认单位按px处理传入带单位字符串如100rpx时原样使用。源码中calcSize方法image.js监听width, height两个属性的变化通过addUnit工具common/utils.js统一追加px单位纯数字会被转换成${value}px带单位的字符串则直接透传。生成的样式通过innerStyle同时作用于占位层与图片节点保证加载占位与图片本体尺寸一致。五、加载状态与失败状态定制t-image内部维护isLoading与isFailed两个布尔状态见 image.js并根据状态渲染三层结构见 image.wxml加载中占位层isLoading为 true加载失败占位层isFailed为 true图片本体!isFailed时渲染。loading 属性loading属性控制加载中的占位内容类型为String / Slot默认值default| 取值 | 行为 | | -- | -- | |default| 使用默认加载风格即内置的t-loading圆点加载动画themedots、size44rpx | | 空字符串或slot| 使用插槽渲染插槽名称为loading| | 其他字符串 | 作为普通文本直接显示如loading加载中|error 属性error属性控制加载失败时的占位内容类型为String / Slot默认值default| 取值 | 行为 | | -- | -- | |default| 使用默认加载失败风格即内置的t-icon nameclose关闭图标 | | 空字符串或slot| 使用插槽渲染插槽名称为error| | 其他字符串 | 作为普通文本直接显示如error加载失败|组件在image.json中声明了multipleSlots: true见 image.json支持多插槽渲染。插槽自定义示例t-image src{{imgUrl}} !-- 自定义加载中内容 -- view slotloading图片加载中…/view !-- 自定义加载失败内容 -- view sloterror图片走丢了/view /t-image加载状态机源码解析src属性的 observerimage.js会先对比preSrc仅在图片地址真正变化时调用update()若src为空直接进入失败态并触发error事件errMsg为图片链接为空否则重置为加载中状态交由原生image的load/error事件推进状态。onLoaded在图片加载完成后将isLoading置为 false、isFailed置为 false并向上触发load事件onLoadError则将isLoading置为 false、isFailed置为 true并向上触发error事件见 image.js。此外 WXML 中还透传了aria-hidden与aria-label在加载中 / 失败 / 图片展示阶段合理控制无障碍语义提升辅助功能体验。六、形状shape与圆角shape属性控制图片圆角类型类型为String默认值square可选项| 取值 | 效果 | 底层实现见 image.wxss | | -- | -- | -- | |circle| 圆形适用于头像 |border-radius: 50%; overflow: hidden;| |round| 圆角矩形圆角值由 CSS 变量控制 |border-radius: var(--td-image-round-radius, var(--td-radius-default, 12rpx)); overflow: hidden;| |square| 直角矩形 |border-radius: 0; overflow: hidden;|该形状样式同时应用于占位层与图片本体因此加载中、失败态的占位块与图片共享相同的圆角外观。七、原生能力透传懒加载、WebP 与长按菜单以下属性由t-image直接透传给原生image组件见 image.wxmllazyBoolean默认false是否开启图片懒加载对应原生lazy-load属性。开启后图片进入视口附近时才加载适合长列表场景能有效减少网络请求。从源码看image.js懒加载开启时会给图片节点追加--lazy类名其样式将图片绝对定位并置于z-index: -1见 image.wxss确保懒加载过程中的占位层正常展示webpBoolean默认false是否解析 WebP 格式。默认不解析且该能力只支持网络资源本地图片无效show-menu-by-longpressBoolean默认false长按图片时显示系统菜单发送给朋友、收藏、保存图片、搜一搜、识别二维码/小程序码等。示例t-image src{{imgUrl}} lazy webp show-menu-by-longpress modeaspectFill /八、事件t-image对外暴露两个事件| 事件名 | 触发时机 | | -- | -- | |load| 图片加载完成时触发事件对象携带原生 detail 数据图片宽高等 | |error| 图片加载失败时触发包括src为空的情况 |监听方式在onLoaded源码中通过this.triggerEvent(load, e.detail)触发见 image.jst-image src{{imgUrl}} bind:loadonImgLoad bind:erroronImgError /Page({ onImgLoad(e) { console.log(图片加载完成, e.detail); }, onImgError(e) { console.log(图片加载失败, e.detail); }, });九、常见问题本地图片无法正确引用官方文档给出的排查结论建议使用绝对路径而不是相对路径。小程序中绝对路径以app.json所在位置为基准。例如app.json位于miniprogram/根目录时引用本地图片可写为t-image src/image/icon_API.png modeaspectFit /相对路径容易因页面层级嵌套分包、多级目录而计算错误统一使用以app.json为基准的绝对路径最稳妥。此外需确认图片文件确实已上传到代码包内、路径大小写与文件名完全一致。十、外部样式类External Classest-image提供 4 个外部样式类用于在不侵入组件内部的情况下定制各区块样式。从源码看image.js这些类声明于externalClasses数组中前缀取自统一配置prefix即t| 类名 | 作用对象 | | -- | -- | |t-class| 根节点样式类 | |t-class-load| 加载样式类加载中占位及加载失败占位通用 | |t-class-image| 图片本体样式类 | |t-class-error| 加载失败样式类 |使用示例t-image src{{imgUrl}} t-classmy-img t-class-loadmy-img-load t-class-imagemy-img-body t-class-errormy-img-error //* 页面 wxss */ .my-img { border: 2rpx solid #eee; } .my-img-body { border-radius: 8rpx; }同时组件在image.json中配置了styleIsolation: apply-shared页面样式可作用于组件内部配合外部样式类可实现灵活的局部定制。十一、CSS 变量定制组件提供了 4 个 CSS 变量用于在不改动源码的情况下自定义主题样式| CSS 变量 | 默认值 | 说明 | | -- | -- | -- | |--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-default12rpx |shaperound时的圆角半径 |这些变量在 image.wxss 中均带有三层回退var(--td-image-color, var(--td-text-color-placeholder, var(--td-font-gray-3, rgba(0, 0, 0, 0.4))))形式即组件变量 → 全局 TDesign 变量 → 内置硬编码默认值三层兜底保证了任何主题下都有可用样式。可在页面或全局 wxss 中覆盖page { --td-image-loading-bg-color: #f5f5f5; --td-image-round-radius: 16rpx; --td-image-loading-color: #999999; }十二、项目中的真实使用示例1. 自定义分享图缩略展示在 activity_create/index.wxml 中创建活动页使用t-image展示用户选择的分享图aspectFill模式保证 48px 见方的缩略图铺满且居中裁切t-cell bind:tapchooseShareImage title自定义分享图 hover view slotnote t-icon wx:if{{!shareImage}} nameimage-add size48rpx / t-image wx:else src{{shareImage}} modeaspectFill width48 height48 / /view /t-cell2. 其他 TDesign 组件的内部复用t-image同时也是本仓库其他组件的内部依赖cell组件通过t-image渲染左侧图片cell.jsonempty组件通过t-image渲染空状态插图modeaspectFit见 empty.wxml通用模板 common/template/image.wxml 将t-image的所有属性、事件封装为可复用 template供业务侧按需传入。这印证了t-image作为基础图片组件的高复用性它既可直接服务于业务页面也可作为上层组件的内部构件。十三、完整 Props 速查表综合 props.js 与 type.d.ts 的类型定义t-image的完整属性如下| 名称 | 类型 | 默认值 | 描述 | 必传 | | -- | -- | -- | -- | -- | | 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表示默认加载中风格空值或slot表示使用loading插槽渲染其他值为普通文本如加载中 | N | | mode | String |scaleToFill| 图片裁剪、缩放模式。可选项scaleToFill/aspectFit/aspectFill/widthFix/heightFix/top/bottom/center/left/right/top left/top right/bottom left/bottom right| N | | shape | String |square| 图片圆角类型。可选项circle/round/square| N | | show-menu-by-longpress | Boolean |false| 长按图片显示发送给朋友、收藏、保存图片、搜一搜、打开名片/前往群聊/打开小程序的菜单 | N | | src | String | - | 图片链接 | N | | t-id | String | - | 图片标签 id用于节点查询定位 | N | | webp | Boolean |false| 是否解析 WebP 格式默认不解析只支持网络资源 | N | | width | String / Number | - | 宽度默认单位为px| N |十四、相关文件索引如需深入阅读组件实现与配套工具可查看以下仓库文件组件入口与状态机miniprogram/packageAPI/components/tdesign-miniprogram/image/image.js属性声明miniprogram/packageAPI/components/tdesign-miniprogram/image/props.js组件模板miniprogram/packageAPI/components/tdesign-miniprogram/image/image.wxml组件样式与 CSS 变量miniprogram/packageAPI/components/tdesign-miniprogram/image/image.wxssTypeScript 类型定义miniprogram/packageAPI/components/tdesign-miniprogram/image/type.d.ts组件信息元数据API 文档数据源miniprogram/packageAPI/components/tdesign-miniprogram/image/image-info.json通用工具尺寸单位、节点查询miniprogram/packageAPI/components/tdesign-miniprogram/common/utils.js版本比较工具miniprogram/packageAPI/components/tdesign-miniprogram/common/version.js结语t-image以极小的心智负担覆盖了微信小程序图片展示的大部分典型需求裁切缩放、圆角形状、加载/失败占位、懒加载、WebP、长按菜单与无障碍支持一应俱全且通过外部样式类和 CSS 变量提供了充分的定制空间。理解其状态机 原生能力透传 主题变量三层回退的源码设计不仅能帮助你在使用中精准定位问题也能为封装其他基础组件提供良好的参考范式。赞分享示例工程小程序前端【免费下载链接】miniprogram-demo微信小程序组件 / API / 云开发示例项目地址https://gitcode.com/gh_mirrors/mi/miniprogram-demo点击查看免费下载相关推荐TDesign Image 图片组件详解TDesign MiniProgram 图片展示、加载状态与圆角裁切完全指南TDesign Image 图片组件详解TDesign MiniProgram 图片展示、加载状态与圆角裁切完全指南 TDesign MiniProgram前端UI组件小程序设计系统移动开发TDesign 微信小程序下拉刷新组件 t-pull-down-refresh完整用法、API 详解与源码实现解析TDesign 微信小程序下拉刷新组件 t pull down refresh完整用法、API 详解与源码实现解析 本文围绕 TDesign 微信小程序组件库前端UI组件小程序设计系统移动开发TDesign小程序组件库中t-radio-group禁用状态问题解析TDesign小程序组件库中t radio group禁用状态问题解析 TDesign作为腾讯开源的UI组件库在小程序开发中被广泛使用。其中t radio g前端UI组件小程序设计系统移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考