前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载本文以 rsuite 的 Accordion手风琴组件为核心系统讲解如何通过点击标题展开/折叠内容区域在有限空间内呈现大量信息。你将掌握 Accordion 的默认多面板展开、bordered 边框模式、只展开单面板的互斥模式、受控/非受控两种用法、自定义指示器与标题、禁用面板以及底层 PanelGroup 与 Panel 的实现原理和可访问性规范。文中所有代码均可直接复制运行。组件概述为什么需要手风琴Accordion 组件用于通过点击标题来展开和折叠内容区域常见于 FAQ 列表、侧边栏菜单、设置项分组等信息量大、空间有限的场景。rsuite 的 Accordion 以Accordion为容器、Accordion.Panel为面板的复合组件形式提供其组件定位在官方文档中描述为The Accordion component is used to expand and collapse the content area by clicking the title. It is often used to display a large amount of content in a limited space.用于通过点击标题展开和折叠内容区域常用于在有限空间中显示大量内容。从源码结构看Accordion是一个轻量封装// src/Accordion/Accordion.tsx const Accordion forwardRefdiv, AccordionProps, typeof Subcomponents((props, ref) { const { propsWithDefaults } useCustom(Accordion, props); return PanelGroup accordion ref{ref} {...propsWithDefaults} /; }, Subcomponents); const Subcomponents { Panel: AccordionPanel };其中AccordionProps OmitPanelGroupProps, accordion也就是说Accordion本质上是强制开启了accordion互斥模式的PanelGroupPanelGroup.tsx并挂载了一个Panel子组件AccordionPanel.tsx 直接复用Panel无任何额外逻辑。这意味着理解 Accordion 的关键在于理解 PanelGroup 的互斥展开机制与 Panel 的折叠状态管理。获取组件与快速上手安装与导入Accordion 属于 rsuite 核心组件库与其他组件一样从rsuite包中直接导入import { Accordion, Placeholder } from rsuite;完整的文档示例页面在 docs/pages/components/accordion/index.tsx 中通过ImportGuide components{[Accordion]} /提供导入指引同时将Accordion、Placeholder、Stack、Avatar、ButtonGroup、Button以及示例用到的图标组件注入为依赖。最小可用示例import { Accordion, Placeholder } from rsuite; const App () ( Accordion bordered defaultActiveKey{1} 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 );代码中的Placeholder.Paragraph是 rsuite 提供的占位内容组件仅用于在示例中填充面板内容区域实际开发中替换为你的真实内容即可。示例代码来自 accordion.md。基础用法默认多面板展开模式默认情况下Accordion 允许多个面板同时展开每个面板独立切换点击标题展开面板再次点击则折叠。下面的示例让第一个面板默认展开defaultExpanded其余面板默认折叠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 );对应的文档章节为默认Basic见 basic.md。这里的defaultExpanded是面板级别的初始展开状态属性与 Accordion 容器级的defaultActiveKey作用维度不同前者只影响单个面板的初始状态且不参与互斥约束。带边框模式bordered在容器上设置bordered属性即可让每个面板显示边框形成清晰的分隔视觉import { Accordion, Placeholder } from rsuite; const App () ( 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 /Accordion );见 bordered.md。bordered最终会作为修饰类名作用于根元素。从 PanelGroup.tsx 的源码可以看到const classes merge(className, withPrefix({ accordion, bordered }));withPrefix({ accordion, bordered })会根据布尔值生成rs-panel-group accordion、rs-panel-group bordered之类的修饰类对应样式定义在 src/PanelGroup/styles 目录中。互斥模式只展开一个面板当设置defaultActiveKey非受控或activeKey受控时Accordion 进入互斥模式——同一时刻只能展开一个面板。点击新面板时旧面板自动折叠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 );见 accordion.md。这里eventKey是每个面板的唯一标识Accordion 通过它来追踪当前激活的面板。互斥模式的底层实现原理互斥行为由PanelGroup的受控逻辑实现。在 PanelGroup.tsx 中const [activeKey, setActiveKey] useControlled(activeProp, defaultActiveKey); const handleSelect useEventCallback( (activeKey: KeyType | undefined, event: React.MouseEvent) { setActiveKey(activeKey); onSelect?.(activeKey, event); } ); const contextValue useMemo( () ({ accordion, activeKey, onGroupSelect: handleSelect }), [accordion, activeKey, handleSelect] );关键点有三useControlled(activeProp, defaultActiveKey)统一处理受控与非受控两种模式传入activeKey时为受控组件状态由外部管理不传时回落到defaultActiveKey内部自管状态。容器通过PanelGroupContext把accordion、activeKey、onGroupSelect下发给每个面板。面板点击时Panel.tsx 中调用onGroupSelect?.(eventKey, event)把自身eventKey上报给容器容器更新activeKey进而驱动其他面板折叠。onSelect回调签名是(eventKey: string, event) void其中 eventKey 类型在PanelGroup中定义为string | number。受控组件用 activeKey onSelect 精确控制当业务需要展开哪个面板由外部状态如按钮、路由、URL 参数决定时使用受控模式。activeKey通过onSelect回调更新实现单向数据流import { 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 / ); };见 controlled.md。该示例展示了两个典型用法外部联动通过ButtonGroup中的按钮切换activeKey状态从而驱动面板展开点击面板反向同步onSelect{setActiveKey}使面板自身的点击行为回写状态。结合源码可以确认受控模式下PanelGroup内部的setActiveKey依然会被调用随后onSelect被触发外部拿到新的activeKey后通过 props 回传形成闭环。若外部状态未正确更新面板的展开/折叠将以 props 为准这是 React 受控组件的标准语义。自定义指示器caretAs面板标题左侧默认有一个展开指示箭头caret。通过caretAs属性可以替换为任意 React 组件如图标库中的图标实现指示器的个性化import { 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 );见 custom-indicator.md。caretAs的类型为ReactNode因此既可以是组件也可以是任意渲染节点。示例中每个面板使用了不同的图标来自react-icons/fa演示了每个面板拥有独立指示器的能力。这些图标在文档页面 index.tsx 中同样被注册为依赖。自定义标题header 为 ReactNodeheader属性接受ReactNode因此可以放入任意 JSX 结构如 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 avatarUrlhttps://avatars.githubusercontent.com/u/6412038 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 avatarUrlhttps://avatars.githubusercontent.com/u/6128107 titleVue subtitleVue.js is a progressive framework for building UI on the web. / } eventKey{2} Vue is a JavaScript framework for building user interfaces. /Accordion.Panel Accordion.Panel header{ Header avatarUrlhttps://avatars.githubusercontent.com/u/139426 titleAngular subtitleDeliver web apps with confidence / } eventKey{3} Angular is a web framework that empowers developers to build fast, reliable applications. /Accordion.Panel /Accordion );见 custom-header.md。这里用Stack布局头像 标题 副标题形成类似联系列表的富交互标题区。值得注意的是Stack与Avatar也是 rsuite 的组件可在 src/Stack 与 src/Avatar 中查看其实现示例中通过var(--rs-text-secondary)使用 rsuite 的 CSS 变量控制副标题颜色这类主题变量由 docs/styles/_variables.scss 体系提供。禁用面板disabled通过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 );见 disabled-panel.md。disabled同时参与 ARIA 语义见下节aria-disabled确保禁用状态对屏幕阅读器可感知。可访问性AccessibilityAccordion 遵循 WAI-ARIA 手风琴模式面板展开区域具备完整的 ARIA 属性映射与键盘交互支持。ARIA 属性aria-expanded表示面板当前是展开还是折叠状态aria-controls标识由该面板标题控制的内容区域aria-labelledby标识作为面板标题的元素aria-disabled表示面板是否被禁用。从 Panel.tsx 源码可以看到这些属性的实际生成逻辑const bodyId ${id}-panel; const buttonId ${id}-btn;面板的展开按钮标题通过aria-expanded反映折叠状态通过aria-controls指向内容区 ID内容区通过aria-labelledby关联标题按钮 ID形成完整的可访问性关联链。这与 WAI-ARIA 官方 Accordion Pattern 的推荐实现一致。键盘交互Tab移动焦点到下一个可聚焦的面板标题Enter或Space展开或折叠当前聚焦的面板。官方文档还将 W3C 的 ARIA Practices: Accordion Pattern 列为参考资料建议在自定义面板行为时以该规范为基准。Props 完整参考Accordion继承 PanelGroup 容器属性属性类型(默认值)描述activeKeystring激活项的事件键受控模式下当前展开面板的 eventKey。borderedboolean显示边框。classPrefixstring组件 CSS 类名的前缀默认由主题配置决定PanelGroup 默认为panel-group。defaultActiveKeystring默认激活项的事件键非受控模式下初始展开的面板。onSelect(eventKey: string, event) void激活项变化时的回调。说明AccordionProps OmitPanelGroupProps, accordion即容器上不再需要手动传accordion因为它恒为true。onSelect的eventKey在源码层面实际为string | number。Accordion.Panel即 rsuite Panel 组件属性类型(默认值)描述bodyFillboolean内容区域是否填满容器填充样式。caretAsReactNode自定义展开指示器。classPrefixstring(panel)组件 CSS 类名前缀。defaultExpandedboolean面板默认展开。disabledboolean禁用面板。eventKeystring面板对应的事件键在互斥模式下作为激活标识。expandedboolean面板是否展开受控状态下控制单个面板。headerReactNode面板标题支持任意 JSX。从 AccordionPanel.tsx 可以看到AccordionPanelProps PanelProps即面板的所有能力完全来自Panel组件单个面板的展开状态在 Panel.tsx 中通过useExpanded钩子管理const [expanded, setExpanded, collapsible] useExpanded({ expanded: expandedProp, defaultExpanded, eventKey, ... });面板的点击处理同时触发组件级onSelect与容器级onGroupSelect再本地切换expanded状态从而支持单面板自由折叠 容器互斥两套行为并存。组件关系与源码地图关注点源码/文档位置Accordion 入口与子组件挂载src/Accordion/Accordion.tsx面板即 Panel 组件src/Accordion/AccordionPanel.tsx互斥容器 PanelGroupsrc/PanelGroup/PanelGroup.tsx面板折叠状态与 ARIA 实现src/Panel/Panel.tsx样式定义src/PanelGroup/styles组件测试src/Accordion/test/Accordion.spec.tsxStorybook 示例src/Accordion/stories/Accordion.stories.tsx官方文档中文docs/pages/components/accordion/zh-CN/index.md官方文档英文docs/pages/components/accordion/en-US/index.md总结与实践建议默认模式允许多面板同时展开适合 FAQ、帮助中心等互不干扰的内容列表互斥模式传入activeKey/defaultActiveKey保证任何时刻只有一个面板展开适合设置项分组、步骤式内容受控模式把展开状态提升到业务层适合需要与路由、外部按钮联动的场景个性化通过caretAs换指示器、header换富标题、bordered换视觉风格均可与 rsuite 的Stack、Avatar、主题 CSS 变量无缝组合无障碍方面组件已内置aria-expanded/aria-controls/aria-labelledby/aria-disabled与键盘交互支持接入时无需额外处理即可通过标准可达性检查。从实现上看Accordion 是 rsuite 组件体系中组合优于继承的典型代表一个强制开启互斥模式的 PanelGroup 加上复用的 Panel便构成了完整的手风琴能力。理解这条封装链Accordion → PanelGroup(accordiontrue) → Panel后你也能基于 PanelGroup 快速构建自己的折叠类复合组件。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐shadcn-vue 手风琴Accordion组件完全指南从安装、用法到源码级定制shadcn vue 手风琴Accordion组件完全指南从安装、用法到源码级定制 导读 本文围绕 shadcn vue 仓库中 Accordion手风UI组件前端rsuite Accordion 手风琴组件完全指南用法、受控模式与无障碍实现rsuite Accordion 手风琴组件完全指南用法、受控模式与无障碍实现 Accordion手风琴是 rsuite 中用于在有限空间内展示大量内容的前端UI组件rsuite Accordion 手风琴组件实战指南从默认用法到受控模式与无障碍设计rsuite Accordion 手风琴组件实战指南从默认用法到受控模式与无障碍设计 rsuite 的 Accordion 手风琴组件用于通过点击标题来展前端UI组件上一篇TexturePacker高效集成指南前端游戏精灵动画性能优化实战下一篇2024终极Neo4j图数据库入门指南构建高性能关系数据应用的完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考