# Accordion 手风琴 · HeroUI

> 用于在紧凑空间中组织信息的可折叠内容面板。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/components/accordion
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## 引入

```tsx
import { Accordion } from '@heroui/react';
```

### 用法


> 示例 `accordion-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### 组件结构

引入 Accordion 组件并通过点语法访问所有子部分。

```tsx
import { Accordion } from '@heroui/react';

export default () => (
  <Accordion>
    <Accordion.Item>
      <Accordion.Heading>
        <Accordion.Trigger>
          <Accordion.Indicator />
        </Accordion.Trigger>
      </Accordion.Heading>
      <Accordion.Panel>
        <Accordion.Body/>
      </Accordion.Panel>
    </Accordion.Item>
  </Accordion>
)
```

### Surface


> 示例 `accordion-surface`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### 多项同时展开


> 示例 `accordion-multiple`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### 受控


> 示例 `accordion-controlled`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### 自定义指示器


> 示例 `accordion-custom-indicator`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### 禁用状态


> 示例 `accordion-disabled`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### FAQ 布局


> 示例 `accordion-faq`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### 自定义样式


> 示例 `accordion-custom-styles`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### 无分隔线


> 示例 `accordion-without-separator`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


### 自定义渲染函数


> 示例 `accordion-custom-render-function`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/accordion


## 样式

### 传入 Tailwind CSS 类


      {items.map((item, index) => (
        
          
            
              {item.iconUrl ? (
                <img
                  alt={item.title}
                  className="group-hover/item:scale-120 group-hover/item:-rotate-10 h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:drop-shadow-lg"
                  src={item.iconUrl}
                />
              ) : null}
              
                {item.title}
                {item.subtitle}
              
              svg]:size-4">
                
              
            
          
          
            {item.content}
          
        
      ))}
    
  );
}`} />

### 自定义组件类

若要自定义 Accordion 组件类，可使用 `@layer components` 指令。
  
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .accordion {
    @apply rounded-xl bg-gray-50;
  }

  .accordion__trigger {
    @apply font-semibold text-lg;
  }

  .accordion--outline {
    @apply shadow-lg border-2;
  }
}
```

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

Accordion 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/accordion.css)）：

#### 基础类
- `.accordion` - Accordion 根容器
- `.accordion__body` - 正文容器
- `.accordion__heading` - 标题包裹层
- `.accordion__indicator` - 展开/收起指示图标
- `.accordion__item` - 单个 Accordion 项
- `.accordion__panel` - 可折叠面板容器
- `.accordion__trigger` - 可点击的触发按钮

#### 变体类
- `.accordion--outline` - 描边变体（边框与背景）

#### 状态类
- `.accordion__trigger[aria-expanded="true"]` - 展开状态
- `.accordion__panel[aria-hidden="false"]` - 面板可见状态

### 交互状态

该组件同时支持 CSS 伪类与 data 属性：

- **悬停**：触发器上 `:hover` 或 `[data-hovered="true"]`
- **聚焦**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]`
- **禁用**：触发器上 `:disabled` 或 `[aria-disabled="true"]`
- **展开**：触发器上 `[aria-expanded="true"]`

## API 参考

### Accordion Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `allowsMultipleExpanded` | `boolean` | `false` | 是否允许多项同时展开。 |
| `defaultExpandedKeys` | `Iterable` | - | 初始展开的 key。 |
| `expandedKeys` | `Iterable` | - | 受控的展开 key。 |
| `onExpandedChange` | `(keys: Set) => void` | - | 展开 key 变化时调用的事件处理函数。 |
| `isDisabled` | `boolean` | `false` | 是否禁用整个 Accordion。 |
| `variant` | `"default" \| "surface"` | `"default"` | Accordion 的视觉变体。 |
| `hideSeparator` | `boolean` | `false` | 是否隐藏 Accordion 项之间的分隔线。 |
| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
| `children` | `ReactNode` | - | Accordion 项。 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|


### Accordion.Item Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `id` | `Key` | - | 该项的唯一标识。 |
| `isDisabled` | `boolean` | `false` | 是否禁用该项。 |
| `defaultExpanded` | `boolean` | `false` | 初始是否展开。 |
| `isExpanded` | `boolean` | - | 受控展开状态。 |
| `onExpandedChange` | `(isExpanded: boolean) => void` | - | 展开状态变化时调用的事件处理函数。 |
| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
| `children` | `ReactNode` | - | 项内容。 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionItemRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

### Accordion.Trigger Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
| `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数。 |
| `onPress` | `() => void` | - | 额外的按下事件处理函数。 |
| `isDisabled` | `boolean` | - | 是否禁用触发器。 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TriggerRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

### Accordion.Panel Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
| `children` | `ReactNode` | - | 面板内容。 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionPanelRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

### Accordion.Indicator Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
| `children` | `ReactNode` | - | 自定义指示图标。 |

### Accordion.Body Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 额外的 Tailwind CSS 类。 |
| `children` | `ReactNode` | - | 正文内容。 |

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt