前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载TDesigntdesign-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 reft-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、图标尺寸 48rpxdirection: column时容器为160rpx × 160rpx最小正方形、padding48rpx、图标尺寸 64rpx。loading 且带文字时最小尺寸放大到204rpx × 204rpx。用法二组件状态themetheme用于表达成功、警告、错误等状态类型可选项为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还会影响根节点 classt-toast--success等便于针对特定状态覆写样式。用法三显示遮罩与防止滚动穿透show-overlay控制是否显示半透明遮罩层prevent-scroll-through控制显示期间是否禁止页面点击与滚动。示例见 _example/cover/index.vueToast({ 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.vueimport { 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传页面/组件实例thisselector缺省为#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 类型OverlayPropsOverlay 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/columnplacement仅接受top/middle/bottomtheme仅接受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组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐TDesign Uniapp Toast 轻提示组件从 API 参考到源码级实现原理TDesign Uniapp Toast 轻提示组件从 API 参考到源码级实现原理 TDesign Uniapp tdesign/uniapp 的 T前端UI组件小程序设计系统移动开发TDesign UniApp TabBar 标签栏组件实战指南API 配置、事件交互与样式定制TDesign UniApp TabBar 标签栏组件实战指南API 配置、事件交互与样式定制 TabBar标签栏是 TDesign UniApp 组件库前端UI组件小程序设计系统移动开发tdesign-uniapp Cell 单元格组件完全指南属性、插槽、样式定制与 CellGroup 分组实战tdesign uniapp Cell 单元格组件完全指南属性、插槽、样式定制与 CellGroup 分组实战 Cell 单元格是 TDesign 移动端体系前端UI组件小程序设计系统移动开发上一篇tfsec CloudStack 检查详解防止 user_data 中的敏感信息泄露cloudstack-compute-no-sensitive-info下一篇AtlasOSWindows系统优化与隐私保护的完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
