rsuite Accordion 手风琴组件完全指南：折叠面板、受控展开与可访问性实践

前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载手风琴Accordion是 rsuite 中用于在有限空间内展示大量内容的经典交互组件通过点击标题即可展开或折叠内容区域天然适合 FAQ、设置分组、步骤说明等场景。本文以 rsuite 官方文档 docs/pages/components/accordion/zh-CN/index.md 为骨架结合仓库源码逐层讲解其用法、受控模式、自定义能力与无障碍实现读完你就能在项目中熟练使用并深入理解其内部机制。获取组件Accordion是 rsuite 的顶层导出组件之一直接按需引入即可import { Accordion } from rsuite;组件以复合组件形式暴露子面板Accordion.Panel无需单独导入Accordion Accordion.Panel header面板标题面板内容/Accordion.Panel /Accordion从源码看Accordion本身是一个轻量封装它内部将accordion标记为 true 并渲染 PanelGroup同时把Accordion.Panel静态挂载为子组件见 src/Accordion/Accordion.tsx 与 src/Accordion/AccordionPanel.tsx。因此Accordion的几乎所有能力都继承自 PanelGroup 与 Panel理解这两者就能吃透手风琴。默认用法多面板同时展开默认情况下手风琴允许多个面板同时展开。点击任意标题即可展开或折叠对应面板互不影响import { Accordion, Placeholder } from rsuite; const App () ( Accordion Accordion.Panel headerAccordion Panel 1 defaultExpanded Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 2 Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 3 Placeholder.Paragraph / /Accordion.Panel /Accordion );要点defaultExpanded让面板在首次渲染时默认展开示例中 Panel 1 默认展开内容区可直接放置任意 React 节点示例使用了 rsuite 的Placeholder.Paragraph占位组件模拟真实内容此时每个面板独立管理自己的展开状态符合默认手风琴的宽松模式。带边框样式通过bordered属性可为整个手风琴加上边框视觉上更接近经典的卡片式折叠列表Accordion bordered Accordion.Panel headerAccordion Panel 1 defaultExpanded Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 2 Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 3 Placeholder.Paragraph / /Accordion.Panel /Accordionbordered的样式实现位于 src/PanelGroup/styles/index.scss样式目录src/PanelGroup/styles/并会同步作用到每个面板的边框呈现。只展开一个面板经典手风琴模式经典手风琴的语义是同一时刻仅展开一个面板。当给Accordion设置defaultActiveKey或受控的activeKey并为面板指定eventKey后组件即进入单展开模式import { Accordion, Placeholder } from rsuite; const App () ( Accordion defaultActiveKey{1} bordered Accordion.Panel headerAccordion Panel 1 eventKey{1} Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 2 eventKey{2} Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 3 eventKey{3} Placeholder.Paragraph / /Accordion.Panel /Accordion );这里eventKey是面板的身份键defaultActiveKey{1}表示初始激活eventKey{1}的面板此后点击其他面板会自动收起已展开的面板。底层原理结合源码PanelGroup.tsx 使用useControlled(activeProp, defaultActiveKey)管理激活键并通过PanelGroupContext把{ accordion, activeKey, onGroupSelect }下发给每个面板Panel.tsx 从 context 中取出onGroupSelect与激活键再交由内部useExpanded钩子决定当前面板是否展开调用点见 Panel.tsx 中useExpanded({ expanded, defaultExpanded, eventKey, collapsible })。因此可以推断进入单展开模式后面板的展开状态由activeKey eventKey推导得出展开逻辑集中在 PanelGroup 的 context 中统一协调。受控组件用 activeKey onSelect 完全掌控如果希望由外部状态完全控制当前展开的面板例如与工具栏、面包屑或其他组件联动可同时使用activeKey与onSelectimport { Accordion, Placeholder, ButtonGroup, Button } from rsuite; const App () { const [activeKey, setActiveKey] React.useState(1); return ( ButtonGroup {[1, 2, 3].map(key ( Button key{key} active{key activeKey} onClick{() setActiveKey(key)} Expand Item {key} /Button ))} /ButtonGroup hr / Accordion activeKey{activeKey} bordered onSelect{setActiveKey} Accordion.Panel headerAccordion Panel 1 eventKey{1} Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 2 eventKey{2} Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 3 eventKey{3} Placeholder.Paragraph / /Accordion.Panel /Accordion / ); };该示例演示了外部按钮组与手风琴双向联动点击按钮把activeKey写入 state手风琴据此展开对应面板反过来点击面板标题会触发onSelect(eventKey, event)源码见 PanelGroup.tsx 中handleSelect的setActiveKey与onSelect?.(activeKey, event)调用从而同步更新按钮高亮。使用受控模式时注意onSelect回调签名为(eventKey: string | number, event: React.SyntheticEvent) void第二个参数为触发事件的原始事件对象若在受控模式下不更新activeKey面板将保持点了不切换的锁定状态这正是实现自定义展开逻辑的切入点。自定义指示器caretAs每个面板标题右侧默认有一个展开/折叠指示箭头。通过caretAs可传入任意图标组件将其替换为自定义指示器例如使用react-iconsimport { Accordion, Placeholder } from rsuite; import { FaAngleDoubleDown, FaArrowAltCircleDown, FaArrowDown } from react-icons/fa; const App () ( Accordion defaultActiveKey{1} bordered Accordion.Panel headerAccordion Panel 1 eventKey{1} caretAs{FaAngleDoubleDown} Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 2 eventKey{2} caretAs{FaArrowAltCircleDown} Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 3 eventKey{3} caretAs{FaArrowDown} Placeholder.Paragraph / /Accordion.Panel /Accordion );caretAs类型为React.ElementType即任意可渲染为图标的组件。在 Panel.tsx 中caretAs被透传给PanelHeader用于渲染标题右侧的指示器展开/折叠时其状态类会随之变化图标旋转等动效由样式层完成。自定义标题富内容 Headerheader属性接收任意ReactNode因此完全可以构建头像 标题 副标题的富标题。官方示例组合了Stack、Avatar等组件import { Accordion, Placeholder, Stack, Avatar } from rsuite; const Header props { const { avatarUrl, title, subtitle, ...rest } props; return ( Stack {...rest} spacing{10} alignItemsflex-start Avatar src{avatarUrl} alt{title} / Stack spacing{2} directioncolumn alignItemsflex-start div{title}/div div style{{ color: var(--rs-text-secondary), fontSize: 12 }}{subtitle}/div /Stack /Stack ); }; const App () ( Accordion bordered defaultActiveKey{1} Accordion.Panel header{Header titleReact subtitleThe library for web and native user interfaces /} eventKey{1} React is a JavaScript library for building user interfaces. /Accordion.Panel Accordion.Panel header{Header titleVue subtitleA progressive framework for building UI on the web /} eventKey{2} Vue builds on top of standard HTML, CSS, and JavaScript and provides a declarative, component-based programming model. /Accordion.Panel Accordion.Panel header{Header titleAngular subtitleDeliver web apps with confidence /} eventKey{3} Angular empowers developers to build fast, reliable applications. /Accordion.Panel /Accordion );从 Panel.tsx 源码可以看到header存在时组件才渲染PanelHeader即无 header 的面板不会生成可点击标题区同时 header 通过PanelHeader与aria-labelledby关联见下文可访问性。禁用面板通过disabled可以禁用某个面板使其标题不可点击、内容不可展开import { Accordion, Placeholder } from rsuite; const App () ( Accordion defaultActiveKey{1} bordered Accordion.Panel headerAccordion Panel 1 eventKey{1} Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 2 eventKey{2} disabled Placeholder.Paragraph / /Accordion.Panel Accordion.Panel headerAccordion Panel 3 eventKey{3} Placeholder.Paragraph / /Accordion.Panel /Accordion );示例中 Panel 2 处于禁用态。源码层面disabled被传入PanelHeader见 Panel.tsx用于设置aria-disabled并阻断交互样式层也会呈现置灰效果。可访问性Accessibility手风琴的正确无障碍实现是标题按钮 折叠内容的 ARIA 模式。rsuite 的 Accordion 从以下两方面内置了无障碍支持ARIA 属性属性含义aria-expanded表示面板当前是展开还是折叠状态aria-controls标识该标题所控制的内容区域关联面板内容 IDaria-labelledby标识面板内容的标题元素反向关联标题 IDaria-disabled表示面板是否被禁用这些属性在 Panel.tsx 中自动生成组件通过useUniqueId生成唯一 ID进而派生出bodyId ${id}-panel与buttonId ${id}-btn再分别传给PanelHeader渲染aria-expanded、aria-controls、aria-disabled与PanelBody渲染aria-labelledby与role。也就是说你无需手写任何 ARIA 代码组件会为每个面板自动建立按钮 ↔ 内容的无障碍关联。键盘交互Tab在面板之间移动焦点聚焦下一个可聚焦的面板标题Enter或Space展开或折叠当前聚焦的面板。这一交互模式与 W3C ARIA 手风琴实践Accordion Pattern保持一致保证了纯键盘用户的完整操作路径。Props 总览Accordion属性类型(默认值)描述activeKeystring | number激活项的事件键受控模式使用borderedboolean是否显示边框classPrefixstring组件 CSS 类名的前缀默认panel-group见 PanelGroup.tsxdefaultActiveKeystring | number默认激活项的事件键非受控onSelect(eventKey, event) void激活项发生变化时的回调说明源码中AccordionProps OmitPanelGroupProps, accordion见 Accordion.tsx即accordion由组件内部固定为 true其余 PanelGroup 的能力全部透传activeKey/defaultActiveKey的真实类型为KeyType string | number。Accordion.Panel属性类型(默认值)描述bodyFillboolean内容区域是否填充铺满容器caretAsReactNode / React.ElementType自定义展开指示器图标classPrefixstring(panel)组件 CSS 类名的前缀defaultExpandedboolean默认展开面板非受控disabledboolean禁用面板eventKeystring | number面板对应的事件键expandedboolean是否展开面板受控headerReactNode面板标题可为任意富内容Accordion.Panel本质就是 Panel 组件AccordionPanelProps PanelProps因此它还继承了一部分未在本文档表格中列出的底层能力例如collapsible、shaded、scrollShadow、bodyProps、id、headerRole/panelRole以及进入/离开动画回调onEnter/onEntering/onEntered/onExit/onExiting/onExited动画事件类型定义于src/internals/types需要精细控制时可直接使用这些属性。小结从用法到实现用法速记默认多开 →bordered加边框 →defaultActiveKey/activeKey进入单开模式 →onSelect实现受控联动 →caretAs换图标 →header富标题 →disabled禁面板实现脉络Accordion固定accordion语义→PanelGroupuseControlled管理激活键、PanelGroupContext下发accordion/activeKey/onGroupSelect→PaneluseExpanded推导展开态、自动生成 ARIA 关联。这条链路Accordion.tsx → PanelGroup.tsx → Panel.tsx清晰展示了 rsuite 复合组件的组合模式也解释了为何手风琴能与 PanelGroup/Panel 共享同一套状态与无障碍体系。对照本仓库中的示例片段docs/pages/components/accordion/fragments/ 下的basic.md、bordered.md、accordion.md、controlled.md、custom-indicator.md、custom-header.md、disabled-panel.md即可在本地运行全部官方案例快速上手。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐rsuite Accordion 手风琴组件完全指南用法、受控模式与无障碍实现rsuite Accordion 手风琴组件完全指南用法、受控模式与无障碍实现 Accordion手风琴是 rsuite 中用于在有限空间内展示大量内容的前端UI组件Mesop Select 组件完整指南在 Python 中构建单选与多选下拉框Mesop Select 组件完整指南在 Python 中构建单选与多选下拉框 导读 Select下拉选择框是 Mesop 中让用户从一组预定义值中选择的前端后端Web框架Taro UI 手风琴组件 Accordion可折叠内容的实现技巧Taro UI 手风琴组件 Accordion可折叠内容的实现技巧 Taro UI 是一款基于 Taro 框架开发的多端 UI 组件库其中的手风琴组件AcUI组件前端跨平台上一篇gh_mirrors/30s/30-seconds-of-python 插件开发指南下一篇TortoiseGit新手入门从安装到提交代码的完整图文教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考