@ybais/center-toast — 面向用户的错误轻提示

自研居中 Toast，API 与交互对齐 antd-mobile Toast：屏幕正中（或 top/bottom）、黑底半透明、白字，命令式调用，不依赖 sonner。

Install

pnpm add @ybais/center-toast react react-dom
# npm i @ybais/center-toast react react-dom
# yarn add @ybais/center-toast react react-dom

Requirements

| 依赖 | 类型 | 说明 | |------|------|------| | react | peer | — | | react-dom | peer | — |

必须在应用入口引入样式：

import "@ybais/center-toast/style.css";

无其它 @ybais/* 硬依赖。常与 @ybais/error-guard 分工使用（见使用边界）。

Get started

import "@ybais/center-toast/style.css";
import { showCenterToast } from "@ybais/center-toast";

// 仅面向用户的失败提示
showCenterToast("提交失败，请稍后重试");
showCenterToast.fail("支付未完成");

const handler = showCenterToast({
  content: "处理中…",
  duration: 0,
  icon: "loading",
});
handler.close();

使用边界（硬约定）

| 场景 | 用什么 | |------|--------| | 面向用户的错误文案（提交失败、支付失败、需用户感知的业务失败） | showCenterToast / .fail | | 可恢复系统/接口错误、reportError / showApiError | sonner（@ybais/error-guard） | | Bridge 不可用、开发调试、浏览器预览提示 | reportDebug（@ybais/error-guard） | | 成功态、已复制、加载中、随手提示 | 禁止 showCenterToast；改 sonner / 业务 UI / 不加提示 |

业务代码不得把本模块当通用 toast。

API

| 方法 | 说明 | |------|------| | showCenterToast(content \| options) | 展示提示，返回 { close } | | showCenterToast.fail(content, options?) | 失败图标（用户向错误） | | showCenterToast.success / .loading | 保留 API 兼容；新代码勿用于非错误场景 | | showCenterToast.clear() | 关闭当前提示 | | showCenterToast.config(partial) | 全局默认 duration / position / maskClickable |

ShowCenterToastOptions

| 字段 | 类型 | 默认 | 说明 | |------|------|------|------| | content | ReactNode | — | 文案或自定义内容 | | duration | number | 2000（loading 为 0） | 毫秒；0 不自动关闭 | | icon | 'success' \| 'fail' \| 'loading' \| ReactNode | — | 图标 | | position | 'top' \| 'center' \| 'bottom' | 'center' | 垂直位置 | | maskClickable | boolean | true | false 时阻止背景点击 | | afterClose | () => void | — | 退场动画结束后回调 | | getContainer | () => HTMLElement | document.body | 挂载容器 |

边界行为

• 空内容：'' / 纯空白 / null / undefined / false 不展示，返回空操作的 { close }。
• 重复调用：新 Toast 立即替换旧 Toast，旧 Toast 的 afterClose 不会触发。
• 幂等 close：对已关闭或已被替换的实例调用 close() 无副作用。
• duration: 0：不启动自动关闭定时器，需 handler.close() 或 showCenterToast.clear()。
• SSR / 无 document：安全降级为 no-op。
• WebView：样式避免 inset / gap / overflow-wrap: anywhere；支持 prefers-reduced-motion 关闭动画。