手风琴：渐进式披露规则与示例

手风琴是一组带标签的披露控件，让读者可以在原位展开或折叠辅助内容。用于可选的参考细节，而非页面的主要答案。

这一组渲染示例展示了渐进式披露：标签保持可扫描性，一个面板保持打开，无论用户是否交互，两个答案都存在于页面的 HTML 中。

为什么这个元素很重要

渐进式披露意味着在当前决策所需的范围内显示信息，同时将更深层或不太常见的细节保留为按需可用。当页面服务于不同知识水平的读者时，这种方式很有帮助。回头客可以跳过实现说明；首次使用的用户则可以展开查看。这种控件降低了视觉密度，而无需删除内容或强迫每位读者阅读每个例外情况。

同样的便利也可能变成隐藏。搜索直接答案的读者到达页面后，看到八个关闭的标签，必须猜测哪个面板包含答案并执行额外操作。在移动设备上，反复打开和关闭还会使内容在视口中移动。因此，手风琴只有在大多数读者无需打开每个面板即可完成主要任务时，才值得使用。

机器可提取性增加了一项更严格的测试。可提取性是指搜索引擎、AI 问答系统、解析器和辅助工具接收文本并保持其与标签关联的能力。每个答案必须存在于初始服务端渲染的文档对象模型（DOM）——即浏览器对页面的结构化表示——中。CSS 可以在视觉上折叠已存在的面板；JavaScript 不得仅在点击后才获取或生成答案。爬虫可能永远不会点击、执行客户端代码或等待二次请求。

在使用此模式之前，请先遵循元素编写规则 。如果内容的用途与更具体的类型化元素匹配，则该元素优先。手风琴可以包含允许的辅助内容，但不得仅仅为了缩短页面而重命名或扁平化警告、对比、定义或步骤序列。

何时使用

当以下四个条件全部成立时使用手风琴：

1. 读者可以从标签预判面板的内容。
2. 内容对部分读者有用，而非所有人必需。
3. 所有面板内容都包含在初始 HTML 中，并且无需指针设备即可访问。
4. 折叠能显著改善预期视口上的扫描效果。

好的候选包括可选的兼容性详情、不常见的错误分支、辅助性定义、次要政策条款、配送例外，以及分组的参考答案。手风琴也适用于大规模的常见问题集合，前提是每个问题保持可见且每个答案独立完整。

近似的错误用例揭示了最常见的误用：

• 只有两个简短章节的短页面： 可见的标题和段落比两个控件扫描更快。
• 看起来更短的长文章： 折叠十个大型章节减少了感知高度，但增加了交互并隐藏了页面的范畴。
• 主要产品信息： 价格、可用性、材料限制、取消条款和核心规格影响决策，不得依赖展开。
• 顺序流程： 步骤需要顺序和上下文。关闭的面板可能导致读者跳过前置条件或按错误顺序执行步骤。
• 对比： 读者需要同时查看相同标准下的内容。分离的面板迫使读者依赖记忆进行比较。
• 安全警告或法律限定： 错过它的后果高于隐藏它的视觉收益。
• 导航替代品： 手风琴不是目录。它展示同一位置的内容，而非跳转到稳定的页面章节。

不确定时，将内容以可见方式发布。额外的滚动通常可以补救；但被遗漏的答案、未披露的约束或不可用的 DOM 节点则不能。

放置位置

将手风琴放置在页面已提供直接答案和足够可见解释（使读者理解该组内容）之后。用 H2 标题和一句范围说明来引入它。然后该组作为该章节内的补充参考层。

具体位置规则：

• 将其放在其所限定的可见解释之后，切勿放在声明与支持该声明的证据之间。
• 保持在父章节内，其主题标签应能标注所有项目。如果标签缺少对应的标题才有意义，则说明该组放错了位置。
• 将产品详情手风琴放在核心价值、价格背景和购买条件之后；将故障排除分支放在共享诊断和最安全的首项检查之后。
• 将结尾的常见问题手风琴放在主要结论之后、最终下一步行动之前，前提是它回答的是剩余问题而非重复问题。
• 当读者可能链接到该组时，为其提供稳定的章节锚点。单个面板链接是可选的，但如果提供，则必须打开并聚焦到正确的项目。

手风琴不得直接紧邻标签页、第二个手风琴或密集的对比表。相邻的交互模式迫使读者在选择内容之前先选择机制。它不得中断有序的步骤、将警告与后果分开，或置于产品价格与该价格的条件之间。不得在组内或每个面板后立即放置促销横幅；促销会干扰参考任务，使展开操作感觉像销售陷阱。

结构

带标签的结构包含七个部分：

1. 组标题： 在周围文档层级中命名共同主题。
2. 项目标签： 预测具体内容，避免使用"了解更多"等模糊标签。
3. 披露控件： 原生 summary 或 button，接收键盘焦点并切换一个面板。
4. 状态指示器： 视觉上传达打开或关闭状态，同时通过原生语义或 aria-expanded 暴露编程状态。
5. 面板： 包含答案或参考细节，并保留在初始 DOM 中。
6. 控件关系： 原生 <details>/<summary> 语义或 aria-controls 加上匹配的 ID，将每个控件与恰好一个面板关联。
7. 项目边界： 间距、边框和 DOM 分组确保一个标签不会显得在控制相邻的答案。

可见的 V 形图标是装饰性的。将其从辅助技术中隐藏，因为展开状态已经提供了含义。仅靠旋转无法传达状态；控件语义必须完成这项任务。

设计示例

每个变体使用相同的字段和 DOM 存在规则。根据阅读任务选择变体，而非根据装饰。

标准单开组

打开一个项目会关闭之前打开的项目。当面板是替代选项，且读者通常一次只需要一个时使用，例如互斥的故障排除症状。

多开参考组

读者可以保持多个面板打开。当读者可能需要比较或结合补充详情时使用，例如支持的文件类型和账户权限。如果同时比较是主要任务，请改用可见表格。

默认打开导向

在初始加载时打开第一个或最常见的项目，以展示内容模式并提供有用的导向。切勿仅为了填充空间而打开多个项目。

紧凑常见问题变体

使用问题标签和简洁的独立答案。交互本身并不能直接证明结构化数据的合理性；schema 取决于内容类型和精确的可见记录。

长内容压力状态

包含超过两个短段落的面板提示该内容可能值得一个可见章节。压力变体用于测试换行、链接、列表、焦点和响应式布局，而非作为正常的编辑目标。

参数

契约将组行为与项目内容分离，以便每个平台都能保留相同的标签、状态和关系。

第一个父级标题映射到 heading。每个嵌套项目的第一个标题映射到 label，之后的内容映射到该项目的 content。这是一种明确的嵌套项目映射，与基础优先级和正文规则一致。open=true 仅设置初始呈现；不改变内容重要性。当 linkable=true 时，导航到项目片段必须将其展开、可预测地移动焦点，并使标题在任何固定页眉下方保持可见。

语法与代码示例

三种表示法均代表一个规范组。它们可能渲染不同的包装类，但必须保留初始 HTML 中的内容、源顺序、无障碍名称和状态。

可移植 Markdown 指令

:::accordion{mode=multiple linkable=true}
## 导出详情

::item{id="included-fields" open=true}
### 包含哪些字段？

导出包含您账户和报告范围内当前可用的字段。
::

::item{id="filter-behavior"}
### 筛选器会影响导出吗？

是的。创建文件前请确认活动的日期范围、市场和状态筛选器。
:::
:::

Hugo shortcode

{{< accordion heading="导出详情" mode="multiple" linkable="true" >}}
{{< accordion-item id="included-fields" label="包含哪些字段？" open="true" >}}
导出包含您账户和报告范围内当前可用的字段。
{{< /accordion-item >}}
{{< accordion-item id="filter-behavior" label="筛选器会影响导出吗？" >}}
是的。创建文件前请确认活动的日期范围、市场和状态筛选器。
{{< /accordion-item >}}
{{< /accordion >}}

这是 Hugo 适配器规范。仅通过向任意标题添加样式类无法满足规范要求；需要一个能生成原生披露 HTML 或等效按钮-面板关系的渲染器。

WordPress 块

<!-- wp:amicited/accordion {"heading":"导出详情","mode":"multiple","linkable":true} -->
<!-- wp:amicited/accordion-item {"id":"included-fields","label":"包含哪些字段？","open":true} -->
<p>导出包含您账户和报告范围内当前可用的字段。</p>
<!-- /wp:amicited/accordion-item -->
<!-- wp:amicited/accordion-item {"id":"filter-behavior","label":"筛选器会影响导出吗？"} -->
<p>是的。创建文件前请确认活动的日期范围、市场和状态筛选器。</p>
<!-- /wp:amicited/accordion-item -->
<!-- /wp:amicited/accordion -->

已注册的 WordPress 块存储规范字段，而非依赖一组不相关的 Details 块的视觉组合。其服务端渲染必须在交互前输出每个答案。

示例

良好示例

账户删除详情出现在对删除操作的可视说明以及操作不可逆的可视警告之后。其三个标签分别是"计划中的导出会怎样？"、“请求的存档可保留多长时间？“和"其他管理员可以取消该请求吗？"。每个面板包含一个可选分支，所有答案均在 HTML 中，键盘焦点可见。

这个示例有效的理由是：主要后果和必要操作保持可见。手风琴包含适用于不同读者的次要问题，每个标签让读者能够预判打开它是否值得。

不良示例

选择您的套餐包含标签为"入门版”、“团队版"和"企业版"的关闭面板。价格、使用限制、合同期限、取消条件和可用性都在面板内部。一次只能打开一个套餐。

这个示例失败的原因是：购买标准需要并排对比可见性。读者必须反复打开面板并记住信息，而非交互式提取器可能错过客户端加载的价格。应将其替换为可见的价格或规格表，并为可选的详情（如发票格式或不常见的资格规则）保留披露功能。

Schema 标记与无障碍性

手风琴没有专用的 Schema.org 类型。交互本身不产生任何结构化数据。如果其记录是真实的问题和答案，FAQ 内容契约可提供 FAQPage；如果该组包含产品详情、政策或故障排除说明，则仅使用页面和内容所证明合理的 schema。可见文本与任何结构化表示必须匹配。

对于简单的披露，优先使用原生 <details> 和 <summary>，因为浏览器提供键盘操作和状态语义。当设计或单开行为需要自定义实现时，每个控件必须是一个 button，暴露 aria-expanded="true" 或 "false"，通过 aria-controls 引用其面板，并拥有面板可引用 aria-labelledby 的唯一 ID。不要在有点击处理器的 div 上放置控件。

Enter 或 Space 必须操作聚焦的控件。Tab 在打开面板内的控件和交互内容之间移动；焦点不得进入关闭的内容。打开或关闭面板通常将焦点保留在其控件上。标题之间的方向键导航是可选的，但如果实现，不得替代正常的 Tab 行为。

将所有标签保留在无障碍树中，所有答案保留在源 HTML 中。视觉上关闭的面板可使用原生披露行为或支持的隐藏状态，但其内容在展开时必须可用，无需第二次获取。折叠状态不得通过独立的桌面和移动副本导致重复内容。在 200% 缩放、长标签、仅使用键盘、减少动画和屏幕阅读器环境下进行测试。仅在运动可被抑制且内容不会延迟时，才对高度或图标旋转进行动画处理。

编写规则

标签承担交互的成本，因此必须做出精确的承诺。写 3–14 个词，通常不超过 120 个字符。对常见问题内容使用直接问句，对参考内容使用描述性名词短语。避免"更多”、“详情”、“阅读此处"以及仅通过数字区分的标签。

每组使用 3–8 个项目。每个面板通常应包含 20–120 个词，最多不超过 250 个。两个短面板作为开放散文更清晰；九个或更多需要分组、可见导航或编辑合并。保持标签在语法上平行，并按读者任务、预期频率或真实的类别顺序排列项目——除非查找确实是按字母顺序，否则不要按字母顺序排列。

面板语气应直接、独立且基于事实。在第一句话中陈述答案，因为读者已经付出了交互成本。在面板内或组之前的可见文本中定义任何必要术语。不要以"有几件事需要考虑"之类的空话开头。

切勿将以下内容仅放在手风琴中：

• 页面的直接答案或独特的价值主张；
• 安全警告、禁忌症、法律义务或不可逆的后果；
• 价格、可用性、实质性产品限制或必需的购买条件；
• 有序的步骤、前置条件或完成检查；
• 支持周围声明所必需的证据；
• 主要的对比或决策矩阵；
• 表单、结账控件、同意选项或页面的主要行动号召；
• 另一个手风琴、标签页或轮播。

紧凑列表、小表格、内联链接或辅助图片在完全属于某个可选项目且在移动设备上可用时是可以接受的。如果某个面板需要自己的目录或超过一个标题级别，请将其提升为可见章节或独立页面。

使用此元素的文章类型

postTypes 前言数组是此使用矩阵的来源。列入表示该元素在所述条件下可用，而非该类型每个页面都必须使用。

QA 检查清单

• 手风琴前出现可见的直接答案。
• 每个项目都是可选的参考内容，而非所有读者都需要的信息。
• 该组有 3–8 个项目，带有精确、平行的标签。
• 每个面板的完整文本均存在于初始服务端渲染的 HTML 中。
• 没有答案依赖于点击触发的网络请求或仅客户端的插入。
• 原生 details/summary 或真正的按钮提供正确的键盘行为。
• 自定义控件暴露 aria-expanded、aria-controls、唯一 ID 和关联的面板标签。
• 焦点可见，切换后可预测，且无法进入关闭的面板。
• 长标签在不裁剪、不重叠或不隐藏状态指示器的情况下换行。
• 布局在 200% 缩放和窄视口下无水平滚动。
• 动画尊重减少运动偏好，且绝不延迟内容访问。
• 单个片段链接（如果支持）打开并显示正确的面板。
• 结构化数据基于内容含义，而非手风琴的外观。
• 如果输出 FAQPage 记录，则与可见的问题和答案文本完全匹配。
• 无嵌套手风琴、相邻标签页集合、重复的移动副本或主要 CTA。
• 即使每个面板都关闭，页面仍能传达其主要答案。

常见问题

前言存储了此页面的规范常见问题记录。它们的答案强化了实现边界：内容可以在视觉上折叠，但仍保持存在、可访问，且次于可见答案。