企业官网建设流程全解析

• 前端
• UI组件
• 小程序
• 设计系统
• 移动开发

空状态（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 icon="info-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是空状态最常用的视觉来源，其取值有两种形态：

1. 字符串形态：直接传图标名称，如icon="info-circle-filled"，组件内部会将其包装为{ name: icon }交给t-icon渲染；
2. 对象形态：透传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组件并以mode="aspectFit"模式展示（见 empty.wxml）。aspectFit是微信小程序image组件的裁剪缩放模式之一，含义为「保持纵横比缩放图片，使图片的长边能完全显示出来」，适合用于等比展示空状态插画。

由于内部依赖t-image与t-icon，empty.json 中已声明usingComponents引入../icon/icon与../image/image，使用方无需关心这一内部依赖。此外 empty.json 设置了"styleIsolation": "apply-shared"，页面样式可以影响到组件内部，这为外部样式类与 CSS 变量之外的常规样式覆盖提供了通道。

三种内置形态与插槽（Slots）

t-empty提供 3 个具名插槽，对应文档中的 Empty Slots 定义：

| 插槽名 | 说明 | | -- | -- | | action | 操作按钮区域 | | description | 自定义描述显示内容（可覆盖默认description文本） | | image | 自定义图片显示内容（当未使用image/icon属性时生效） |

组件在 empty.ts 中声明了multipleSlots: true，即开启了多插槽支持，三个具名插槽可以同时使用。

结合模板 empty.wxml，可以梳理出空状态各区域的渲染优先级：

• 缩略图区域（__thumb）：优先渲染image属性（t-image），其次渲染icon图标，两者都未配置时才回退到image插槽；
• 描述区域（__description）：description文本属性与description插槽会同时渲染在该区域内；
• 操作区域（__actions）：仅承载action插槽内容。

形态一：图标空状态

<t-empty icon="info-circle-filled" description="描述文字" />

形态二：自定义图片空状态

<t-empty image="{{image}}" description="描述文字" />

对应演示见 _example/imageEmpty/index.wxml，页面在data.image中传入图片地址即可。该形态渲染出的t-image自带t-class-image外部样式类，可直接通过该类控制图片尺寸。

形态三：带操作空状态

<t-empty icon="info-circle-filled" description="描述文字"> <t-button slot="action" theme="primary" size="large">操作按钮</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-image（prefix为组件库统一前缀t）。使用示例参考 _example/imageEmpty/index.wxml：

<t-empty t-class="empty-cls" t-class-image="t-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.wxml）：

view.t-empty（根节点，应用 style + customStyle + t-class） ├── view.__thumb（缩略图区域，aria-hidden="true"） │ ├── t-image（image 属性优先） │ ├── t-icon（icon 属性次之，经 calcIcon 转换） │ └── slot name="image"（兜底） ├── view.__description（描述区域） │ ├── 文本 description（属性渲染） │ └── slot name="description"（插槽） └── view.__actions（操作区域） └── slot name="action"（插槽）

几个值得注意的实现细节：

1. 图片优先级高于图标：wx:if="{{image}}"优先于wx:elif="{{_.isNoEmptyObj(_icon)}}"（该判断来自 common/utils.wxs 的isNoEmptyObj），二者均未配置时才渲染image插槽；
2. 无障碍处理：缩略图区域标记了aria-hidden="true"，避免装饰性图标被读屏器重复播报；
3. 样式合并入口：根节点通过_._style([style, customStyle])（见 common/utils.wxs）合并两个样式参数，这也解释了文档中style与custom-style同时存在的意义——后者在开启虚拟化组件节点（Virtual Host）场景下依然能正确落在根节点上，相关行为在 index.test.js 中针对 Virtual Host 与非 Virtual Host 两种模式分别断言；
4. 状态零维护：组件类不定义任何方法，仅通过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组件
• 小程序
• 设计系统
• 移动开发