Ant Design Collapse（折叠面板）完整实战指南：声明式 API、交互形态、Semantic DOM 与主题定制

Ant Design Collapse折叠面板完整实战指南声明式 API、交互形态、Semantic DOM 与主题定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-designCollapse折叠面板是 Ant Design「数据展示」分类中的基础组件用于把复杂、冗长的内容按区域分组收纳让页面保持整洁。本指南以仓库中的官方文档 components/collapse/index.zh-CN.md 为骨架结合组件源码 components/collapse/Collapse.tsx、components/collapse/CollapsePanel.tsx 与其样式生成文件 components/collapse/style/index.ts系统讲解从基础使用到手风琴、嵌套、自定义图标、幽灵面板、可折叠触发区域等全部能力并下沉到 Semantic DOM、Design Token 与无障碍实现层面帮助你既会用、也能解释清楚它的底层原理。何时使用 Collapse根据官方文档Collapse 面向两类典型诉求对复杂区域进行分组和隐藏保持页面整洁。当一块内容信息量很大、且用户并不总需要一次性看到全部时把它们折叠为「标题 内容」的结构是最常用的交互解法例如 FAQ、分组设置项、长表单的补充说明区。手风琴Accordion是特殊的折叠面板形态同一时刻只允许一个内容区域展开。它适合「多选一」式的浏览能有效避免页面纵向空间被多个展开面板同时占用。Collapse 基于rc-component/collapseRcCollapse封装实现入口文件 components/collapse/index.tsx 将组件与Collapse.Panel一并导出同时在 API 层对文档、废弃提示、主题与无障碍做了大量 Ant Design 级增强。快速上手基于 items 的声明式写法自 5.6.0 起官方推荐直接通过items属性声明面板而不再手写Collapse.Panel子组件。基础示例见 components/collapse/demo/basic.tsximport React from react; import type { CollapseProps } from antd; import { Collapse } from antd; const text A dog is a type of domesticated animal. ...; const items: CollapseProps[items] [ { key: 1, label: This is panel header 1, children: p{text}/p }, { key: 2, label: This is panel header 2, children: p{text}/p }, { key: 3, label: This is panel header 3, children: p{text}/p }, ]; const App: React.FC () { const onChange (key: string | string[]) console.log(key); return Collapse items{items} defaultActiveKey{[1]} onChange{onChange} /; }; export default App;要点说明items中每一项都是一个ItemTypekey与激活态一一对应label是面板标题children是折叠内容区body。defaultActiveKey用于非受控初始化展开项activeKeyonChange则构成受控用法。onChange回调参数key的类型为string | string[]。若需要嵌套结构面板内再套折叠面板直接把Collapse作为上一级面板的children即可参见 components/collapse/demo/mix.tsx。从源码看Collapse 内部通过toArray(children)兼容旧式子元素写法components/collapse/Collapse.tsx 的items分支因此两种写法可以混合过渡。API 详解通用属性如className、style、rootClassName等参考通用属性文档本节完整继承官方文档的参数表并给出组件级说明。Collapse 主组件参数说明类型默认值版本全局配置accordion手风琴模式booleanfalse×activeKey当前激活 tab 面板的 keystring[] | string / number[] | number手风琴模式下默认第一个元素×bordered带边框风格的折叠面板booleantrue×classNames用于自定义组件内部各语义化结构的 class支持对象或函数RecordSemanticDOM, string | (info: { props }) RecordSemanticDOM, string-6.0.0collapsible所有子面板是否可折叠或指定可折叠触发区域header|icon|disabled-4.9.0×defaultActiveKey初始化选中面板的 keystring[] | string / number[] | number-×destroyInactivePanel销毁折叠隐藏的面板已废弃请改用destroyOnHiddenbooleanfalse×destroyOnHidden销毁折叠隐藏的面板booleanfalse5.25.0×expandIcon自定义切换图标(panelProps) ReactNode-5.15.0expandIconPlacement设置图标位置start|endstart-×expandIconPosition设置图标位置请使用expandIconPlacement替换start|end-4.21.0×ghost使折叠面板透明且无边框booleanfalse4.4.0×size设置折叠面板大小large|medium|smallmedium5.2.0×styles用于自定义组件内部各语义化结构的行内 style支持对象或函数RecordSemanticDOM, CSSProperties | (info: { props }) RecordSemanticDOM, CSSProperties-6.0.0onChange切换面板的回调function-×items折叠项目内容ItemType-5.6.0×需要区分的两点设计决策destroyOnHidden与已废弃的destroyInactivePanel二者语义一致源码中做了显式兼容——destroyOnHidden{destroyOnHidden ?? destroyInactivePanel}见 components/collapse/Collapse.tsx同时在开发环境下通过devUseWarning(Collapse)打印废弃提示。为减少频繁展开/收起时的 DOM 重建默认false仅隐藏、不销毁仅在内容包含重型组件或状态时按需开启。expandIconPosition→expandIconPlacement4.21.0 引入的旧名称已废弃二者可混用源码中通过expandIconPlacement ?? expandIconPosition ?? start取合并值并据其生成${prefixCls}-icon-placement-start/end样式类以控制箭头在标题前默认还是标题后。size的取值沿革文档类型为large | medium | small。底层尺寸类型SizeType定义在 components/config-provider/SizeContext.tsx并保留了对middle的兼容注释明确middle将在 v7 移除。Collapse 源码通过useSize从 ConfigProvider 的 SizeContext 继承全局尺寸仅在small/large时追加-small/-large类名medium使用基准样式即可。ItemTypeitems 中单项的配置参数说明类型默认值版本classNames语义化结构 classNameRecordheader | body, string-5.21.0collapsible是否可折叠或指定可折叠触发区域header|icon|disabled-childrenbody 区域内容ReactNode-extra自定义渲染每个面板右上角的内容ReactNode-forceRender被隐藏时是否渲染 body 区域 DOM 结构booleanfalsekey对应 activeKeystring | number-label面板标题ReactNode--showArrow是否展示当前面板上的箭头为 false 时collapsible 不能设为 iconbooleantruestyles语义化结构 styleRecordheader | body, CSSProperties-5.21.0面板级优先在 components/collapse/CollapsePanel.tsx 中showArrow默认true一旦设为false组件会追加${prefixCls}-no-arrow类并隐藏箭头。由于箭头是唯一可点击的视觉锚点此时不应再把collapsible设为icon。Collapse.Panel已废弃:::warning 已废弃 版本 5.6.0 时请使用items方式配置面板。 :::参数说明类型默认值版本collapsible是否可折叠或指定可折叠触发区域header|icon|disabled-4.9.0icon: 4.24.0extra自定义渲染每个面板右上角的内容ReactNode-forceRender被隐藏时是否渲染 body 区域 DOM 结构booleanfalseheader面板标题ReactNode-key对应 activeKeystring | number-showArrow是否展示当前面板上的箭头为 false 时collapsible 不能设为 iconbooleantrue此外源码还保留了对disabled的兼容使用Collapse.Panel时若传入disabled开发环境会告警并提示改用collapsibledisabled。这些面板参数在ItemType中均有等价字段因此迁移到items写法是纯结构变更、无行为差异。交互形态手风琴与可折叠触发区域手风琴模式accordion参考 components/collapse/demo/accordion.tsx只需一行const items: CollapseProps[items] [ { key: 1, label: This is panel header 1, children: p{text}/p }, { key: 2, label: This is panel header 2, children: p{text}/p }, ]; const App: React.FC () Collapse accordion items{items} /;手风琴模式下同一时刻仅一个面板展开activeKey无需也不应维护为数组。collapsible谁可以触发折叠参考 components/collapse/demo/collapsible.tsxcollapsible有四种可取值粒度既可以在整个Collapse上设置作用于全部子面板也可以在items的单个ItemType上覆盖header默认点击标题文本或图标均能切换icon仅点击箭头图标可切换标题文本点击不响应disabled面板完全不可折叠不设置跟随父级collapsible或采用默认可折叠行为。注意一旦某面板设置了showArrow: false该面板上就不存在可点击的图标因此不能搭配collapsibleicon。受控回调与「额外节点不触发折叠」onChange(key: string | string[])会在每次切换后收到当前激活面板的 key 集合。若在面板extra中放置操作按钮如下拉、设置而按钮点击又不想带动面板本身的展开/收起可在按钮事件中调用event.stopPropagation()——这正是 components/collapse/demo/extra.tsx 所演示的关键手法const genExtra () ( SettingOutlined onClick{(event) { event.stopPropagation(); // 阻止冒泡避免触发面板切换 }} / ); Collapse defaultActiveKey{[1]} onChange{onChange} expandIconPlacementend // 也可通过 Select 动态切换 start/end items{[{ key: 1, label: This is panel header 1, children: div{text}/div, extra: genExtra() }]} /该示例同时演示了expandIconPlacement的动态切换start表示箭头位于标题左侧end表示位于右侧。上例中为extra内容留出右侧空间将箭头放到end更合适。外观形态尺寸、无边框与幽灵面板尺寸size参考 components/collapse/demo/size.tsxCollapse items{[{ key: 1, label: This is small size panel header, children: p{text}/p }]} sizesmall / Collapse sizelarge items{[...]} /三种尺寸分别对应样式文件中的headerPaddingSM/contentPaddingSM、headerPadding/contentPaddingmedium基准样式、headerPaddingLG/contentPaddingLG三组内边距 Token做到标题与内容区的同步缩放见 components/collapse/style/index.ts。简洁风格borderless参考 components/collapse/demo/borderless.tsx。bordered{false}时组件会添加${prefixCls}-borderless类整个容器去掉外边框仅保留面板之间细分割线内容区背景切换为borderlessContentBg默认透明、内边距切换为borderlessContentPadding。适合与卡片、悬浮区域等容器搭配。const App: React.FC () ( Collapse items{items} bordered{false} defaultActiveKey{[1]} / );幽灵折叠面板ghost参考 components/collapse/demo/ghost.tsx。ghost将面板做成透明且无边框的形态——容器、面板、分割线全部置为透明仅保留标题与内容排版常用来在有色背景如页头、卡片标题区上叠加展开内容Collapse defaultActiveKey{[1]} ghost items{items} /从 components/collapse/style/index.ts 的genGhostStyle可看到其实现细节根容器background: transparent; border: 0面板与 body 均透明body 使用paddingBlock: paddingSM保证展开时有舒适呼吸感。自定义展开图标默认箭头由源码统一提供未展开时是ant-design/icons的RightOutlined向右展开后rotate{90}转成向下RTL 环境下方向相反rotate -90。默认图标参与交互时会被赋予aria-labelexpanded/collapsed非交互场景则标记aria-hidden属于无障碍细节详见 components/collapse/Collapse.tsx 的renderExpandIcon。替换图标expandIcon参考 components/collapse/demo/custom.tsxexpandIcon接收包含isActive等字段的 panelProps返回自定义 ReactNodeimport { CaretRightOutlined } from ant-design/icons; Collapse bordered{false} defaultActiveKey{[1]} expandIcon{({ isActive }) CaretRightOutlined rotate{isActive ? 90 : 0} /} style{{ background: token.colorBgContainer }} items{getItems(panelStyle)} /该示例还展示了用theme.useToken()读取colorFillAlter、borderRadiusLG等全局 Token把每个面板包装成独立的「悬浮卡片」样式——这是在 Collapse 上做定制化 UI 的常见范式。隐藏箭头与第三方图标垂直对齐隐藏箭头见 components/collapse/demo/noarrow.tsx在某项上设置showArrow: false即可让该面板不带箭头。注意面板标题仍整体可点击切换。第三方 svg 图标见 components/collapse/demo/icon.tsx。当标题label中使用 lucide、react-icons 等渲染为裸svg的图标时组件保证其与标题文本垂直居中Ant Design 图标默认走.anticon包裹同样自动居中。Semantic DOM语义化结构级定制自语义化结构调整起Collapse 逐步开放内部结构节点的样式覆盖官方示例见 components/collapse/demo/_semantic.tsx。当前 Collapse 可定制的语义节点如下节点说明可用版本root根元素折叠面板的边框、圆角、背景色等容器样式控制面板整体布局与外观6.0.0header头部元素flex 布局、内边距、颜色、行高、光标样式、过渡动画等头部交互与样式5.21.0title标题元素flex 自适应布局、右边距等标题文字排版6.0.0body内容元素内边距、颜色、背景色等内容展示样式5.21.0icon图标元素字号、过渡动画、旋转变换等箭头样式与动效6.0.0这些节点在classNames/styles属性中既可以传对象key 为上述节点名也可以传函数接收{ props }可根据 props 如size动态返回不同的映射参考 components/collapse/demo/style-class.tsxconst styles: CollapseProps[styles] { root: { backgroundColor: #fafafa, border: 1px solid #e0e0e0, borderRadius: 8 }, header: { backgroundColor: #f0f0f0, padding: 12px 16px, color: #141414 }, }; // 函数形式可依据 props 条件化输出 const stylesFn: CollapseProps[styles] ({ props }): GetPropCollapseProps, styles, Return { if (props.size large) { return { root: { backgroundColor: #fff }, header: { backgroundColor: #F5EFFF } }; } };ItemType.classNames/ItemType.styles则面向单个面板的header与body两个节点5.21.0 起适合做面板粒度的差异样式。主题变量Design Token定制Collapse 的全部组件级 Token 定义在 components/collapse/style/index.ts 的ComponentToken接口中并在prepareComponentToken中基于全局 Alias Token 计算默认值。可定制项汇总如下Token说明默认值由基础 Token 推导headerPadding头部内边距mediumpaddingSMpaddingheaderPaddingSM小号头部内边距paddingXSpaddingSMheaderPaddingLG大号头部内边距paddingpaddingLGheaderBg头部背景色colorFillAltercontentPadding内容区内边距mediumpadding 固定 16pxcontentPaddingSM小号内容区内边距paddingSMcontentPaddingLG大号内容区内边距paddingLGcontentBg内容区背景色colorBgContainerborderlessContentPadding简洁风格内容区内边距paddingXXS 16px paddingborderlessContentBg简洁风格内容区背景透明另外样式生成器通过mergeToken派生collapsePanelBorderRadius borderRadiusLG用于面板的整体圆角若跟随深色/亮色主题这些 Token 会自动重算。通过ConfigProvider的theme.components.Collapse即可全局定制示例见 components/collapse/demo/component-token.tsxConfigProvider theme{{ components: { Collapse: { headerPadding: 0px 10px 20px 30px, headerBg: #eaeeff, contentPadding: 0px 10px 20px 30px, contentBg: #e6f7ff, }, }, }} Collapse items{items} / /ConfigProvider在 components/collapse/style/index.ts 中这些 Token 通过genStyleHooks(Collapse, ...)注册为 CSS-in-JS 样式并按genBaseStyle基础容器/面板/内容/箭头→genBorderlessStyle→genGhostStyle→genArrowStyle→genCollapseMotion展开收起动画的顺序组装最终返回hashId与 CSS 变量类名用于样式隔离。源码实现折叠动画与交互的底层逻辑阅读 components/collapse/Collapse.tsx 可以确认几个关键实现事实双层架构Collapse 是对rc-component/collapse的二次封装antd 层负责前缀类名getPrefixCls(collapse)、主题样式、语义化类名/样式合并与无障碍细节交互与状态管理则下沉到 rc 组件。展开动画通过initCollapseMotion初始化折叠动效来自 components/_util/motion.ts并设置motionAppear: false与leavedClassName: ${prefixCls}-panel-hidden实现收起后保留最后高度、最终隐藏的平滑过渡。尺寸上下文mergedSize useSize(ctx customizeSize ?? ctx ?? middle)使 Collapse 可以响应 ConfigProvider 的全局size设置见 components/config-provider/hooks/useSize.ts。RTL当 ConfigContext 的direction为 rtl 时会追加${prefixCls}-rtl类并反转箭头旋转方向。语义合并组件级classNames/styles与 ConfigProvider 组件配置中的同名项通过useMergeSemantic合并root 样式会同时落到容器的style上实现「全局默认 → 单组件覆盖」的层级。此外测试目录 components/collapse/tests/ 中包含了a11y.test.ts、accessibility.test.tsx、demo-extend.test.ts、demo-semantic.test.tsx等用例对默认激活、边框切换、无边框渲染、语义类名与无障碍可访问性均有自动化覆盖可作为行为规范的权威参照。小结Collapse 的能力图谱可以归结为三层数据层items/activeKey/受控与非受控形态层size、bordered、ghost、expandIconPlacement、自定义图标以及定制层classNames/styles的语义节点、ItemType面板级覆盖、Design Token 主题变量。当默认样式无法满足视觉要求时优先通过 Semantic DOMheader/body/title/icon/root与组件 Token 而非!important覆盖来达成当需要把折叠面板接入品牌主题体系时借助ConfigProvider的组件配置即可实现一处声明、处处生效。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考