ant-design 折叠面板（Collapse）基础用法与实现原理详解

ant-design 折叠面板（Collapse）基础用法与实现原理详解

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design

折叠面板（Collapse）是 ant-design 中用于收纳和展开复杂内容区域的核心展示组件，在设置面板、筛选条件分组、FAQ 列表等场景中广泛使用。本文以 components/collapse/demo/basic.md 中的基础示例为主线，结合组件 API、源码实现与 Less 样式，带你掌握 Collapse 的声明式用法、受控与非受控两种模式，以及它基于 rc-collapse 的底层渲染机制。

组件定位：何时使用折叠面板

根据 components/collapse/index.md 的官方说明，Collapse 组件用于展示可以折叠/展开的内容区域，其典型使用场景包括：

• 对复杂区域进行分组和隐藏，保持页面整洁，避免一次性向用户暴露过多信息；
• 手风琴（accordion）模式：一种特殊的折叠面板，只允许单个内容区域同时展开，适合内容层级清晰、需要"一次只看一个"的交互场景。

快速上手：同时展开多个面板的基础示例

basic.md展示的是 Collapse 最经典的用法：一个 Collapse 容器内放多个 Panel（面板），默认展开第一个，同时允许多个面板并行展开。完整代码如下：

import { Collapse } from 'antd'; const Panel = Collapse.Panel; function callback(key) { console.log(key); } const text = ` A dog is a type of domesticated animal. Known for its loyalty and faithfulness, it can be found as a welcome guest in many households across the world. `; ReactDOM.render( <Collapse defaultActiveKey={['1']} onChange={callback}> <Panel header="This is panel header 1" key="1"> <p>{text}</p> </Panel> <Panel header="This is panel header 2" key="2"> <p>{text}</p> </Panel> <Panel header="This is panel header 3" key="3"> <p>{text}</p> </Panel> </Collapse> , mountNode);

这段代码拆解如下：

非受控模式与 defaultActiveKey

示例使用的是非受控模式：组件内部自行维护展开状态，defaultActiveKey只在首次渲染时生效，指定了默认展开key="1"的面板，因此页面加载后第一块内容直接可见。由于传入的是数组['1']，多个面板可以同时处于展开状态——这正是"可以同时展开多个面板"这一特性的来源。

受控模式与 activeKey

如果你需要把展开状态交由外部管理（例如与路由、搜索条件联动），应改用受控模式：传入activeKey并自行在onChange中更新状态，此时组件完全由你传入的值驱动。两种模式的核心 API 差异如下（来源：components/collapse/index.md 的 API 表）：

Collapse.Panel：面板单元的属性

面板单元通过Collapse.Panel取得，每个 Panel 的属性如下：

header既可以是纯字符串（如示例中的"This is panel header 1"），也可以传入任意 React 元素——这意味着你可以在面板头内放置图标、徽标、操作按钮等自定义内容。

底层实现：Collapse 与 rc-collapse 的关系

从源码层面看，ant-design 的 Collapse 是一个对社区基础组件库 rc-collapse 的轻量封装。components/collapse/index.jsx 的全部实现如下：

import Collapse from 'rc-collapse'; import React from 'react'; class AntCollapse extends React.Component { render() { return <Collapse {...this.props} />; } } AntCollapse.defaultProps = { prefixCls: 'ant-collapse', }; AntCollapse.Panel = Collapse.Panel; export default AntCollapse;

可以总结出三点实现事实：

1. 透传式封装：AntCollapse将外部传入的所有 props 原样透传给rc-collapse的<Collapse>，因此 rc-collapse 支持的能力（如手风琴、嵌套、动画）在 ant-design 中同样可用；
2. 样式前缀注入：通过defaultProps.prefixCls = 'ant-collapse'指定 CSS 类名前缀，使 rc-collapse 的通用样式与 ant-design 的主题样式（即 style/components/collapse.less 中定义的ant-collapse系列类）正确对接；
3. 静态属性挂载：AntCollapse.Panel = Collapse.Panel，将 rc-collapse 的面板子组件直接挂载为静态属性，从而支持const Panel = Collapse.Panel;的取用方式，与示例代码的写法完全吻合。

另外，在 package.json 中可以看到项目依赖"rc-collapse": "~1.6.0"，即本仓库锁定的底层版本范围。

交互细节与视觉呈现：来自样式的佐证

展开/收起交互的视觉反馈由 style/components/collapse.less 控制，几个值得留意的点：

• 箭头图标旋转动画：面板头左侧的箭头通过transition: transform 0.24s ease实现旋转过渡；收起时箭头为270deg（.collapse-close()），展开（aria-expanded="true"）时旋转为360deg（.collapse-open()），形成平滑的指向翻转效果；
• 展开动画：.ant-collapse-anim-active定义了height .2s @ease-out的高度过渡，让内容区域的展开/收起不是生硬跳变；
• 内容区域：.ant-collapse-content背景为白色、带padding: 0 16px，与容器浅灰底色（#f4f4f4）形成层次对比，便于区分"可折叠外壳"与"内容正文"。

这也解释了示例中<p>{text}</p>的内容会被渲染在带内边距的白色内容区内，而面板头部则是高 38px 的灰色可点击区域。

扩展实战：手风琴模式与面板嵌套

basic.md之外，Collapse 还提供两种高频变体，可用于加深理解：

手风琴模式（accordion）：给<Collapse>加上accordion属性后，每次只允许一个面板展开，且默认展开第一个（对应 API 表中"accordion 模式下默认第一个元素"的说明）。可参考 components/collapse/demo/accordion.md。

面板嵌套：Collapse 支持任意层级的嵌套——外层用手风琴模式做分组导航，内层用defaultActiveKey做多选展开，实现"手风琴 + 多面板"的组合布局。可参考 components/collapse/demo/mix.md，其中外层onChange同样可以监听到面板切换事件。

小结

折叠面板的入门用法非常简洁：<Collapse>容器配合Collapse.Panel子面板，用defaultActiveKey控制默认展开、用onChange响应切换即可。其背后是 ant-design 对 rc-collapse 的透传封装与ant-collapse前缀样式体系的支撑；需要更精细的控制时，切换到activeKey受控模式，或叠加accordion、嵌套面板等能力，即可覆盖从简单分组到复杂导航的大多数折叠交互场景。

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design