前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载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前缀作为 classprefix定义在 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.vuetemplate view t-empty iconinfo-circle-filled description描述文字 / /view /template3.2 自定义图片空状态当图标无法满足诉求时可通过image属性传入图片地址组件内部会复用t-image组件以aspectFit模式展示图片参考 _example/imageEmpty/index.vuetemplate view t-empty t-classempty-cls t-class-imaget-empty__image :imageimage 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.vuetemplate view t-empty iconinfo-circle-filled description描述文字 template #action t-button themeprimary sizelarge 操作按钮 /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支持两种取值形式字符串直接传图标名称例如iconinfo-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 模板中可以明确看出image 区域image属性 icon属性 image插槽即插槽仅在未传图片且未传图标时生效description 区域description属性与description插槽同时渲染属性文本在上插槽内容紧随其后action 区域仅渲染action插槽内容。六、Empty External Classes 外部样式类外部样式类是 TDesign 组件库为适配小程序、Uniapp 平台样式隔离机制提供的定制入口允许开发者在外部通过 class 覆盖组件内部节点样式。组件声明见 empty.vue。| 类名 | 描述 | | -- | -- | | t-class | 根节点样式类 | | t-class-description | 描述样式类 | | t-class-image | 图片样式类 |同时源码中还额外声明了t-class-actions操作区样式类文档未单列但可直接使用。用法示例t-empty t-classempty-cls t-class-descriptiont-empty__desc t-class-imaget-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-232rpxspacer-464rpx定义于 theme/raw/_spacer.lesstext-color-placeholder实际为var(--td-text-color-placeholder, font-gray-3)定义于 style/_variables.lessfont-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 组件库的通用工程化模式Props 与类型分离props.ts运行时声明与 type.tsTdEmptyProps接口由脚本自动生成并保持一致二者通过uniComponent组装进组件图标归一化icon属性无论传字符串还是对象都统一经过 common/utils.js 的setIcon转为iconName/iconData两路数据再交由t-icon渲染样式令牌化颜色、间距、字体全部通过 CSS 变量承接设计令牌便于全局换肤与局部覆盖平台兼容通过外部样式类、styleIsolation: shared、虚拟宿主判断canUseVirtualHost等机制同时兼容小程序与各端运行环境。掌握了这些原理与上文完整覆盖的 Props、Slots、外部样式类和 CSS 变量四套定制入口你就可以在任何 TDesign Uniapp 项目中轻松搭建贴合业务场景的空状态页面。赞分享前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐TDesign Uniapp Empty 空状态组件实战指南引入、属性、插槽与样式定制TDesign Uniapp Empty 空状态组件实战指南引入、属性、插槽与样式定制 Empty 空状态组件是 TDesign 移动端组件库中用于列表无数前端UI组件小程序设计系统移动开发TDesign 小程序 Empty 空状态组件Props 参数、插槽定制与 CSS 变量完整指南TDesign 小程序 Empty 空状态组件Props 参数、插槽定制与 CSS 变量完整指南 空状态Empty是数据展示类页面最常见的占位组件用于列前端UI组件小程序设计系统移动开发TDesign Uniapp FormItem 表单项组件实战指南Props、插槽、校验机制与样式定制TDesign Uniapp FormItem 表单项组件实战指南Props、插槽、校验机制与样式定制 导读 TDesigntdesign miniprog前端UI组件小程序设计系统移动开发上一篇Hive 框架 Bounty 贡献者指南从领取赏金到晋升 Core Contributor 的完整实战手册下一篇Apereo CAS REST 认证策略REST Authentication Policy配置指南通过外部接口检测账号状态与登录策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考