syncfusion-react-buttons

Syncfusion React Buttons

📌 Agent 通知：“导航指南”部分中的 📄 Read: 链接仅用于被动读取文件参考，不代表会自动调用工具、执行命令或串联操作。

---

Button

Syncfusion ButtonComponent 是一种图形用户界面元素，点击后会触发操作。它支持文本、图标或两者兼有，并提供丰富的样式、无障碍和行为选项。

导航指南

入门

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

• 安装和包配置
• CSS 导入和主题配置
• 渲染第一个 ButtonComponent
• 启用波纹效果
• 基本点击处理

类型和样式

📄 阅读： references/button-types-and-styles.md

• 预定义颜色样式（primary、success、info、warning、danger、link）
• 扁平、轮廓、圆形和切换按钮类型
• 基本 HTML 按钮类型（submit、reset）
• 图标按钮（字体图标、SVG）
• 图标位置（左侧/右侧）
• 按钮大小（小、普通）

操作模式

📄 阅读： references/button-how-to.md

• 创建块级（全宽）按钮
• 创建圆角按钮
• 为按钮添加导航链接
• 使用 CSS 自定义按钮外观
• 将原生 input 和锚点元素设置为按钮样式
• 设置禁用状态
• 启用从右到左（RTL）支持
• 添加悬停提示
• 实现重复按钮

样式和外观

📄 阅读： references/button-style-and-appearance.md

• 可用 CSS 类及其用途
• 覆盖默认样式
• 使用 Theme Studio 创建自定义主题

无障碍

📄 阅读： references/button-accessibility.md

• 符合 WCAG 2.2、Section 508 标准
• WAI-ARIA 属性
• 键盘导航
• 屏幕阅读器支持

API 参考

📄 阅读： references/button-api.md

• 所有属性、方法和事件
• 属性类型、默认值和限制

---

快速开始

⚠️ 请在终端中手动运行以下命令。不要自动执行。

# Run in your terminal
npm install @syncfusion/ej2-react-buttons --save

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

import { enableRipple } from '@syncfusion/ej2-base';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';
import './App.css';

enableRipple(true);

function App() {
  return (
    <div>
      <ButtonComponent>Default</ButtonComponent>
      <ButtonComponent cssClass='e-primary'>Primary</ButtonComponent>
      <ButtonComponent cssClass='e-success'>Success</ButtonComponent>
    </div>
  );
}
export default App;

---

常见模式

样式化按钮

<ButtonComponent cssClass='e-primary'>Save</ButtonComponent>
<ButtonComponent cssClass='e-danger'>Delete</ButtonComponent>
<ButtonComponent cssClass='e-flat'>Flat</ButtonComponent>
<ButtonComponent cssClass='e-outline'>Outline</ButtonComponent>

图标按钮

<ButtonComponent iconCss='e-icons e-save'>Save</ButtonComponent>
<ButtonComponent iconCss='e-icons e-delete' iconPosition='Right'>Delete</ButtonComponent>

切换按钮

const [active, setActive] = React.useState(false);
<ButtonComponent isToggle={true} cssClass='e-flat'
  onClick={() => setActive(!active)}>
  {active ? 'Pause' : 'Play'}
</ButtonComponent>

禁用按钮

<ButtonComponent disabled={true}>Disabled</ButtonComponent>

块级（全宽）按钮

<ButtonComponent cssClass='e-block e-primary'>Full Width</ButtonComponent>

---

ButtonGroup

ButtonGroup 是一个纯 CSS 组件，可将一系列按钮组合在一起，采用水平（默认）或垂直布局。它支持普通按钮行为，以及单选型（单选）和复选框型（多选）行为。按钮可以与 DropDownButton 和 SplitButton 组件嵌套使用。

导航指南

入门

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

• 安装和包配置
• 添加 CSS 引用和主题导入
• ButtonGroup 基本实现
• 运行应用程序

类型和样式

📄 阅读： references/buttongroup-types-and-styles.md

• 轮廓 ButtonGroup（e-outline）
• 预定义颜色样式（e-primary、e-success、e-info、e-warning、e-danger）
• 在组内混用样式

选择和嵌套

📄 阅读： references/buttongroup-selection-and-nesting.md

• 单选（单选型）
• 多选（复选框型）
• 设置初始选中状态
• 在 ButtonGroup 中嵌套 DropDownButton
• 在 ButtonGroup 中嵌套 SplitButton

使用指南

📄 阅读： references/buttongroup-how-to.md

• 为按钮添加图标（iconCss）
• 圆角（e-round-corner）
• 禁用单个按钮或所有按钮
• 启用波纹效果
• 启用 RTL 支持
• 垂直方向（e-vertical）
• 使用单选/复选框 ButtonGroup 提交表单
• 使用 createButtonGroup 实用函数进行初始化

样式与外观

📄 阅读： references/buttongroup-style-and-appearance.md

• 可用于自定义的 CSS 类
• 覆盖悬停、焦点和激活状态
• 集成 Theme Studio

无障碍

📄 阅读： references/buttongroup-accessibility.md

• 符合 WCAG 2.2、Section 508 标准
• 键盘导航快捷键
• 屏幕阅读器支持

---

快速开始

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

function App() {
  return (
    <div className='e-btn-group'>
      <ButtonComponent>HTML</ButtonComponent>
      <ButtonComponent>CSS</ButtonComponent>
      <ButtonComponent>Javascript</ButtonComponent>
    </div>
  );
}
export default App;

src/App.css 中必需的 CSS 导入：

@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-splitbuttons/styles/tailwind3.css";

---

常见模式

单选 ButtonGroup

<div className='e-btn-group'>
  <input type="radio" id="radioleft" name="align" value="left" />
  <label className="e-btn" htmlFor="radioleft">Left</label>
  <input type="radio" id="radiomiddle" name="align" value="middle" />
  <label className="e-btn" htmlFor="radiomiddle">Center</label>
  <input type="radio" id="radioright" name="align" value="right" />
  <label className="e-btn" htmlFor="radioright">Right</label>
</div>

复选框（多选）ButtonGroup

<div className='e-btn-group'>
  <input type="checkbox" id="checkbold" name="font" value="bold" />
  <label className="e-btn" htmlFor="checkbold">Bold</label>
  <input type="checkbox" id="checkitalic" name="font" value="italic" />
  <label className="e-btn" htmlFor="checkitalic">Italic</label>
  <input type="checkbox" id="checkline" name="font" value="underline" />
  <label className="e-btn" htmlFor="checkline">Underline</label>
</div>

垂直 ButtonGroup

<div className='e-btn-group e-vertical'>
  <ButtonComponent>HTML</ButtonComponent>
  <ButtonComponent>CSS</ButtonComponent>
  <ButtonComponent>Javascript</ButtonComponent>
</div>

---

关键属性

属性 / 类	组件	描述
cssClass	ButtonComponent	应用样式类（e-outline、e-primary、e-success、e-info、e-warning、e-danger）
iconCss	ButtonComponent	按钮图标的 CSS 类
disabled	ButtonComponent	禁用按钮
isPrimary	ButtonComponent	将按钮标记为主要按钮
e-btn-group	容器 div	ButtonGroup 必需的包装类
e-outline	容器 div + 按钮	为组应用轮廓样式
e-round-corner	容器 div	为组应用圆角
e-vertical	容器 div	垂直布局
e-rtl	容器 div	从右向左布局

---

下拉按钮

Syncfusion DropDownButtonComponent 会渲染一个按钮，点击后可切换显示包含操作项列表的上下文弹出菜单。它支持图标、分隔线、模板、动画、无障碍功能和丰富的自定义选项。

导航指南

入门

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

• 安装和软件包设置
• CSS 导入和主题配置
• 渲染第一个 DropDownButtonComponent
• 使用 items 绑定数据源
• 最简可运行示例

弹出项与导航

📄 阅读： references/dropdownbutton-popup-items.md

• 使用 iconCss 为弹出项添加图标
• 通过项上的 url 设置导航 URL
• 使用分隔线对弹出项分组
• 使用 beforeItemRender 设置项模板
• 弹出菜单（目标）模板
• 项文本中的下划线字符

图标与布局

📄 阅读： references/dropdownbutton-icons-and-layout.md

• 使用 iconCss 和 iconPosition 设置按钮图标
• 使用 e-caret-hide 设置纯图标按钮
• 精灵图图标
• 使用 e-vertical 设置垂直按钮布局
• 自定义图标大小和按钮宽度

外观与样式

📄 阅读： references/dropdownbutton-appearance-and-styling.md

• CSS 类覆盖（颜色样式、大小、状态）
• 使用 e-round-corner 设置圆角
• 使用 e-caret-hide 隐藏下拉箭头
• 使用 popupWidth 设置弹出菜单宽度
• 使用 Theme Studio 自定义
• 弹出菜单打开/关闭的动画设置

事件与交互

📄 阅读： references/dropdownbutton-events-and-interactivity.md

• 处理项点击时的 select 事件
• 使用 beforeOpen / beforeClose 动态设置插入符图标
• 使用 open 事件自定义弹出菜单的位置
• 使用 disabled 禁用按钮
• 使用 enableRtl 支持 RTL
• 选择项时打开对话框
• 动态使用 addItems / removeItems 方法
• 使用 toggle 方法以编程方式打开/关闭

项模板

📄 阅读： references/dropdownbutton-item-template.md

• 使用 itemTemplate 属性自定义项的渲染方式
• 在项中渲染链接、图标和丰富内容

ListView 集成

📄 阅读： references/dropdownbutton-listview-integration.md

• 将 target 属性与 ListView 元素配合使用
• 带类别标题的分组弹出项

无障碍访问

📄 阅读： references/dropdownbutton-accessibility.md

• 符合 WCAG 2.2、Section 508 和 ADA 标准
• WAI-ARIA 属性（role、aria-haspopup、aria-expanded）
• 键盘导航快捷键
• 屏幕阅读器支持

API 参考

📄 阅读： references/dropdownbutton-api.md

• 所有属性：items、cssClass、iconCss、iconPosition、disabled、enableRtl、animationSettings、popupWidth、target、itemTemplate、content、closeActionEvents、createPopupOnClick、enableHtmlSanitizer、enablePersistence、locale
• 所有事件：beforeClose、beforeOpen、beforeItemRender、close、open、select、created
• 所有方法：addItems、removeItems、toggle、focusIn、destroy、getPersistData
• 类型定义：ItemModel、MenuEventArgs、OpenCloseMenuEventArgs、BeforeOpenCloseMenuEventArgs

---

快速入门

import { DropDownButtonComponent, ItemModel } from '@syncfusion/ej2-react-splitbuttons';
import { enableRipple } from '@syncfusion/ej2-base';
import * as React from 'react';
import './App.css';

enableRipple(true);

function App() {
  const items: ItemModel[] = [
    { text: 'Cut' },
    { text: 'Copy' },
    { text: 'Paste' },
  ];

  return (
    <DropDownButtonComponent items={items}>
      Clipboard
    </DropDownButtonComponent>
  );
}

export default App;

---

常见模式

带图标和弹出图标的按钮

const items: ItemModel[] = [
  { text: 'Edit',   iconCss: 'ddb-icons e-edit' },
  { text: 'Delete', iconCss: 'ddb-icons e-delete' },
];
<DropDownButtonComponent items={items} iconCss="ddb-icons e-message">
  Message
</DropDownButtonComponent>

带分隔符的分组项

const items: ItemModel[] = [
  { text: 'Cut',   iconCss: 'e-db-icons e-cut' },
  { text: 'Copy',  iconCss: 'e-icons e-copy' },
  { separator: true },
  { text: 'Font',  iconCss: 'e-db-icons e-font' },
];

处理项选择

import { MenuEventArgs } from '@syncfusion/ej2-react-splitbuttons';

function onSelect(args: MenuEventArgs) {
  console.log('Selected:', args.item.text);
}
<DropDownButtonComponent items={items} select={onSelect}>
  Actions
</DropDownButtonComponent>

---

浮动操作按钮

Syncfusion React FabComponent 是一个悬浮于 UI 上方的圆形按钮，用于表示应用中的主要操作。它支持灵活的定位、图标 + 文本内容、预定义样式、全面的无障碍访问支持以及 CSS 自定义。

软件包： @syncfusion/ej2-react-buttons

导航指南

开始使用

📄 阅读： references/floating-action-button-getting-started.md

• 安装 @syncfusion/ej2-react-buttons
• Tailwind3 的 CSS 主题导入
• FabComponent 基本设置
• 使用 target 相对于容器定位
• 处理点击事件

图标和内容

📄 阅读： references/floating-action-button-icons.md

• 使用 iconCss 属性创建仅含图标的 FAB
• 使用 content 属性设置文本标签
• 使用 iconPosition 设置图标在左或右的布局
• 图标 + 文本组合示例

位置

📄 阅读： references/floating-action-button-positions.md

• position 属性提供全部九种预定义值（TopLeft → BottomRight）
• 使用 target 属性将 FAB 限定在容器内
• 使用 cssClass 自定义 CSS 位置

样式和外观

📄 阅读： references/floating-action-button-styles.md

• 预定义的 cssClass 值：e-primary、e-outline、e-info、e-success、e-warning、e-danger
• CSS 类覆盖参考表
• 使用 CSS 过渡效果在悬停时显示文本
• 自定义轮廓颜色

事件

📄 阅读： references/floating-action-button-events.md

• 使用 onClick 事件处理点击
• 使用 created 事件在渲染完成后进行初始化

无障碍访问

📄 阅读： references/floating-action-button-accessibility.md

• 符合 WCAG 2.2 / Section 508 标准
• WAI-ARIA 属性（aria-label、aria-disabled、role="button"）
• 键盘导航（Enter、Space、Tab、Escape）
• 通过 enableRtl 支持 RTL
• 屏幕阅读器支持

API 参考

📄 **阅读： references/floating-action-button-api.md

• 所有属性：content、cssClass、disabled、enableHtmlSanitizer、enablePersistence、enableRtl、iconCss、iconPosition、isPrimary、isToggle、position、target、visible
• 方法：click()、destroy()、focusIn()、getPersistData()、refreshPosition()
• 事件：created、onClick

---

快速入门

⚠️ 请在终端中手动运行以下命令。请勿自动执行。

# Run in your terminal
npm install @syncfusion/ej2-react-buttons --save

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

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

function App() {
  return (
    <div>
      <div id="targetElement" style={{ position: 'relative', minHeight: '350px', border: '1px solid' }}></div>
      <FabComponent id="fab" content="Add" target="#targetElement" />
    </div>
  );
}
export default App;

---

常见模式

仅图标的 FAB（最常见）

import { FabComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  return (
    <div>
      <div id="target" style={{ position: 'relative', minHeight: '350px' }}></div>
      <FabComponent id="fab" iconCss="e-icons e-edit" target="#target" />
    </div>
  );
}
export default App;

带点击处理程序的 FAB

import { FabComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  function handleClick(): void {
    alert('FAB clicked!');
  }

  return (
    <div>
      <div id="target" style={{ position: 'relative', minHeight: '350px' }}></div>
      <FabComponent id="fab" iconCss="e-icons e-edit" content="Edit" onClick={handleClick} target="#target" />
    </div>
  );
}
export default App;

使用自定义样式的 FAB

import { FabComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function App() {
  return (
    <div>
      <div id="target" style={{ position: 'relative', minHeight: '350px' }}></div>
      <FabComponent id="fab" iconCss="e-icons e-delete" cssClass="e-danger" target="#target" />
    </div>
  );
}
export default App;

---

关键属性一览

属性	类型	默认值	用途
iconCss	string	''	FAB 图标的 CSS 类
content	string	''	显示在 FAB 上或旁边的文本标签
iconPosition	'Left' | 'Right'	'Left'	图标相对于文本的位置
position	FabPosition	'BottomRight'	在目标元素或视口中的预定义位置
target	string | HTMLElement	''	用于限定 FAB 作用范围的容器元素选择器
cssClass	string	''	用于设置样式的自定义 CSS 类
disabled	boolean	false	禁用 FAB
visible	boolean	true	显示或隐藏 FAB
isPrimary	boolean	true	应用主要样式
enableRtl	boolean	false	从右向左渲染
enableHtmlSanitizer	boolean	true	对 content 中的 HTML 进行清理

---

Speed Dial

Syncfusion SpeedDialComponent 是一种浮动操作按钮（FAB），点击或悬停时会显示一组上下文操作项。它支持线性和径向显示模式、灵活定位、模板、动画、模态覆盖层以及完整的无障碍功能。

导航指南

入门

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

• 安装和软件包设置
• CSS 导入和主题配置
• 渲染第一个 SpeedDialComponent
• 基本项目配置
• 目标元素设置

项目配置

📄 阅读： references/speeddial-items.md

• SpeedDialItemModel 字段（text、iconCss、id、title、disabled）
• 仅图标、仅文本、图标和文本组合
• 禁用单个项目
• 动画效果（Fade、Zoom 等）
• 项目模板概述

显示模式

📄 阅读： references/speeddial-display-modes.md

• 线性模式（默认）和方向值（Up、Down、Left、Right、Auto）
• 径向模式概述和用法

径向菜单

📄 阅读： references/speeddial-radial-menu.md

• 将 mode 设置为 Radial
• radialSettings：direction（Clockwise、AntiClockwise、Auto）
• startAngle 和 endAngle 配置
• 使用 offset 控制项目与按钮之间的距离

位置和可见性控制

📄 阅读： references/speeddial-positions.md

• 位置值（TopLeft、TopCenter、TopRight、MiddleLeft、MiddleCenter、MiddleRight、BottomLeft、BottomCenter、BottomRight）
• 相对于目标元素定位
• opensOnHover 控制悬停时的打开行为
• 通过 show() 和 hide() 方法进行编程控制
• 布局变化后调用 refreshPosition()

样式和外观

📄 阅读： references/speeddial-styles.md

• 使用 openIconCss 和 closeIconCss 设置按钮图标
• 使用 content 属性设置文本按钮
• 预定义的 cssClass 值（e-primary、e-outline、e-info、e-success、e-warning、e-danger）
• disabled 和 visible 属性
• 通过 title 属性显示工具提示
• 自定义 CSS 覆盖

模板

📄 阅读： references/speeddial-template.md

• 用于自定义项渲染的 itemTemplate
• 用于完全自定义弹出窗口的 popupTemplate
• JSX 函数模板模式

事件

📄 阅读： references/speeddial-events.md

• clicked、created、beforeOpen、onOpen、beforeClose、onClose、beforeItemRender
• 事件参数类型：SpeedDialItemEventArgs、SpeedDialBeforeOpenCloseEventArgs、SpeedDialOpenCloseEventArgs
• beforeOpen 和 beforeClose 的取消模式

模态

📄 阅读： references/speeddial-modal.md

• 启用模态遮罩层
• 交互阻止行为
• 点击背景时关闭

无障碍

📄 阅读： references/speeddial-accessibility.md

• 符合 WCAG 2.2、Section 508 标准
• WAI-ARIA 属性（role、aria-expanded、aria-label 等）
• 键盘导航快捷键
• 屏幕阅读器支持
• 通过 enableRtl 支持 RTL

API 参考

📄 阅读： references/speeddial-api.md

• 所有属性、方法和事件的类型及默认值

---

快速开始

⚠️ 请在终端中手动运行以下命令。请勿自动执行。

# Run in your terminal
npm install @syncfusion/ej2-react-buttons --save

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

import { SpeedDialComponent, SpeedDialItemModel } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';
import './App.css';

function App() {
  const items: SpeedDialItemModel[] = [
    { text: 'Cut', iconCss: 'e-icons e-cut' },
    { text: 'Copy', iconCss: 'e-icons e-copy' },
    { text: 'Paste', iconCss: 'e-icons e-paste' }
  ];

  return (
    <div id="targetElement" style={{ position: 'relative', minHeight: '350px', border: '1px solid' }}>
      <SpeedDialComponent
        id='speeddial'
        content='Edit'
        openIconCss='e-icons e-edit'
        closeIconCss='e-icons e-close'
        items={items}
        target="#targetElement"
      />
    </div>
  );
}
export default App;

---

常见模式

带工具提示的纯图标项

const items: SpeedDialItemModel[] = [
  { iconCss: 'e-icons e-cut', title: 'Cut' },
  { iconCss: 'e-icons e-copy', title: 'Copy' },
  { iconCss: 'e-icons e-paste', title: 'Paste' }
];
<SpeedDialComponent id='speeddial' openIconCss='e-icons e-edit' items={items} target="#targetElement" />

径向模式

import { RadialSettingsModel } from '@syncfusion/ej2-react-buttons';
const radialSettings: RadialSettingsModel = { direction: 'AntiClockwise', offset: '80px' };
<SpeedDialComponent id='speeddial' openIconCss='e-icons e-edit' items={items}
  mode='Radial' radialSettings={radialSettings} target="#targetElement" />

处理项点击

import { SpeedDialItemEventArgs } from '@syncfusion/ej2-react-buttons';
function itemClick(args: SpeedDialItemEventArgs) {
  console.log('Clicked:', args.item.text);
}
<SpeedDialComponent id='speeddial' items={items} content='Edit' clicked={itemClick} target="#targetElement" />

带遮罩层的模态窗口

<SpeedDialComponent id='speeddial' items={items} openIconCss='e-icons e-edit'
  modal={true} target="#targetElement" />

通过编程方式打开/关闭

let speeddialRef: SpeedDialComponent;
<SpeedDialComponent id='speeddial' items={items} openIconCss='e-icons e-edit'
  target="#targetElement" ref={scope => { speeddialRef = scope; }} />
// Open:  speeddialRef.show();
// Close: speeddialRef.hide();

实现 Syncfusion React ProgressButton

@syncfusion/ej2-react-splitbuttons 中的 ProgressButtonComponent 提供了一个按钮，可直观显示后台操作的进度，并配有动画微调器、背景进度条填充，以及操作各阶段的内容/样式钩子。

导航指南

任务	阅读
安装包并首次渲染	references/getting-started.md
微调器的位置/大小/模板 + 进度条 + 动画 + 步进/百分比/启动/停止	references/spinner-and-progress.md
CSS 类、主题、Theme Studio	references/style-and-appearance.md
ARIA 属性、键盘快捷键、屏幕阅读器兼容性	references/accessibility.md
启用背景进度填充	references/how-to-enable-progress-in-button.md
隐藏微调器（仅显示进度条）	references/how-to-hide-spinner.md
垂直、顶部或反向进度填充	references/how-to-customize-progress-using-cssclass.md
在进度运行时更改按钮文本/CSS 类	references/how-to-change-text-content-and-styles-of-the-progressbutton-during-progress.md
跟踪/处理生命周期事件	references/how-to-trace-events-of-progress-button.md
完整 API 参考（所有属性、事件、方法、类型）	references/api.md

---

快速开始

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

// src/App.tsx
import { ProgressButtonComponent } from '@syncfusion/ej2-react-splitbuttons';
import './App.css';

function App() {
  return <ProgressButtonComponent content="Submit" />;
}
export default App;

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

---

常见模式

进度条 + 隐藏微调器

<ProgressButtonComponent
  content="Upload"
  enableProgress={true}
  cssClass="e-hide-spinner"
  duration={4000}
/>

自定义微调器（右侧、小尺寸、模板化）

import { SpinSettingsModel } from '@syncfusion/ej2-react-splitbuttons';

const spinSettings: SpinSettingsModel = {
  position: 'Right',
  width: 20,
  template: '<div class="my-spinner"></div>'
};

<ProgressButtonComponent content="Submit" spinSettings={spinSettings} />

带居中微调器的滑动动画

import { AnimationSettingsModel, SpinSettingsModel } from '@syncfusion/ej2-react-splitbuttons';

const spinSettings: SpinSettingsModel = { position: 'Center' };
const animationSettings: AnimationSettingsModel = {
  effect: 'SlideLeft',
  duration: 500,
  easing: 'linear'
};

<ProgressButtonComponent
  content="Slide Left"
  enableProgress={true}
  spinSettings={spinSettings}
  animationSettings={animationSettings}
/>

通过编程方式控制启动/停止

let progressBtn: ProgressButtonComponent;

<ProgressButtonComponent
  content="Download"
  enableProgress={true}
  duration={4000}
  cssClass="e-hide-spinner"
  ref={(scope) => { progressBtn = scope as ProgressButtonComponent; }}
/>

// Pause:  progressBtn.stop();
// Resume: progressBtn.start();
// Finish: progressBtn.progressComplete();

生命周期事件

<ProgressButtonComponent
  content="Progress"
  enableProgress={true}
  begin={(args) => console.log('started', args.percent)}
  progress={(args) => console.log('progress', args.percent)}
  end={(args) => console.log('done', args.percent)}
  fail={(args) => console.log('failed', args)}
/>

---

参考文件

文件	内容
references/getting-started.md	安装、CSS 导入、第一个组件
references/spinner-and-progress.md	加载器配置、动画、步骤、动态百分比、启动/停止
references/style-and-appearance.md	CSS 类表、主题设置
references/accessibility.md	ARIA、键盘导航、合规性矩阵
references/how-to-enable-progress-in-button.md	enableProgress 操作指南
references/how-to-hide-spinner.md	e-hide-spinner 操作指南
references/how-to-customize-progress-using-cssclass.md	垂直 / 顶部 / 反向填充
references/how-to-change-text-content-and-styles-of-the-progressbutton-during-progress.md	进度期间动态更改文本/样式
references/how-to-trace-events-of-progress-button.md	事件跟踪示例
references/api.md	完整 API：属性、事件、方法、类型

开关

Syncfusion 的 SwitchComponent 是一种图形化切换控件，可在选中（开启）和未选中（关闭）状态之间切换。它属于 @syncfusion/ej2-react-buttons 包，支持文本标签、尺寸变体、禁用状态、表单提交、RTL、程序化控制和完整的 CSS 自定义。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装软件包和 npm 设置
• CSS 主题导入
• 基本的 SwitchComponent 渲染
• 初始化选中状态
• 运行应用程序

功能和配置

📄 阅读： references/features.md

• onLabel / offLabel 文本标签
• disabled 属性
• 用于表单提交的 name 和 value
• 用于自定义样式的 cssClass
• 用于支持从右到左布局的 enableRtl
• 用于在重新加载后保留状态的 enablePersistence
• 用于添加 HTML 属性的 htmlAttributes
• 用于本地化的 locale

事件和方法

📄 阅读： references/events-and-methods.md

• change 事件和 ChangeEventArgs
• 用于取消状态转换的 beforeChange 事件
• created 生命周期事件
• 用于程序化控制状态的 toggle() 方法
• click()、focusIn() 和 destroy() 方法
• 使用 ref 命令式调用方法

操作指南

📄 阅读： references/how-to.md

• 更改开关尺寸（小号或默认）
• 使用 beforeChange 阻止状态更改
• 设置文本标签（ON/OFF）
• 在标签点击时启用涟漪效果
• 启用 RTL 布局
• 设置禁用状态
• 在表单中提交名称和值
• 通过 toggle() 方法程序化切换

样式和外观

📄 阅读： references/style-and-appearance.md

• CSS 类参考表
• 自定义条形和手柄形状
• 自定义开关颜色
• 小尺寸变体
• 使用 Theme Studio

API 参考

📄 阅读： references/api.md

• 所有属性及其类型和默认值
• 所有方法及其返回类型
• 所有事件及其参数接口
• ChangeEventArgs 和 BeforeChangeEventArgs

快速入门

import { SwitchComponent } from '@syncfusion/ej2-react-buttons';
import { enableRipple } from '@syncfusion/ej2-base';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-buttons/styles/tailwind3.css';

enableRipple(true);

function App() {
  return <SwitchComponent checked={true} />;
}
export default App;

请先安装软件包：

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

常见模式

带 ON/OFF 文本标签的开关

<SwitchComponent onLabel="ON" offLabel="OFF" checked={true} />

注意：Material 主题不支持文本标签。

处理状态更改

import { ChangeEventArgs, SwitchComponent } from '@syncfusion/ej2-react-buttons';

function App() {
  function onChange(args: ChangeEventArgs) {
    console.log('Switch is now:', args.checked);
  }
  return <SwitchComponent change={onChange} />;
}

禁用的开关

<SwitchComponent disabled={true} />

小尺寸开关

<SwitchComponent cssClass="e-small" />

以编程方式切换

import { useRef } from 'react';
import { SwitchComponent } from '@syncfusion/ej2-react-buttons';

function App() {
  const switchRef = useRef<SwitchComponent>(null);

  function handleToggle() {
    switchRef.current?.toggle();
  }

  return (
    <>
      <SwitchComponent ref={switchRef} checked={false} />
      <button onClick={handleToggle}>Toggle</button>
    </>
  );
}

使用名称和值提交表单

<SwitchComponent name="wifi" value="enabled" checked={true} />

关键属性一览

属性	类型	默认值	用途
checked	boolean	false	初始选中状态
disabled	boolean	false	禁止用户交互
cssClass	string	''	自定义 CSS 类（小尺寸请使用 e-small）
onLabel	string	''	选中时显示的标签
offLabel	string	''	未选中时显示的标签
name	string	''	表单字段名称
value	string	''	表单字段值
enableRtl	boolean	false	从右向左布局
enablePersistence	boolean	false	重新加载时保留状态

SplitButton

一份全面的指南，介绍如何在 React 应用中实现 SplitButton 组件。SplitButton 将主要操作按钮与用于次要操作的下拉菜单组合在一起。

涵盖的组件

一种同时显示主要操作和次要操作下拉菜单的按钮。

常见使用场景：

• 保存选项： 保存、另存为、全部保存
• 发送选项： 发送、定时发送、全部发送
• 下载选项： 下载、全部下载、导出
• 共享选项： 共享、共享链接、通过电子邮件共享
• 打印选项： 打印、打印预览、打印设置

文档

入门

📄 阅读： references/getting-started.md

• 安装和包设置
• SplitButton 基础实现
• CSS 导入和主题
• 第一个可运行示例
• 模块设置（独立式和基于模块的）

类型和样式

📄 阅读： references/types-and-styles.md

• 按钮样式（主要、成功、信息、警告、危险、链接）
• 按钮类型（扁平、轮廓、圆形）
• 图标位置（左侧、右侧、顶部、底部）
• 尺寸选项（小、中、大）
• 设置样式的锚点元素
• RTL 支持

SplitButton 功能

📄 阅读： references/splitbutton-features.md

• 下拉菜单项
• 图标和文本组合
• 禁用状态
• 事件处理（单击、选择、打开前）
• 动态操作项
• 键盘导航
• 工具提示和标题

API 参考

📄 阅读： references/api-reference.md

• 完整的属性文档
• 方法及其用法
• 事件处理器和回调
• 模型接口
• 类型定义
• 快速参考表

自定义

📄 阅读： references/customization.md

• 自定义 CSS 类
• 主题和配色方案
• 自定义图标和字体
• 自定义操作项模板
• 响应式设计
• 动画和过渡效果
• 操作项分隔符和分组

无障碍功能

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 标准
• 键盘导航模式
• ARIA 属性
• 屏幕阅读器支持
• 焦点管理
• 无障碍标签和描述

快速入门

基础 SplitButton

import { SplitButtonComponent } from '@syncfusion/ej2-react-splitbuttons';
import '@syncfusion/ej2-react-splitbuttons/styles/material.css';

function App() {
  const items = [
    { text: 'Save' },
    { text: 'Save As' },
    { text: 'Save All' }
  ];

  const handleClick = (args) => {
    console.log('Primary action clicked');
  };

  const handleSelect = (args) => {
    console.log('Menu item selected:', args.item.text);
  };

  return (
    <SplitButtonComponent
      items={items}
      onClick={handleClick}
      select={handleSelect}
    >
      Save
    </SplitButtonComponent>
  );
}

export default App;

带图标的 SplitButton

import { SplitButtonComponent } from '@syncfusion/ej2-react-splitbuttons';
import '@syncfusion/ej2-react-splitbuttons/styles/material.css';

function SaveButton() {
  const items = [
    { text: 'Save', iconCss: 'e-icons e-save' },
    { text: 'Save As', iconCss: 'e-icons e-save-as' },
    { text: 'Save All', iconCss: 'e-icons e-save-all' }
  ];

  return (
    <SplitButtonComponent
      items={items}
      iconCss="e-icons e-save"
      cssClass="e-primary"
    >
      Save
    </SplitButtonComponent>
  );
}

export default SaveButton;

带事件处理的 SplitButton

import { SplitButtonComponent } from '@syncfusion/ej2-react-splitbuttons';
import { useState } from 'react';

function EventHandlingExample() {
  const [lastAction, setLastAction] = useState('');

  const items = [
    { text: 'Send Now' },
    { text: 'Schedule Send' },
    { text: 'Send Test' }
  ];

  const handlePrimaryClick = () => {
    setLastAction('Primary action: Send Now');
    console.log('Email sent immediately');
  };

  const handleMenuSelect = (args) => {
    setLastAction(`Menu selected: ${args.item.text}`);
    console.log('Selected:', args.item.text);
  };

  const handleBeforeOpen = (args) => {
    console.log('Dropdown menu opening');
  };

  return (
    <div>
      <SplitButtonComponent
        items={items}
        onClick={handlePrimaryClick}
        select={handleMenuSelect}
        beforeOpen={handleBeforeOpen}
        cssClass="e-primary"
      >
        Send
      </SplitButtonComponent>
      <p>{lastAction}</p>
    </div>
  );
}

export default EventHandlingExample;

带动态操作项的 SplitButton

import { SplitButtonComponent } from '@syncfusion/ej2-react-splitbuttons';
import { useRef, useState } from 'react';

function DynamicItemsExample() {
  const [items, setItems] = useState([
    { text: 'Option 1' },
    { text: 'Option 2' }
  ]);

  const splitBtnRef = useRef(null);

  const addItem = () => {
    const newItem = { text: `Option ${items.length + 1}` };
    setItems([...items, newItem]);
  };

  const removeItem = () => {
    if (items.length > 1) {
      setItems(items.slice(0, -1));
    }
  };

  return (
    <div>
      <SplitButtonComponent
        ref={splitBtnRef}
        items={items}
        cssClass="e-primary"
      >
        Action
      </SplitButtonComponent>
      <div style={{ marginTop: '20px' }}>
        <button onClick={addItem}>Add Item</button>
        <button onClick={removeItem} style={{ marginLeft: '10px' }}>
          Remove Item
        </button>
      </div>
    </div>
  );
}

export default DynamicItemsExample;

带自定义模板的 SplitButton

import { SplitButtonComponent } from '@syncfusion/ej2-react-splitbuttons';

function CustomTemplateExample() {
  const items = [
    { text: 'Bold', icon: 'B' },
    { text: 'Italic', icon: 'I' },
    { text: 'Underline', icon: 'U' }
  ];

  const itemTemplate = (props) => {
    return (
      <div style={{ display: 'flex', alignItems: 'center', padding: '8px' }}>
        <span style={{ 
          fontWeight: props.icon === 'B' ? 'bold' : 'normal',
          fontStyle: props.icon === 'I' ? 'italic' : 'normal',
          textDecoration: props.icon === 'U' ? 'underline' : 'none',
          marginRight: '8px'
        }}>
          {props.icon}
        </span>
        <span>{props.text}</span>
      </div>
    );
  };

  return (
    <SplitButtonComponent
      items={items}
      itemTemplate={itemTemplate}
      cssClass="e-primary"
    >
      Format Text
    </SplitButtonComponent>
  );
}

export default CustomTemplateExample;

常见模式

保存选项模式

const items = [
  { text: 'Save', iconCss: 'e-icons e-save' },
  { separator: true },
  { text: 'Save As', iconCss: 'e-icons e-save-as' },
  { text: 'Save All', iconCss: 'e-icons e-save-all' }
];

下载模式

const items = [
  { text: 'Download PDF' },
  { text: 'Download Excel' },
  { text: 'Download CSV' },
  { separator: true },
  { text: 'Download All' }
];

共享模式

const items = [
  { text: 'Share Link', iconCss: 'e-icons e-link' },
  { text: 'Email', iconCss: 'e-icons e-mail' },
  { text: 'Print', iconCss: 'e-icons e-print' },
  { text: 'Export', iconCss: 'e-icons e-export' }
];

状态管理模式

const [isLoading, setIsLoading] = useState(false);

const handleAction = async (args) => {
  setIsLoading(true);
  try {
    // Perform action
    await performAction(args.item.text);
  } finally {
    setIsLoading(false);
  }
};

关键属性概览

属性	类型	默认值	用途
items	ItemModel[]	[]	下拉菜单项
cssClass	string	''	用于设置样式的 CSS 类
iconCss	string	''	主按钮的图标 CSS
iconPosition	string	'Left'	图标位置（Left、Right、Top、Bottom）
disabled	boolean	false	禁用按钮
enableRtl	boolean	false	启用 RTL 模式
created	function	-	组件创建时触发的事件
click	function	-	主按钮点击处理程序
select	function	-	菜单项选择处理程序
beforeOpen	function	-	下拉菜单打开前触发
beforeClose	function	-	下拉菜单关闭前触发
open	function	-	下拉菜单打开后触发
close	function	-	下拉菜单关闭后触发

后续步骤

1. 安装与设置 → 阅读 getting-started.md
2. 样式选项 → 阅读 types-and-styles.md
3. 功能 → 阅读 splitbutton-features.md
4. 完整 API → 阅读 api-reference.md
5. 高级自定义 → 阅读 customization.md
6. 无障碍功能 → 阅读 accessibility.md

故障排除快捷链接

• 未显示菜单项？ → 查看 references/getting-started.md#css-imports
• 事件未触发？ → 查看 references/splitbutton-features.md#event-handling
• 样式问题？ → 查看 references/types-and-styles.md
• 无障碍方面有疑问？ → 查看 references/accessibility.md

资源

• 官方文档： Syncfusion React SplitButton
• API 参考： Syncfusion SplitButton API
• 在线演示： Syncfusion React Demos

RadioButton

用于实现 Syncfusion React RadioButtonComponent 的技能——一种图形用户界面元素，可让用户从一组选项中恰好选择一个。支持选中/未选中状态、标签位置、小尺寸、表单集成、RTL、禁用状态以及完整的 CSS 自定义。

导航指南

开始使用

📄 阅读： references/getting-started.md

• 安装软件包并导入 CSS
• 渲染基本的 RadioButtonComponent
• 使用 name 属性对单选按钮分组
• 快速设置 Vite + React 项目
• 启用涟漪效果

标签和尺寸

📄 阅读： references/label-and-size.md

• 使用 label 属性添加标题
• 使用 labelPosition 将标签放在前面或后面
• 使用 cssClass="e-small" 应用小尺寸
• 默认与紧凑尺寸变体

功能和状态

📄 阅读： references/features-and-state.md

• 使用 checked 设置选中/未选中状态
• 使用 disabled 禁用 RadioButton
• 使用 name 和 value 对按钮分组并提交表单
• 使用 enableRtl 设置 RTL 布局
• 通过 change 事件处理状态变化
• 使用 created 监听组件生命周期

样式和外观

📄 阅读： references/style-and-appearance.md

• 覆盖默认 CSS 类
• 创建语义化颜色变体（primary、success、warning 等）
• 使用 cssClass 设置自定义样式
• 集成 Theme Studio 以实现全局主题设置
• CSS 类参考表

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• WAI-ARIA 属性（role、aria-checked、aria-disabled）
• 键盘导航快捷键
• 屏幕阅读器支持

API 参考

📄 阅读： references/api.md

• 所有属性：checked、disabled、label、labelPosition、name、value、cssClass、enableRtl、enablePersistence、enableHtmlSanitizer、htmlAttributes、locale
• 方法：click()、destroy()、focusIn()、getSelectedValue()
• 事件：change（ChangeArgs）、created

快速入门

import { enableRipple } from '@syncfusion/ej2-base';
import { RadioButtonComponent } from '@syncfusion/ej2-react-buttons';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-buttons/styles/tailwind3.css';

enableRipple(true);

function App() {
  return (
    <ul>
      <li><RadioButtonComponent label="Option 1" name="group1" checked={true} /></li>
      <li><RadioButtonComponent label="Option 2" name="group1" /></li>
      <li><RadioButtonComponent label="Option 3" name="group1" /></li>
    </ul>
  );
}
export default App;

常见模式

使用变更处理程序管理受控状态

import { RadioButtonComponent, ChangeArgs } from '@syncfusion/ej2-react-buttons';
import { useState } from 'react';

function App() {
  const [selected, setSelected] = useState('monthly');

  const handleChange = (args: ChangeArgs) => {
    setSelected(args.value);
  };

  return (
    <ul>
      <li>
        <RadioButtonComponent
          label="Monthly"
          name="plan"
          value="monthly"
          checked={selected === 'monthly'}
          change={handleChange}
        />
      </li>
      <li>
        <RadioButtonComponent
          label="Yearly"
          name="plan"
          value="yearly"
          checked={selected === 'yearly'}
          change={handleChange}
        />
      </li>
    </ul>
  );
}

使用 name/value 提交表单

<form>
  <RadioButtonComponent name="payment" value="card"    label="Credit Card" checked={true} />
  <RadioButtonComponent name="payment" value="bank"    label="Net Banking" />
  <RadioButtonComponent name="payment" value="cod"     label="Cash on Delivery" />
  <button type="submit">Submit</button>
</form>

在一组选项中禁用某个选项

<RadioButtonComponent label="Available"   name="seat" />
<RadioButtonComponent label="Unavailable" name="seat" disabled={true} />

紧凑小尺寸

<RadioButtonComponent label="Compact" name="size" cssClass="e-small" />

RTL 支持

<RadioButtonComponent label="خيار 1" name="rtl" enableRtl={true} />

关键属性摘要

属性	类型	默认值	用途
label	string	''	显示在按钮旁的说明文字
name	string	''	将按钮分组，使其互斥
value	string	''	选中时提交的表单值
checked	boolean	false	设置选中状态
disabled	boolean	false	禁止用户交互
labelPosition	'Before' | 'After'	'After'	标签位置
cssClass	string	''	自定义 CSS 类
enableRtl	boolean	false	从右向左布局
enablePersistence	boolean	false	在页面重新加载后保留状态

选择指南

• 让用户从多个选项中选择一个 → 使用 name 分组，并为每个选项设置 value
• 预选默认选项 → 在目标选项上设置 checked={true}
• 读取所选选项 → 使用 change 事件（args.value）或调用 getSelectedValue()
• 禁止选择某个选项 → 使用 disabled={true}
• 紧凑的 UI 布局 → 添加 cssClass="e-small"
• RTL 语言界面 → 使用 enableRtl={true}
• 自定义颜色/品牌样式 → 配合自定义 CSS 规则使用 cssClass（参见 style-and-appearance.md）

芯片

Syncfusion React Chips（ChipListComponent）组件可渲染紧凑、可交互的元素，用于表示输入、属性或操作。它支持单选/多选、删除、拖放、头像、图标、模板和丰富的样式设置。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和包配置（@syncfusion/ej2-react-buttons）
• CSS/主题导入
• 渲染基本芯片或芯片列表
• 单个芯片与使用 ChipsDirective / ChipDirective 的芯片列表
• 运行应用程序

类型和选择

📄 阅读： references/types-and-selection.md

• 四种芯片类型：Input、Choice、Filter、Action
• 单选（selection="Single"）——Choice 芯片
• 多选（selection="Multiple"）——Filter 芯片
• 可删除芯片（enableDelete）
• 使用 selectedChips 预选芯片
• 用于 Action 芯片的点击事件（onClick）

自定义

📄 阅读： references/customization.md

• 预定义样式：e-primary、e-success、e-info、e-warning、e-danger
• 前置图标（leadingIconCss、leadingIconUrl）
• 头像图片（avatarIconCss）和头像文本（avatarText）
• 后置图标（trailingIconCss、trailingIconUrl）
• 轮廓芯片（cssClass="e-outline"）
• 自定义芯片模板（template 属性）
• 使用 htmlAttributes 设置自定义 HTML 属性

拖放

📄 阅读： references/drag-and-drop.md

• 启用拖放（allowDragAndDrop）
• 限制拖动区域（dragArea）
• 拖动事件：dragStart、dragging、dragStop
• 跨容器拖放

样式自定义

📄 阅读： references/style.md

• 自定义芯片文本、图标和删除按钮的 CSS 覆盖样式
• 轮廓芯片边框样式
• 选中芯片的背景和颜色
• 头像文本背景样式
• 自定义芯片高度和尺寸

无障碍功能

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2、Section 508 和 ADA 标准
• WAI-ARIA 属性（role、aria-selected、aria-disabled 等）
• 键盘导航快捷键
• 支持 RTL 和屏幕阅读器

API 参考

📄 阅读： references/api.md

• 所有属性：text、chips、selection、enableDelete、cssClass、selectedChips、enabled、enableRtl、enablePersistence、allowDragAndDrop、dragArea、htmlAttributes、leadingIconCss、leadingIconUrl、avatarIconCss、avatarText、trailingIconCss、trailingIconUrl
• 方法：add()、remove()、find()、getSelectedChips()、select()、destroy()
• 事件：click、beforeClick、created、delete、deleted、dragStart、dragging、dragStop

快速入门

import { ChipListComponent, ChipsDirective, ChipDirective } from '@syncfusion/ej2-react-buttons';
import { enableRipple } from '@syncfusion/ej2-base';
import * as React from 'react';
import './App.css';

enableRipple(true);

function App() {
  return (
    <ChipListComponent id="chip-list">
      <ChipsDirective>
        <ChipDirective text="Angular" />
        <ChipDirective text="React" />
        <ChipDirective text="Vue" />
      </ChipsDirective>
    </ChipListComponent>
  );
}
export default App;

CSS（App.css）：

@import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-react-buttons/styles/tailwind3.css';

常见模式

筛选芯片（多选）

<ChipListComponent selection="Multiple">
  <ChipsDirective>
    <ChipDirective text="React" />
    <ChipDirective text="Angular" />
    <ChipDirective text="Vue" />
  </ChipsDirective>
</ChipListComponent>

带事件的可删除芯片

<ChipListComponent enableDelete={true} delete={(e) => console.log('Deleting:', e.text)}>
  <ChipsDirective>
    <ChipDirective text="Tag One" />
    <ChipDirective text="Tag Two" />
  </ChipsDirective>
</ChipListComponent>

带头像首字母的芯片

<ChipListComponent>
  <ChipsDirective>
    <ChipDirective text="Andrew" avatarText="A" />
    <ChipDirective text="Laura" avatarText="L" />
  </ChipsDirective>
</ChipListComponent>

以编程方式控制（通过 ref 添加/移除芯片）

const chipRef = React.useRef<ChipListComponent>(null);

// Add a chip
chipRef.current?.add('New Tag');

// Remove chip at index 0
chipRef.current?.remove([0]);

// Get selected
const selected = chipRef.current?.getSelectedChips();