summary标签本质是details的唯一交互锚点,必须为首个直接子元素;支持纯文本、内联元素(如<svg>)及emoji,但禁用块级元素;失效主因包括结构错位、CSS阻断(如pointer-events:none)或JS覆盖默认行为。

summary 标签里能写什么内容? 本质是一个可点击的标题容器,它支持任意内联内容:纯文本、加粗文字、<code> 片段、甚至小图标(用 <svg> 或 emoji)。但要注意它**不能包含块级元素**(比如 <p>、<div>、<ul>),否则 HTML 解析会出错或被浏览器自动修正。
- 写法正确:
<summary>API 响应格式 <code>200 OK</code></summary>
- 写法错误:
<summary><p>错误示例</p></summary>(<p> 会被挤到 <summary> 外)
- 实用技巧:用
<strong> 强调关键词,比纯 CSS 加粗更语义清晰;emoji 如 ▶️ / ? 可替代默认 marker,但需搭配 list-style: none
为什么 summary 文案点不动?常见渲染失效原因
不是所有“看起来像 summary”的元素都真能触发折叠。典型失效场景:
-
summary 没有作为 details 的第一个直接子元素:中间插了空格、注释或 <span> 都会导致浏览器忽略其交互逻辑
- 父级
details 被设了 display: contents 或 pointer-events: none,阻断了事件冒泡
- CSS 中误写了
summary { pointer-events: none; }(调试时容易手抖加上)
- 在 Shadow DOM 内部使用时,未正确透传事件(需额外处理)
最简验证法:删掉所有样式,只留裸标签结构,看是否恢复可点击。
如何让 summary 标题响应键盘操作?
原生 summary 默认支持空格键和回车键切换展开状态,但前提是它没被覆盖默认行为:
- 不要给
summary 绑定 onclick 并调用 event.preventDefault(),否则键盘操作失效
- 避免用
tabindex="-1" 移除其可聚焦性;如需控制 tab 顺序,用 tabindex="0" 保持可访问性
- 若自定义了焦点样式(如
summary:focus),记得同时适配 summary:focus-visible,避免 Chrome/Firefox 表现不一致
这点容易被忽略:无障碍测试工具(如 axe)会直接报错“summary 缺少键盘可操作性”,而视觉上完全看不出问题。
移动端点击区域太小,怎么安全放大?
summary 默认只在文字区域响应点击,手指点不准就失败。安全做法是:
- 用
padding 扩展点击热区,而非 width/min-width(后者可能破坏流式布局)
- 设置
summary { display: block; } 确保 padding 生效(部分老版本 Safari 需要)
- 避免对
summary::before 或 ::after 做大尺寸伪元素并设 pointer-events: auto,这在 iOS Safari 上常失效
- 如果必须撑满父容器宽度,直接给
summary 设 width: 100%,但要确认父 details 没有 overflow: hidden 截断
真正麻烦的是:某些安卓 WebView(尤其旧版 UC 浏览器)对 summary 的 touch 事件支持极弱,此时只能降级为 JS 控制的模拟面板——但那就不是本文讨论范围了。
<code> 片段、甚至小图标(用 <svg> 或 emoji)。但要注意它**不能包含块级元素**(比如 <p>、<div>、<ul>),否则 HTML 解析会出错或被浏览器自动修正。
- 写法正确:
<summary>API 响应格式 <code>200 OK</code></summary> - 写法错误:
<summary><p>错误示例</p></summary>(<p>会被挤到<summary>外) - 实用技巧:用
<strong>强调关键词,比纯 CSS 加粗更语义清晰;emoji 如 ▶️ / ? 可替代默认 marker,但需搭配list-style: none
为什么 summary 文案点不动?常见渲染失效原因
不是所有“看起来像 summary”的元素都真能触发折叠。典型失效场景:
-
summary没有作为details的第一个直接子元素:中间插了空格、注释或<span>都会导致浏览器忽略其交互逻辑 - 父级
details被设了display: contents或pointer-events: none,阻断了事件冒泡 - CSS 中误写了
summary { pointer-events: none; }(调试时容易手抖加上) - 在 Shadow DOM 内部使用时,未正确透传事件(需额外处理)
最简验证法:删掉所有样式,只留裸标签结构,看是否恢复可点击。
如何让 summary 标题响应键盘操作?
原生 summary 默认支持空格键和回车键切换展开状态,但前提是它没被覆盖默认行为:
- 不要给
summary绑定onclick并调用event.preventDefault(),否则键盘操作失效 - 避免用
tabindex="-1"移除其可聚焦性;如需控制 tab 顺序,用tabindex="0"保持可访问性 - 若自定义了焦点样式(如
summary:focus),记得同时适配summary:focus-visible,避免 Chrome/Firefox 表现不一致
这点容易被忽略:无障碍测试工具(如 axe)会直接报错“summary 缺少键盘可操作性”,而视觉上完全看不出问题。
移动端点击区域太小,怎么安全放大?
summary 默认只在文字区域响应点击,手指点不准就失败。安全做法是:
- 用
padding扩展点击热区,而非width/min-width(后者可能破坏流式布局) - 设置
summary { display: block; }确保 padding 生效(部分老版本 Safari 需要) - 避免对
summary::before或::after做大尺寸伪元素并设pointer-events: auto,这在 iOS Safari 上常失效 - 如果必须撑满父容器宽度,直接给
summary设width: 100%,但要确认父details没有overflow: hidden截断
真正麻烦的是:某些安卓 WebView(尤其旧版 UC 浏览器)对 summary 的 touch 事件支持极弱,此时只能降级为 JS 控制的模拟面板——但那就不是本文讨论范围了。

















