amis Toast 轻提示组件完全指南：JSON 配置、动作触发与源码原理

发布时间：2026/9/14 0:05:04

amis Toast 轻提示组件完全指南JSON 配置、动作触发与源码原理【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amisToast轻提示是 amis 低代码框架中用于在页面短暂展示反馈信息的前端组件。它既可以直接作为按钮的actionType: toast动作使用也可以在表单提交、接口请求失败等场景下由框架内部调用帮助开发者在不跳转页面、不打断操作的前提下向用户传递成功、失败、警告等即时消息。阅读完本文你将掌握 Toast 的完整配置项位置、图标、关闭按钮、持续时间、HTML 渲染、逐条消息的差异化设置以及它背后的事件动作机制与单例渲染原理可直接在 amis 页面 JSON 中落地使用。Toast 轻提示组件是什么在 amis 中Toast 并不是一个需要主动放入页面 body 的普通渲染组件而是一种全局轻提示能力通过按钮或事件动作触发后提示消息会以浮层形式出现在屏幕指定位置并在数秒后自动消失整个过程不需要用户点击确认。从实现层面看Toast 由两部分协作完成动作声明页面 JSON 中通过actionType: toast声明触发方式配合toast.items描述要展示的消息内容渲染层底层的 ToastComponent 以单例模式挂载源码注释明确说明单例模式App 级别只需要一个 ToastComponent引入了多个会兼容也只有第一个生效所有 Toast 消息都通过它统一渲染和销毁。在 amis-core 中Toast 被注册为全局动作之一ToastAction.ts 中的registerAction(toast, new ToastAction())使其可以被按钮动作或事件动作引用最终调用env.notify(level, msg, config)完成消息弹出见 packages/amis-core/src/actions/ToastAction.ts。基本用法通过按钮动作触发最常用的方式是将按钮的actionType指定为toast并在toast.items中配置要展示的轻提示内容{ label: 提示, type: button, actionType: toast, toast: { items: [ {body: 轻提示内容} ] } }点击按钮后页面顶部中央会出现一条轻提示内容消息默认展示类型图标数秒后自动消失。一个页面中可以放置多个这样的按钮各自配置独立的提示内容{ type: page, body: [ { label: 提示, type: button, actionType: toast, toast: { items: [ {body: 轻提示内容} ] } }, { label: 提示2, type: button, actionType: toast, toast: { items: [ {body: 轻提示内容2} ] } } ] }设置提示位置position通过toast.position可以控制轻提示出现的屏幕方位支持 7 个可选值可选值说明top-left左上方top-center上方居中默认top-right右上方center屏幕正中间bottom-left左下方bottom-center下方居中bottom-right右下方{ label: 提示, type: button, actionType: toast, toast: { position: bottom-center, items: [ {body: 轻提示内容2} ] } }需要注意默认位置为top-center移动端默认变为center屏幕正中间。这一逻辑在 Toast.tsx 中实现——当mobileUI开启且未显式指定position时消息会被强制居中展示。从源码看多条 Toast 会按照各自的位置进行分组渲染ToastComponent.render()使用groupBy(items, item position)把同一方位的消息聚到同一个Toast-wrap容器中见 packages/amis-ui/src/components/Toast.tsx因此不同方向的提示互不干扰。控制关闭按钮closeButton默认情况下 Toast 不展示关闭按钮消息到期自动消失。如需让用户手动关闭可将closeButton设为true{ label: 提示, type: button, actionType: toast, toast: { closeButton: true, items: [ {body: 轻提示内容} ] } }设为false则明确不展示关闭按钮{ label: 提示, type: button, actionType: toast, toast: { closeButton: false, items: [ {body: 轻提示内容} ] } }实现细节上是否展示关闭按钮在 Toast.tsx 中判断closeButton{!mobileUI (item.closeButton ?? closeButton)}——移动端一律不展示关闭按钮PC 端若单条消息未单独配置则继承外层toast.closeButton。另外关闭按钮的展示与否还会影响点击行为展示了关闭按钮时点击消息本体不会触发关闭反之点击消息即可提前关闭见 Toast.tsx 的onClick{closeButton ? noop : this.close}。控制类型图标showIconToast 会根据消息的level类型展示对应的图标成功、错误、信息、警告各有不同图标。若不需要图标可将showIcon设为false{ label: 提示, type: button, actionType: toast, toast: { showIcon: false, items: [ {body: 轻提示内容} ] } }图标渲染逻辑位于 Toast.tsxshowIcon false时整块图标区域不渲染否则根据level值映射到success/fail/info/warning四个图标。类型图标还受到移动端样式的影响移动端会附加Toast-mobile--has-icon类名以适配显示。设置持续时间timeout通过timeout可控制提示停留的毫秒数单位是毫秒{ label: 提示, type: button, actionType: toast, toast: { timeout: 1000, items: [ {body: 轻提示内容} ] } }关于持续时间的默认值官方属性表给出的规则为默认 5000mserror 类型为 6000ms移动端为 3000ms。源码中与之呼应的关键实现ToastComponent 的 defaultProps 定义了timeout: 4000、errorTimeout: 6000并注释错误的时候 time 调长实际计算在 Toast.tsx 第 224-225 行item.timeout ?? (level error ? errorTimeout : timeout)即单条消息未配置 timeout 时error 类型使用更长的 6000ms其余类型使用默认时长移动端分支在 Toast.tsx 第 150 行强制将 timeout 置为 3000ms。无论配置多少时长消息都会通过Transition组件配合 750ms 的过渡动画完成淡入淡出鼠标悬停在消息上时计时会暂停handleMouseEnter清除定时器移开后重新计时见 Toast.tsx。带标题的提示每个 Toast 条目都可以通过title设置标题配合body组成标题内容的消息结构{ label: 提示, type: button, actionType: toast, toast: { items: [ {title: 标题, body: 轻提示内容} ] } }title与body的类型都是string | SchemaNode既可以是纯文本字符串也可以是 amis Schema 节点。渲染时标题会套用Toast-title类名、正文套用Toast-body类名见 Toast.tsx方便通过 CSS 定制样式。每条提示单独设置不同类型levellevel决定消息的类型与对应图标支持info、success、error、warning四种取值。外层toast.items是一个数组因此可以在一次触发中同时弹出多条不同类型的消息{ label: 提示, type: button, actionType: toast, toast: { items: [ {body: 普通消息提示, level: info}, {body: 成功消息提示, level: success}, {body: 错误消息提示, level: error}, {body: 警告消息提示, level: warning} ] } }每条消息会依据自身的level渲染对应样式的Toast Toast--info/success/error/warning容器与图标见 Toast.tsx。需要说明的是level的默认值为infoToastMessage 的 defaultProps未配置时按普通信息提示处理。每条提示单独设置不同位置除了在外层统一设置position也可以为items中的每一条消息单独指定位置实现一次触发、多处弹出的效果{ label: 提示, type: button, actionType: toast, toast: { items: [ {body: 左上方提示, position: top-left}, {body: 上方提示, position: top-center}, {body: 右上方提示, position: top-right}, {body: 中间提示, position: center}, {body: 左下方提示, position: bottom-left}, {body: 下方提示, position: bottom-center}, {body: 右上下方提示, position: bottom-right} ] } }渲染层会优先使用每条消息自身的position未配置时回退到外层toast.position见 Toast.tsx 第 206 行的groupBy(items, item item.position || position)。每条提示单独设置关闭按钮与持续时间closeButton与timeout同样支持逐条覆盖{ label: 提示, type: button, actionType: toast, toast: { items: [ {body: 展示关闭按钮, closeButton: true}, {body: 不展示关闭按钮, closeButton: false} ] } }{ label: 提示, type: button, actionType: toast, toast: { items: [ {body: 持续1秒, timeout: 1000}, {body: 持续3秒, timeout: 3000} ] } }源码中这两项的逐条覆盖逻辑分别为item.closeButton ?? closeButton与item.timeout ?? (level error ? errorTimeout : timeout)见 packages/amis-ui/src/components/Toast.tsx即单条配置优先未配置时继承外层默认值。这种外层默认单条覆盖的设计让你既能批量统一风格又能在个别场景下做差异化处理。渲染 HTML 内容allowHtmlToast 的body默认支持 HTML 片段渲染allowHtml默认为true。因此可以直接传入带标签的内容{ label: 提示, type: button, actionType: toast, toast: { items: [ {body: strongHello/strong spanworld/span} ] } }在渲染实现中allowHtml为true时正文通过Html html{...} /组件渲染否则以纯文本方式输出见 Toast.tsx。如果你展示的是不可信内容可以将allowHtml设为false避免被当作 HTML 解析。属性表Toast 动作属性外层属性名类型默认值说明actionTypestringtoast指定为 toast 轻提示组件itemsArrayToastItem[]轻提示内容positionstringtop-center移动端为center提示显示位置可用top-right、top-center、top-left、bottom-center、bottom-left、bottom-right、centercloseButtonbooleanfalse是否展示关闭按钮移动端不展示showIconbooleantrue是否展示图标timeoutnumber5000error类型为6000移动端为3000持续时间ToastItem 属性表单条消息属性名类型默认值说明titlestring \| SchemaNode无标题bodystring \| SchemaNode无内容levelstringinfo展示图标可选info、success、error、warningpositionstringtop-center移动端为center提示显示位置可选值同上closeButtonbooleanfalse是否展示关闭按钮showIconbooleantrue是否展示图标timeoutnumber5000error类型为6000移动端为3000持续时间allowHtmlbooleantrue是否会被当作 HTML 片段处理以上字段在类型层面与 amis-core 的 AMISToastBase 定义一一对应其中position与level在类型系统中被限定为枚举值配置时若写错会在 TypeScript 校验阶段直接报错。源码原理从动作注册到单例渲染1. 动作注册与 env.notify 调用链ToastAction.ts 将toast注册为全局动作registerAction(toast, new ToastAction())。其run方法的核心逻辑是event.context.env?.notify?.( action.args?.msgType || info, String(action.args?.msg), {...action.args, mobileUI: renderer.props.mobileUI} );也就是说toast动作最终统一走env.notify(level, msg, config)这条消息通道。这解释了为什么 amis 中大量内置逻辑如表单提交失败、接口请求报错都会以 Toast 形式弹出提示——它们都在内部调用了同一套env.notify可参考 ChainedSelect.tsx、InputTable.tsx 等渲染器中的env.notify(error, ...)调用。2. 单例 ToastComponent 与编程式 APIpackages/amis-ui/src/components/Toast.tsx 同时导出了组件与编程式调用入口export const toast { container: toastRef, success: (content, conf) show(content, conf, success), error: (content, conf) show(content, conf, error), info: (content, conf) show(content, conf, info), warning: (content, conf) show(content, conf, warning) };toastRef在ToastComponent挂载时被赋值卸载时清空见 Toast.tsx 第 123-132 行从而保证全局只有一个生效实例notifiy方法在移动端会清空已有 items移动端只能存在一个并把默认位置改为center、超时改为 3000ms见 Toast.tsx 第 134-157 行。3. 多条消息的分组与定时销毁ToastComponent.render()按 position 分组渲染不同方向的容器每条ToastMessage使用react-transition-group的Transition完成进出场动画并在onEntered时启动setTimeout定时关闭onMouseEnter暂停计时、onMouseLeave重新计时见 Toast.tsx 第 310-334 行。关闭按钮通过onClick{this.close}主动触发销毁最终经onExited{onDismiss}从父组件状态中移除Toast.tsx 第 353-360 行。总结amis 的 Toast 轻提示组件以按钮动作 JSON 配置的形式提供了轻量、灵活的消息反馈能力items支持批量弹出多条消息position/closeButton/showIcon/timeout/level/title/allowHtml既能在外层统一设置也能在每条消息上单独覆盖底层则由单例的ToastComponent统一渲染配合env.notify事件通道与toast.success / error / info / warning编程式 API可在任意页面逻辑中随时唤起提示。理解这套动作声明全局渲染的机制后你不仅能配置出各种形态的轻提示还能在自己的 amis 扩展或事件动作中复用同一套消息能力。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考