Toast 轻提示

介绍

在页面指定位置显示轻提示，用于操作反馈、加载状态等场景。采用命令式调用，支持文本提示、图标提示、加载动画、动态更新等功能。

引入

import { TnToast, TnToastOption, TnToastLoadingOption } from "@tuniao/tn-ui";

代码演示

基础用法

通过 TnToast.show() 方法展示轻提示，传入字符串或 TnNotifyOption 配置项。默认居中显示，1.5 秒后自动关闭。

点我查看代码

// 文本提示
TnToast.show("操作成功");

// 配置对象
const option: TnToastOption = new TnToastOption();
option.message = "提交成功";
option.duration = 2000;
TnToast.show(option);

提示类型

通过 type 属性设置提示的图标类型，支持 success、warning、fail、loading 四种类型。

点我查看代码

// 成功提示
const success: TnToastOption = new TnToastOption();
success.message = "提交成功";
success.type = "success";
TnToast.show(success);

// 警告提示
const warning: TnToastOption = new TnToastOption();
warning.message = "请注意检查";
warning.type = "warning";
TnToast.show(warning);

// 失败提示
const fail: TnToastOption = new TnToastOption();
fail.message = "操作失败";
fail.type = "fail";
TnToast.show(fail);

// 加载提示
const loading: TnToastOption = new TnToastOption();
loading.message = "加载中...";
loading.type = "loading";
loading.duration = 0; // 不自动关闭
TnToast.show(loading);

自定义图标

通过 icon 属性设置自定义图标，支持图片路径或资源。自定义图标优先级高于 type。

点我查看代码

const option: TnToastOption = new TnToastOption();
option.message = "自定义图标提示";
option.icon = $r("app.media.custom_icon");
option.iconSize = 40;
TnToast.show(option);

显示位置

通过 position 属性设置提示的显示位置，支持 top（顶部）、center（居中）、bottom（底部），默认为 center。

点我查看代码

// 顶部显示
const top: TnToastOption = new TnToastOption();
top.message = "顶部提示";
top.position = "top";
TnToast.show(top);

// 居中显示（默认）
const center: TnToastOption = new TnToastOption();
center.message = "居中提示";
center.position = "center";
TnToast.show(center);

// 底部显示
const bottom: TnToastOption = new TnToastOption();
bottom.message = "底部提示";
bottom.position = "bottom";
TnToast.show(bottom);

文字换行

通过 wordBreak 属性设置文本换行模式，支持 normal（正常换行）、break-all（任意字符换行）、break-word（单词边界换行）。

点我查看代码

// 正常换行
const normal: TnToastOption = new TnToastOption();
normal.message = "Hello World Abcdefghijklmnopqrstuvwxyz12345 End";
normal.wordBreak = "normal";
TnToast.show(normal);

// 任意字符换行
const breakAll: TnToastOption = new TnToastOption();
breakAll.message = "Hello World Abcdefghijklmnopqrstuvwxyz12345 End";
breakAll.wordBreak = "break-all";
TnToast.show(breakAll);

// 单词边界换行
const breakWord: TnToastOption = new TnToastOption();
breakWord.message = "Hello World Abcdefghijklmnopqrstuvwxyz12345 End";
breakWord.wordBreak = "break-word";
TnToast.show(breakWord);

自定义时长

通过 duration 属性设置提示自动关闭的时长，单位为毫秒，默认 1500。设置为 0 时不自动关闭，需调用 TnToast.hide() 手动关闭。

点我查看代码

// 1 秒后关闭
const fast: TnToastOption = new TnToastOption();
fast.message = "1秒后关闭";
fast.duration = 1000;
TnToast.show(fast);

// 5 秒后关闭
const slow: TnToastOption = new TnToastOption();
slow.message = "5秒后关闭";
slow.duration = 5000;
TnToast.show(slow);

// 不自动关闭
const manual: TnToastOption = new TnToastOption();
manual.message = "需手动关闭";
manual.duration = 0;
TnToast.show(manual);

// 手动关闭
TnToast.hide();

加载提示

使用 TnToast.showLoading() 快捷方法显示加载提示，支持三种加载动画模式：circle（圆形）、flower（花朵）、semicircle（半圆）。

点我查看代码

// 圆形加载（默认）
const circle: TnToastLoadingOption = new TnToastLoadingOption();
circle.message = "加载中...";
circle.loadingMode = "circle";
TnToast.showLoading(circle);

// 花朵加载
const flower: TnToastLoadingOption = new TnToastLoadingOption();
flower.message = "处理中...";
flower.loadingMode = "flower";
TnToast.showLoading(flower);

// 半圆加载（自定义颜色）
const semicircle: TnToastLoadingOption = new TnToastLoadingOption();
semicircle.message = "上传中...";
semicircle.loadingMode = "semicircle";
semicircle.loadingColor = "#01beff";
TnToast.showLoading(semicircle);

// 异步操作完成后关闭
setTimeout(() => {
  TnToast.hide();
}, 2000);

动态更新

通过 TnToast.message 属性动态更新提示文本，常用于进度提示场景。

点我查看代码

// 显示加载提示
const loading: TnToastLoadingOption = new TnToastLoadingOption();
loading.message = "上传中 0%";
TnToast.showLoading(loading);

// 模拟上传进度
let progress: number = 0;
const timer: number = setInterval(() => {
  progress += 10;
  TnToast.message = `上传中 ${progress}%`;

  if (progress >= 100) {
    clearInterval(timer);
    TnToast.hide();
    TnToast.show({ message: "上传完成", type: "success" });
  }
}, 300);

位置偏移

通过 offsetY 属性设置提示在 Y 轴方向的偏移量，单位为 vp。正值向下偏移，负值向上偏移。

点我查看代码

// 向下偏移
const down: TnToastOption = new TnToastOption();
down.message = "向下偏移 50vp";
down.position = "center";
down.offsetY = 50;
TnToast.show(down);

// 向上偏移
const up: TnToastOption = new TnToastOption();
up.message = "向上偏移 50vp";
up.position = "center";
up.offsetY = -50;
TnToast.show(up);

遮罩层

通过 isShowMask 属性控制是否显示背景遮罩层，遮罩层可防止用户在提示显示期间操作页面。

点我查看代码

const option: TnToastOption = new TnToastOption();
option.message = "处理中，请稍候...";
option.type = "loading";
option.isShowMask = true;
option.duration = 0;
TnToast.show(option);

// 异步操作完成后关闭
setTimeout(() => {
  TnToast.hide();
}, 3000);

事件回调

支持 onOpen 和 onClose 两种事件回调，分别在提示打开和关闭时触发。

点我查看代码

const option: TnToastOption = new TnToastOption();
option.message = "操作成功";
option.type = "success";
option.onOpen = () => {
  console.info("提示已打开");
};
option.onClose = () => {
  console.info("提示已关闭");
};
TnToast.show(option);

API

方法

方法名	说明	参数	返回值
TnToast.show	显示轻提示	option: string | TnToastOption	void
TnToast.showLoading	显示加载提示（快捷方法）	option?: TnToastLoadingOption	void
TnToast.hide	关闭当前提示	-	void
TnToast.message	动态更新提示文本（setter）	msg: string	-

TnToastOption

参数	说明	类型	默认值
message	提示文本内容	string	""
type	图标类型	TnToastType	-
duration	自动关闭时长(ms)，0 为不自动关闭	number	1500
position	显示位置	TnToastPosition	"center"
wordBreak	文本换行模式	TnToastWordBreak	"normal"
icon	自定义图标（优先级高于 type）	ResourceStr	-
iconSize	图标尺寸(vp)	number	36
isShowMask	是否显示背景遮罩层	boolean	false
offsetY	Y 轴偏移量(vp)	number	0
loadingMode	加载动画模式（type 为 loading 时生效）	TnLoadingModeType	"circle"
loadingColor	加载动画颜色（type 为 loading 时生效）	ResourceColor	白色
onOpen	提示打开后的回调	() => void	-
onClose	提示关闭后的回调	() => void	-

TnToastLoadingOption

参数	说明	类型	默认值
message	提示文本内容	string	""
duration	自动关闭时长(ms)，默认 0 不自动关闭	number	0
loadingMode	加载动画模式	TnLoadingModeType	"circle"
loadingColor	加载动画颜色	ResourceColor	白色

类型定义

// 提示图标类型
type TnToastType = "success" | "warning" | "fail" | "loading";

// 提示显示位置
type TnToastPosition = "top" | "center" | "bottom";

// 文本换行模式
type TnToastWordBreak = "normal" | "break-all" | "break-word";

// 加载动画模式
type TnLoadingModeType = "circle" | "flower" | "semicircle";