react-s-alert 全部 12 个配置项详解：stack、beep、offset 参数完全手册

react-s-alert 全部 12 个配置项详解：stack、beep、offset 参数完全手册

【免费下载链接】react-s-alertAlerts / Notifications for React with rich configuration options项目地址: https://gitcode.com/gh_mirrors/re/react-s-alert

react-s-alert是一款为 React 打造的轻量化 Alert/Notifications 提示组件库，内置 stack 堆叠、beep 声音提示、offset 偏移量等全部 12 个配置项，支持丰富的自定义选项。本文带你用最短时间吃透 react-s-alert 配置手册，让你轻松搞定提示框的位置、动画、自动关闭与音效。

为什么选择 react-s-alert？

react-s-alert 是经典提示库 sAlert 的 React 重写版，核心优势：

• ⚡轻量零依赖：仅需 React，无其他运行时依赖
• 🎨7 种动画特效：slide、scale、bouncyflip、flip、genie、jelly、stackslide
• 📦灵活配置体系：全局配置 + 单次调用配置，随时覆盖
• 🔊音效提示：beep 参数支持按提示类型播放不同声音

安装命令：

npm install react-s-alert --save

12 个配置项速查表

所有配置项定义见 lib/SAlert.js（PropTypes 声明处），配置合并逻辑见 lib/s-alert-parts/s-alert-tools.js。

💡 规则很简单：单次调用配置会覆盖全局配置，这是 SAlert.js 中returnFirstDefined的取值顺序决定的。

全局专属配置项

1. stack：控制提示堆叠方式

stack决定多个提示是堆叠排列还是重叠显示，只能在全局组件上设置（见 SAlert.js 的 globalConfig 注册逻辑）：

<Alert stack={{limit: 3, spacing: 50}} /> // 最多堆叠3个，间距50px <Alert stack={true} /> // 简单堆叠，不限数量

• limit：限制屏幕上同时显示的提示数量，超出自动移除最早的（见 SAlert.js 的超限处理）
• spacing：提示之间的间距（px）

堆叠时的位置计算在 lib/s-alert-parts/s-alert-data-prep.js 中完成——它会临时渲染一个提示框测量高度，再逐条累计 top/bottom 偏移。

2. contentTemplate：自定义提示内容模板

传入自己的 React 组件替换默认的 lib/SAlertContentTmpl.js：

<Alert contentTemplate={MyContentTemplate} />

配合customFields使用，可以在提示中展示动态数据（如客户姓名、确认按钮等），是打造富交互提示的关键。

位置与外观配置

3. position：提示框出现在屏幕哪个位置

支持 6 种位置，对应 lib/s-alert-default.css 中的定位样式：

<Alert position='top-right' />

4. offset：首个提示框的偏移量（px）

offset会以像素为单位加在第一条提示上（top 或 bottom，取决于 position）。适合避开导航栏、固定头部等遮挡元素：

<Alert offset={150} />

非堆叠模式下，offset 直接生成top: 150px或bottom: 150px的内联样式，见 s-alert-data-prep.js。stack 与 offset 可以叠加使用：offset 顶住第一条，spacing 拉开其余的。

5. effect：7 种入场/退场动画

动画由独立的 CSS 文件驱动，必须导入对应 CSS 才生效：

import 'react-s-alert/dist/s-alert-default.css'; // 必须 import 'react-s-alert/dist/s-alert-css-effects/slide.css'; // 按需 Alert.success('保存成功!', { effect: 'genie' });

6. html：是否渲染 HTML 富文本

默认提示内容是纯文本；开启html: true后，消息字符串会经过 SAlertContent.js 的dangerouslySetInnerHTML渲染，可包含<h1>、链接等标签：

<Alert html={true} />

7. timeout：自动关闭时间（毫秒）

• 数字（单位 ms）：到点自动消失，默认5000
• 'none'：不自动关闭，需手动Alert.close(id)或Alert.closeAll()

Alert.error('网络异常', { timeout: 'none' });

计时器在 SAlertContent.js 中启动，组件卸载时自动清理。

声音与回调配置

8. beep：提示音效（String 或 Object）

包内没有默认音频，需要自行提供.mp3等音频路径（建议使用有授权的素材）。支持两种写法：

// 写法一：一个声音用于所有提示 <Alert beep='/audio/notify.mp3' /> // 写法二：按提示类型配置4种声音 <Alert beep={{ info: '/audio/info.mp3', error: '/audio/error.mp3', warning: '/audio/warning.mp3', success: '/audio/success.mp3' }} />

播放逻辑在 SAlertContent.js：组件创建时按 condition 匹配音源播放，关闭时会停止音频。

9. onShow：提示出现时触发

Alert.success('已登录', { onShow: () => console.log('onShow Fired!') });

在 SAlertContent.js 的componentDidMount中执行，适合做埋点统计。

10. onClose：提示关闭时触发

Alert.info('5秒后刷新', { onClose: () => window.location.reload() });

在组件卸载时触发（见 SAlertContent.js），无论是手动关闭、超时还是 closeAll 都会执行。

11. preserveContext：保留父组件 React Context

sAlert 通过ReactDOM.render直接把提示挂载到 DOM 来测量高度。如果提示里要用Material UI这类依赖 Context 传递主题的组件，请开启：

<Alert preserveContext />

开启后改用ReactDOM.unstable_renderSubtreeIntoContainer渲染（见 s-alert-data-prep.js），使提示始终继承父组件的 Context。

12. customFields：传给自定义模板的任意字段

配合contentTemplate使用，把业务数据传进自定义提示组件：

Alert.warning('需要确认订单', { customFields: { customerName: 'Tom' } });

自定义模板中通过this.props.customFields.customerName读取。

完整上手示例：五步接入 react-s-alert

1. 安装并导入组件：import Alert from 'react-s-alert';（入口 index.js 指向构建产物）
2. 导入默认 CSS（必须）+ 想要的特效 CSS
3. 在根组件末尾放置容器：<Alert stack={{limit: 3}} position='top-right' timeout={5000} />
4. 任意位置调用静态方法弹出提示
5. 需要时手动关闭

Alert.success('操作成功', { effect: 'slide' }); Alert.error('出错了', { timeout: 'none', offset: 100, beep: '/a.mp3' }); Alert.close(alertId); // 关闭指定提示 Alert.closeAll(); // 关闭全部

四个方法info / error / warning / success定义在 SAlert.js，每次调用都会返回 alertId，方便后续精确关闭。提示的增删状态由内置的轻量 store 管理，实现见 lib/s-alert-parts/s-alert-store.js。

配置优先级与最佳实践

• 🧠全局定基调：position、timeout、effect 放组件 props；单次覆盖用于特殊场景（如 error 提示timeout: 'none'）
• 📐stack 是开关：不开启时新提示会覆盖旧提示的位置计算逻辑（见 s-alert-data-prep.js），高频提示场景务必开启
• 🎯offset 避遮挡：有固定 header 时，offset设为 header 高度 + 间距
• 🔕beep 慎用：默认 false 即静音；开启后请准备 4 类音效提升体验
• 🧩复杂提示走模板：动态数据 + 按钮交互，用contentTemplate+customFields实现

常见问题 FAQ

Q1：提示框不显示动画？没有导入对应特效的 CSS 文件，或effect名称拼写错误。

Q2：多个提示会互相重叠吗？默认会重叠；加stack={true}即自动堆叠，stack={{limit: 3}}限制最大数量。

Q3：如何让提示常驻不消失？设置timeout: 'none'，然后用Alert.close(id)或关闭按钮控制消失。

Q4：配置不生效？检查作用域：stack和contentTemplate只能在组件 props 上设置；其余 10 项支持全局 + 单次两级。

掌握以上全部 12 个 react-s-alert 配置项——stack 堆叠、beep 音效、offset 偏移等参数，你已可覆盖 React 提示通知场景的所有定制需求。

【免费下载链接】react-s-alertAlerts / Notifications for React with rich configuration options项目地址: https://gitcode.com/gh_mirrors/re/react-s-alert