前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载空状态Empty是数据展示类页面最常见的占位组件用于列表无数据、搜索无结果、订单为空等场景下的友好提示。本文以 TDesign 微信小程序组件库中t-empty组件为对象基于其官方 API 文档结合 empty 组件源码、模板结构 与 单元测试系统讲解该组件的全部 Props、三种插槽、外部样式类与五个可定制 CSS 变量并给出可复制运行的接入与定制方案。读完本文你将能够独立完成空状态组件的引入、三类形态图标 / 图片 / 带操作的实现以及通过样式变量与外部类进行的深度视觉定制。组件定位与适用场景t-empty是 TDesign 小程序组件库中的数据展示类组件官方定位为「用于空状态时的占位提示」见 README.md。典型使用场景包括列表数据为空时的占位提示如订单列表、收藏列表搜索结果无命中时的引导页面初始状态或异常状态的友好兜底。从渲染框架支持情况看该组件同时兼容Skyline与WebView两种渲染模式。仓库中也提供了对应的 Skyline 演示页见 _example/skyline/empty.wxml在 Skyline 渲染模式下依然可以正常使用scroll-view等外层滚动容器承载该组件。组件本身是纯展示型组件不维护业务状态、不触发对外事件职责非常单一——根据传入的image/icon/description与插槽内容渲染一套居中的空状态视觉区块。这种轻量设计使它可以被灵活嵌入到任何页面或自定义组件中。快速接入全局与局部引入与 TDesign 小程序组件库中其他组件一致t-empty支持两种引入方式全局引入在项目根目录app.json的usingComponents中声明一次全页面可用usingComponents: { t-empty: tdesign-miniprogram/empty/empty }局部引入在需要使用的页面或组件对应的index.json中声明{ usingComponents: { t-empty: tdesign-miniprogram/empty/empty } }引入后即可在 WXML 中直接使用例如最简单的图标空状态写法与_example/base/index.wxml中的演示一致t-empty iconinfo-circle-filled description描述文字 /说明以上路径写法对应组件库 npm 包解构后的目录结构empty/empty指empty目录下的empty组件其组件声明见 empty.json。若项目按 npm 方式安装tdesign-miniprogram并完成「构建 npm 包」上述路径可直接生效。Props 参数详解依据官方文档t-empty共暴露 5 个 Props。下表为完整参数清单合并了中文与英文文档的字段说明| 参数名 | 类型 | 默认值 | 说明 | | -- | -- | -- | -- | | style | Object | - | 组件根节点行内样式 | | custom-style | Object | - | 自定义样式一般用于开启虚拟化组件节点场景 | | description | String | - | 描述文字显示在图标 / 图片下方 | | icon | String / Object | - | 图标名称。值为字符串表示图标名称值为Object类型时表示透传至内部t-icon组件 | | image | String | - | 图片地址或Image组件属性或自定义任意节点 |参数声明可在 props.ts 中核对description、image为String类型icon为type: null即字符串或对象均可与文档一致。icon字符串与对象两种传法icon是空状态最常用的视觉来源其取值有两种形态字符串形态直接传图标名称如iconinfo-circle-filled组件内部会将其包装为{ name: icon }交给t-icon渲染对象形态透传t-icon组件的属性如size、color、prefix、style等例如t-empty icon{{ { name: info-circle-filled, size: 48px, color: #0052d9 } }} description暂无数据 /这一转换逻辑实现在 common/utils.ts 的calcIcon函数中字符串会转换为{ name }对象对象则原样透传否则返回null。而 empty.ts 中通过observers监听icon变化并调用calcIcon计算_icon因此运行时动态切换图标同样有效。image图片空状态的渲染细节当传入image图片地址时组件内部会渲染t-image组件并以modeaspectFit模式展示见 empty.wxml。aspectFit是微信小程序image组件的裁剪缩放模式之一含义为「保持纵横比缩放图片使图片的长边能完全显示出来」适合用于等比展示空状态插画。由于内部依赖t-image与t-iconempty.json 中已声明usingComponents引入../icon/icon与../image/image使用方无需关心这一内部依赖。此外 empty.json 设置了styleIsolation: apply-shared页面样式可以影响到组件内部这为外部样式类与 CSS 变量之外的常规样式覆盖提供了通道。三种内置形态与插槽Slotst-empty提供 3 个具名插槽对应文档中的 Empty Slots 定义| 插槽名 | 说明 | | -- | -- | | action | 操作按钮区域 | | description | 自定义描述显示内容可覆盖默认description文本 | | image | 自定义图片显示内容当未使用image/icon属性时生效 |组件在 empty.ts 中声明了multipleSlots: true即开启了多插槽支持三个具名插槽可以同时使用。结合模板 empty.wxml可以梳理出空状态各区域的渲染优先级缩略图区域__thumb优先渲染image属性t-image其次渲染icon图标两者都未配置时才回退到image插槽描述区域__descriptiondescription文本属性与description插槽会同时渲染在该区域内操作区域__actions仅承载action插槽内容。形态一图标空状态t-empty iconinfo-circle-filled description描述文字 /形态二自定义图片空状态t-empty image{{image}} description描述文字 /对应演示见 _example/imageEmpty/index.wxml页面在data.image中传入图片地址即可。该形态渲染出的t-image自带t-class-image外部样式类可直接通过该类控制图片尺寸。形态三带操作空状态t-empty iconinfo-circle-filled description描述文字 t-button slotaction themeprimary sizelarge操作按钮/t-button /t-empty对应演示见 _example/buttonEmpty/index.wxml在action插槽中放入按钮如t-button即可形成「提示 行动点」的完整引导闭环。该插槽的交互行为也经过了测试验证在 index.test.js 中通过miniprogram-simulate模拟点击插槽内节点并断言事件回调被触发。外部样式类External Classes文档定义了 3 个外部样式类用于在不侵入组件内部的前提下定制局部样式| 类名 | 说明 | | -- | -- | | t-class | 组件根节点样式类 | | t-class-description | 描述文字样式类 | | t-class-image | 图片样式类 |对应实现在 empty.ts 的externalClasses声明中${prefix}-class、${prefix}-class-description、${prefix}-class-imageprefix为组件库统一前缀t。使用示例参考 _example/imageEmpty/index.wxmlt-empty t-classempty-cls t-class-imaget-empty__image image{{image}} description描述文字 //* 页面或组件的 wxss 中 */ .empty-cls { margin: 40rpx 0; } .t-empty__image { width: 320rpx; height: 320rpx; }外部样式类配合styleIsolation: apply-shared的组合使页面级样式能够可靠地作用到组件内部的指定节点是「局部精准定制」的主要手段。CSS 变量五个可定制样式项文档明确了组件支持以下 5 个 CSS 变量用于自定义样式。下表补齐了各变量在源码中的实际默认值来自 empty.less 与 common/style/_variables.less| CSS 变量名 | 默认值 | 源码默认值解析 | 作用 | | -- | -- | -- | -- | | --td-empty-action-margin-top | spacer-4 | 64rpx间距-大 | 操作区域与描述区域的上间距 | | --td-empty-description-color | text-color-placeholder | 占位文字色 | 描述文字颜色 | | --td-empty-description-font | font-body-medium | 28rpx/44rpx 正文字体 | 描述文字字体字号/行高 | | --td-empty-description-margin-top | spacer-2 | 32rpx间距-小 | 描述区域与缩略图的上间距 | | --td-empty-icon-color | text-color-placeholder | 占位文字色 | 图标颜色 |其中spacer-2 32rpx、spacer-4 64rpx、font-body-medium 28rpx/44rpx均可查证于 _variables.less分别位于第 79、81、117 行。组件源码还定义了图标字号为固定192rpx见 empty.less 中empty-icon-size: 192rpx如需调整图标大小可在icon属性对象形态中传入size或通过--td-empty-icon-color之外的普通 CSS 规则覆盖。这些变量默认通过var(--xxx, fallback)方式声明因此使用时只需在任意上层作用域如页面的wxss或app.wxss覆盖同名变量即可全局生效page { --td-empty-description-color: #666666; --td-empty-icon-color: #0052d9; --td-empty-description-font: 30rpx/48rpx PingFang SC; --td-empty-description-margin-top: 48rpx; --td-empty-action-margin-top: 96rpx; }源码结构理解组件的内部渲染顺序最后从源码层面梳理t-empty的完整内部结构对应 empty.wxmlview.t-empty根节点应用 style customStyle t-class ├── view.__thumb缩略图区域aria-hiddentrue │ ├── t-imageimage 属性优先 │ ├── t-iconicon 属性次之经 calcIcon 转换 │ └── slot nameimage兜底 ├── view.__description描述区域 │ ├── 文本 description属性渲染 │ └── slot namedescription插槽 └── view.__actions操作区域 └── slot nameaction插槽几个值得注意的实现细节图片优先级高于图标wx:if{{image}}优先于wx:elif{{_.isNoEmptyObj(_icon)}}该判断来自 common/utils.wxs 的isNoEmptyObj二者均未配置时才渲染image插槽无障碍处理缩略图区域标记了aria-hiddentrue避免装饰性图标被读屏器重复播报样式合并入口根节点通过_._style([style, customStyle])见 common/utils.wxs合并两个样式参数这也解释了文档中style与custom-style同时存在的意义——后者在开启虚拟化组件节点Virtual Host场景下依然能正确落在根节点上相关行为在 index.test.js 中针对 Virtual Host 与非 Virtual Host 两种模式分别断言状态零维护组件类不定义任何方法仅通过observers响应icon变化非常适合作为纯展示占位被高频复用。小结t-empty是一个麻雀虽小、五脏俱全的轻量展示组件5 个 Props 覆盖「图标 / 图片 / 自定义节点」三种视觉来源3 个具名插槽支持描述与操作区域的自由定制3 个外部样式类与 5 个 CSS 变量提供了「精准到节点」与「全局统一」两套定制通道。接入时只需在app.json或页面index.json声明t-empty: tdesign-miniprogram/empty/empty即可。若需要在实际页面中组合验证各类写法可参考仓库内 _example/base、_example/imageEmpty、_example/buttonEmpty 三个完整演示片段它们也是 demo.test.js 自动化快照测试的覆盖对象可作为稳定可靠的使用范本。赞分享前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐tdesign-miniprogram Badge 徽标组件详解Props、插槽、CSS 变量与源码实现tdesign miniprogram Badge 徽标组件详解Props、插槽、CSS 变量与源码实现 TDesign 小程序组件库中的 Badge徽标前端UI组件小程序设计系统移动开发naive-ui Empty 空状态组件完全指南Props、Slots、尺寸与主题定制naive ui Empty 空状态组件完全指南Props、Slots、尺寸与主题定制 导读 naive ui 的 NEmpty 组件用于在列表、表格、筛选结前端UI组件TDesign 小程序 Steps 步骤条组件完整指南属性、状态、插槽与源码原理详解TDesign 小程序 Steps 步骤条组件完整指南属性、状态、插槽与源码原理详解 本文基于 TDesign MiniProgram 组件库 packag前端UI组件小程序设计系统移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
