在 React 中实现 Syncfusion…

当你需要在 React 应用中使用 Syncfusion 的 Toast、Message、Skeleton、Spinner 或 Badge 组件实现通知、加载占位、加载指示和状态徽标时，按此流程操作。

适用场景

解决思路

1. 安装依赖：让用户运行 `npm install @syncfusion/ej2-react-notifications@33.x.x --save`（Spinner 用 `@syncfusion/ej2-react-popups@33.x.x`），并用 `npm audit` 验证；不要自行安装。
2. 导入 CSS 主题：在 `src/App.css` 中先 `@import` `@syncfusion/ej2-base/styles/tailwind3.css`，再导入对应组件的样式（如 `@syncfusion/ej2-react-notifications/styles/tailwind3.css` 或 `@syncfusion/ej2-notifications/styles/tailwind3.css`），ej2-base 必须在前。
3. Toast：用 `ToastComponent` 设置 `title`、`content`（纯文本/HTML/元素）、`target` 自定义容器、`showCloseButton`、`showProgressBar` 与 `progressDirection`（Ltr/Rtl）、`newestOnTop` 堆叠顺序、`width`/`height`（px、%、auto）。
4. Toast 定位：使用九种预定义 X/Y 位置（Left/Center/Right 与 Top/Bottom）、自定义像素或百分比坐标、指定容器元素做相对定位，或在多个屏幕位置放置多个 Toast 实例。
5. Toast 超时与关闭：设置 `timeOut`（默认 5000 ms）、悬停时 `extendedTimeout`（默认 1000 ms）、`timeOut: 0` 实现常驻、在 `click` 事件中用 `clickToClose` 点击关闭、在 `beforeClose` 中阻止移动端滑动关闭。
6. Toast 模板与样式：用 `template` 属性传 HTML 字符串或 DOM 选择器，在 `show()` 调用时传动态模板，使用语义化 CSS 类 `e-toast-success`、`e-toast-info`、`e-toast-warning`、`e-toast-danger`，并通过 CSS 选择器自定义标题、内容、图标和背景。
7. Toast 动画：通过 `animation` 属性设置 `show` 和 `hide` 效果，可选 FadeIn、FadeZoomIn、SlideBottomIn、ZoomIn、FlipLeftUpIn 等，默认 FadeIn/FadeOut，并考虑 reduced-motion 无障碍。
8. Toast 服务与高级模式：用 `ToastUtility.show()` 快速显示无需实例化组件的 Toast，使用四种预定义类型 `Information`、`Success`、`Error`、`Warning`，可传完整 `ToastModel`，在 `beforeOpen` 中播放音频、限制最大同时显示数量、结合 `close` 防止重复 Toast。
9. Toast 无障碍：使用 WAI-ARIA 的 `role="alert"`、`aria-live="assertive"`、`aria-label`，满足 WCAG 2.2、Section 508、ADA，支持 JAWS/NVDA/VoiceOver 屏幕阅读器，通过 `enableRtl` 支持 RTL，并用移动端和无障碍检查器验证。
10. Toast 常用模式：用 `cssClass` 加语义类型类；用 `timeOut: 0` + `showCloseButton: true` 实现常驻；用 `buttons` 属性添加 Ignore/Confirm/Undo 按钮；用 `beforeOpen` 取消重复 Toast；用 `beforeOpen` 和 `element.childElementCount` 限制最大可见数量。
11. Message：用 `MessageComponent` 通过 `content` 属性或 JSX 子元素渲染内容，使用 `severity` 属性设置 Normal、Success、Info、Warning、Error 五级严重程度，使用 `variant` 属性设置 Text（默认）、Outlined、Filled 三种变体。
12. Message 图标与关闭：用 `showIcon`（默认 `true`）控制严重程度图标显示，通过 `cssClass` CSS 覆盖自定义图标；用 `showCloseIcon`（默认 `false`）显示关闭图标，用 `closed` 事件处理关闭回调，用 `visible` 属性切换可见性。
13. Message 自定义：用 `e-content-center`、`e-content-right` 控制内容对齐（默认左对齐），用 `cssClass` 自定义外观，可纯 HTML + CSS 渲染，用 JSX 元素或渲染函数作为 `content` 模板，用 `enableRtl` 支持 RTL，用 `enablePersistence` 持久化。
14. Message 无障碍：满足 WCAG 2.2、Section 508、ADA，使用 WAI-ARIA 属性（`role=alert`、`aria-label`），支持键盘导航（Tab、Enter/Space）和屏幕阅读器。
15. Skeleton：用 `SkeletonComponent` 设置 `height` 和 `width`，用 `shape` 属性选择 `"Circle"`、`"Square"`、`"Rectangle"`、`"Text"`（默认），Circle/Square 必须设 width，Rectangle/Text 需 width + height，用多形状组合卡片骨架布局。
16. Skeleton 微光效果：用 `shimmerEffect` 属性选择 `"Wave"`（默认）、`"Pulse"`、`"Fade"`，根据 UI 场景选择效果，列表骨架可用 Pulse。
17. Skeleton 样式与可见性：用 `cssClass` 自定义 CSS（波浪颜色、背景、动画速度），用 `visible` 属性根据加载状态切换骨架，实现骨架到实际内容的过渡，并可用 CSS 变量定制。
18. Skeleton 无障碍：满足 WCAG 2.2、Section 508、ADA，使用 WAI-ARIA 属性 `role="status"`、`aria-label`、`aria-live`、`aria-busy`，用 `label` 属性提供可访问名称，用 `enableRtl` 支持 RTL，并尊重 `prefers-reduced-motion`。
19. Spinner：用 `createSpinner` 初始化（参数 `target` 必填，可选 `width`、`label`、`cssClass`、`template`、`type`），再用 `showSpinner` 显示、`hideSpinner` 隐藏；必须先 `createSpinner` 再 `showSpinner`，且逻辑放在 `useEffect` 中确保 DOM 已存在。
20. Spinner 全局配置：在任意 `createSpinner` 之前调用 `setSpinner` 设置全局默认类型，可选 `SpinnerType` 包括 Material、Material3、Fabric、Bootstrap、Bootstrap4、Bootstrap5、HighContrast、Tailwind、Tailwind3、Fluent、Fluent2。
21. Spinner 常用模式：异步请求用 `try/finally` 确保 `finally` 中调用 `hideSpinner`；用 React state 同步显示/隐藏；用 `document.body` 做全页加载；用 `type`、`width`、`label`、`cssClass` 自定义。
22. Spinner 无障碍：在加载区域加 `aria-busy`，用 `aria-live` 区域向屏幕阅读器播报，用 `type: 'HighContrast'` 适配高对比度显示，管理键盘焦点（触发时聚焦、完成后返回焦点），满足 WCAG 2.1。
23. Spinner 关键规则：不存在 `SpinnerComponent` 类，只能使用 `createSpinner`、`showSpinner`、`hideSpinner`、`setSpinner`；不要用 `color`、`size`、`visible`、`isLoading` 作为 SpinnerArgs；始终在 `finally` 中调用 `hideSpinner`。
24. Badge：Badge 是纯 CSS 组件，无需导入 React 组件类，在目标元素内嵌套 `<span>`（或 `<a>`）并添加 `e-badge` 基础类及修饰类即可。
25. Badge 颜色与形状：使用 8 种颜色变体（primary、secondary、success、danger、warning、info、light、dark）和形状类型（circle、pill、link、notification、dot、overlap），可组合修饰类（如 overlap + notification + circle），支持 top（默认）和 bottom 定位。
26. Badge 自定义：用 CSS 类覆盖自定义颜色，用 `font-size` 调整大小，用 CSS 覆盖自定义位置（left-top、left-bottom），在自定义 CSS 与内置修饰类之间做选择。
27. Badge 集成：将 Badge 嵌入 ListView 列表项，动态更新徽标内容（递增计数），用 React 状态管理配合 DOM 更新实现徽标状态。
28. 所有组件通用：不要自主执行多步操作，每次安装、运行、创建文件前先与用户确认；不要自行启动开发服务器，让用户运行 `npm run dev`。
29. Spinner 故障排查：不显示时确认先 `createSpinner` 再 `showSpinner` 且 DOM 存在；一直显示时在 `finally` 中调用 `hideSpinner`；无动画时确认同时导入 `ej2-base` 和 `ej2-react-popups` CSS 且 ej2-base 在前；TypeScript 报错时用 `as HTMLElement` 或 `useRef<HTMLDivElement>`；超出边界时给目标元素加 `position: relative`；主题错误时设置匹配的 `type`。

适用边界 · 注意事项

• 未安装 `@syncfusion/ej2-react-notifications` 或 `@syncfusion/ej2-react-popups` 包、且未导入对应主题 CSS 时无法使用。
• Spinner 不适用于需要确定性进度百分比的场景，应改用 Progress Bar；需要用户确认的模态加载应改用 Dialog。
• Badge 是纯 CSS 组件，不适用于需要复杂交互逻辑或非 Syncfusion 主题体系的场景。