syncfusion-react-accordion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Accordion

实现Syncfusion React Accordion组件

The React Accordion component provides a clean, organized way to display content in collapsible panels. It's perfect for creating expandable content sections, FAQs, multi-step forms, and navigation menus with minimal code.

React Accordion组件提供了一种简洁、有序的方式来在可折叠面板中展示内容。它非常适合用少量代码创建可展开内容区块、常见问题（FAQs）、多步骤表单和导航菜单。

Component Overview

组件概述

The Accordion component renders a stack of collapsible panels where:

Each panel has a header (clickable to toggle) and content area
Headers can be simple text or custom templates
Content can be static, dynamic, or rendered from other React components
Supports single expand mode (one panel at a time) or multiple (many panels at once)
Built-in animations for smooth expand/collapse transitions
Full keyboard navigation and accessibility support

Accordion组件渲染一组可折叠面板，其中：

每个面板包含一个可点击切换的标题和内容区域
标题可以是简单文本或自定义模板
内容可以是静态内容、动态内容，也可以由其他React组件渲染
支持单展开模式（同一时间仅一个面板展开）或多展开模式（可同时展开多个面板）
内置动画效果，实现流畅的展开/折叠过渡
支持完整的键盘导航和无障碍访问

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

When to read: First time setting up the Accordion component

Package installation (@syncfusion/ej2-react-navigations)
CSS imports and theme configuration (Tailwind, Bootstrap)
Two initialization methods (Items API vs HTML markup)
Item configuration (header, content, cssClass, disabled, expanded)
Basic component setup with examples
First render and minimal working example

📄 阅读： references/getting-started.md

阅读时机： 首次设置Accordion组件时

包安装（@syncfusion/ej2-react-navigations）
CSS导入与主题配置（Tailwind、Bootstrap）
两种初始化方式（Items API vs HTML标记）
项配置（header、content、cssClass、disabled、expanded）
基础组件设置示例
首次渲染与最简可用示例

Expand Modes

展开模式

📄 Read: references/expand-modes.md

When to read: Controlling which panels expand at the same time

Single expand mode (only one panel open at a time)
Multiple expand mode (default, many panels can be open)
Setting initial expanded state with
```
expandedIndices
```
property
Toggle behavior on header click
Use cases for choosing each mode
Keeping single pane open always pattern

📄 阅读： references/expand-modes.md

阅读时机： 需要控制同时展开的面板数量时

单展开模式（同一时间仅一个面板处于展开状态）
多展开模式（默认模式，可同时展开多个面板）
使用
```
expandedIndices
```
属性设置初始展开状态
标题点击时的切换行为
各模式的适用场景
始终保持单个面板展开的模式

Animation Effects

动画效果

📄 Read: references/animation-effects.md

When to read: Customizing panel transitions and visual effects

Default animations (SlideDown for expand, SlideUp for collapse)
Choosing from available animation effects (FadeIn, ZoomIn, etc.)
Configuring easing and duration properties
Separate expand/collapse animation control
Disabling animations entirely
Performance considerations

📄 阅读： references/animation-effects.md

阅读时机： 自定义面板过渡与视觉效果时

默认动画（展开时SlideDown，折叠时SlideUp）
可选动画效果（FadeIn、ZoomIn等）
配置缓动函数与时长属性
分别控制展开/折叠动画
完全禁用动画
性能考量

Content Loading

内容加载

📄 Read: references/content-loading.md

When to read: Loading content dynamically or from external sources

Loading accordion items dynamically with
```
addItem()
```
method
Loading content from data sources (dataSource property)
Fetching content via HTTP requests and POST
Template-based rendering (headerTemplate, itemTemplate)
Rendering other React components inside panels
Lazy loading and deferred content patterns

📄 阅读： references/content-loading.md

阅读时机： 动态加载内容或从外部源加载内容时

使用
```
addItem()
```
方法动态添加Accordion项
从数据源加载内容（dataSource属性）
通过HTTP请求获取内容
基于模板的渲染（headerTemplate、itemTemplate）
在面板内渲染其他React组件
懒加载与延迟加载模式

Events & Lifecycle

事件与生命周期

📄 Read: references/events-lifecycle.md

When to read: Handling user interactions and component lifecycle

Component lifecycle events (created, destroyed)
Expand/collapse events (expanding, expanded)
Click event handling (clicked)
Event arguments and properties
Preventing default actions with event.cancel
Real-world event patterns and examples

📄 阅读： references/events-lifecycle.md

阅读时机： 处理用户交互与组件生命周期时

组件生命周期事件（created、destroyed）
展开/折叠事件（expanding、expanded）
点击事件处理（clicked）
事件参数与属性
使用event.cancel阻止默认行为
实际场景中的事件模式与示例

Styling & Customization

样式与定制

📄 Read: references/styling-customization.md

When to read: Customizing appearance and integrating with design systems

CSS classes for styling (header, panel, content areas)
Built-in theme options and theme switching
Custom styling with CSS and utilities (Tailwind, Bootstrap)
RTL (right-to-left) support
Responsive design patterns
Using cssClass property for custom styling

📄 阅读： references/styling-customization.md

阅读时机： 自定义外观并与设计系统集成时

用于样式定制的CSS类（标题、面板、内容区域）
内置主题选项与主题切换
使用CSS与工具类（Tailwind、Bootstrap）进行自定义样式
RTL（从右到左）布局支持
响应式设计模式
使用cssClass属性进行自定义样式

Advanced Features

高级功能

📄 Read: references/advanced-features.md

When to read: Building complex layouts and optimizing performance

Component methods (expandItem, enableItem, hideItem, etc.)
Nested accordions and hierarchical structures
React hooks integration (useState, useRef, useEffect)
Keyboard navigation behavior
Accessibility features (ARIA attributes, screen readers)
Performance optimization for large accordion lists
Custom expand/collapse action patterns

📄 阅读： references/advanced-features.md

阅读时机： 构建复杂布局与优化性能时

组件方法（expandItem、enableItem、hideItem等）
嵌套Accordion与层级结构
React hooks集成（useState、useRef、useEffect）
键盘导航行为
无障碍功能（ARIA属性、屏幕阅读器支持）
大型Accordion列表的性能优化
自定义展开/折叠操作模式

Quick Start Example

快速入门示例

Basic accordion with three collapsible panels:

jsx

import React from 'react';
import { AccordionComponent, AccordionItemDirective, AccordionItemsDirective } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-buttons/styles/tailwind3.css';
import '@syncfusion/ej2-popups/styles/tailwind3.css';
import '@syncfusion/ej2-react-navigations/styles/tailwind3.css';

export default function App() {
  return (
    <AccordionComponent expandMode='Multiple'>
      <AccordionItemsDirective>
        <AccordionItemDirective 
          header='HTML' 
          content='HTML is a markup language used to create web pages.' 
        />
        <AccordionItemDirective 
          header='CSS' 
          content='CSS is used to style HTML elements and create layouts.' 
        />
        <AccordionItemDirective 
          header='JavaScript' 
          content='JavaScript adds interactivity to web applications.' 
        />
      </AccordionItemsDirective>
    </AccordionComponent>
  );
}

包含三个可折叠面板的基础Accordion：

jsx

import React from 'react';
import { AccordionComponent, AccordionItemDirective, AccordionItemsDirective } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-buttons/styles/tailwind3.css';
import '@syncfusion/ej2-popups/styles/tailwind3.css';
import '@syncfusion/ej2-react-navigations/styles/tailwind3.css';

export default function App() {
  return (
    <AccordionComponent expandMode='Multiple'>
      <AccordionItemsDirective>
        <AccordionItemDirective 
          header='HTML' 
          content='HTML is a markup language used to create web pages.' 
        />
        <AccordionItemDirective 
          header='CSS' 
          content='CSS is used to style HTML elements and create layouts.' 
        />
        <AccordionItemDirective 
          header='JavaScript' 
          content='JavaScript adds interactivity to web applications.' 
        />
      </AccordionItemsDirective>
    </AccordionComponent>
  );
}

Common Patterns

常见模式

Pattern 1: FAQ Section (Single Expand Mode)

模式1：常见问题（FAQ）区块（单展开模式）

Questions automatically collapse when a new one is opened:

jsx

<AccordionComponent expandMode='Single'>
  <AccordionItemsDirective>
    <AccordionItemDirective header='What is React?' content='React is a JavaScript library for building UIs with components.' />
    <AccordionItemDirective header='What is JSX?' content='JSX is a syntax extension for writing HTML-like code in JavaScript.' />
  </AccordionItemsDirective>
</AccordionComponent>

点击新问题时，旧问题自动折叠：

jsx

<AccordionComponent expandMode='Single'>
  <AccordionItemsDirective>
    <AccordionItemDirective header='What is React?' content='React is a JavaScript library for building UIs with components.' />
    <AccordionItemDirective header='What is JSX?' content='JSX is a syntax extension for writing HTML-like code in JavaScript.' />
  </AccordionItemsDirective>
</AccordionComponent>

Pattern 2: Persistent Expansion (Multiple Mode)

模式2：持久化展开（多模式）

All panels can remain expanded simultaneously:

jsx

<AccordionComponent expandMode='Multiple'>
  <AccordionItemsDirective>
    <AccordionItemDirective expanded={true} header='Features' content='...' />
    <AccordionItemDirective expanded={true} header='Installation' content='...' />
  </AccordionItemsDirective>
</AccordionComponent>

所有面板可同时保持展开状态：

jsx

<AccordionComponent expandMode='Multiple'>
  <AccordionItemsDirective>
    <AccordionItemDirective expanded={true} header='Features' content='...' />
    <AccordionItemDirective expanded={true} header='Installation' content='...' />
  </AccordionItemsDirective>
</AccordionComponent>

Pattern 3: Default Expanded State

模式3：默认展开状态

Pre-expand specific panels on load:

jsx

<AccordionItemDirective 
  expanded={true}
  header='Quick Start' 
  content='This section opens by default.' 
/>

加载时预先展开指定面板：

jsx

<AccordionItemDirective 
  expanded={true}
  header='Quick Start' 
  content='This section opens by default.' 
/>

Key Props & Methods

核心属性与方法

Component Properties

组件属性

Property	Type	Purpose	Default
`expandMode`	'Single' \| 'Multiple'	Control single/multiple panel expansion	'Multiple'
`expandedIndices`	number[]	Array of indices for initially expanded items	[]
`animation`	AnimationSettings	Expand/collapse animation config	SlideDown/SlideUp
`dataSource`	Object[]	Array of items for data binding	[]
`headerTemplate`	string \| function	Custom header template for all items	null
`itemTemplate`	string \| function	Custom item template for rendering	null
`height`	string \| number	Component height in px/%	'auto'
`width`	string \| number	Component width in px/%	'100%'
`enableHtmlSanitizer`	boolean	Sanitize untrusted HTML content	true
`enablePersistence`	boolean	Persist expanded state between reloads	false
`enableRtl`	boolean	Enable right-to-left layout	false
`locale`	string	Locale code for internationalization	''

属性	类型	用途	默认值
`expandMode`	'Single' \| 'Multiple'	控制单/多面板展开模式	'Multiple'
`expandedIndices`	number[]	初始展开项的索引数组	[]
`animation`	AnimationSettings	展开/折叠动画配置	SlideDown/SlideUp
`dataSource`	Object[]	用于数据绑定的项数组	[]
`headerTemplate`	string \| function	所有项的自定义标题模板	null
`itemTemplate`	string \| function	用于渲染的自定义项模板	null
`height`	string \| number	组件高度（px/%）	'auto'
`width`	string \| number	组件宽度（px/%）	'100%'
`enableHtmlSanitizer`	boolean	清理不可信HTML内容	true
`enablePersistence`	boolean	重载页面时保留展开状态	false
`enableRtl`	boolean	启用从右到左布局	false
`locale`	string	国际化语言代码	''

Item Properties

项属性

Property	Type	Purpose	Default
`header`	string	Item header text (accepts HTML)	-
`content`	string	Item content text (accepts HTML)	-
`expanded`	boolean	Set initial expanded state for item	false
`disabled`	boolean	Disable specific accordion item	false
`cssClass`	string	Custom CSS classes for item	-

属性	类型	用途	默认值
`header`	string	项标题文本（支持HTML）	-
`content`	string	项内容文本（支持HTML）	-
`expanded`	boolean	设置项的初始展开状态	false
`disabled`	boolean	禁用指定Accordion项	false
`cssClass`	string	项的自定义CSS类	-

Component Methods

组件方法

Method	Parameters	Purpose
`addItem()`	item, index (optional)	Add new accordion item(s)
`removeItem()`	index	Remove item at specified index
`enableItem()`	index, isEnable	Enable/disable specific item
`hideItem()`	index, isHidden	Show/hide specific item
`expandItem()`	isExpand, index (optional)	Expand/collapse items
`select()`	index	Set focus to item header
`destroy()`	none	Remove component from DOM

方法	参数	用途
`addItem()`	item, index（可选）	添加新的Accordion项
`removeItem()`	index	删除指定索引的项
`enableItem()`	index, isEnable	启用/禁用指定项
`hideItem()`	index, isHidden	显示/隐藏指定项
`expandItem()`	isExpand, index（可选）	展开/折叠项
`select()`	index	将焦点设置到项标题
`destroy()`	none	从DOM中移除组件

Common Use Cases

常见使用场景

Use Case	Mode	Key Feature
FAQ Section	Single	Only one question visible at a time
Settings Panel	Multiple	Check multiple options simultaneously
Multi-Step Form	Single	Guide user through steps sequentially
Content Organizer	Multiple	Browse multiple topics at once
Navigation Menu	Single	Tree-like hierarchical navigation
Data Dashboard	Multiple	View multiple data sections together

使用场景	模式	核心特性
FAQ区块	Single	同一时间仅显示一个问题
设置面板	Multiple	可同时选择多个选项
多步骤表单	Single	引导用户按顺序完成步骤
内容整理器	Multiple	可同时浏览多个主题
导航菜单	Single	树状层级导航
数据仪表盘	Multiple	可同时查看多个数据区块

Next Steps

下一步

Start with Getting Started to set up your first Accordion
Choose Expand Mode based on your use case
Add Animations for polish and user feedback
Load Content Dynamically if using data sources
Customize Styling to match your design system
Explore Advanced Features for complex scenarios

Need help? Check the specific reference files above based on what you're trying to build!

从快速入门开始，搭建你的第一个Accordion组件
根据使用场景选择展开模式
添加动画效果，提升用户体验
若使用数据源则动态加载内容
自定义样式，匹配你的设计系统
探索高级功能，应对复杂场景

需要帮助？根据你要实现的功能，查看上述对应的参考文档！