React 用 Portal + Context 实现全局 Toast:一次调用、自动消失与队列管理-育师

React 用 Portal + Context 实现全局 Toast:一次调用、自动消失与队列管理

做后台系统时,几乎每个页面都要弹提示:保存成功、网络错误、权限不足。如果每个页面都自己维护一个visible状态、写一段setTimeout关闭,重复代码满天飞,还经常出现「多个提示叠在一起互相覆盖」的 bug。

我们要的效果很朴素:任何组件里,一行toast.success('保存成功')就能在页面右上角弹出提示,3 秒后自己消失,多个提示自动排队叠放。这篇就从零把它搭出来,顺带讲清 Portal 和 Context 各自解决的到底是什么问题。

朴素写法的坑:提示被 overflow 裁掉了

先看很多人第一版会怎么写——在页面组件里放一个提示 div:

function Page() { const [msg, setMsg] = useState(''); return ( <div style={{ overflow: 'hidden' }}> {/* 一堆内容 */} {msg && <div className="toast">{msg}</div>} </div> ); }

两个问题立刻暴露:

提示 div 是页面 DOM 的子节点,一旦某个祖先设了overflow: hidden或transform,提示要么被裁掉一半,要么定位基准跑偏,position: fixed都不一定救得回来。
每个页面都要自己维护msg状态和关闭逻辑,换个页面就得重写一遍。

第一个问题交给Portal:把提示的真实 DOM 渲染到body下,彻底逃出祖先的overflow和层叠上下文。第二个问题交给Context:把「弹提示」这个能力做成全局服务,任何组件useToast()就能拿到。

第一步:用 Context 承载 toast 队列

先定义状态形状。每条 toast 有唯一 id(用来精确移除)、类型和文案:

import { createContext, useCallback, useContext, useRef, useState } from 'react'; const ToastContext = createContext(null); let seed = 0; // 模块级自增,保证 id 全局唯一,不依赖数组长度 export function ToastProvider({ children }) { const [toasts, setToasts] = useState([]); const remove = useCallback((id) => { setToasts((list) => list.filter((t) => t.id !== id)); }, []); const push = useCallback((type, message, duration = 3000) => { const id = ++seed; setToasts((list) => [...list, { id, type, message }]); // 到点自动移除;返回 id 方便调用方提前手动关 setTimeout(() => remove(id), duration); return id; }, [remove]); return ( <ToastContext.Provider value={push}> {children} <ToastViewport toasts={toasts} onClose={remove} /> </ToastContext.Provider> ); }

这里有个容易踩的点:id 千万别用toasts.length或Date.now()。数组长度会因为删除而重复;Date.now()在同一毫秒内连发两条会撞车。用一个模块级自增变量最稳。

第二步:用 Portal 把视图渲染到 body

ToastViewport负责把所有提示画到屏幕右上角。关键就是createPortal——它让 React 组件的 DOM 挂到指定容器,但事件冒泡、Context 读取仍按 React 组件树走,而不是按真实 DOM 位置走。

import { createPortal } from 'react-dom'; function ToastViewport({ toasts, onClose }) { // SSR 阶段没有 document,直接不渲染,避免 hydration 报错 if (typeof document === 'undefined') return null; return createPortal( <div style={{ position: 'fixed', top: 16, right: 16, display: 'flex', flexDirection: 'column', gap: 8, zIndex: 9999, }} > {toasts.map((t) => ( <div key={t.id} onClick={() => onClose(t.id)} style={{ padding: '10px 16px', borderRadius: 6, color: '#fff', cursor: 'pointer', background: t.type === 'error' ? '#e5484d' : '#30a46c', boxShadow: '0 4px 12px rgba(0,0,0,.15)', }} > {t.message} </div> ))} </div>, document.body // 挂到 body,逃出任何祖先的 overflow/transform ); }

多个提示天然「排队叠放」,因为它们只是 flex 列里的兄弟节点,新的往下加,旧的到点自己删——队列管理不用额外写逻辑,数组本身就是队列。

第三步:封装一个好用的 Hook

直接暴露push(type, message)不够顺手,包一层语义化 API:

export function useToast() { const push = useContext(ToastContext); if (!push) { // 忘了套 Provider 时,给一个明确报错,而不是让 push 是 null 后面才崩 throw new Error('useToast 必须在 ToastProvider 内使用'); } return { success: (msg, d) => push('success', msg, d), error: (msg, d) => push('error', msg, d), }; }

那句throw很值:漏套 Provider 是高频错误,提前抛一句人话,比等到调用时报push is not a function好排查得多。

在应用根部套上 Provider:

function App() { return ( <ToastProvider> <YourRoutes /> </ToastProvider> ); }

业务里随手就能用:

function SaveButton() { const toast = useToast(); const onSave = async () => { try { await api.save(); toast.success('保存成功'); } catch (e) { toast.error('保存失败:' + e.message); } }; return <button onClick={onSave}>保存</button>; }

一个隐蔽的性能坑:Provider 重渲染拖垮全页

上面ToastContext.Provider value={push}传的是push,它被useCallback固定了引用,所以toasts变化时,消费useToast()的业务组件不会跟着重渲染——它们只依赖push,不依赖toasts。

如果图省事把value={{ push, toasts }}一起传下去,那每弹一条提示,全站useToast()的组件都会重渲染。把「触发能力」和「列表数据」分开:能力给业务组件,数据只留给 viewport 自己消费。这也是 Context 拆分的通用原则——变化频繁的数据别和稳定的能力混在一个 value 里。

小结

Portal 解决「位置」:把提示 DOM 挂到body,逃出祖先的overflow: hidden、transform和z-index层叠陷阱,同时保持 React 树的事件与 Context 语义。
Context 解决「触达」:把弹提示做成全局能力,任何组件一行调用,不用层层传 props。
队列 = 数组:新提示 push 进数组,setTimeout到点按 id filter 掉,叠放和自动消失都是数组的自然行为。
id 用模块级自增,别用 length 或时间戳;value 里分离能力与数据,避免全站无谓重渲染;SSR 下判空 document,避免 hydration 崩。