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

TDesign（tdesign-miniprogram）的 Toast 组件用于轻量级反馈或提示，不会打断用户操作，是 UniApp 项目中最常用的全局反馈手段之一。本篇基于仓库中packages/uniapp-components/toast/README.md的完整 API 文档展开，结合组件源码 toast.vue、脚本入口 index.js 与各示例页面，讲清楚 Toast 的引入方式、四种典型用法（基础提示、组件状态、遮罩、手动关闭）、完整 Props/Events/Slots API，以及 CSS 变量级别的样式定制，读完即可在 UniApp 项目中独立落地任意场景的轻提示。

组件构成与目录结构

Toast 组件在仓库中的完整目录如下，理解各文件职责有助于快速定位问题：

| 文件 | 职责 | | -- | -- | | toast.vue | 组件本体：模板、show/hide 方法、遮罩与过渡逻辑 | | toast.less | 样式实现，暴露全部 CSS 变量 | | props.ts | Props 定义与取值校验（validator） | | type.ts | TypeScript 类型TdToastProps定义 | | index.js | 脚本调用入口：Toast/showToast/hideToast| | index.d.ts | 脚本调用的 TS 类型声明ToastOptionsType| | _example/ | base / theme / cover / close 四个官方示例 |

组件在包内通过 packages/uniapp-components/index.js 统一导出（export { default as Toast, showToast, hideToast } from './toast/index'），因此业务代码既可以按路径引入，也可以直接从@tdesign/uniapp导入脚本方法。

引入方式

方式一：easycom 模式（推荐）

官方推荐使用 easycom 模式引入组件，配置后无需手动 import 即可直接在模板中使用<t-toast />。在pages.json中添加如下配置（CLI 模式，使用node_modules下的@tdesign/uniapp）：

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

完整配置说明（含 HBuilderX 的uni_modules模式）可参考 快速开始文档。

方式二：手动引入

不使用 easycom 时，在<script>中手动导入组件：

import TToast from '@tdesign/uniapp/toast/toast.vue';

在components中注册后即可在模板中声明<t-toast ref="t-toast" />。注意所有官方示例中，Toast 实例都统一使用id/ref为t-toast的节点，这是后续脚本调用定位实例的前提。

用法一：基础提示

基础用法覆盖纯文本、多行文字、带横向图标、带竖向图标和加载状态五种形态，对应示例 _example/base/index.vue。核心是通过Toast()脚本方法向页面上的<t-toast />实例下发参数：

import { Toast } from '@tdesign/uniapp'; // 纯文本 Toast({ context: this, selector: '#t-toast', message: '轻提示文字内容' }); // 多行文字（最多不超过三行，超出省略） Toast({ context: this, selector: '#t-toast', message: '最多一行展示十个汉字宽度限制最多不超过三行文字' }); // 带横向图标（direction 缺省为 row） Toast({ context: this, selector: '#t-toast', message: '带横向图标', icon: 'check-circle' }); // 带竖向图标（图标在上、文字在下） Toast({ context: this, selector: '#t-toast', message: '带竖向图标', icon: 'check-circle', direction: 'column' }); // 加载状态（渲染 loading 图标而非普通图标） Toast({ context: this, selector: '#t-toast', message: '加载中...', theme: 'loading', direction: 'column' });

几点源码级的实现细节值得注意：

• 图标透传：icon支持字符串（内置图标名）或对象。从 toast.vue 模板看，当theme === 'loading'时组件不渲染t-icon，而是渲染一个t-loading圆形加载器（inherit-color继承反色文字）；否则将icon对象经calcIcon归一化后透传给 Icon 组件的prefix/name/size/color等属性。
• 文案行数限制：__text节点使用-webkit-line-clamp: 3限制最多三行，与示例中"最多不超过三行文字"的说明一致，见 toast.less。
• 横向/竖向尺寸差异：direction: row时内容区 padding 为28rpx 44rpx、图标尺寸 48rpx；direction: column时容器为160rpx × 160rpx最小正方形、padding48rpx、图标尺寸 64rpx。loading 且带文字时最小尺寸放大到204rpx × 204rpx。

用法二：组件状态（theme）

theme用于表达成功、警告、错误等状态类型，可选项为loading / success / warning / error。示例见 _example/theme/index.vue：

// 成功提示 Toast({ context: this, selector: '#t-toast', message: '成功文案', theme: 'success', direction: 'column' }); // 警告提示 Toast({ context: this, selector: '#t-toast', message: '警告文案', theme: 'warning', direction: 'column' }); // 错误提示 Toast({ context: this, selector: '#t-toast', message: '错误文案', theme: 'error', direction: 'column' });

theme取值本身不带图标，图标由组件内部映射。从 toast.vue 的 show() 方法 可以看到映射表：

| theme | 实际渲染 | | -- | -- | |loading|t-loading圆形加载动画（非静态图标） | |success|check-circle图标 | |warning|error-circle图标（源码iconMap中的映射） | |error|close-circle图标 |

优先级规则：当theme命中映射表时优先使用映射图标；未命中时才回退到调用方显式传入的icon（源码中使用coalesce(typeMapIcon, options.icon)合并）。此外theme还会影响根节点 class（t-toast--success等），便于针对特定状态覆写样式。

用法三：显示遮罩与防止滚动穿透

show-overlay控制是否显示半透明遮罩层，prevent-scroll-through控制显示期间是否禁止页面点击与滚动。示例见 _example/cover/index.vue：

Toast({ context: this, selector: '#t-toast', message: '禁止滑动和点击', direction: 'column', duration: 3000, preventScrollThrough: true, // 显示期间禁止滑动和点击 icon: 'poweroff', });

从 toast.vue 的遮罩绑定逻辑 看，遮罩由内部t-overlay实现，其显示条件为visible && (showOverlay || dataPreventScrollThrough)，即开启防穿透但不开遮罩时也会渲染一个背景透明的 Overlay来拦截触摸事件，这正是"禁止滑动和点击但保持页面可见"效果的实现方式。遮罩默认z-index: 11000，可通过overlay-props透传zIndex、duration、backgroundColor、preventScrollThrough等 Overlay 属性定制，其完整类型见 Overlay 组件 API 文档。

Toast 主体自身通过@touchstart.stop.prevent阻止触摸事件冒泡，避免显示期间误触页面元素。

用法四：手动关闭（duration 控制）

duration决定自动隐藏时间（毫秒）。从 toast.vue 的定时逻辑 看，只有duration > 0才会启动隐藏定时器；因此传入0或负数（示例中用-1）可让 Toast 保持显示，直到手动调用hideToast关闭。示例见 _example/close/index.vue：

import { Toast, hideToast } from '@tdesign/uniapp'; // 显示提示：duration 为 -1，永不自动消失 handleShow() { Toast({ context: this, selector: '#t-toast', duration: -1, message: '轻提示文字内容' }); }, // 手动关闭 handleHide() { hideToast({ context: this, selector: '#t-toast' }); },

脚本入口 index.js 中三个函数的职责：

| 函数 | 说明 | | -- | -- | |Toast(options)（默认导出） | 定位实例并调用其show()；duration缺省合并为2000毫秒 | |showToast(options)|Toast的别名 | |hideToast(options)| 定位实例并调用其hide()|

定位逻辑为getInstance(context, selector)，context传页面/组件实例（this），selector缺省为'#t-toast'。Toast参数结构（ToastOptionsType）见 index.d.ts，包含context / selector / icon / message / duration / theme / placement / preventScrollThrough / direction / close字段，其中close为可选回调，在 Toast 隐藏时执行。

API 参考

Toast Props

| 名称 | 类型 | 默认值 | 描述 | 必传 | | -- | -- | -- | -- | -- | | custom-style | Object | - | 自定义样式 | N | | direction | String | row | 图标排列方式。可选项：row/column | N | | duration | Number | 2000 | 弹窗显示毫秒数 | N | | icon | String / Object | - | 自定义图标。传入对象则透传至 Icon 组件 | N | | message | String | - | 弹窗显示文字 | N | | overlay-props | Object | - | 遮罩层属性，透传至 Overlay。TS 类型：OverlayProps，Overlay API Documents。详细类型定义 | N | | placement | String | middle | 弹窗展示位置。可选项：top/middle/bottom | N | | prevent-scroll-through | Boolean | false | 防止滚动穿透，即不允许点击和滚动 | N | | show-overlay | Boolean | false | 是否显示遮罩层 | N | | theme | String | - | 提示类型。可选项：loading/success/warning/error | N | | using-custom-navbar | Boolean | false | 是否使用了自定义导航栏 | N |

取值约束在 props.ts 中以validator明确校验：direction仅接受row/column，placement仅接受top/middle/bottom，theme仅接受loading/success/warning/error。

placement 的定位实现：模板中根节点内联样式直接映射为top: 25%（top）/45%（middle）/75%（bottom），配合left: 50%与transform: translate(-50%, -50%)实现三档垂直居中定位，见 toast.vue 模板 与 toast.less。

Toast Events

| 名称 | 参数 | 描述 | | -- | -- | -- | | close | - | 轻提示隐藏的时候触发 | | destroy | - | 轻提示销毁的时候触发 |

触发时机在源码中可验证：hide()内this.$emit('close')（同时执行外部传入的close回调）；beforeUnmount生命周期触发destroyed()并清理隐藏定时器后发出销毁事件，见 toast.vue。从源码结构看，销毁事件实际发出的事件名为destory（代码中的拼写），监听时以仓库事件实现为准。

Toast Slots

| 名称 | 描述 | | -- | -- | | icon | 自定义图标 | | message | 弹窗显示文字 |

Toast External Classes

| 类名 | 描述 | | -- | -- | | t-class | 根节点样式类 |

CSS Variables

组件提供了下列 CSS 变量，可用于自定义样式。默认值在 toast.less 中定义：

| 名称 | 默认值 | 描述 | | -- | -- | -- | | --td-toast-bg-color | @mask-active | 背景色（主题变量@mask-active即rgba(0, 0, 0, 0.6)，见 _variables.less） | | --td-toast-color | @text-color-anti | 文字/图标反色 | | --td-toast-column-icon-size | 64rpx | 竖向排列图标尺寸 | | --td-toast-max-width | 370rpx | 最大宽度 | | --td-toast-radius | @radius-default | 圆角 | | --td-toast-row-icon-size | 48rpx | 横向排列图标尺寸 |

例如仅调整背景透明度：

page { --td-toast-bg-color: rgba(0, 0, 0, 0.5); }

生命周期与细节行为

• 页面隐藏自动关闭：组件注册了pageLifetimes.hide，页面切到后台时自动调用hide()，避免 Toast 残留（toast.vue）。
• 重复触发保护：hide()内部有realVisible判断，防止"页面关闭"与"定时关闭"两条路径重复触发 close 事件。
• 层级与过渡：Toast 根节点z-index: 12001，显示/隐藏使用t-fade-enter / t-fade-leave-to类配合opacity 300ms ease过渡，由transitionMixins提供（@transitionend中切换过渡类）。
• 样式隔离：组件声明styleIsolation: 'shared'，页面全局样式可作用于组件，配合上述 CSS 变量即可完成定制。

小结

TDesign UniApp 的 Toast 以"页面放置<t-toast />占位 + 脚本方法下发参数"的模式工作：Toast/showToast负责按selector定位实例并显示，hideToast负责手动关闭；theme决定状态图标，direction/placement决定布局形态与位置，duration小于等于 0 时进入常驻模式，show-overlay与prevent-scroll-through分别控制遮罩与交互拦截。全部行为与参数均可在 toast.vue、toast.less、props.ts 与 _example/ 目录的四个官方示例中逐条对照验证。

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