HTML 的 <summary> 元素

1. 引言

在 HTML 中，<details> 和 <summary> 是一对非常实用的组合元素。它们允许开发者在不借助任何 JavaScript 的情况下，轻松实现可折叠/展开的内容区域。<summary> 元素作为 <details> 的第一个子元素，充当该折叠区域的可见标题或摘要，用户点击它即可切换内容的显示与隐藏。

本文将系统讲解 <summary> 元素的基本用法、属性、样式定制、无障碍访问以及实际应用场景，帮助你全面掌握这一原生交互组件。

2. 基本概念

2.1 什么是 `<summary>` 元素

<summary> 元素必须作为 <details> 元素的第一个子元素使用，它定义了 <details> 元素的可见摘要标题。当用户点击 <summary> 时，<details> 会在展开与折叠状态之间切换。

2.2 基本语法结构

<details>
  <summary>点击展开查看详情</summary>
  <p>这里是默认隐藏的详细内容。</p>
</details>

在上面的示例中，<summary> 中的文本「点击展开查看详情」始终可见，而 <p> 中的内容默认隐藏，用户点击摘要后才会显示。

3. 核心属性与状态

3.1 open 属性

<details> 元素支持 open 属性。当该属性存在时，内容区域默认展开；否则默认折叠。

<!-- 默认展开 -->
<details open>
  <summary>默认展开的章节</summary>
  <p>这段内容在页面加载时就可见。</p>
</details>

3.2 交互状态检测

开发者可以通过 JavaScript 监听 toggle 事件来感知展开/折叠状态的变化：

const details = document.querySelector('details');

details.addEventListener('toggle', () => {
  if (details.open) {
    console.log('内容已展开');
  } else {
    console.log('内容已折叠');
  }
});

4. 样式定制

4.1 自定义折叠指示器

浏览器默认会在 <summary> 前显示一个三角箭头。你可以通过 CSS 的 list-style 属性或 ::-webkit-details-marker 伪元素来隐藏或替换它。

/* 隐藏默认三角箭头 */
summary {
  list-style: none;
}

summary::-webkit-details-marker {
  display: none;
}

4.2 自定义展开/折叠图标

隐藏默认箭头后，可以结合 ::after 伪元素和 details[open] 属性选择器，实现自定义图标切换：

summary::after {
  content: '▶';
  margin-left: 8px;
  transition: transform 0.2s;
}

details[open] summary::after {
  content: '▼';
}

4.3 完整样式示例

<style>
  details {
    border: 1px solid #ddd;
    border-radius: 6px;
    padding: 12px;
    margin-bottom: 12px;
  }

  summary {
    cursor: pointer;
    font-weight: bold;
    list-style: none;
  }

  summary::-webkit-details-marker {
    display: none;
  }

  summary::before {
    content: '▸';
    display: inline-block;
    margin-right: 8px;
    transition: transform 0.2s;
  }

  details[open] summary::before {
    transform: rotate(90deg);
  }
</style>

<details>
  <summary>产品特性</summary>
  <ul>
    <li>轻量级实现</li>
    <li>无需 JavaScript</li>
    <li>原生无障碍支持</li>
  </ul>
</details>

5. 无障碍访问

<summary> 元素天然具备良好的无障碍支持：

浏览器会自动为 <summary> 分配可点击的按钮角色；
支持键盘操作，用户可通过 Tab 聚焦、Enter 或空格键切换展开状态；
屏幕阅读器能够正确朗读展开/折叠状态。

建议在 <summary> 中使用简洁明确的描述性文本，让用户清楚了解点击后将会看到什么内容。

6. 实际应用场景

6.1 FAQ 手风琴效果

<details>
  <summary>如何重置密码？</summary>
  <p>在登录页面点击「忘记密码」，按照邮件提示完成重置。</p>
</details>

<details>
  <summary>支持哪些支付方式？</summary>
  <p>我们支持支付宝、微信支付和银联卡。</p>
</details>

6.2 代码示例折叠

<details>
  <summary>查看完整代码</summary>

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet('World'));

</details>


### 6.3 移动端菜单

在移动端页面中，可以利用 [`<details>`](https://xplanc.org/primers/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.details.md) 实现轻量的下拉菜单，无需引入额外的 JS 库。

## 7. 浏览器兼容性

[`<details>`](https://xplanc.org/primers/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.details.md) 和 [`<summary>`](https://xplanc.org/primers/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.summary.md) 元素在现代浏览器中均得到良好支持，包括 Chrome、Firefox、Safari、Edge 以及移动端主流浏览器。对于需要兼容老旧浏览器的场景，可以引入相应的 polyfill 或使用 JavaScript 方案替代。

## 8. 总结

[`<summary>`](https://xplanc.org/primers/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.summary.md) 元素是 HTML 原生交互组件中非常实用的一员。它与 [`<details>`](https://xplanc.org/primers/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.details.md) 配合，能够以极简的代码实现折叠面板、FAQ、代码展示等常见交互，同时具备良好的无障碍支持和浏览器兼容性。掌握它，可以让你的页面在不依赖任何框架的情况下更加灵活和易用。