n-toast 轻提示

命令式反馈组件：页面放置一个实例，经 ref 调用 open(options) 弹出、close() 手动关闭。消息内容 / 类型 / 位置 / 时长逐次调用各异，全部走 open 的 options；props 只承载全局默认（下次 open 生效）。单实例替换式：展示中再次 open 即替换内容并重启计时，不叠层。

1. 两种形态：mode="box" 深色圆角块（默认，position 三档定位）；mode="banner" 通栏通知条（全宽功能色底白字，钉顶或钉底，沿钉放端滑入）
2. type 预设八类：success / error / warning / info / primary / question / loading / none——box 决定图标、banner 决定图标 + 底色；loading 显示加载圈（收起需调 close()，如配合 duration: 0）
3. icon / image 可覆盖预设图标；message 留空且默认插槽有内容时走插槽完全自定义
4. mask 开启后全屏阻断页面点击与滚动（点遮罩不关闭，对齐系统 toast 语义）；默认关闭、页面照常交互
5. duration 传 0 表示不自动关闭，由业务在恰当时机调 close()

平台兼容性

App	H5	微信小程序	支付宝小程序	百度小程序	头条小程序	QQ小程序
√	√	√	×	×	×	×

如何调用

页面放一个实例后有两种调用方式，打到同一个实例：

函数式（推荐）：useUi() 从库主入口导入（每文件一行），按当前页面自动路由到本页实例，无需 ref 绑定；页面栈内多页共存时互不串扰。设计语言对齐参考源 useUi 入口形态，未来 modal / action-sheet 等命令式组件陆续并入同一入口：

<template>
	<n-toast />
</template>

import { useUi } from "../../uni_modules/new-ui"; // 路径按页面相对层级调整

// 最简调用：一条纯文案提示（box 居中，2 秒自动收起）
function tip() {
	useUi().showToast({ message: "已保存" });
}

// 带类型图标 + 位置 + 时长
function ok() {
	useUi().showToast({ message: "提交成功", type: "success", duration: 1500 });
}

// 手动收起（duration: 0 不自动关）
function busyStart() {
	useUi().showToast({ message: "提交中...", type: "loading", duration: 0 });
}
function busyEnd() {
	useUi().hideToast();
}

全部调用字面量直传即可，类型自动推断，无需导入任何 type；NToastOptions 仅在显式标注变量时可选导入（import { type NToastOptions } from "../../uni_modules/new-ui"）。全部字段见下方「open(options) 参数」。当前页面未挂载 <n-toast /> 时 showToast 不做任何事并控制台提示，不影响页面其它逻辑。

ref 直调：页面内放多个实例需要分别控制时用；NToastComponentPublicInstance 是 uni-app x 编译器为 easycom 组件自动生成的全局类型（组件名驼峰 + ComponentPublicInstance），defineExpose 暴露的方法在其上可见，类型无需 import：

<template>
	<n-toast ref="toast" />
</template>

import { ref } from "vue";

const toast = ref<NToastComponentPublicInstance | null>(null);

toast.value?.open({ message: "已保存" });
toast.value?.close();

API

属性

参数	说明	类型	默认值	可选值
duration	默认展示时长（毫秒，open 未传 duration 时生效）；0 = 不自动关闭	Number	2000	-
position	默认显示位置（open 未传 position 时生效）：box 三档 top 距顶约 15% 视口高 / center / bottom 距底 120px；banner 通栏仅 top/bottom 生效（center 归一为顶部）	String	center	top / center / bottom
mode	默认形态（open 未传 mode 时生效）	String	box	box / banner
type	默认类型（open 未传 type 时生效）	String	none	success / error / warning / info / primary / question / loading / none
align	默认文本水平对齐（banner 形态，open 未传 align 时生效）	String	center	left / center / right
show-icon	默认显示类型图标（banner 形态，open 未传 show-icon 时生效）	Boolean	true	-
mask	默认透明遮罩开关（open 未传 mask 时生效）：true 时阻断页面点击与滚动	Boolean	false	-
safe-area-inset-top	通知条垫高顶部安全区（状态栏高度，仅 banner 钉顶时生效）：自定义导航 / 沉浸式状态栏页面开启，带原生导航栏的页面视口本就不含状态栏	Boolean	false	-
safe-area-inset-bottom	通知条垫高底部安全区（小白条/手势条高度，仅 banner 钉底时生效）：钉底通栏贴屏幕底，默认垫高使文案不进手势条区域	Boolean	true	-
z-index	弹层层级：0 = 跟随内置默认（1050，高于弹窗、低于整页加载）；大于 0 写入根节点	Number	0	-
background	深色块底色 / 通知条底色（任意 CSS 色值）；空串取令牌（box 半透明黑，banner 按类型取功能色）	String	""	与 css 相同
color	文字与图标颜色（任意 CSS 色值）；空串取白色	String	""	与 css 相同
text-style	微调文案的行内样式，如 "font-size:16px;letter-spacing:1px"	String	""	与 css 相同
custom-class	挂到根节点的额外 class（类需定义在组件样式表内，如覆盖层级的自定义类）	String	""	-
custom-style	根节点行内样式	String	""	与 css 相同

open(options) 参数

参数	说明	类型	默认值	可选值
message	提示文案（空串且默认插槽有内容时走插槽内容；与图标、类型全空且无插槽时不弹）	String	-	-
type	预设类型：box 决定图标、banner 决定图标 + 底色；loading 显示加载圈	String	props.type	success / error / warning / info / primary / question / loading / none
icon	自定义图标名（n-icon 内置名），非空覆盖 type 图标	String	-	-
image	自定义图片地址，非空覆盖图标（n-icon 图片模式）	String	-	-
position	显示位置：box 三档 top/center/bottom；banner 通栏仅 top/bottom 生效（钉顶/钉底，center 归一为顶部）	String	props.position	top / center / bottom
mode	形态：box 深色圆角块 / banner 顶部通知条	String	props.mode	box / banner
duration	展示时长（毫秒）；0 = 不自动关闭（配合 close() 手动收起）	Number	props.duration	-
mask	透明遮罩阻断页面点击与滚动（点遮罩不关闭，对齐系统 toast 语义）	Boolean	props.mask	-
align	文本水平对齐（仅 banner 生效；box 恒居中）	String	props.align	left / center / right
show-icon	显示类型图标（仅 banner 生效，box 恒显示）	Boolean	props.show-icon	-
background	底色覆盖：box 深色块底色 / banner 功能色底（任意 CSS 色值）	String	props.background	与 css 相同
color	文字与图标颜色覆盖（缺省白色）	String	props.color	与 css 相同
z-index	弹层层级：大于 0 时覆盖内置层级	Number	props.z-index	-

方法

函数式 useUi().showToast(options) / useUi().hideToast()，或 ref 直调组件的 open(options) / close()：

方法	说明	参数
open	弹出轻提示；展示中调用即替换内容并重启计时（单实例替换式，不叠层）	options?: NToastOptions
close	手动关闭；duration: 0 的提示（如加载中）由此收起，未在展示中时调用无效果	无

事件

事件名	说明	回调参数
open	调用 open() 弹出时触发（入场过渡开始前）	-
close	开始关闭时触发（计时到点自动收起或调用 close()；退场过渡完成后整体卸载）	-

插槽

插槽名	说明
default	完全自定义提示内容（message 留空时生效），排版自管；深底上请用浅色文字

实现说明

• 命令式而非受控：toast 的消息 / 类型 / 位置 / 时长逐次调用各异，受控模式要求使用者自管关闭计时器；props 全部是全局默认、open(options) 逐次覆盖，与系统 toast 的调用习惯一致。全部参数在 open() 时刻定格为快照，运行中改 props 不影响已弹出的提示。
• 单实例替换式：展示中再次 open 即替换内容并重启计时，不叠层——对齐系统 toast 语义；叠层列表会让多条提示互相遮挡、收起时序混乱。
• 点击策略在根节点整体切换：mask 关闭时根挂 pointer-events: none 全端穿透（页面照常交互）；开启时恢复命中并以空 tap 处理器 + 触摸移动拦截阻断点击与滚动。不做"穿透根 + 可点遮罩子层"——App 端父层 pointer-events: none 时子元素即使显式设回 auto 也不响应（官方 CSS 兼容性说明），拦截与穿透必须整体在根上切。点遮罩不关闭提示，对齐系统 toast。
• 通知条通栏钉顶或钉底（center 对通栏无意义，归一为顶部），入场沿钉放端滑入：顶部条从上、底部条从下；钉底默认垫底部安全区（safe-area-inset-bottom，对齐 n-popup 同名语义），文案不进小白条/手势条区域；钉顶的安全区垫高用 safe-area-inset-top。
• 通知条图标 20px、文字行高同为 20px（等高行盒，居中不基线错位）；文字与图标间距挂在图标上。长文案会换行但行距同值，通知条建议保持单行，长提示用 box 形态。
• safe-area-inset-top 默认关闭：顶部安全区高度是屏幕系数值，带原生导航栏的页面视口本就不含状态栏，默认垫高反而多出一截；自定义导航 / 沉浸式状态栏页面开启即可正确避让。
• 深色块底色为半透明黑（悬浮于任意内容之上保留环境感），通知条底色直接取五个功能色令牌随深浅主题联动；文字与图标缺省白色，color 可整体换色。层级默认 1050：高于弹窗（1000）、低于整页加载（1100）。

机制对照与未采纳项

同类组件（深色块提示 / 顶部通知条 / 图片小方块提示）三系参考源逐一摸排后的取舍：

参考源机制	本库取舍
多条叠层队列 + 逐条 id 关闭 + 「只保留当前」清除参数	不采纳叠层：对齐系统 toast 的单实例替换式（再次 open 即替换重启计时）——叠层时多条互相遮挡、收起时序混乱，需要排队的是消息中心场景（用 n-popup 组合）
带图标时强制居中定位	位置语义交给使用者：position 独立可控，带图标同样可钉顶 / 钉底
内距数组 / 图标宽 / 字号等样式 props	走主题令牌（--n-toast-* / $n-toast-*）与 text-style 行内通道，不铺逐项样式 props
图片小方块提示（图片 + 可选文案）	已覆盖：image 字段 + message 留空即纯图标 / 纯图片形态
通知条受控显隐（show 受控 + 双向更新）、自定义 top 偏移、字号 prop	命令式 open / close（逐次参数各异是本质）；钉顶 / 钉底 + safe-area-inset-top 垫高覆盖 top 偏移场景；字号走 text-style
预设类型含「禁用 / 停止」等图标	预设八类之外用 icon 自定义图标名覆盖
通栏形态的独立开关	mode 双形态（box / banner）逐次可切，banner 即通栏形态

新窗口 ↗

演示加载中…

示例代码加载中…