syncfusion-react-notifications

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Notifications

实现Syncfusion React通知组件

Toast

The Syncfusion React Toast component displays brief, non-intrusive notifications that auto-dismiss after a configurable timeout. Toasts support rich content through templates, action buttons, animated entry/exit, precise positioning, and programmatic control via

ToastUtility

Syncfusion React Toast组件用于展示简短、无侵入性的通知，可配置超时时间后自动关闭。Toast支持通过模板实现富内容、操作按钮、动画入场/退场效果、精准定位，还可通过

ToastUtility

进行程序化控制。

Package and Setup

包安装与初始化配置

📄 Read: references/getting-started.md

Installing
```
@syncfusion/ej2-react-notifications
```
CSS imports for all required themes
Basic
```
ToastComponent
```
usage (class and functional patterns)
Rendering toast in a custom target container
Triggering show in the
```
created
```
event

📄 阅读： references/getting-started.md

安装
```
@syncfusion/ej2-react-notifications
```
导入所有所需主题的CSS
```
ToastComponent
```
基础用法（类组件与函数组件模式）
在自定义目标容器中渲染toast
在
```
created
```
事件中触发展示

Documentation and Navigation Guide

文档与导航指南

Configuration and Layout

配置与布局

📄 Read: references/configuration.md

Setting
```
title
```
and
```
content
```
(plain text, HTML, elements)
Custom
```
target
```
container for scoped notifications
```
showCloseButton
```
for manual dismissal
```
showProgressBar
```
and
```
progressDirection
```
(Ltr / Rtl)
```
newestOnTop
```
stacking order
```
width
```
and
```
height
```
dimensions (px, %, auto)

📄 阅读： references/configuration.md

设置
```
title
```
和
```
content
```
（纯文本、HTML、DOM元素）
为作用域通知设置自定义
```
target
```
容器
配置
```
showCloseButton
```
支持手动关闭
```
showProgressBar
```
和
```
progressDirection
```
（从左到右/从右到左）
```
newestOnTop
```
堆叠顺序
```
width
```
和
```
height
```
尺寸配置（px、%、auto）

Positioning

定位

📄 Read: references/position.md

Nine predefined X/Y positions (Left, Center, Right / Top, Bottom)
Custom pixel and percentage coordinates
Targeting a container element for relative positioning
Multiple Toast instances at different screen positions

📄 阅读： references/position.md

9种预定义X/Y轴位置（左、中、右/上、下）
自定义像素和百分比坐标
绑定容器元素实现相对定位
屏幕不同位置同时展示多个Toast实例

Timeout and Dismissal

超时与关闭逻辑

📄 Read: references/timeout-and-dismissal.md

```
timeOut
```
property (default 5000 ms)
```
extendedTimeout
```
on hover (default 1000 ms)
Static persistent toasts with
```
timeOut: 0
```
Click-to-close via
```
clickToClose
```
in the
```
click
```
event
Preventing mobile swipe dismissal with
```
beforeClose
```

📄 阅读： references/timeout-and-dismissal.md

```
timeOut
```
属性（默认5000毫秒）
悬停时的
```
extendedTimeout
```
（默认1000毫秒）
通过
```
timeOut: 0
```
实现静态持久化toast
通过
```
click
```
事件的
```
clickToClose
```
实现点击关闭
通过
```
beforeClose
```
禁止移动端滑动关闭

Templates and Styling

模板与样式

📄 Read: references/templates-and-styling.md

```
template
```
property with HTML strings and DOM selectors
Dynamic templates passed at
```
show()
```
call time

Semantic CSS classes:

e-toast-success

e-toast-info

e-toast-warning

e-toast-danger

CSS selectors for title, content, icon, and background customization

📄 阅读： references/templates-and-styling.md

```
template
```
属性支持HTML字符串和DOM选择器
调用
```
show()
```
时传入动态模板

语义化CSS类：

e-toast-success

、

e-toast-info

、

e-toast-warning

、

e-toast-danger

支持通过CSS选择器自定义标题、内容、图标和背景

Animation

动画

📄 Read: references/animation.md

```
animation
```
property with
```
show
```
and
```
hide
```
effect settings
Available effects: FadeIn, FadeZoomIn, SlideBottomIn, ZoomIn, FlipLeftUpIn, and more
Default: FadeIn / FadeOut
Accessibility: reduced-motion considerations

📄 阅读： references/animation.md

```
animation
```
属性支持配置
```
show
```
和
```
hide
```
效果
可用效果：FadeIn、FadeZoomIn、SlideBottomIn、ZoomIn、FlipLeftUpIn等
默认效果：FadeIn / FadeOut
无障碍支持：减动模式适配

Toast Services and Advanced Patterns

Toast服务与高级用法

📄 Read: references/toast-services.md

```
ToastUtility.show()
```
for quick toasts without component instantiation
Four predefined types:
```
Information
```
,
```
Success
```
,
```
Error
```
,
```
Warning
```
Passing a full
```
ToastModel
```
to
```
ToastUtility.show()
```
Playing audio on
```
beforeOpen
```
Restricting maximum simultaneous toasts with
```
beforeOpen
```
Preventing duplicate toasts using
```
beforeOpen
```
+
```
close
```

📄 阅读： references/toast-services.md

```
ToastUtility.show()
```
无需实例化组件即可快速创建toast
4种预定义类型：
```
Information
```
、
```
Success
```
、
```
Error
```
、
```
Warning
```
向
```
ToastUtility.show()
```
传入完整
```
ToastModel
```
配置
在
```
beforeOpen
```
事件中播放提示音
通过
```
beforeOpen
```
限制同时展示的最大toast数量
通过
```
beforeOpen
```
+
```
close
```
事件避免重复toast

Accessibility

无障碍访问

📄 Read: references/accessibility.md

WAI-ARIA:

role="alert"

aria-live="assertive"

aria-label

WCAG 2.2, Section 508, ADA compliance
Screen reader support (JAWS, NVDA, VoiceOver)
RTL support via
```
enableRtl
```
Mobile and accessibility checker validation

📄 阅读： references/accessibility.md

WAI-ARIA：

role="alert"

、

aria-live="assertive"

、

aria-label

符合WCAG 2.2、Section 508、ADA标准
屏幕阅读器支持（JAWS、NVDA、VoiceOver）
通过
```
enableRtl
```
支持从右到左布局
移动端与无障碍检测工具验证

API Reference

API参考

📄 Read: references/api.md

All properties with types, defaults, and descriptions
```
show()
```
and
```
hide()
```
method signatures

All events:

beforeOpen

open

click

beforeClose

close

created

destroyed

beforeSanitizeHtml

📄 阅读： references/api.md

所有属性的类型、默认值与说明
```
show()
```
和
```
hide()
```
方法签名

所有事件：

beforeOpen

、

open

、

click

、

beforeClose

、

close

、

created

、

destroyed

、

beforeSanitizeHtml

Quick Start Example

快速开始示例

tsx

import { ToastComponent } from '@syncfusion/ej2-react-notifications';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-notifications/styles/tailwind3.css';
import { useRef } from 'react';

function App() {
  const toastRef = useRef<ToastComponent>(null);

  return (
    <>
      <button onClick={() => toastRef.current?.show()}>Show Toast</button>
      <ToastComponent
        ref={toastRef}
        title="Success!"
        content="Your changes have been saved."
        cssClass="e-toast-success"
        position={{ X: 'Right', Y: 'Bottom' }}
        timeOut={4000}
        showProgressBar={true}
        showCloseButton={true}
      />
    </>
  );
}

tsx

import { ToastComponent } from '@syncfusion/ej2-react-notifications';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-notifications/styles/tailwind3.css';
import { useRef } from 'react';

function App() {
  const toastRef = useRef<ToastComponent>(null);

  return (
    <>
      <button onClick={() => toastRef.current?.show()}>Show Toast</button>
      <ToastComponent
        ref={toastRef}
        title="Success!"
        content="Your changes have been saved."
        cssClass="e-toast-success"
        position={{ X: 'Right', Y: 'Bottom' }}
        timeOut={4000}
        showProgressBar={true}
        showCloseButton={true}
      />
    </>
  );
}

Quick Utility Toast (No Component Needed)

工具类快速调用Toast（无需声明组件）

tsx

import { ToastUtility } from '@syncfusion/ej2-react-notifications';

// Show a success toast instantly
ToastUtility.show('File saved successfully', 'Success', 3000);

// Show an error toast
ToastUtility.show('Connection failed', 'Error', 5000);

tsx

import { ToastUtility } from '@syncfusion/ej2-react-notifications';

// 立即展示成功toast
ToastUtility.show('File saved successfully', 'Success', 3000);

// 展示错误toast
ToastUtility.show('Connection failed', 'Error', 5000);

Common Patterns

常用用法

Semantic type toasts

语义化类型toast

Use

cssClass

with

e-toast-success

e-toast-info

e-toast-warning

e-toast-danger

for visual differentiation — see references/templates-and-styling.md.

搭配

cssClass

使用

e-toast-success

、

e-toast-info

、

e-toast-warning

、

e-toast-danger

实现视觉区分——参考references/templates-and-styling.md。

Static/persistent toasts

静态/持久化toast

Set

timeOut: 0

with

showCloseButton: true

for notifications users must explicitly dismiss — see references/timeout-and-dismissal.md.

设置

timeOut: 0

并开启

showCloseButton: true

，实现需要用户主动关闭的通知——参考references/timeout-and-dismissal.md。

Action-required toasts

需要操作的toast

Use the

buttons

property to add Ignore/Confirm/Undo buttons — see references/configuration.md.

使用

buttons

属性添加忽略/确认/撤销按钮——参考references/configuration.md。

Prevent duplicates

避免重复toast

Use the

beforeOpen

event to cancel duplicate toasts already on screen — see references/toast-services.md.

使用

beforeOpen

事件取消已在屏幕上展示的重复toast——参考references/toast-services.md。

Limit max visible toasts

限制最大可见toast数量

Cap simultaneous toasts at N using

beforeOpen

and

element.childElementCount

— see references/toast-services.md.

通过

beforeOpen

和

element.childElementCount

将同时展示的toast数量限制为N——参考references/toast-services.md。

Message

The Syncfusion

MessageComponent

displays contextual messages with visual severity indicators—icons and colors—to communicate importance and context to end users. It supports five severity levels, three visual variants, close-icon dismissal, custom templates, and full accessibility compliance.

Syncfusion

MessageComponent

用于展示上下文提示消息，带有视觉严重程度指示器（图标和颜色），向终端用户传递信息的重要性和上下文。它支持5种严重等级、3种视觉变体、关闭图标触发关闭、自定义模板，完全符合无障碍访问标准。

Navigation Guide

导航指南

Getting Started

快速开始

📄 Read: references/message-getting-started.md

Installation of
```
@syncfusion/ej2-react-notifications
```
CSS imports and theme configuration
Rendering the first
```
MessageComponent
```
Content via
```
content
```
prop or JSX children
Running the Vite development server

📄 阅读： references/message-getting-started.md

安装
```
@syncfusion/ej2-react-notifications
```
CSS导入与主题配置
渲染第一个
```
MessageComponent
```
通过
```
content
```
属性或JSX子元素传入内容
启动Vite开发服务器

Severity Levels

严重等级

📄 Read: references/message-severities.md

Five severity levels: Normal, Success, Info, Warning, Error
```
severity
```
prop usage and valid values
Visual distinctions (icons and colors per severity)
Choosing the right severity for your use case

📄 阅读： references/message-severities.md

5种严重等级：Normal、Success、Info、Warning、Error
```
severity
```
属性用法与有效值
视觉区别（不同严重等级对应不同图标和颜色）
不同场景下严重等级的选择建议

Display Variants

展示变体

📄 Read: references/message-variants.md

Three variants: Text (default), Outlined, Filled
```
variant
```
prop usage
Combining variant with severity
Visual trade-offs and when to use each

📄 阅读： references/message-variants.md

3种变体：Text（默认）、Outlined、Filled
```
variant
```
属性用法
变体与严重等级的组合使用
不同变体的视觉权衡与适用场景

Icons and Close Icon

图标与关闭图标

📄 Read: references/message-icons-and-close.md

Severity icon visibility:
```
showIcon
```
prop (default
```
true
```
)
Disabling severity icons
Custom severity icons via
```
cssClass
```
CSS overrides
Close icon:
```
showCloseIcon
```
prop (default
```
false
```
)
```
closed
```
event handler for dismiss callbacks
Toggling visibility with the
```
visible
```
prop

📄 阅读： references/message-icons-and-close.md

严重等级图标可见性：
```
showIcon
```
属性（默认
```
true
```
）
禁用严重等级图标
通过
```
cssClass
```
CSS覆盖实现自定义严重等级图标
关闭图标：
```
showCloseIcon
```
属性（默认
```
false
```
）
```
closed
```
事件处理器用于关闭回调
通过
```
visible
```
属性切换可见性

Customization and Templates

自定义与模板

📄 Read: references/message-customization.md

Content alignment: left (default), center (
```
e-content-center
```
), right (
```
e-content-right
```
)
Custom appearance with
```
cssClass
```
CSS-only message rendering (no JS, pure HTML + CSS)
Content templates: JSX element or render function via
```
content
```
prop
RTL support via
```
enableRtl
```
Persistence with
```
enablePersistence
```

📄 阅读： references/message-customization.md

内容对齐：左对齐（默认）、居中（
```
e-content-center
```
）、右对齐（
```
e-content-right
```
）
通过
```
cssClass
```
自定义外观
仅用CSS渲染消息（无JS，纯HTML+CSS）
内容模板：通过
```
content
```
属性传入JSX元素或渲染函数
通过
```
enableRtl
```
支持从右到左布局
通过
```
enablePersistence
```
实现状态持久化

Accessibility

无障碍访问

📄 Read: references/message-accessibility.md

WCAG 2.2, Section 508, ADA compliance
WAI-ARIA attributes (
```
role=alert
```
,
```
aria-label
```
)
Keyboard navigation (Tab, Enter/Space)
Screen reader support

📄 阅读： references/message-accessibility.md

符合WCAG 2.2、Section 508、ADA标准
WAI-ARIA属性（
```
role=alert
```
、
```
aria-label
```
）
键盘导航（Tab、Enter/Space）
屏幕阅读器支持

API Reference

API参考

📄 Read: references/message-api.md

All properties with types, defaults, and descriptions
Methods:
```
destroy
```
,
```
getPersistData
```
Events:
```
closed
```
,
```
created
```
,
```
destroyed
```
```
MessageCloseEventArgs
```
interface
```
Severity
```
and
```
Variant
```
enum values

📄 阅读： references/message-api.md

所有属性的类型、默认值与说明
方法：
```
destroy
```
、
```
getPersistData
```
事件：
```
closed
```
、
```
created
```
、
```
destroyed
```
```
MessageCloseEventArgs
```
接口
```
Severity
```
和
```
Variant
```
枚举值

Quick Start

快速开始

bash

npm install @syncfusion/ej2-react-notifications --save

css

/* src/App.css */
@import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-react-notifications/styles/tailwind3.css';

tsx

import { MessageComponent } from '@syncfusion/ej2-react-notifications';
import './App.css';

function App() {
  return (
    <MessageComponent content="Please read the comments carefully" />
  );
}
export default App;

bash

npm install @syncfusion/ej2-react-notifications --save

css

/* src/App.css */
@import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-react-notifications/styles/tailwind3.css';

tsx

import { MessageComponent } from '@syncfusion/ej2-react-notifications';
import './App.css';

function App() {
  return (
    <MessageComponent content="Please read the comments carefully" />
  );
}
export default App;

Common Patterns

常用用法

Severity Messages

不同严重等级的消息

tsx

<MessageComponent content="Editing is restricted" />
<MessageComponent content="Operation completed" severity="Success" />
<MessageComponent content="Read these notes" severity="Info" />
<MessageComponent content="Check your connection" severity="Warning" />
<MessageComponent content="Submission failed" severity="Error" />

tsx

<MessageComponent content="Editing is restricted" />
<MessageComponent content="Operation completed" severity="Success" />
<MessageComponent content="Read these notes" severity="Info" />
<MessageComponent content="Check your connection" severity="Warning" />
<MessageComponent content="Submission failed" severity="Error" />

Variant + Severity Combo

变体+严重等级组合

tsx

<MessageComponent content="Editing is restricted" variant="Filled" />
<MessageComponent content="Operation completed" severity="Success" variant="Outlined" />
<MessageComponent content="Submission failed" severity="Error" variant="Filled" />

tsx

<MessageComponent content="Editing is restricted" variant="Filled" />
<MessageComponent content="Operation completed" severity="Success" variant="Outlined" />
<MessageComponent content="Submission failed" severity="Error" variant="Filled" />

Dismissible Message

可关闭消息

tsx

import { useState } from 'react';

function App() {
  const [visible, setVisible] = useState(true);
  return (
    <MessageComponent
      content="Your session will expire soon"
      severity="Warning"
      showCloseIcon={true}
      visible={visible}
      closed={() => setVisible(false)}
    />
  );
}

tsx

import { useState } from 'react';

function App() {
  const [visible, setVisible] = useState(true);
  return (
    <MessageComponent
      content="Your session will expire soon"
      severity="Warning"
      showCloseIcon={true}
      visible={visible}
      closed={() => setVisible(false)}
    />
  );
}

Content Template

内容模板

tsx

const contentTemplate = () => (
  <div>
    <h4>Build succeeded</h4>
    <p>All 42 tests passed.</p>
  </div>
);

<MessageComponent content={contentTemplate} severity="Success" />

tsx

const contentTemplate = () => (
  <div>
    <h4>Build succeeded</h4>
    <p>All 42 tests passed.</p>
  </div>
);

<MessageComponent content={contentTemplate} severity="Success" />

Skeleton

The Syncfusion React

SkeletonComponent

renders animated placeholder shapes that mimic the layout of loading content. It reduces perceived load time and communicates progress to users with configurable shapes, shimmer animations, and full accessibility support.

Package:

@syncfusion/ej2-react-notifications

Syncfusion React

SkeletonComponent

用于渲染动画占位形状，模拟加载中内容的布局。它可以降低用户感知的加载时长，通过可配置的形状、微光动画向用户传递加载进度，完全支持无障碍访问。

包：

@syncfusion/ej2-react-notifications

Navigation Guide

导航指南

Getting Started

快速开始

📄 Read: references/skeleton-getting-started.md

Installing
```
@syncfusion/ej2-react-notifications
```
CSS theme imports (tailwind3)
Minimal
```
SkeletonComponent
```
setup with
```
height
```
and
```
width
```
Running the Vite/React app

📄 阅读： references/skeleton-getting-started.md

安装
```
@syncfusion/ej2-react-notifications
```
CSS主题导入（tailwind3）
配置
```
height
```
和
```
width
```
的最简
```
SkeletonComponent
```
实现
启动Vite/React应用

Shapes

形状

📄 Read: references/skeleton-shapes.md

```
shape
```
prop:
```
"Circle"
```
,
```
"Square"
```
,
```
"Rectangle"
```
,
```
"Text"
```
(default)
Dimension rules: width required for Circle/Square; width + height for Rectangle/Text
Building multi-shape card skeleton layouts
Choosing the right shape for avatar, image, text, and icon placeholders

📄 阅读： references/skeleton-shapes.md

```
shape
```
属性：
```
"Circle"
```
、
```
"Square"
```
、
```
"Rectangle"
```
、
```
"Text"
```
（默认）
尺寸规则：圆形/正方形必须配置宽度；矩形/文本必须配置宽高
构建多形状卡片骨架布局
头像、图片、文本、图标占位符的形状选择建议

Shimmer Effects

微光效果

📄 Read: references/skeleton-shimmer-effect.md

```
shimmerEffect
```
prop:
```
"Wave"
```
(default),
```
"Pulse"
```
,
```
"Fade"
```
Visual behavior of each effect type
List skeleton example with Pulse effect
Selecting an effect to match UI context

📄 阅读： references/skeleton-shimmer-effect.md

```
shimmerEffect
```
属性：
```
"Wave"
```
（默认）、
```
"Pulse"
```
、
```
"Fade"
```
每种效果类型的视觉表现
Pulse效果的列表骨架示例
匹配UI上下文的效果选择建议

Styles and Visibility

样式与可见性

📄 Read: references/skeleton-styles.md

```
cssClass
```
prop for custom CSS overrides (wave color, background, animation speed)
```
visible
```
prop to toggle skeleton on/off based on loading state
Transition pattern: skeleton → actual content
CSS variable customization

📄 阅读： references/skeleton-styles.md

```
cssClass
```
属性用于自定义CSS覆盖（波浪颜色、背景、动画速度）
```
visible
```
属性基于加载状态切换骨架屏显隐
过渡模式：骨架屏 → 实际内容
CSS变量自定义

Accessibility

无障碍访问

📄 Read: references/skeleton-accessibility.md

WCAG 2.2, Section 508, ADA compliance

WAI-ARIA attributes:

role="status"

aria-label

aria-live

aria-busy

```
label
```
prop for accessible skeleton names
RTL support via
```
enableRtl
```
```
prefers-reduced-motion
```
respect

📄 阅读： references/skeleton-accessibility.md

符合WCAG 2.2、Section 508、ADA标准

WAI-ARIA属性：

role="status"

、

aria-label

、

aria-live

、

aria-busy

```
label
```
属性用于设置骨架屏的无障碍名称
通过
```
enableRtl
```
支持从右到左布局
适配
```
prefers-reduced-motion
```
减动模式

API Reference

API参考

📄 Read: references/skeleton-api.md

All properties:

cssClass

enablePersistence

enableRtl

height

label

locale

shape

shimmerEffect

visible

width

Methods:
```
destroy()
```
```
SkeletonType
```
and
```
ShimmerEffect
```
enum values

📄 阅读： references/skeleton-api.md

所有属性：

cssClass

、

enablePersistence

、

enableRtl

、

height

、

label

、

locale

、

shape

、

shimmerEffect

、

visible

、

width

方法：
```
destroy()
```
```
SkeletonType
```
和
```
ShimmerEffect
```
枚举值

Quick Start

快速开始

bash

npm install @syncfusion/ej2-react-notifications --save

css

/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-notifications/styles/tailwind3.css";

tsx

import { SkeletonComponent } from '@syncfusion/ej2-react-notifications';
import * as React from 'react';
import './App.css';

function App() {
  return (
    <SkeletonComponent height="15px" width="100%" />
  );
}
export default App;

bash

npm install @syncfusion/ej2-react-notifications --save

css

/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-notifications/styles/tailwind3.css";

tsx

import { SkeletonComponent } from '@syncfusion/ej2-react-notifications';
import * as React from 'react';
import './App.css';

function App() {
  return (
    <SkeletonComponent height="15px" width="100%" />
  );
}
export default App;

Common Patterns

常用用法

Profile Card Skeleton

个人资料卡骨架屏

tsx

import { SkeletonComponent } from '@syncfusion/ej2-react-notifications';
import * as React from 'react';

function ProfileCardSkeleton() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '12px', padding: '16px' }}>
      {/* Avatar placeholder */}
      <SkeletonComponent shape="Circle" width="48px" />
      {/* Name and subtitle placeholders */}
      <div style={{ flex: 1 }}>
        <SkeletonComponent width="60%" height="15px" />
        <br />
        <SkeletonComponent width="40%" height="12px" />
      </div>
    </div>
  );
}
export default ProfileCardSkeleton;

tsx

import { SkeletonComponent } from '@syncfusion/ej2-react-notifications';
import * as React from 'react';

function ProfileCardSkeleton() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '12px', padding: '16px' }}>
      {/* 头像占位符 */}
      <SkeletonComponent shape="Circle" width="48px" />
      {/* 名称和副标题占位符 */}
      <div style={{ flex: 1 }}>
        <SkeletonComponent width="60%" height="15px" />
        <br />
        <SkeletonComponent width="40%" height="12px" />
      </div>
    </div>
  );
}
export default ProfileCardSkeleton;

Toggle Skeleton on Data Load

数据加载时切换骨架屏

tsx

import { SkeletonComponent } from '@syncfusion/ej2-react-notifications';
import * as React from 'react';

function DataCard() {
  const [loading, setLoading] = React.useState(true);
  const [content, setContent] = React.useState('');

  React.useEffect(() => {
    setTimeout(() => {
      setContent('Data loaded successfully');
      setLoading(false);
    }, 2000);
  }, []);

  return (
    <div>
      {loading ? (
        <SkeletonComponent width="80%" height="20px" />
      ) : (
        <p>{content}</p>
      )}
    </div>
  );
}
export default DataCard;

tsx

import { SkeletonComponent } from '@syncfusion/ej2-react-notifications';
import * as React from 'react';

function DataCard() {
  const [loading, setLoading] = React.useState(true);
  const [content, setContent] = React.useState('');

  React.useEffect(() => {
    setTimeout(() => {
      setContent('Data loaded successfully');
      setLoading(false);
    }, 2000);
  }, []);

  return (
    <div>
      {loading ? (
        <SkeletonComponent width="80%" height="20px" />
      ) : (
        <p>{content}</p>
      )}
    </div>
  );
}
export default DataCard;

Shimmer List with Pulse Effect

Pulse效果的列表微光骨架屏

tsx

import { SkeletonComponent } from '@syncfusion/ej2-react-notifications';
import * as React from 'react';

function ListSkeleton() {
  return (
    <ul style={{ listStyle: 'none', padding: 0 }}>
      {[1, 2, 3].map((i) => (
        <li key={i} style={{ display: 'flex', gap: '10px', marginBottom: '12px' }}>
          <SkeletonComponent shape="Circle" width="40px" shimmerEffect="Pulse" />
          <div style={{ flex: 1 }}>
            <SkeletonComponent width="70%" height="14px" shimmerEffect="Pulse" />
            <br />
            <SkeletonComponent width="45%" height="12px" shimmerEffect="Pulse" />
          </div>
        </li>
      ))}
    </ul>
  );
}
export default ListSkeleton;

tsx

import { SkeletonComponent } from '@syncfusion/ej2-react-notifications';
import * as React from 'react';

function ListSkeleton() {
  return (
    <ul style={{ listStyle: 'none', padding: 0 }}>
      {[1, 2, 3].map((i) => (
        <li key={i} style={{ display: 'flex', gap: '10px', marginBottom: '12px' }}>
          <SkeletonComponent shape="Circle" width="40px" shimmerEffect="Pulse" />
          <div style={{ flex: 1 }}>
            <SkeletonComponent width="70%" height="14px" shimmerEffect="Pulse" />
            <br />
            <SkeletonComponent width="45%" height="12px" shimmerEffect="Pulse" />
          </div>
        </li>
      ))}
    </ul>
  );
}
export default ListSkeleton;

Key Props at a Glance

核心属性速览

Prop	Type	Default	Purpose
`shape`	`'Text' \| 'Circle' \| 'Square' \| 'Rectangle'`	`'Text'`	Skeleton shape variant
`width`	`string \| number`	`''`	Width; required for Circle/Square
`height`	`string \| number`	`''`	Height; used for Rectangle/Text
`shimmerEffect`	`'Wave' \| 'Pulse' \| 'Fade'`	`'Wave'`	Animation style
`visible`	`boolean`	`true`	Show/hide skeleton
`cssClass`	`string`	`''`	Custom CSS class(es)
`label`	`string`	`'Loading…'`	ARIA label for accessibility
`enableRtl`	`boolean`	`false`	Right-to-left rendering
`enablePersistence`	`boolean`	`false`	Persist state across reloads

属性	类型	默认值	作用
`shape`	`'Text' \| 'Circle' \| 'Square' \| 'Rectangle'`	`'Text'`	Skeleton形状变体
`width`	`string \| number`	`''`	宽度；圆形/正方形必填
`height`	`string \| number`	`''`	高度；矩形/文本使用
`shimmerEffect`	`'Wave' \| 'Pulse' \| 'Fade'`	`'Wave'`	动画样式
`visible`	`boolean`	`true`	展示/隐藏骨架屏
`cssClass`	`string`	`''`	自定义CSS类
`label`	`string`	`'Loading…'`	无障碍ARIA标签
`enableRtl`	`boolean`	`false`	从右到左渲染
`enablePersistence`	`boolean`	`false`	跨刷新持久化状态

Syncfusion React Spinner

A skill for implementing the Syncfusion React Spinner — a load indicator that blocks user interaction with a target element while an operation is in progress.

用于实现Syncfusion React Spinner的技能说明——这是一个加载指示器，可在操作进行中阻止用户与目标元素交互。

Documentation

文档

Getting Started

快速开始

📄 Read: references/spinner-getting-started.md

Installation:

npm install @syncfusion/ej2-react-popups

CSS theme imports (ej2-base + ej2-react-popups)
Basic functional and class component patterns
```
createSpinner
```
→
```
showSpinner
```
workflow
Show/hide control
Full-page overlay spinner
Troubleshooting missing styles and TypeScript errors

📄 阅读： references/spinner-getting-started.md

安装：

npm install @syncfusion/ej2-react-popups

CSS主题导入（ej2-base + ej2-react-popups）
基础函数组件与类组件模式
```
createSpinner
```
→
```
showSpinner
```
工作流
显示/隐藏控制
全屏覆盖spinner
样式缺失与TypeScript错误排查

Spinner Features

Spinner功能

📄 Read: references/spinner-features.md

Global spinner configuration with
```
setSpinner
```
All
```
SpinnerType
```
values (Material, Bootstrap5, Fluent2, etc.)
Spinner size via
```
width
```
property
Label text alongside spinner
Custom HTML template support
Show/hide toggle patterns
Multiple spinners on one page
Async data fetching with
```
finally
```
cleanup
React state + spinner synchronization
Spinner inside cards and modals

📄 阅读： references/spinner-features.md

通过
```
setSpinner
```
全局配置spinner
所有
```
SpinnerType
```
取值（Material、Bootstrap5、Fluent2等）
通过
```
width
```
属性设置spinner尺寸
spinner旁的标签文本
自定义HTML模板支持
显示/隐藏切换模式
单页多spinner实现
带
```
finally
```
清理的异步数据请求
React状态与spinner同步
卡片和模态框内的spinner

API Reference

API参考

📄 Read: references/spinner-api.md

```
createSpinner(args: SpinnerArgs)
```
— full signature and params
```
showSpinner(container: HTMLElement)
```
— signature
```
hideSpinner(container: HTMLElement)
```
— signature
```
setSpinner(args: SetSpinnerArgs)
```
— signature
```
SpinnerArgs
```
interface (target, width, label, cssClass, template, type)
```
SetSpinnerArgs
```
interface (template, cssClass, type)
All 11
```
SpinnerType
```
values
CSS import paths per theme
Common invalid API gotchas

📄 阅读： references/spinner-api.md

```
createSpinner(args: SpinnerArgs)
```
—— 完整签名与参数
```
showSpinner(container: HTMLElement)
```
—— 签名
```
hideSpinner(container: HTMLElement)
```
—— 签名
```
setSpinner(args: SetSpinnerArgs)
```
—— 签名
```
SpinnerArgs
```
接口（target、width、label、cssClass、template、type）
```
SetSpinnerArgs
```
接口（template、cssClass、type）
所有11种
```
SpinnerType
```
取值
各主题的CSS导入路径
常见API使用误区

Customization

自定义

📄 Read: references/spinner-customization.md

```
cssClass
```
for CSS hook customization
```
width
```
for spinner icon sizing
```
template
```
for custom HTML animations
```
setSpinner
```
for global defaults
Overriding spinner colors via CSS
Label positioning with CSS
Overlay backdrop customization
Theme-specific type mapping
Responsive spinner patterns

📄 阅读： references/spinner-customization.md

```
cssClass
```
用于CSS自定义钩子
```
width
```
用于调整spinner图标大小
```
template
```
用于自定义HTML动画
```
setSpinner
```
用于设置全局默认值
通过CSS覆盖spinner颜色
通过CSS调整标签位置
覆盖层背景自定义
主题对应类型映射
响应式spinner模式

Accessibility

无障碍访问

📄 Read: references/spinner-accessibility.md

```
aria-busy
```
on the loading region
```
aria-live
```
region for screen reader announcements
```
type: 'HighContrast'
```
for high contrast displays
Keyboard accessibility (trigger focus, return focus)
Focus management patterns
Complete accessible spinner pattern
WCAG 2.1 compliance checklist

📄 阅读： references/spinner-accessibility.md

加载区域的
```
aria-busy
```
属性
屏幕阅读器播报的
```
aria-live
```
区域
```
type: 'HighContrast'
```
适配高对比度显示
键盘无障碍（触发焦点、返回焦点）
焦点管理模式
完整的无障碍spinner实现模式
WCAG 2.1合规检查清单

Quick Start

快速开始

Minimal Spinner (Functional Component)

最简Spinner实现（函数组件）

tsx

import { createSpinner, showSpinner } from '@syncfusion/ej2-react-popups';
import * as React from 'react';
import { useEffect } from 'react';
import './App.css';

function App() {
  useEffect(() => {
    createSpinner({
      target: document.getElementById('container') as HTMLElement
    });
    showSpinner(document.getElementById('container') as HTMLElement);
  }, []);

  return (
    <div id="container" style={{ height: '200px' }} />
  );
}

export default App;

tsx

import { createSpinner, showSpinner } from '@syncfusion/ej2-react-popups';
import * as React from 'react';
import { useEffect } from 'react';
import './App.css';

function App() {
  useEffect(() => {
    createSpinner({
      target: document.getElementById('container') as HTMLElement
    });
    showSpinner(document.getElementById('container') as HTMLElement);
  }, []);

  return (
    <div id="container" style={{ height: '200px' }} />
  );
}

export default App;

Spinner with Show/Hide Toggle

带显示/隐藏切换的Spinner

tsx

import { createSpinner, showSpinner, hideSpinner } from '@syncfusion/ej2-react-popups';
import { useEffect, useRef, useState } from 'react';

function DataLoader() {
  const ref = useRef<HTMLDivElement>(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (ref.current) {
      createSpinner({ target: ref.current, label: 'Loading...' });
    }
  }, []);

  const load = async () => {
    setLoading(true);
    showSpinner(ref.current as HTMLElement);
    try {
      await fetchData();
    } finally {
      hideSpinner(ref.current as HTMLElement);
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={load} disabled={loading}>Load Data</button>
      <div ref={ref} style={{ height: '200px', position: 'relative' }} />
    </div>
  );
}

tsx

import { createSpinner, showSpinner, hideSpinner } from '@syncfusion/ej2-react-popups';
import { useEffect, useRef, useState } from 'react';

function DataLoader() {
  const ref = useRef<HTMLDivElement>(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (ref.current) {
      createSpinner({ target: ref.current, label: 'Loading...' });
    }
  }, []);

  const load = async () => {
    setLoading(true);
    showSpinner(ref.current as HTMLElement);
    try {
      await fetchData();
    } finally {
      hideSpinner(ref.current as HTMLElement);
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={load} disabled={loading}>Load Data</button>
      <div ref={ref} style={{ height: '200px', position: 'relative' }} />
    </div>
  );
}

Global Spinner Type

全局Spinner类型配置

tsx

import { setSpinner } from '@syncfusion/ej2-react-popups';

// Call BEFORE any createSpinner — sets global default type
setSpinner({ type: 'Bootstrap5' });

tsx

import { setSpinner } from '@syncfusion/ej2-react-popups';

// 在所有createSpinner调用前执行 —— 设置全局默认类型
setSpinner({ type: 'Bootstrap5' });

Common Patterns

常用用法

Pattern 1: Async Fetch with Cleanup

模式1：带清理的异步请求

tsx

const fetchWithSpinner = async (container: HTMLElement) => {
  showSpinner(container);
  try {
    const data = await fetch('/api/data').then(r => r.json());
    return data;
  } finally {
    hideSpinner(container); // Always hide, even on error
  }
};

tsx

const fetchWithSpinner = async (container: HTMLElement) => {
  showSpinner(container);
  try {
    const data = await fetch('/api/data').then(r => r.json());
    return data;
  } finally {
    hideSpinner(container); // 即使报错也始终隐藏
  }
};

Pattern 2: React State Sync

模式2：React状态同步

tsx

useEffect(() => {
  if (!ref.current) return;
  if (isLoading) {
    showSpinner(ref.current);
  } else {
    hideSpinner(ref.current);
  }
}, [isLoading]);

tsx

useEffect(() => {
  if (!ref.current) return;
  if (isLoading) {
    showSpinner(ref.current);
  } else {
    hideSpinner(ref.current);
  }
}, [isLoading]);

Pattern 3: Full-Page Loading

模式3：全屏加载

tsx

useEffect(() => {
  createSpinner({ target: document.body, label: 'Initializing...' });
  showSpinner(document.body);

  initializeApp().finally(() => hideSpinner(document.body));
}, []);

tsx

useEffect(() => {
  createSpinner({ target: document.body, label: 'Initializing...' });
  showSpinner(document.body);

  initializeApp().finally(() => hideSpinner(document.body));
}, []);

Pattern 4: Spinner with Custom Type

模式4：自定义类型Spinner

tsx

createSpinner({
  target: el,
  type: 'Fluent2',
  width: '40px',
  label: 'Processing...',
  cssClass: 'my-overlay'
});

tsx

createSpinner({
  target: el,
  type: 'Fluent2',
  width: '40px',
  label: 'Processing...',
  cssClass: 'my-overlay'
});

Key API Quick Reference

核心API速览

Function	Signature	Purpose
`createSpinner`	`(args: SpinnerArgs) => void`	Initialize spinner on DOM element
`showSpinner`	`(el: HTMLElement) => void`	Show an existing spinner
`hideSpinner`	`(el: HTMLElement) => void`	Hide a visible spinner
`setSpinner`	`(args: SetSpinnerArgs) => void`	Set global defaults for all spinners

SpinnerArgs properties:

target

(required),

width

label

cssClass

template

type

SpinnerType values:

'Material'

'Material3'

'Fabric'

'Bootstrap'

'Bootstrap4'

'Bootstrap5'

'HighContrast'

'Tailwind'

'Tailwind3'

'Fluent'

'Fluent2'

函数	签名	作用
`createSpinner`	`(args: SpinnerArgs) => void`	在DOM元素上初始化spinner
`showSpinner`	`(el: HTMLElement) => void`	展示已存在的spinner
`hideSpinner`	`(el: HTMLElement) => void`	隐藏可见的spinner
`setSpinner`	`(args: SetSpinnerArgs) => void`	为所有spinner设置全局默认值

SpinnerArgs属性：

target

（必填）、

width

、

label

、

cssClass

、

template

、

type

SpinnerType取值：

'Material'

'Material3'

'Fabric'

'Bootstrap'

'Bootstrap4'

'Bootstrap5'

'HighContrast'

'Tailwind'

'Tailwind3'

'Fluent'

'Fluent2'

Critical Rules

重要规则

❌ No
SpinnerComponent
class —

import { SpinnerComponent }

does NOT exist

✅ Only use:

createSpinner

showSpinner

hideSpinner

setSpinner

❌ Do NOT use:
```
color
```
,
```
size
```
,
```
visible
```
,
```
isLoading
```
as SpinnerArgs — they don't exist
✅ Valid SpinnerArgs:
```
target
```
,
```
width
```
,
```
label
```
,
```
cssClass
```
,
```
template
```
,
```
type
```
⚠️ Call
createSpinner
BEFORE
showSpinner
— order matters
⚠️ Put spinner logic in
useEffect
— the DOM element must exist before calling createSpinner
✅ Always call
hideSpinner
in
finally
— prevents stuck loading states

❌ 不存在
SpinnerComponent
类 —— 没有

import { SpinnerComponent }

这种用法

✅ 仅可使用：

createSpinner

、

showSpinner

、

hideSpinner

、

setSpinner

❌ 禁止使用：
```
color
```
、
```
size
```
、
```
visible
```
、
```
isLoading
```
作为SpinnerArgs参数 —— 这些属性不存在
✅ 有效的SpinnerArgs参数：
```
target
```
、
```
width
```
、
```
label
```
、
```
cssClass
```
、
```
template
```
、
```
type
```
⚠️ 先调用
createSpinner
再调用
showSpinner
—— 顺序很重要
⚠️ 将spinner逻辑放在
useEffect
中 —— 调用createSpinner前必须确保DOM元素已存在
✅ 始终在
finally
中调用
hideSpinner
—— 避免加载状态卡住

Troubleshooting

问题排查

Issue	Solution
Spinner not showing	Ensure `createSpinner` is called before `showSpinner` ; check DOM element exists
Spinner stays visible	Call `hideSpinner` in `finally` block; check for unhandled promise rejections
No animation	Verify both `ej2-base` and `ej2-react-popups` CSS imported; `ej2-base` must come first
TypeScript error	Cast: `document.getElementById('id') as HTMLElement` or use `useRef<HTMLDivElement>`
Spinner outside bounds	Add `position: relative` to target element
Wrong theme	Set `type` to match your app's CSS theme (e.g., `'Fluent2'` for Fluent 2 CSS)

问题	解决方案
Spinner不展示	确保 `createSpinner` 调用在 `showSpinner` 之前；检查DOM元素是否存在
Spinner一直可见	在 `finally` 块中调用 `hideSpinner` ；检查是否有未处理的promise rejection
无动画	确认已导入 `ej2-base` 和 `ej2-react-popups` 的CSS； `ej2-base` 的导入必须在前面
TypeScript报错	强制类型转换： `document.getElementById('id') as HTMLElement` 或使用 `useRef<HTMLDivElement>`
Spinner超出边界	为目标元素添加 `position: relative` 样式
主题不匹配	将 `type` 设置为与应用CSS主题匹配的值（例如Fluent 2 CSS对应 `'Fluent2'` ）

Related Components

Resources

资源

Official Docs: https://ej2.syncfusion.com/react/documentation/spinner/
Getting Started: https://ej2.syncfusion.com/react/documentation/spinner/getting-started
npm Package: @syncfusion/ej2-react-popups

undefined

官方文档： https://ej2.syncfusion.com/react/documentation/spinner/
快速开始： https://ej2.syncfusion.com/react/documentation/spinner/getting-started
npm包： @syncfusion/ej2-react-popups