企业官网建设流程全解析

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

Empty（空状态）组件用于在数据为空、加载失败、暂无内容等场景下提供友好的占位提示，引导用户完成后续操作。本文以 TDesign Uniapp 组件库（npm 包@tdesign/uniapp）中的t-empty组件为核心，结合其源码实现（packages/uniapp-components/empty/）系统讲解组件的引入方式、全部 Props、插槽用法、外部样式类与 CSS 变量定制方案，并附上可直接复制的实战示例，帮助你快速掌握该组件的全部能力。

一、组件定位与设计

Empty 空状态组件是 TDesign 设计体系中的数据反馈类组件，核心职责是在列表无数据、搜索无结果、页面内容为空等场景下做视觉占位。从 empty.vue 的模板结构可以清晰看到，组件内部由三个部分组成：

• 缩略图区域（thumb）：优先渲染图片，其次渲染图标，否则渲染自定义image插槽；
• 描述文字区域（description）：渲染传入的description文本或自定义描述插槽；
• 操作区域（actions）：通过action插槽承载按钮等引导操作。

组件根节点使用t-empty前缀作为 class（prefix定义在 common/config.js，值为t），整体采用 flex 纵向布局并居中对齐，图标默认尺寸为192rpx（见 empty.less 中的@empty-icon-size）。

二、引入组件

推荐使用easycom 模式引入组件。配置后无需手动 import 即可直接在模板中使用<t-empty />，详细配置请参考 快速开始。

easycom 的核心原理是在pages.json中配置自定义规则，将t-xxx标签自动映射到组件文件。CLI 模式（基于node_modules下的@tdesign/uniapp）配置如下：

{ "easycom": { "custom": { "^t-(.*)": "@tdesign/uniapp/$1/$1.vue" } } }

HBuilderX 模式（基于uni_modules下的tdesign-uniapp）配置如下：

{ "easycom": { "custom": { "^t-(.*)": "@/uni_modules/tdesign-uniapp/components/$1/$1.vue" } } }

如需手动引入，则按常规方式导入并注册组件：

import TEmpty from '@tdesign/uniapp/empty/empty.vue'; export default { components: { TEmpty, }, };

三、三种典型使用场景

组件官方示例位于 _example，包含图标空状态、自定义图片空状态、带操作空状态三种典型形态，下面逐一讲解。

3.1 图标空状态

最轻量的用法：只传入icon图标名称和description描述文字，适合大多数空数据占位场景（参考 _example/base/index.vue）：

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

3.2 自定义图片空状态

当图标无法满足诉求时，可通过image属性传入图片地址，组件内部会复用t-image组件以aspectFit模式展示图片（参考 _example/imageEmpty/index.vue）：

<template> <view> <t-empty t-class="empty-cls" t-class-image="t-empty__image" :image="image" description="描述文字" /> </view> </template> <script> import TEmpty from '@tdesign/uniapp/empty/empty.vue'; export default { options: { styleIsolation: 'shared', }, components: { TEmpty, }, data() { return { image: 'https://tdesign.gtimg.com/mobile/demos/empty1.png', }; }, }; </script> <style> :deep(.t-empty__image) { width: 240rpx !important; height: 240rpx !important; } </style>

注意示例中通过:deep(.t-empty__image)覆盖图片尺寸，这是图片空状态定制尺寸的常用手法。从 empty.vue 的模板可以看到，当同时传入image时，图片优先级高于icon，且二者都未提供时才会渲染image插槽。

3.3 带操作空状态

在空状态下方放置操作按钮，引导用户执行“刷新”“重新加载”“去创建”等动作（参考 _example/buttonEmpty/index.vue）：

<template> <view> <t-empty icon="info-circle-filled" description="描述文字"> <template #action> <t-button theme="primary" size="large"> 操作按钮 </t-button> </template> </t-empty> </view> </template> <script> import TButton from '@tdesign/uniapp/button/button.vue'; import TEmpty from '@tdesign/uniapp/empty/empty.vue'; export default { components: { TEmpty, TButton, }, }; </script>

四、Empty Props 详解

组件 Props 定义位于 props.ts，对应的 TypeScript 接口位于 type.ts。

| 名称 | 类型 | 默认值 | 描述 | 必传 | | -- | -- | -- | -- | -- | | custom-style | Object | - | 自定义样式 | N | | description | String | - | 描述文字 | N | | icon | String / Object | - | 图标名称。值为字符串表示图标名称，值为Object类型，表示透传至icon| N | | image | String | - | 图片地址 | N |

4.1 custom-style

用于为组件根节点注入自定义样式。需要注意的是，虽然文档表中标注类型为Object，但实际在组件框架层 instantiationDecorator.js 中将customStyle定义为[String, Object]的联合类型，默认值为空字符串，因此字符串与对象两种写法均可被接受。在 empty.vue 中，该样式通过tools._style([customStyle])处理后绑定到根节点view上。

4.2 description

描述文字，直接渲染在图标或图片下方。从 empty.less 的样式实现看，描述区域设置了white-space: pre-wrap，这意味着描述文本中的换行符会被保留，可以自然实现多行描述。

4.3 icon

支持两种取值形式：

• 字符串：直接传图标名称，例如icon="info-circle-filled"；
• 对象：透传给t-icon组件的属性集合。

对象形式的底层转换逻辑位于 common/utils.js 的setIcon函数：当icon为字符串时，内部将其转换为iconName；当为对象时，则整体作为iconData传递。最终在 empty.vue 模板中，iconData上的style、prefix、name、size、color、ariaHidden、ariaLabel、ariaRole等字段会被逐一透传给内部t-icon组件。因此对象形式实际支持的能力包括：

<t-empty :icon="{ name: 'info-circle-filled', size: '40px', color: '#0052d9', prefix: 't', style: 'margin-top: 8rpx', ariaLabel: '暂无数据', }" description="描述文字" />

4.4 image

图片地址。传入后组件内部使用t-image组件以aspectFit模式渲染图片（见 empty.vue），可保证图片等比缩放且完整显示。

五、Empty Slots 插槽

组件提供三个具名插槽，用于在保持组件骨架不变的前提下完全自定义局部内容。

| 名称 | 描述 | | -- | -- | | action | 操作按钮 | | description | 自定义description显示内容 | | image | 自定义image显示内容 |

插槽的渲染优先级从 empty.vue 模板中可以明确看出：

1. image 区域：image属性 >icon属性 >image插槽（即插槽仅在未传图片且未传图标时生效）；
2. description 区域：description属性与description插槽同时渲染（属性文本在上，插槽内容紧随其后）；
3. action 区域：仅渲染action插槽内容。

六、Empty External Classes 外部样式类

外部样式类是 TDesign 组件库为适配小程序、Uniapp 平台样式隔离机制提供的定制入口，允许开发者在外部通过 class 覆盖组件内部节点样式。组件声明见 empty.vue。

| 类名 | 描述 | | -- | -- | | t-class | 根节点样式类 | | t-class-description | 描述样式类 | | t-class-image | 图片样式类 |

同时源码中还额外声明了t-class-actions（操作区样式类，文档未单列但可直接使用）。用法示例：

<t-empty t-class="empty-cls" t-class-description="t-empty__desc" t-class-image="t-empty__image" description="描述文字" />

外部样式类通常需配合styleIsolation: 'shared'使用（组件与页面中均已设置），结合:deep()选择器即可精确控制内部节点样式。

七、CSS 变量与主题定制

Empty 组件在 empty.less 中通过 CSS 变量预留了完整的定制能力，所有默认值均来自 TDesign 设计令牌（token），可通过在页面或page节点上覆盖变量实现全局或局部主题定制。

| 变量名 | 默认值 | 描述 | | -- | -- | -- | | --td-empty-action-margin-top | @spacer-4 | 操作区顶部间距 | | --td-empty-description-color | @text-color-placeholder | 描述文字颜色 | | --td-empty-description-font | @font-body-medium | 描述文字字体 | | --td-empty-description-margin-top | @spacer-2 | 描述区顶部间距 | | --td-empty-icon-color | @text-color-placeholder | 图标颜色 |

各默认 token 的具体取值（均可从仓库中溯源）：

• @spacer-2=32rpx，@spacer-4=64rpx，定义于 theme/raw/_spacer.less；
• @text-color-placeholder实际为var(--td-text-color-placeholder, @font-gray-3)，定义于 style/_variables.less；
• @font-body-medium实际为var(--td-font-body-medium, 28rpx / 44rpx @font-family)，即字号 28rpx、行高 44rpx，定义于 style/_variables.less，其完整字体族与字号/行高令牌可参考 theme/raw/_font.less。

组件在使用变量时统一采用var(--td-xxx, 默认值)的兜底写法，例如：

@empty-description-color: var(--td-empty-description-color, @text-color-placeholder);

因此即使主题变量未被覆盖，组件也能正常工作；一旦覆盖即立即生效。典型定制示例：

page { --td-empty-description-color: #0052d9; /* 描述文字改为主题蓝 */ --td-empty-icon-color: #999; /* 图标颜色 */ --td-empty-description-margin-top: 48rpx; /* 加大描述与图标间距 */ --td-empty-action-margin-top: 80rpx; /* 加大操作区与描述间距 */ }

八、源码原理小结

综合来看，Empty 组件的实现遵循了 TDesign Uniapp 组件库的通用工程化模式：

1. Props 与类型分离：props.ts（运行时声明）与 type.ts（TdEmptyProps接口）由脚本自动生成并保持一致，二者通过uniComponent组装进组件；
2. 图标归一化：icon属性无论传字符串还是对象，都统一经过 common/utils.js 的setIcon转为iconName/iconData两路数据，再交由t-icon渲染；
3. 样式令牌化：颜色、间距、字体全部通过 CSS 变量承接设计令牌，便于全局换肤与局部覆盖；
4. 平台兼容：通过外部样式类、styleIsolation: 'shared'、虚拟宿主判断（canUseVirtualHost）等机制同时兼容小程序与各端运行环境。

掌握了这些原理与上文完整覆盖的 Props、Slots、外部样式类和 CSS 变量四套定制入口，你就可以在任何 TDesign Uniapp 项目中轻松搭建贴合业务场景的空状态页面。

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