<summary>: 披露摘要元素

Baseline 广泛可用 *

此特性已相当成熟,可在许多设备和浏览器版本上使用。自 ⁨2020 年 1 月⁩ 起,所有主流浏览器均已支持。

* 此特性的某些部分可能存在不同级别的支持。

<summary> HTML 元素用于指定 <details> 元素的披露框的摘要、标题或图例。点击 <summary> 元素会切换其父级 <details> 元素的打开和关闭状态。

试一试

<details>
  <summary>
    I have keys but no doors. I have space but no room. You can enter but can’t
    leave. What am I?
  </summary>
  A keyboard.
</details>
details {
  border: 1px solid #aaaaaa;
  border-radius: 4px;
  padding: 0.5em 0.5em 0;
}

summary {
  font-weight: bold;
  margin: -0.5em -0.5em 0;
  padding: 0.5em;
}

details[open] {
  padding: 0.5em;
}

details[open] summary {
  border-bottom: 1px solid #aaaaaa;
  margin-bottom: 0.5em;
}

属性

此元素仅包含全局属性

用法说明

<summary> 元素的内容可以是任何标题内容、纯文本或可以在段落中使用的 HTML。

<summary> 元素只能作为 <details> 元素的第一个子元素使用。当用户点击摘要时,父级 <details> 元素会切换打开或关闭状态,然后一个 toggle 事件会发送到 <details> 元素,你可以用它来了解状态何时发生变化。

<details> 的内容为 <summary> 提供了可访问描述

默认标签文本

如果 <details> 元素的第一个子元素不是 <summary> 元素,用户代理将使用默认字符串(通常是“Details”)作为披露框的标签。

默认样式

根据 HTML 规范,<summary> 元素的默认样式包括 display: list-item。这使得可以更改或移除默认显示为标签旁边的披露小部件的图标(通常是三角形)。

你也可以将样式更改为 display: block 以移除披露三角形。

有关详细信息,请参阅浏览器兼容性部分,因为并非所有浏览器都完全支持此元素的全部功能。

对于基于 WebKit 的浏览器(如 Safari),可以通过非标准 CSS 伪元素 ::-webkit-details-marker 控制图标显示。要移除披露三角形,请使用 summary::-webkit-details-marker { display: none }

示例

以下是一些显示 <summary> 用法的示例。你可以在 <details> 元素的文档中找到更多示例。

基本示例

在一个 <details> 元素中使用 <summary> 的基本示例

html
<details open>
  <summary>Overview</summary>
  <ol>
    <li>Cash on hand: $500.00</li>
    <li>Current invoice: $75.30</li>
    <li>Due date: 5/6/19</li>
  </ol>
</details>

结果

作为标题的摘要

你可以在 <summary> 中使用标题元素,如下所示

html
<details open>
  <summary><h4>Overview</h4></summary>
  <ol>
    <li>Cash on hand: $500.00</li>
    <li>Current invoice: $75.30</li>
    <li>Due date: 5/6/19</li>
  </ol>
</details>

结果

目前存在一些可以通过 CSS 解决的间距问题。

警告: 分配给 <summary> 元素的角色因浏览器而异。有些浏览器仍然为其分配默认的button 角色,这会移除其所有子元素的角色。这种不一致性可能会给屏幕阅读器等辅助技术用户带来问题(上一个示例中的 <h4> 将被移除其角色,并且不会被这些用户视为标题)。你应该在多个平台上测试你的 <summary> 实现,以确保一致的可访问性支持。

摘要中的 HTML

此示例为 <summary> 元素添加了一些语义,以指示标签的重要性

html
<details open>
  <summary><strong>Overview</strong></summary>
  <ol>
    <li>Cash on hand: $500.00</li>
    <li>Current invoice: $75.30</li>
    <li>Due date: 5/6/19</li>
  </ol>
</details>

结果

更改摘要的图标

<summary> 元素的标记(即披露三角形)可以使用 CSS 进行自定义。可以使用 ::marker 伪元素定位标记,它接受 list-style 简写属性及其长手组件属性,例如 list-style-type。这使得可以将三角形更改为图像(通常使用 list-style-image)或字符串(包括表情符号)。在此示例中,我们替换了一个披露小部件的内容,并通过设置 list-style: none 来移除另一个小部件的图标,然后通过生成的内容添加自定义披露图标。

CSS

在第一个披露小部件中,我们设置 ::marker 的样式,根据 <details> 元素的 [open] 属性更改content。对于第二个小部件,我们使用 list-style 属性移除标记,然后使用 ::after 伪元素添加带有样式的生成内容。我们还包括 ::-webkit-details-marker 的样式以定位 Safari。浏览器特定的伪元素的选择器包含在 :is() 伪类中,这样它就不会使选择器列表失效。

css
details {
  font-size: 1rem;
  font-family: "Open Sans", "Calibri", sans-serif;
  border: solid;
  padding: 2px 6px;
  margin-bottom: 1em;
}

details:first-of-type summary::marker,
:is(::-webkit-details-marker) {
  content: "+ ";
  font-family: monospace;
  color: red;
  font-weight: bold;
}

details[open]:first-of-type summary::marker {
  content: "− ";
}

details:last-of-type summary {
  list-style: none;
  &::after {
    content: "+";
    color: white;
    background-color: darkgreen;
    border-radius: 1em;
    font-weight: bold;
    padding: 0 5px;
    margin-inline-start: 5px;
  }
  [open] &::after {
    content: "−";
  }
}
details:last-of-type summary::-webkit-details-marker {
  display: none;
}

CSS 包括 [open] 属性选择器,仅当 open 属性存在时(当 <details> 打开时)才匹配。:first-of-type:last-of-type 伪类定位相同类型的第一个和同级元素。我们将带前缀的 -webkit- 伪元素包含在 :is() 伪类中,因为它接受宽容选择器列表,所以如果带前缀的伪元素在浏览器中无效,整个选择器块也不会失效。我们还使用了 CSS 嵌套。请参阅 CSS 选择器模块。

HTML

html
<h1>Quotes from Helen Keller</h1>

<details>
  <summary>On women's rights</summary>
  <p>
    <q>We have prayed, we have coaxed, we have begged, for the vote, with the
      hope that men, out of chivalry, would bestow equal rights upon women and
      take them into partnership in the affairs of the state. We hoped that
      their common sense would triumph over prejudices and stupidity. We thought
      their boasted sense of justice would overcome the errors that so often
      fetter the human spirit; but we have always gone away empty-handed. We
      shall beg no more.</q>
  </p>
</details>

<details>
  <summary>On optimism</summary>
  <p>
    <q>Optimism is the faith that leads to achievement; nothing can be done
      without hope.</q>
  </p>
</details>

结果

技术摘要

内容类别 none
允许内容 短语内容,可选择与标题内容混合
标签省略 无;开始标签和结束标签都是强制性的。
允许父级 <details> 元素。
隐式 ARIA 角色 没有对应的角色
允许的 ARIA 角色 不允许 role
DOM 接口 HTMLElement

规范

规范
HTML
# the-summary-element

浏览器兼容性

另见