用途:本技能面向设计、审计或重构手风琴(accordion)、可折叠区块、披露控件、FAQ 区块及展开/收起模式的场景。核心原则是手风琴属于披露控件——由标题切换内容可见性,应节制使用,不要用它隐藏用户真正需要看到的内容。
何时使用:适合 FAQ、可选设置、按主题组织的长参考资料、每行需要丰富下钻细节的密集列表。不适合主要必看内容、表单字段、短内容及关键错误或确认信息。
优先使用原生 details/summary,可免费获得键盘操作、屏幕阅读器状态、切换与动画基础能力。只有原生方案不适用(如复杂多区块控制)时才使用自定义 ARIA:按钮包裹标题文本,标题元素包裹按钮以保留文档大纲,使用 aria-expanded、aria-controls、role="region" 与 aria-labelledby,并用 hidden 隐藏面板。
模式:默认多展开,仅在内容单节很长或互斥时使用单展开。图标以 chevron 为约定,展开时旋转 90°,过渡 150–200ms ease-out,图标默认右对齐。触发行高 48–56px,面板与触发行水平内边距对齐、垂直 16–24px,整行可点击,移动端点击目标不小于 44px。
动效:可用 details[open] 配合 opacity/translateY 动画;高度动画可用 grid-template-rows: 0fr→1fr 或 max-height、JS 测量,时长 200–300ms,展开 ease-out、收起 ease-in,并遵守 prefers-reduced-motion。
FAQ 与深链:重要问题置前、多展开、10 项以上提供全部展开/收起按钮,可用 schema.org FAQPage。文档或 FAQ 可用 /faq#returns 形式的哈希深链,加载时匹配 id 自动展开并滚动。
限制与反模式:不要用手风琴隐藏表单字段、关键状态或错误;自定义触发器必须带 aria-expanded;点击目标不能只有图标;避免无 focus-visible、无谓单展开、超过 400ms 的重动画、嵌套手风琴。审计清单与决策树见原文。资料未提供收费、平台或安装信息。