Accordion 手风琴

引入

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

用法

组件结构

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

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

多项同时展开

受控

自定义指示器

禁用状态

FAQ 布局

自定义样式

无分隔线

自定义渲染函数

样式

传入 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 指令。

了解更多。

@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 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

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	-	正文内容。