syncfusion-angular-accordion

实现 Syncfusion Angular Accordion 组件

何时使用此技能

在以下情况下使用此技能：

• 创建可折叠内容面板 - 将相关内容整理到可展开的分区中，折叠后节省空间
• 构建分步向导 - 创建多步表单或工作流，让用户逐步浏览 Accordion 项目
• 实现常见问题解答区 - 展示常见问题，并提供可展开的答案
• 创建导航菜单 - 构建分层菜单或导航结构，其中包含可展开的嵌套项目
• 动态加载内容 - 在用户展开 Accordion 项目时按需获取并显示内容
• 添加自定义动画 - 通过流畅的展开／折叠过渡效果提升用户体验
• 整理复杂数据 - 通过可展开的类别和子类别展示结构化数据

组件概述

Syncfusion Angular Accordion 组件会显示垂直可折叠的内容面板，用户可一次展开一个或多个分区。主要功能包括：

• 单项／多项展开模式 - 控制是否可同时打开一个或多个项目
• 数据绑定 - 从数组或 OData 服务绑定 Accordion 项目
• 动态项目管理 - 在运行时添加、删除或更新项目
• 事件处理 - 响应展开、折叠和点击事件
• 自定义动画 - 使用自定义效果和时长配置流畅的过渡效果
• 嵌套 Accordion - 创建分层 Accordion 结构，用于复杂导航
• TreeView 集成 - 嵌入 TreeView 等其他组件，实现高级导航
• 内容投影 - 使用 Angular 的 ng-content 创建可复用的内容组件

文档目录总览

快速导航至文档：

1. 入门指南 - 安装、设置和基本初始化
2. 展开模式 - 单项与多项展开模式及其配置
3. 数据绑定 - 数据源、OData、REST API 和刷新策略
4. 动态加载与交互 - 事件、方法和动态项目管理
5. 高级功能 - 动画、嵌套 Accordion、样式和 RTL
6. 用例与模式 - 实际实现和模式

文档与导航指南

入门指南

📄 阅读： references/getting-started.md

适用场景：

• 设置首个 Accordion 组件
• 安装所需的软件包和依赖项
• 了解 CSS 导入和主题配置
• 学习基本初始化方法（基于模板、项目数组、HTML 元素）
• 创建首个可运行示例

展开模式

📄 阅读： references/expand-modes.md

适用场景：

• 决定用户应展开一个还是多个项目
• 配置单项模式（一次只打开一个项目）
• 使用多项模式同时打开多个项目
• 为用例选择合适的模式
• 处理大型数据集时的性能问题

数据绑定

📄 阅读： references/data-binding.md

适用场景：

• 从外部数据源绑定 Accordion 数据
• 使用 DataManager 从 OData 服务获取数据
• 将数据属性映射到标题和内容
• 使用结构化数据数组
• 在数据更新后刷新 Accordion 内容

动态加载和交互

📄 阅读： references/dynamic-loading-and-interactions.md

适用场景：

• 在运行时动态添加项目
• 处理展开/折叠/点击事件
• 通过 AJAX 或远程请求加载内容
• 实现由复选框控制的展开
• 阻止项目折叠或强制项目保持展开
• 使用 ng-content 创建可复用的内容组件
• 创建始终展开的手风琴项

高级功能

📄 阅读： references/advanced-features.md

适用场景：

• 使用效果和缓动自定义展开/折叠动画
• 为分层结构创建嵌套手风琴
• 在手风琴项中集成 TreeView 组件
• 应用自定义 CSS 样式和主题
• 启用 RTL（从右到左）支持
• 设置标题、项目和展开/折叠图标的样式

用例和模式

📄 阅读： references/use-cases-patterns.md

适用场景：

• 遵循最佳实践构建 FAQ 部分
• 创建带验证的多步向导表单
• 设计分类设置面板
• 构建导航菜单和组织层级结构
• 显示帮助和文档部分
• 学习真实场景中的模式和代码组织策略

快速入门示例

包含三个项目的基本模板式手风琴：

import { Component } from '@angular/core';
import { AccordionModule } from '@syncfusion/ej2-angular-navigations';

@Component({
  standalone: true,
  selector: 'app-root',
  imports: [AccordionModule],
  template: `
    <ejs-accordion>
      <e-accordionitems>
        <e-accordionitem expanded="true">
          <ng-template #header>
            <div>ASP.NET</div>
          </ng-template>
          <ng-template #content>
            <div>Microsoft ASP.NET is a set of technologies in the Microsoft .NET Framework for building Web applications and XML Web services.</div>
          </ng-template>
        </e-accordionitem>
        
        <e-accordionitem>
          <ng-template #header>
            <div>ASP.NET MVC</div>
          </ng-template>
          <ng-template #content>
            <div>The Model-View-Controller (MVC) architectural pattern separates an application into three main components: the model, the view, and the controller.</div>
          </ng-template>
        </e-accordionitem>
        
        <e-accordionitem>
          <ng-template #header>
            <div>JavaScript</div>
          </ng-template>
          <ng-template #content>
            <div>JavaScript (JS) is an interpreted computer programming language used for creating interactive web pages and applications.</div>
          </ng-template>
        </e-accordionitem>
      </e-accordionitems>
    </ejs-accordion>
  `
})
export class AppComponent {}

使用项目数组方式：

import { Component } from '@angular/core';
import { AccordionModule } from '@syncfusion/ej2-angular-navigations';

@Component({
  standalone: true,
  selector: 'app-root',
  imports: [AccordionModule],
  template: `<ejs-accordion [items]="accordionItems"></ejs-accordion>`
})
export class AppComponent {
  public accordionItems = [
    {
      header: 'ASP.NET',
      content: 'Microsoft ASP.NET is a set of technologies in the Microsoft .NET Framework for building Web applications.',
      expanded: true
    },
    {
      header: 'ASP.NET MVC',
      content: 'The Model-View-Controller (MVC) architectural pattern separates an application into three main components.'
    },
    {
      header: 'JavaScript',
      content: 'JavaScript (JS) is an interpreted computer programming language used for creating interactive web pages.'
    }
  ];
}

常见模式

模式 1：单项展开模式（一次展开一项）

适用于希望手风琴一次只展开一项的场景，例如导航菜单和设置面板。

<ejs-accordion expandMode="Single">
  
</ejs-accordion>

模式 2：动态添加项目

根据用户操作或数据加载，以编程方式添加项目。

@ViewChild('accordion') accordionObj?: AccordionComponent;

addNewItem() {
  this.accordionObj?.addItem({
    header: 'New Item',
    content: 'New content here'
  });
}

模式 3：事件驱动工作流

响应手风琴事件，以执行验证或数据加载等自定义逻辑。

<ejs-accordion (expanding)="onExpanding($event)" (expanded)="onExpanded($event)">
  
</ejs-accordion>

onExpanding(event: ExpandEventArgs) {
  // Prevent collapse of currently open item
  event.cancel = true;
}

模式 4：展开/折叠动画

添加流畅的动画，以提供更好的视觉反馈。

<ejs-accordion [animation]="animationSettings">
  
</ejs-accordion>

animationSettings = {
  expand: { effect: 'SlideDown', duration: 400, easing: 'ease' },
  collapse: { effect: 'SlideUp', duration: 400, easing: 'ease' }
};

完整 API 参考

有关各个 API 元素的详细文档及可运行的代码示例，请参阅参考文件。以下是全面摘要。

Accordion 组件属性（共 13 项）

属性	类型	默认值	用途	了解更多
items	AccordionItemModel[]	[]	Accordion 项集合	数据绑定
dataSource	DataManager | Object[]	null	用于绑定项目的数据源	数据绑定
expandMode	'Single' | 'Multiple'	'Multiple'	控制单项或多项展开	展开模式
expandedIndices	number[]	[]	初始展开项目的索引	展开模式
animation	AccordionAnimationSettingsModel	{ expand: { effect: 'SlideDown', duration: 400, easing: 'linear' }, collapse: { effect: 'SlideUp', duration: 400, easing: 'linear' } }	展开/折叠动画设置	高级功能
headerTemplate	string | Function	null	项目标题模板	入门指南
itemTemplate	string | Function	null	项目内容模板	入门指南
height	string | number	auto	组件高度	入门指南
width	string | number	100%	组件宽度	入门指南
enableRtl	boolean	false	启用从右向左的布局	高级功能
enablePersistence	boolean	false	将展开状态保存到 localStorage	入门指南
enableHtmlSanitizer	boolean	true	清理内容中的 HTML	数据绑定
locale	string	'en-US'	本地化区域设置	高级功能

AccordionItem 属性（共 8 项）

属性	类型	默认值	用途	了解更多
header	string | HTMLElement	''	项目标题文本或元素	入门指南
content	string | HTMLElement | Function	''	项目内容文本、HTML 或函数	入门指南
expanded	boolean	false	初始展开状态	展开模式
disabled	boolean	false	禁用项目交互	动态加载
visible	boolean	true	项目可见性	动态加载
cssClass	string	''	项目的自定义 CSS 类	高级功能
iconCss	string	''	Font Awesome/Bootstrap 图标类	入门指南
id	string	''	项目的唯一标识符	入门指南

方法（共 7 个）

方法	签名	用途	了解更多
addItem()	addItem(item: AccordionItemModel | Object[], index?: number): void	在指定索引处或末尾添加项目	动态加载
removeItem()	removeItem(index: number): void	移除指定索引处的项目	动态加载
expandItem()	expandItem(isExpand: boolean, index?: number): void	展开/折叠指定项目或所有项目	动态加载，展开模式
enableItem()	enableItem(index: number, isEnable: boolean): void	启用/禁用项目交互	动态加载
hideItem()	hideItem(index: number, isHidden?: boolean): void	显示/隐藏项目，但不将其移除	动态加载
select()	select(index: number): void	将焦点设为项目标题	动态加载
destroy()	destroy(): void	清理组件资源	动态加载

事件（共 5 个）

事件	事件参数	触发时机	了解更多
created	Event	组件渲染完成	动态加载
expanding	ExpandEventArgs	项目开始展开时（可取消）	动态加载
expanded	ExpandEventArgs	项目完成展开时	动态加载
clicked	AccordionClickArgs	点击标题或内容时	动态加载
destroyed	Event	组件销毁时	动态加载

动画效果（6 种）

效果	展开行为	折叠行为	适用场景
SlideDown	内容向下滑入	不适用（与 SlideUp 配合使用）	默认效果，动画流畅
SlideUp	不适用（与 SlideDown 配合使用）	内容向上滑出	默认折叠效果
FadeDown	内容淡入并滑入	不适用（与 FadeUp 配合使用）	专业外观
FadeUp	不适用（与 FadeDown 配合使用）	内容淡出并滑出	专业外观
Zoom	内容放大	内容缩小	引人注目的效果
None	即时完成	即时完成	性能最佳

缓动函数（5 种）

缓动方式	曲线	适用场景	典型用途
linear	匀速	简单动画	直接展开/折叠
ease	开始和结束较慢，中间较快	默认行为	感觉均衡
ease-in	加速	折叠操作	关闭时逐渐加速
ease-out	减速	展开操作	打开时逐渐减速
ease-in-out	开始和结束较慢	对称动画	两个方向的时长相同

常见用例

1. 常见问题解答 - 可展开的问题/答案对，采用单项展开模式
2. 多步骤向导 - 按顺序排列的项目，支持验证和条件启用
3. 设置面板 - 按可展开的分区组织各类设置
4. 导航菜单 - 使用嵌套手风琴组件实现分层导航
5. 数据浏览器 - 支持动态加载的可展开数据类别
6. 帮助文档 - 按主题组织的可折叠帮助分区

故障排查速查表

项目无法展开？

• 检查项目是否通过 enableItem(false, index) 禁用
• 确认 expandMode 设置符合你的需求

内容未加载？

• 确保已设置 header 和 content 属性
• 检查样式中是否包含 CSS 导入语句

动画不流畅？

• 确认 CSS 已正确导入
• 检查浏览器控制台是否有错误
• 考虑为运行较慢的设备缩短动画时长

多个项目意外关闭？

• 如果需要同时展开多个项目，请确认 expandMode 设置为 'Multiple'
• 检查事件处理程序是否调用了 e.cancel = true

---

如需了解任何方面的详细信息，请参阅上方的文档和导航指南。如果你是首次使用此组件，请从 getting-started.md 开始。