syncfusion-angular-buttons

实现 Syncfusion Angular 按钮

按钮

Syncfusion Angular 按钮是通过 ejs-button 指令呈现的图形用户界面元素。点击时会触发操作，并支持文本、图标或两者同时使用，还提供丰富的样式、无障碍功能和行为选项。

导航指南

入门

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

• 前置条件和软件包依赖项
• 设置新的 Angular 应用（独立架构）
• 通过 ng add 安装 @syncfusion/ej2-angular-buttons
• Material 和其他主题的 CSS/主题导入
• 渲染第一个 ejs-button 指令
• 使用 cssClass 更改按钮类型

类型和样式

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

• 预定义颜色样式（e-primary、e-success、e-info、e-warning、e-danger、e-link）
• 基本 HTML 类型：提交和重置按钮
• 扁平、轮廓、圆形和切换按钮类型
• 通过 e-active 类设置切换按钮的激活状态
• 使用 iconCss 和 iconPosition 创建图标按钮
• 支持 SVG 图标
• 按钮尺寸：小（e-small）和普通

操作指南

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

• 使用 e-block 创建块级（全宽）按钮
• 使用自定义 CSS 创建圆角按钮
• 在按钮内添加导航链接
• 使用自定义 CSS 类自定义按钮外观
• 将原生 <input> 和 <a> 元素设置为按钮样式
• 使用 [disabled]="true" 设置禁用状态
• 使用 [enableRtl]="true" 启用从右到左（RTL）支持
• 使用 created 事件添加悬停提示
• 使用鼠标和触摸事件实现重复按钮

无障碍功能

📄 阅读： references/button-accessibility.md

• WCAG 2.2 和 Section 508 合规性详情
• WAI-ARIA 属性（仅含图标的按钮使用 aria-label）
• 键盘交互：空格键行为
• 屏幕阅读器支持和自动化测试工具

EJ1 迁移

📄 阅读： references/button-ej1-migration.md

• EJ1 到 EJ2 的属性映射（例如，text → content、prefixIcon → iconCss）
• 对应的方法和事件
• EJ2 中不可用的属性

API 参考

📄 阅读： references/button-api.md

• 所有属性的类型、默认值和代码示例
• 方法：click()、focusIn()、destroy()
• 事件：created

---

快速入门

ng add @syncfusion/ej2-angular-buttons

// src/app/app.ts (Angular 20+) or src/app/app.component.ts (Angular 19 and below)
import { ButtonModule } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [ButtonModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div class="e-section-control">
      <button ejs-button>Default</button>
      <button ejs-button cssClass="e-primary">Primary</button>
      <button ejs-button cssClass="e-success">Success</button>
    </div>
  `
})
export class AppComponent { }

Angular 20+ 注意： CLI 会生成 src/app/app.ts、app.html 和 app.css（不带 .component. 后缀）。在 Angular 19 及更早版本中，文件名为 app.component.ts。

---

常见模式

彩色样式按钮

<button ejs-button cssClass="e-primary">Primary</button>
<button ejs-button cssClass="e-success">Success</button>
<button ejs-button cssClass="e-warning">Warning</button>
<button ejs-button cssClass="e-danger">Danger</button>

图标按钮

<button ejs-button iconCss="e-icons e-save">Save</button>
<button ejs-button iconCss="e-icons e-delete" iconPosition="Right">Delete</button>

切换按钮

// In component class
@ViewChild('togglebtn') togglebtn: ButtonComponent | any;
@HostListener('click', ['togglebtn'])
btnClick() {
  if (this.togglebtn.element.classList.contains('e-active')) {
    this.togglebtn.content = 'Pause';
  } else {
    this.togglebtn.content = 'Play';
  }
}

<button #togglebtn ejs-button cssClass="e-flat" [isToggle]="true" content="Play"></button>

禁用按钮

<button ejs-button [disabled]="true">Disabled</button>

块级（全宽）按钮

<button ejs-button cssClass="e-block e-primary">Full Width</button>

---

按钮组

Syncfusion Angular 按钮组是一个纯 CSS 组件，可将多个按钮组合成一个统一的 UI 元素。它支持水平和垂直布局、单选/复选选择行为、轮廓和颜色样式、图标按钮、嵌套拆分/下拉按钮、RTL、表单集成，以及全面的无障碍功能。

软件包： @syncfusion/ej2-angular-buttons 容器类： .e-btn-group 按钮指令： ejs-button（来自 ButtonModule）

---

导航指南

入门

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

• 通过 ng add 安装 @syncfusion/ej2-angular-buttons
• 在独立组件的 imports[] 中导入 ButtonModule
• Material 主题的 CSS 主题导入
• 使用 ejs-button 创建基本水平按钮组
• 使用 e-vertical 类设置垂直方向

类型和样式

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

• 轮廓 ButtonGroup（在容器和每个按钮上添加 e-outline）
• 通过 cssClass 设置颜色样式：e-primary、e-success、e-info、e-warning、e-danger
• 使用 e-round-corner 设置圆角
• 使用 iconCss 属性创建图标按钮

选择（单选和复选）

📄 阅读： references/buttongroup-selection.md

• 单选（radio 类型）：使用 <input type="radio"> + <label class="e-btn">
• 多选（checkbox 类型）：使用 <input type="checkbox"> + <label class="e-btn">
• 使用 checked 属性在初始渲染时显示预选状态
• 在组内嵌套 DropDownButton 或 SplitButton

操作指南

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

• 禁用单个按钮或整个组
• 启用波纹效果
• RTL（从右向左）布局
• 使用单选/复选按钮组提交表单
• 使用 createButtonGroup 工具以编程方式初始化

无障碍访问

📄 阅读： references/buttongroup-accessibility.md

• 符合 WCAG 2.2 / Section 508 标准
• 键盘导航快捷键（常规、复选、单选行为）
• 屏幕阅读器指南

---

快速入门

1. 安装软件包：

ng add @syncfusion/ej2-angular-buttons

2. 将 CSS 添加到 styles.css：

@import 'node_modules/@syncfusion/ej2-base/styles/material.css';
@import 'node_modules/@syncfusion/ej2-buttons/styles/material.css';
@import 'node_modules/@syncfusion/ej2-splitbuttons/styles/material.css';

3. 创建基本的 ButtonGroup：

import { Component } from '@angular/core';
import { ButtonModule } from '@syncfusion/ej2-angular-buttons';

@Component({
  imports: [ButtonModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div class='e-btn-group'>
      <button ejs-button>HTML</button>
      <button ejs-button>CSS</button>
      <button ejs-button>JavaScript</button>
    </div>`
})
export class AppComponent { }

---

常见模式

垂直 ButtonGroup

在容器中添加 e-vertical，按钮便会从上到下排列：

<div class='e-btn-group e-vertical'>
  <button ejs-button>HTML</button>
  <button ejs-button>CSS</button>
  <button ejs-button>JavaScript</button>
</div>

e-vertical 不支持嵌套 SplitButton。

轮廓样式

在容器中添加 e-outline，并在每个按钮上设置 cssClass='e-outline'：

<div class='e-btn-group e-outline'>
  <button ejs-button cssClass='e-outline'>HTML</button>
  <button ejs-button cssClass='e-outline'>CSS</button>
  <button ejs-button cssClass='e-outline'>JavaScript</button>
</div>

单选（单选）

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

复选（多选）

<div class='e-btn-group'>
  <input type="checkbox" id="check_bold" name="font" value="bold"/>
  <label class="e-btn" for="check_bold">Bold</label>
  <input type="checkbox" id="check_italic" name="font" value="italic"/>
  <label class="e-btn" for="check_italic">Italic</label>
  <input type="checkbox" id="check_underline" name="font" value="underline"/>
  <label class="e-btn" for="check_underline">Underline</label>
</div>

---

关键选择指南

用户需求	方案
以视觉方式组合操作按钮	使用 ejs-button 的基本 e-btn-group
每次只能选择一个选项	单选类型（input[radio] + label.e-btn）
可选择多个选项	复选类型（input[checkbox] + label.e-btn）
垂直排列按钮	在容器中添加 e-vertical
带图标的按钮	在每个 ejs-button 上设置 iconCss 属性
为组设置圆角	在容器中设置 e-round-corner
RTL 布局	在容器中设置 e-rtl
以编程方式初始化	使用来自 @syncfusion/ej2-splitbuttons 的 createButtonGroup
使用下拉菜单/弹出窗口扩展组	嵌套 ejs-dropdownbutton 或 ejs-splitbutton

---

DropDownButton

Syncfusion Angular DropDownButton 是通过 ejs-dropdownbutton 指令渲染的图形用户界面元素。它显示一个按钮，点击后会打开包含操作项的弹出菜单。它支持图标、自定义模板、动画、导航链接、无障碍访问、RTL 和动态项目管理。

---

导航指南

开始使用

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

• 前置条件和软件包依赖项
• 设置新的 Angular 应用程序（独立架构）
• 通过 ng add 安装 @syncfusion/ej2-angular-splitbuttons
• Material 和其他主题的 CSS/主题导入
• 渲染第一个 ejs-dropdownbutton 指令
• 定义 ItemModel[] 操作项

图标和外观

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

• 使用 iconCss 和 iconPosition（Left、Top）设置按钮图标
• 使用 e-vertical cssClass 设置垂直按钮布局
• 使用 e-caret-hide cssClass 创建纯图标按钮
• 将精灵图像用作按钮图标
• 隐藏下拉箭头
• 圆角样式
• 自定义图标大小和按钮宽度
• 动态更改插入符/下拉箭头图标

弹出项与模板

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

• 通过 iconCss 为弹出操作项添加图标
• 通过项的 url 属性添加导航链接
• 使用 separator: true 设置分隔项
• 使用 beforeItemRender 事件为单项设置模板
• 通过 target 属性设置整个弹出项的模板
• 使用 itemTemplate 属性自定义项的呈现方式
• 以 ListView 作为弹出目标，对项进行分组
• 在项文本中为字符添加下划线

事件与交互

📄 阅读： references/dropdownbutton-events.md

• select — 处理项选择
• open / close — 弹出项打开/关闭回调
• beforeOpen / beforeClose — 在打开/关闭前取消操作或进行自定义
• beforeItemRender — 在呈现期间自定义每个项
• created — 组件初始化回调
• 在点击弹出项时打开对话框
• 通过 open 事件更改弹出项的打开位置

动画

📄 阅读： references/dropdownbutton-animation.md

• animationSettings 属性概述
• 支持的效果：None、SlideDown、ZoomIn、FadeIn
• 配置 duration 和 easing

配置与行为

📄 阅读： references/dropdownbutton-configuration.md

• 通过 disabled 禁用 DropDownButton
• 通过 enableRtl 支持 RTL
• 使用 popupWidth 设置一致的弹出项宽度
• 使用 createPopupOnClick 延迟创建弹出项
• 使用 enableHtmlSanitizer 安全地呈现 HTML
• 使用 closeActionEvents 自定义弹出项的关闭触发方式
• 使用 enablePersistence 持久化状态
• 动态管理项：addItems、removeItems、toggle

API 参考

📄 阅读： references/dropdownbutton-api.md

• 所有属性及其类型、默认值和说明
• 所有事件及其参数类型
• 所有方法及其参数和返回类型
• ItemModel 接口字段
• 支持的接口：BeforeOpenCloseMenuEventArgs、MenuEventArgs、OpenCloseMenuEventArgs

无障碍功能

📄 阅读： references/dropdownbutton-accessibility.md

• 符合 WCAG 2.2 / Section 508 标准
• WAI-ARIA 属性和角色
• 键盘导航快捷键
• 屏幕阅读器支持
• RTL 支持

---

快速入门

import { Component } from '@angular/core';
import { DropDownButtonModule, ItemModel } from '@syncfusion/ej2-angular-splitbuttons';

@Component({
  standalone: true,
  imports: [DropDownButtonModule],
  selector: 'app-root',
  template: `
    <button ejs-dropdownbutton [items]="items" content="Clipboard" iconCss="e-icons e-copy" (select)="onSelect($event)"></button>
  `
})
export class AppComponent {
  public items: ItemModel[] = [
    { text: 'Cut',   iconCss: 'e-icons e-cut' },
    { text: 'Copy',  iconCss: 'e-icons e-copy' },
    { text: 'Paste', iconCss: 'e-icons e-paste' }
  ];

  onSelect(args: any) {
    console.log('Selected:', args.item.text);
  }
}

---

常见模式

带分隔符分组的弹出项

public items: ItemModel[] = [
  { text: 'Cut' },
  { text: 'Copy' },
  { text: 'Paste' },
  { separator: true },
  { text: 'Font' },
  { text: 'Paragraph' }
];

仅图标按钮（无文本、无箭头）

<button ejs-dropdownbutton [items]="items" iconCss="e-icons e-menu" cssClass="e-caret-hide"></button>

顶部带图标的垂直布局

<button ejs-dropdownbutton [items]="items" content="Paste" iconCss="e-icons e-paste" iconPosition="Top" cssClass="e-vertical"></button>

RTL 布局

<button ejs-dropdownbutton [items]="items" content="Message" enableRtl="true"></button>

自定义弹出项宽度

<button ejs-dropdownbutton [items]="items" [popupWidth]="'250px'" content="Options"></button>

导航项

public items: ItemModel[] = [
  { text: 'Home',   url: '/home' },
  { text: 'About',  url: '/about' }
];

---

浮动操作按钮

Syncfusion Angular 浮动操作按钮（ejs-fab）是一个悬浮在 UI 上方的圆形按钮，代表应用中的主要操作。它支持灵活的定位、图标 + 文本内容、预定义样式、事件、全面的无障碍合规性以及 CSS 自定义。

包： @syncfusion/ej2-angular-buttons 模块： FabModule 选择器： ejs-fab

---

导航指南

入门

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

• 通过 ng add 安装 @syncfusion/ej2-angular-buttons
• 导入 Material 主题的 CSS 主题文件
• 在独立组件中导入 FabModule
• 最简 ejs-fab 配置
• 使用 target 将 FAB 限定在容器内
• 处理 (click) 事件

图标与内容

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

• 使用 iconCss 属性设置仅含图标的 FAB
• 使用 content 属性设置文本标签
• 使用 iconPosition 设置图标位于左侧还是右侧
• 组合图标与文本的 FAB 示例

位置

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

• position 属性支持全部九种预定义值（TopLeft → BottomRight）
• 使用 target 属性将 FAB 限定在容器元素内
• 使用 cssClass 设置自定义 CSS 位置
• 在目标元素调整大小后调用 refreshPosition()

样式和外观

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

• 预定义的 cssClass 值：e-primary、e-outline、e-info、e-success、e-warning、e-danger
• CSS 类覆盖参考表（.e-fab.e-btn、悬停、聚焦、激活、图标）
• 使用 CSS 过渡效果在悬停时显示文本
• 自定义轮廓颜色

事件

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

• (created) 事件，用于渲染后的初始化
• (click) 事件，用于处理点击

无障碍

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

• WCAG 2.2 / Section 508 合规性摘要
• WAI-ARIA 属性（aria-label）
• 键盘交互（Space 键）
• 通过 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、click

---

快速入门

ng add @syncfusion/ej2-angular-buttons

/* styles.css – added automatically by ng add */
@import '../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material.css';
@import '../node_modules/@syncfusion/ej2-icons/styles/material.css';

import { FabModule } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [FabModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div id="targetElement" style="position:relative;min-height:350px;border:1px solid;"></div>
    <button ejs-fab id="fab" content="Add" target="#targetElement"></button>
  `
})
export class AppComponent { }

---

常见模式

仅图标 FAB（最常见）

import { FabModule } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [FabModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div id="target" style="position:relative;min-height:350px;border:1px solid;"></div>
    <button ejs-fab id="fab" iconCss="e-icons e-edit" target="#target"></button>
  `
})
export class AppComponent { }

带点击处理程序的 FAB

import { FabModule } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [FabModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div id="target" style="position:relative;min-height:350px;border:1px solid;"></div>
    <button ejs-fab id="fab" iconCss="e-icons e-edit" content="Edit"
      (click)="onFabClick()" target="#target"></button>
  `
})
export class AppComponent {
  onFabClick(): void {
    alert('FAB clicked!');
  }
}

使用自定义样式的 FAB

import { FabModule } from '@syncfusion/ej2-angular-buttons';
import { Component } from '@angular/core';

@Component({
  imports: [FabModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div id="target" style="position:relative;min-height:350px;border:1px solid;"></div>
    <button ejs-fab id="fab" iconCss="e-icons e-delete" cssClass="e-danger" target="#target"></button>
  `
})
export class AppComponent { }

---

关键属性一览

属性	类型	默认值	用途
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

---

速度拨盘

Syncfusion Angular Speed Dial 组件会渲染一个浮动操作按钮，展开后可显示一组操作项。该组件基于 ejs-speeddial 指令，支持线性和径向显示模式、灵活定位、动画、模态覆盖层、自定义模板，并全面符合无障碍规范。

---

导航指南

开始使用

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

• 先决条件和软件包依赖项
• 通过 ng add 安装 @syncfusion/ej2-angular-buttons
• CSS/主题导入
• 使用 items 渲染第一个 ejs-speeddial 指令
• 独立组件与 NgModule 架构

项目和动画

📄 阅读： references/speeddial-items-and-animation.md

• 配置操作项（SpeedDialItemModel：text、iconCss、id、title、disabled）
• 仅图标、仅文本以及图标加文本的项目变体
• 禁用单个项目
• 配置打开/关闭动画（animation、SpeedDialAnimationSettingsModel）
• 支持的动画效果（Fade、Zoom 等）

显示模式

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

• 线性模式：类似列表的显示方式，使用 direction（Up、Down、Left、Right、Auto）
• 径向模式：使用 mode='Radial' 呈现圆形排列
• 配置径向设置（radialSettings：direction、startAngle、endAngle、offset）
• 根据使用场景选择模式

位置和可见性

📄 阅读： references/speeddial-position-and-visibility.md

• 全部 9 个 position 值（TopLeft → BottomRight）
• 使用 target 将 Speed Dial 锚定在容器内
• 通过 opensOnHover 在悬停时打开项目
• 使用 show() 和 hide() 方法以编程方式显示/隐藏
• 使用 refreshPosition() 刷新按钮位置
• 使用 visible 属性控制可见性

样式和外观

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

• 自定义按钮图标：openIconCss、closeIconCss、content
• 通过 cssClass 应用预定义 CSS 样式（e-primary、e-success、e-warning 等）
• 使用 disabled 启用/禁用组件
• 使用 visible 控制可见性
• 使用 opensOnHover 设置悬停打开行为
• 通过 title 字段设置项目提示
• 使用自定义 CSS 类

模板

📄 阅读： references/speeddial-templates.md

• 使用 itemTemplate 和 <ng-template #itemTemplate> 设置项目模板
• 使用 popupTemplate 和 <ng-template #popupTemplate> 设置弹出框模板
• 模板上下文和绑定

事件

📄 阅读： references/speeddial-events.md

• clicked — 点击操作项目时触发（SpeedDialItemEventArgs）
• created — 组件渲染完成时触发
• beforeOpen / onOpen — 弹出框打开生命周期
• beforeClose / onClose — 弹出框关闭生命周期
• beforeItemRender — 每个项目渲染时触发

无障碍

📄 阅读： references/speeddial-accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• WAI-ARIA 属性（role、aria-label、aria-expanded 等）
• 键盘快捷键（Enter、方向键、Esc、Home、End）
• 屏幕阅读器和 RTL 支持

API 参考

📄 阅读： references/speeddial-api.md

• 所有组件属性及其类型和默认值
• 所有方法：show()、hide()、refreshPosition()
• 所有事件及其参数类型
• SpeedDialItemModel 字段
• SpeedDialAnimationSettingsModel 字段
• RadialSettingsModel 字段

---

快速入门

import { Component } from '@angular/core';
import { SpeedDialModule, SpeedDialItemModel } from '@syncfusion/ej2-angular-buttons';

@Component({
  imports: [SpeedDialModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <div id="target" style="position:relative; min-height:350px; border:1px solid;"></div>
    <button ejs-speeddial
      id="speeddial"
      content="Edit"
      openIconCss="e-icons e-edit"
      closeIconCss="e-icons e-close"
      target="#target"
      [items]="items"
      (clicked)="onItemClicked($event)">
    </button>
  `
})
export class AppComponent {
  public items: SpeedDialItemModel[] = [
    { text: 'Cut',   iconCss: 'e-icons e-cut' },
    { text: 'Copy',  iconCss: 'e-icons e-copy' },
    { text: 'Paste', iconCss: 'e-icons e-paste' }
  ];

  public onItemClicked(args: any) {
    console.log(args.item.text + ' clicked');
  }
}

---

常见模式

带提示的纯图标项目

public items: SpeedDialItemModel[] = [
  { iconCss: 'e-icons e-cut',   title: 'Cut' },
  { iconCss: 'e-icons e-copy',  title: 'Copy' },
  { iconCss: 'e-icons e-paste', title: 'Paste' }
];

径向菜单

<button ejs-speeddial id="speeddial"
  openIconCss="e-icons e-edit"
  closeIconCss="e-icons e-close"
  mode="Radial"
  position="MiddleCenter"
  target="#target"
  [items]="items"
  [radialSettings]="radialSettings">
</button>

public radialSettings: RadialSettingsModel = {
  direction: 'AntiClockwise',
  startAngle: 180,
  endAngle: 360,
  offset: '80px'
};

模态覆盖层

<button ejs-speeddial id="speeddial"
  openIconCss="e-icons e-edit"
  [modal]="true"
  target="#target"
  [items]="items">
</button>

以编程方式显示/隐藏

@ViewChild('speeddial') speeddialObj: SpeedDialComponent;

show() { this.speeddialObj.show(); }
hide() { this.speeddialObj.hide(); }

ProgressButton

Syncfusion Angular ProgressButton（ejs-progressbutton）在标准按钮的基础上加入了内置进度指示——旋转加载图标和/或背景填充 UI——适用于异步操作、表单提交，或任何具有可感知等待时间的操作。

导航指南

任务	参考文件
安装和基本设置	📄 references/getting-started.md
旋转加载图标配置和进度动画	📄 references/spinner-and-progress.md
操作指南（隐藏旋转加载图标、cssClass、事件、文本/样式更改）	📄 references/how-to.md
无障碍和键盘交互	📄 references/accessibility.md
完整 API — 属性、方法、事件、接口	📄 references/api.md

快速入门

# Install the package
ng add @syncfusion/ej2-angular-splitbuttons

// src/app/app.ts (Angular 20+) or app.component.ts (Angular 19 and below)
import { Component } from '@angular/core';
import { ProgressButtonModule } from '@syncfusion/ej2-angular-splitbuttons';

@Component({
  standalone: true,
  imports: [ProgressButtonModule],
  selector: 'app-root',
  template: `
    <button ejs-progressbutton content="Upload" [enableProgress]="true"
            [duration]="3000">
    </button>
  `
})
export class AppComponent {}

/* styles.css — or import individually */
@import '@syncfusion/ej2-base/styles/material.css';
@import '@syncfusion/ej2-buttons/styles/material.css';
@import '@syncfusion/ej2-popups/styles/material.css';
@import '@syncfusion/ej2-splitbuttons/styles/material.css';

常见模式

右侧显示旋转加载图标

template: `
  <button ejs-progressbutton content="Submit"
          [spinSettings]="{ position: 'Right' }">
  </button>
`

背景填充和动画

template: `
  <button ejs-progressbutton content="Download" [enableProgress]="true"
          [animationSettings]="{ effect: 'SlideLeft' }">
  </button>
`

处理生命周期事件

template: `
  <button ejs-progressbutton content="Send"
          (begin)="onBegin($event)"
          (progress)="onProgress($event)"
          (end)="onEnd($event)"
          (fail)="onFail($event)">
  </button>
`
// Component class
onBegin(args: any)    { console.log('Started:', args.percent); }
onProgress(args: any) { console.log('Progress:', args.percent); }
onEnd(args: any)      { console.log('Completed'); }
onFail(args: any)     { console.log('Failed'); }

以编程方式控制

@ViewChild('progressBtn') progressBtn!: ProgressButtonComponent;

startProgress()    { this.progressBtn.start(0); }
stopProgress()     { this.progressBtn.stop(); }
completeProgress() { this.progressBtn.progressComplete(); }

Switch

一个轻量级切换组件（ejs-switch），用于开/关二元输入。支持选中状态、标签、禁用状态、尺寸调整、双向绑定、表单集成、自定义样式、事件，以及完整的 WCAG 2.2 无障碍支持。

导航指南

入门

📄 阅读： references/getting-started.md

• 使用 ng add @syncfusion/ej2-angular-buttons 安装
• 独立组件和 NgModule 配置
• 带有 checked 状态的基本 Switch
• CSS / SCSS 主题导入
• 设置 onLabel 和 offLabel 文本

Switch 功能

📄 阅读： references/switch-features.md

• 禁用状态（disabled 属性）
• 尺寸变体 — 默认和小尺寸（cssClass: 'e-small'）
• RTL 支持（enableRtl）
• 使用 ngModel 进行双向数据绑定
• 使用 toggle() 方法以编程方式切换
• 页面重新加载后保留状态（enablePersistence）

事件与状态控制

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

• change 事件 — 响应用户触发的状态切换
• beforeChange 事件 — 拦截并取消状态变更
• created 事件 — 在组件渲染后运行逻辑
• 原生方法 click() 和 focusIn()

表单集成

📄 阅读： references/form-integration.md

• 用于表单 POST 的 name 和 value 属性
• 规则：不会提交禁用或未选中的值
• 使用 ngModel 进行模板驱动的双向绑定
• 在表单中通过 name 对 Switch 分组

自定义

📄 阅读： references/customization.md

• 使用 cssClass 应用自定义样式
• 修改栏/手柄的形状（通过 CSS 设置为直角）
• 自定义开/关状态下的栏颜色
• 为 Switch 标签启用波纹效果
• 通过 htmlAttributes 添加额外的 HTML 属性

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 / Section 508 / ADA 标准
• WAI-ARIA：role="switch"、aria-disabled
• 键盘导航（使用空格键切换）
• 屏幕阅读器支持和 RTL 无障碍支持

API 参考

📄 阅读： references/api.md

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

---

快速开始

ng add @syncfusion/ej2-angular-buttons

// src/app/app.ts (Angular 19+ standalone)
import { Component } from '@angular/core';
import { SwitchModule } from '@syncfusion/ej2-angular-buttons';

@Component({
  standalone: true,
  imports: [SwitchModule],
  selector: 'app-root',
  template: `
    <ejs-switch [checked]="isOn" (change)="onToggle($event)"></ejs-switch>
  `
})
export class AppComponent {
  isOn = false;

  onToggle(args: any): void {
    console.log('Switch is now:', args.checked);
  }
}

/* styles.css */
@import '../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material.css';

---

常见模式

默认选中

<ejs-switch [checked]="true"></ejs-switch>

使用开/关标签

<ejs-switch [checked]="true" onLabel="ON" offLabel="OFF"></ejs-switch>

Material 主题中不会显示标签。避免使用较长的自定义文本。

小尺寸

<ejs-switch cssClass="e-small"></ejs-switch>

禁用

<ejs-switch [disabled]="true"></ejs-switch>

双向绑定

<ejs-switch [(ngModel)]="isEnabled"></ejs-switch>
<p>State: {{ isEnabled }}</p>

有条件地阻止状态变更

<ejs-switch (beforeChange)="onBeforeChange($event)"></ejs-switch>

onBeforeChange(args: BeforeChangeEventArgs): void {
  // Cancel if condition not met
  if (!this.canToggle) {
    args.cancel = true;
  }
}

以编程方式切换

@ViewChild('switch') switchObj!: SwitchComponent;

toggle(): void {
  this.switchObj.toggle();
}

RadioButton

Syncfusion Angular RadioButton（ejs-radiobutton）是一种表单输入组件，可让用户从一组选项中准确选择一个。它支持标签、尺寸变体、双向绑定、表单集成、无障碍功能和丰富的自定义选项。

导航指南

入门

📄 阅读： references/getting-started.md

• Angular 19+/21 独立组件配置
• 使用 ng add 安装软件包
• CSS/SCSS 主题导入
• 简洁的 RadioButton 示例
• 运行应用程序

标签、尺寸与状态

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

• label 和 labelPosition（Before/After）
• 尺寸变体：默认和小尺寸（e-small）
• checked 和未选中状态
• disabled 状态
• enablePersistence

表单与数据绑定

📄 阅读： references/forms-and-binding.md

• 用于对单选按钮分组的 name 属性
• 用于提交表单的 value 属性
• 表单提交时发送的值
• 使用 [(ngModel)] 进行双向绑定
• 将 RadioButton 组绑定到 DropDownList

自定义与高级功能

📄 阅读： references/customization-and-advanced.md

• 自定义 CSS 类和外观样式
• 从右向左（enableRtl）
• 用于 ARIA 和数据属性的 htmlAttributes
• enableHtmlSanitizer 和 locale
• 方法：getSelectedValue()、click()、focusIn()、destroy()

无障碍访问

📄 阅读： references/accessibility.md

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

API 参考

📄 阅读： references/api.md

• 所有属性及其类型、默认值和用法示例
• 所有方法及其签名
• 事件和 ChangeArgs 接口

---

快速开始

import { Component } from '@angular/core';
import { RadioButtonModule } from '@syncfusion/ej2-angular-buttons';

@Component({
  standalone: true,
  imports: [RadioButtonModule],
  selector: 'app-root',
  template: `
    <ejs-radiobutton label="Option A" name="choice" value="a" [checked]="true"></ejs-radiobutton>
    <ejs-radiobutton label="Option B" name="choice" value="b"></ejs-radiobutton>
    <ejs-radiobutton label="Option C" name="choice" value="c"></ejs-radiobutton>
  `
})
export class AppComponent {}

同一组中的按钮始终应设置相同的 name 属性，以确保互斥。

---

常见模式

检测选择更改

template: `
  <ejs-radiobutton label="Credit Card" name="payment" value="credit"
    (change)="onPaymentChange($event)">
  </ejs-radiobutton>
  <ejs-radiobutton label="Debit Card" name="payment" value="debit"
    (change)="onPaymentChange($event)">
  </ejs-radiobutton>
`

onPaymentChange(args: ChangeArgs): void {
  console.log('Selected value:', args.value);  // 'credit' or 'debit'
}

使用 ngModel 双向绑定

// All buttons share [(ngModel)]="selectedValue"
template: `
  <ejs-radiobutton label="Monthly" name="plan" value="monthly"
    [(ngModel)]="selectedPlan">
  </ejs-radiobutton>
  <ejs-radiobutton label="Annual" name="plan" value="annual"
    [(ngModel)]="selectedPlan">
  </ejs-radiobutton>
  <p>Selected: {{ selectedPlan }}</p>
`

小尺寸变体

<ejs-radiobutton label="Small Option" name="size" cssClass="e-small"></ejs-radiobutton>

禁用 RadioButton

<ejs-radiobutton label="Unavailable" name="plan" [disabled]="true"></ejs-radiobutton>

---

关键属性一览

属性	类型	默认值	用途
label	string	''	按钮旁边的标题文本
name	string	''	将互斥按钮分组
value	string	''	表单提交值
checked	boolean	false	预先选中按钮
disabled	boolean	false	禁止交互
cssClass	string	''	自定义 CSS；小尺寸请使用 'e-small'
labelPosition	RadioLabelPosition	'After'	'Before' 或 'After'
enableRtl	boolean	false	从右向左布局

完整 API 请参阅 references/api.md。

SplitButton

本指南全面介绍如何在 Angular 应用中实现 Syncfusion Essential JS 2 SplitButton 组件。了解如何创建带下拉菜单的分割按钮、管理项目、处理事件、自定义样式并与表单集成。

SplitButton 概述

Syncfusion Angular SplitButton 组件是一种多功能 UI 控件，将主按钮与下拉菜单组合在一起：

• 双重操作设计： 主操作按钮 + 包含多个选项的下拉菜单
• 项目管理： 配置带有文本、图标、分隔符、URL 和禁用状态的项目
• 事件系统： click（主按钮）、select（项目）、open、close、beforeOpen 事件
• 弹出窗口控制： 放置选项、碰撞检测、偏移调整、自动定位
• 图标支持： Material Design 图标、Font Awesome、Bootstrap 图标、自定义字体
• 自定义： CSS 类、主题（Material、Bootstrap、Fabric、Tailwind）、深色模式
• 模板支持： 带 HTML 内容、图像图标和自定义渲染的项目模板
• 无障碍访问： 完全符合 WCAG 2.2 标准，支持键盘导航、ARIA 属性和 RTL
• 表单集成： 支持响应式表单和模板驱动表单
• 动态更新： 运行时添加/移除项目、更新属性、管理状态

软件包： @syncfusion/ej2-angular-splitbuttons

文档导航

根据具体需求阅读以下参考资料：

入门

📄 阅读： references/getting-started.md

• 安装软件包和配置模块
• 导入 CSS 主题和依赖项
• 基本 SplitButton 实现
• 使用项目初始化组件
• 设置事件处理程序
• 运行和测试设置

按钮项目配置

📄 阅读： references/button-items-configuration.md

• ItemModel 接口和属性
• 文本和图标配置
• URL 导航和外部链接
• 项目之间的分隔符
• 项目禁用/启用状态
• 动态项目管理
• 项目点击事件处理

事件与方法

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

• click 事件（主按钮操作）
• select 事件（从下拉菜单中选择项目）
• open 事件（下拉菜单打开）
• close 事件（下拉菜单关闭）
• beforeOpen 事件（下拉菜单打开前）
• 方法：toggle()、addItems()、removeItems()、focusIn()
• ViewChild 访问模式
• 事件参数类型及处理方式

样式与自定义

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

• CSS 类自定义（.e-split-button、.e-dropdown-popup）
• 图标配置（iconCss、prefix、suffix 属性）
• 图标位置（左、右、上、下）
• 主题选择（Material、Bootstrap、Fabric、Tailwind）
• 深色模式实现
• RTL（从右向左）支持
• 自定义 CSS 覆盖与尺寸设置

模板与图标

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

• 图标字体库（Material Design、Bootstrap、Font Awesome）
• 图标位置与尺寸
• 包含 HTML 内容的项目模板
• 图片图标与自定义图形
• 用于丰富样式的内容模板
• 多种图标组合
• 图标对齐与间距

弹出窗口行为与目标自定义

📄 阅读： references/popup-positioning.md

• 默认弹出窗口行为（自动在按钮下方打开）
• popupWidth 属性 — 固定弹出窗口宽度
• target 属性 — 自定义弹出窗口内容（颜色选择器、ListView 等）
• createPopupOnClick — 延迟创建弹出窗口
• closeActionEvents — 自定义关闭触发事件
• 使用 ListView 作为目标的分组项目
• 边缘情况：固定工具栏、模态对话框、可滚动容器

无障碍与全球化

📄 阅读： references/accessibility-and-globalization.md

• 符合 WCAG 2.2 和 Section 508 标准
• ARIA 角色与属性（role="button"、aria-haspopup、aria-expanded）
• 键盘导航（Tab、Enter、Escape、方向键）
• 屏幕阅读器兼容性与播报
• RTL（从右向左）布局支持
• 本地化与 locale 属性用法
• 特定语言的格式设置与翻译

响应式表单集成

📄 阅读： references/reactive-forms-integration.md

• 将 FormControl 与 SplitButton 集成
• FormGroup 与表单绑定
• 验证规则与错误状态
• 表单状态更改与订阅
• 编程式控制与更新
• 重置与提交模式
• 禁用状态管理

API 参考

📄 阅读： references/api-reference.md

• 全部 16 个官方属性：content、items、iconCss、iconPosition、cssClass、disabled、enableRtl、target、popupWidth、animationSettings、closeActionEvents、createPopupOnClick、enableHtmlSanitizer、enablePersistence、locale
• 官方方法：toggle()、addItems()、removeItems()、focusIn()、getPersistData()、onPropertyChanged()
• 全部 8 个官方事件及正确的事件参数接口
• ItemModel 接口：text、id、iconCss、url、separator、disabled
• SplitButtonIconPosition 枚举："Left" | "Top"
• 事件参数接口：BeforeOpenCloseMenuEventArgs、OpenCloseMenuEventArgs、MenuEventArgs、ClickEventArgs

快速开始示例

// app.component.ts
import { Component } from '@angular/core';
import { ItemModel } from '@syncfusion/ej2-angular-splitbuttons';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Dropdown items
  public dropdownItems: ItemModel[] = [
    { text: 'Cut' },
    { text: 'Copy' },
    { text: 'Paste' }
  ];
  
  // Primary button action handler
  onPrimaryClick(): void {
    console.log('Primary action clicked');
  }
  
  // Item selection handler
  onItemSelect(args: any): void {
    console.log('Selected item:', args.item.text);
  }
}

<div style="padding: 20px; font-family: Arial, sans-serif;">
  <h2>Basic SplitButton</h2>
  <ejs-splitbutton 
    content="Paste"
    [items]="dropdownItems"
    (click)="onPrimaryClick()"
    (select)="onItemSelect($event)">
  </ejs-splitbutton>
</div>

/* app.component.css */
@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-splitbuttons/styles/material3.css';

:host ::ng-deep .e-split-button {
  margin: 10px;
}

常见模式

模式 1：带图标的操作菜单

当你需要一个带有丰富图标下拉菜单的分裂按钮时：

export class AppComponent {
  public fileActions: ItemModel[] = [
    { text: 'Save', iconCss: 'e-icons e-save' },
    { text: 'Save As', iconCss: 'e-icons e-save-as' },
    { separator: true },
    { text: 'Export', iconCss: 'e-icons e-export' },
    { text: 'Print', iconCss: 'e-icons e-print' }
  ];
  
  onFileAction(args: any): void {
    const action = args.item.text;
    console.log(`File action: ${action}`);
    // Execute based on selected action
  }
}

模式 2：按条件启用/禁用项目

当你需要根据应用程序状态启用/禁用菜单项目时：

export class AppComponent {
  @ViewChild('splitBtn') splitButtonRef!: SplitButtonComponent;
  
  isEditMode: boolean = false;
  
  public items: ItemModel[] = [
    { text: 'Edit', disabled: true },
    { text: 'Delete', disabled: true },
    { text: 'Duplicate' }
  ];
  
  toggleEditMode(): void {
    this.isEditMode = !this.isEditMode;
    // Update item disabled states
    this.items[0].disabled = !this.isEditMode;
    this.items[1].disabled = !this.isEditMode;
  }
  
  onItemSelect(args: any): void {
    if (!args.item.disabled) {
      console.log('Executing:', args.item.text);
    }
  }
}

模式 3：动态管理项目

当你需要在运行时添加/移除项目时：

export class AppComponent {
  @ViewChild('splitBtn') splitButtonRef!: SplitButtonComponent;
  
  public items: ItemModel[] = [];
  
  ngOnInit(): void {
    // Load initial items
    this.loadItems();
  }
  
  loadItems(): void {
    this.items = [
      { text: 'Item 1' },
      { text: 'Item 2' },
      { text: 'Item 3' }
    ];
  }
  
  addItem(text: string): void {
    this.items.push({ text: text });
  }
  
  removeItem(index: number): void {
    this.items.splice(index, 1);
  }
  
  clearAllItems(): void {
    this.items = [];
  }
}

模式 4：通过 URL 导航菜单项

当需要让菜单项跳转到不同的 URL 时使用。注意：ItemModel 仅支持 url；打开目标（_blank、_self）必须在 (select) 中处理：

export class AppComponent {
  public navigationItems: ItemModel[] = [
    { id: 'home',    text: 'Home',          url: '/' },
    { id: 'docs',    text: 'Documentation', url: '/docs' },
    { separator: true },
    { id: 'github',  text: 'GitHub',        url: 'https://github.com' },
    { id: 'support', text: 'Support',       url: 'https://support.syncfusion.com' }
  ];
  
  onNavigate(args: any): void {
    const itemUrl: string = args.item.url;
    if (!itemUrl) return;
    // Open external URLs in new tab, internal in same tab
    const isExternal = itemUrl.startsWith('http');
    window.open(itemUrl, isExternal ? '_blank' : '_self');
  }
}

模式 5：自定义弹出窗口宽度和目标

当需要固定的弹出窗口宽度或完全自定义的弹出窗口元素时使用：

import { Component } from '@angular/core';
import { ItemModel, SplitButtonModule } from '@syncfusion/ej2-angular-splitbuttons';

@Component({
  standalone: true,
  imports: [SplitButtonModule],
  selector: 'app-root',
  template: `
    
    <ejs-splitbutton
      content="Actions"
      [items]="items"
      popupWidth="250px"
      (beforeOpen)="onBeforeOpen($event)"
      (open)="onOpen()"
      (close)="onClose()">
    </ejs-splitbutton>
  `
})
export class AppComponent {
  public items: ItemModel[] = [
    { text: 'Save',   iconCss: 'e-icons e-save' },
    { text: 'Export', iconCss: 'e-icons e-export' },
    { text: 'Print',  iconCss: 'e-icons e-print' }
  ];

  onBeforeOpen(args: any): void {
    console.log('Popup about to open');
  }

  onOpen(): void {
    console.log('Popup opened');
  }

  onClose(): void {
    console.log('Popup closed');
  }
}

关键属性参考

属性	类型	描述	示例
content	string	主按钮文本	content="Save"
items	ItemModel[]	下拉菜单项	[items]="items"
iconCss	string	主按钮图标 CSS 类	iconCss="e-icons e-save"
iconPosition	SplitButtonIconPosition	图标位置（"Left" 或 "Top"）	iconPosition="Top"
disabled	boolean	启用/禁用组件	[disabled]="false"
cssClass	string	组件上的自定义 CSS 类	cssClass="custom-split-btn"
enableRtl	boolean	启用 RTL 布局	[enableRtl]="true"
target	string | Element	用作弹出窗口内容的自定义元素	target="#colorPicker"
popupWidth	string | number	弹出窗口宽度（默认为 "auto"）	popupWidth="250px"
createPopupOnClick	boolean	延迟创建弹出窗口 DOM	[createPopupOnClick]="true"
closeActionEvents	string	关闭弹出窗口的 DOM 事件	closeActionEvents="mouseleave"
animationSettings	AnimationModel	打开/关闭动画	[animationSettings]="animation"
locale	string	文化/语言代码	locale="ar-SA"
(beforeOpen)	EventEmitter	下拉菜单打开前触发	(beforeOpen)="onBeforeOpen($event)"
(click)	EventEmitter	主按钮被点击时触发	(click)="onPrimaryClick($event)"
(select)	EventEmitter	选中下拉菜单项时触发	(select)="onItemSelect($event)"
(open)	EventEmitter	下拉菜单打开时触发	(open)="onOpen($event)"
(close)	EventEmitter	下拉菜单关闭时触发	(close)="onClose($event)"
(beforeClose)	EventEmitter	下拉菜单关闭前触发	(beforeClose)="onBeforeClose($event)"
(beforeItemRender)	EventEmitter	每个菜单项渲染前触发	(beforeItemRender)="onRender($event)"
(created)	EventEmitter	组件创建后触发	(created)="onCreated()"

⚠️ 注意： 官方 API 中不存在 position、title 和 open()/close() 方法。以编程方式打开或关闭时，请使用 toggle()。完整权威 API 请参阅 references/api-reference.md。

常见用例

用例 1：文档工具栏

• 主操作（保存），下拉菜单包含另存为、导出、打印
• 使用图标提升视觉清晰度
• 没有更改时禁用“保存”
• 解决方案：将 iconCss 与动态禁用状态结合使用
• 参考：按钮项配置 + 样式与自定义

用例 2：表单操作菜单

• 主按钮（提交），下拉菜单包含保存草稿、安排、删除
• 根据表单状态禁用选项
• 分别处理每项操作
• 解决方案：使用 select 事件并跟踪项
• 参考：事件与方法 + 响应式表单集成

用例 3：导航菜单

• 主操作（仪表板），下拉菜单包含其他页面
• 提供指向文档或支持页面的外部链接
• 为国际化应用提供 RTL 支持
• 解决方案：使用 url 属性和 target 属性
• 参考：按钮项配置 + 无障碍与全球化

用例 4：设置面板

• 支持键盘导航的无障碍分裂按钮
• 兼容屏幕阅读器
• 符合 WCAG 2.2 标准
• 解决方案：使用适当的 ARIA 属性和键盘处理程序
• 参考：无障碍与全球化

用例 5：响应式工具栏

• 具有自适应定位的分裂按钮
• 在小屏幕上显示响应式弹出窗口
• 适合触摸操作的间距
• 解决方案：使用动态定位和响应式 CSS
• 参考：弹出窗口定位 + 样式与自定义

Chips

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

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和包配置（@syncfusion/ej2-angular-buttons）
• CSS/主题导入
• 渲染基本 Chip 或 Chip 列表
• 单个 Chip 与使用 e-chips / e-chip 的 Chip 列表
• 运行应用程序

类型与选择

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

• 四种 Chip 类型：输入、选择、筛选、操作
• 单选（selection="Single"）——选择 Chip
• 多选（selection="Multiple"）——筛选 Chip
• 可删除的 Chip（[enableDelete]="true"）
• 使用 [selectedChips] 预选 Chip
• 使用 (click) 处理操作 Chip 的点击事件

自定义

📄 阅读： references/customization.md

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

拖放

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

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

样式自定义

📄 阅读： references/style.md

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

无障碍功能

📄 阅读： 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 { Component } from '@angular/core';
import { ChipListModule } from '@syncfusion/ej2-angular-buttons';
import { enableRipple } from '@syncfusion/ej2-base';

enableRipple(true);

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ChipListModule],
  template: `
    <ejs-chiplist id="chip-list">
      <e-chips>
        <e-chip text="Angular"></e-chip>
        <e-chip text="Vue"></e-chip>
        <e-chip text="Svelte"></e-chip>
      </e-chips>
    </ejs-chiplist>
  `
})
export class AppComponent {}

CSS（src/styles.css）：

@import '~@syncfusion/ej2-base/styles/tailwind3.css';
@import '~@syncfusion/ej2-angular-buttons/styles/tailwind3.css';

常见模式

筛选 chips（多选）

<ejs-chiplist selection="Multiple">
  <e-chips>
    <e-chip text="Angular"></e-chip>
    <e-chip text="Vue"></e-chip>
    <e-chip text="Svelte"></e-chip>
  </e-chips>
</ejs-chiplist>

带事件的可删除 chips

<ejs-chiplist [enableDelete]="true" (delete)="onChipDelete($event)">
  <e-chips>
    <e-chip text="Tag One"></e-chip>
    <e-chip text="Tag Two"></e-chip>
  </e-chips>
</ejs-chiplist>

带头像首字母的 chips

<ejs-chiplist>
  <e-chips>
    <e-chip text="Andrew" avatarText="A"></e-chip>
    <e-chip text="Laura" avatarText="L"></e-chip>
  </e-chips>
</ejs-chiplist>

以编程方式控制（通过 ViewChild 添加/删除 chips）

import { Component, ViewChild } from '@angular/core';
import { ChipListComponent, ChipListModule } from '@syncfusion/ej2-angular-buttons';

@Component({
  selector: 'app-chip-demo',
  standalone: true,
  imports: [ChipListModule],
  template: `
    <ejs-chiplist #chipList id="chip-list">
      <e-chips>
        <e-chip text="Angular"></e-chip>
        <e-chip text="Vue"></e-chip>
      </e-chips>
    </ejs-chiplist>
  `
})
export class ChipDemoComponent {
  @ViewChild('chipList') chipList?: ChipListComponent;

  addChip() {
    this.chipList?.add('New Tag');
  }

  removeFirstChip() {
    this.chipList?.remove([0]);
  }

  getSelected() {
    const selected = this.chipList?.getSelectedChips();
    console.log(selected);
  }
}