hidden

¥Description

hidden 属性用于指示元素的内容不应呈现给用户。该属性可以采用以下任一值：

¥The hidden attribute is used to indicate that the content of an element should not be presented to the user. This attribute can take any one of the following values:

• 一个空字符串
• 关键字 hidden
• 关键字 until-found

有两种与 hidden 属性关联的状态：隐藏状态和隐藏直到找到状态。

¥There are two states associated with the hidden attribute: the hidden state and the hidden until found state.

• 空字符串或关键字 hidden 将元素设置为隐藏状态。此外，无效值会将元素设置为隐藏状态。
• 关键字 until-found 将元素设置为隐藏直到找到状态。

因此，以下所有操作将元素设置为 hidden 状态：

¥Thus, all the following set the element to the hidden state:

<span hidden>I'm hidden</span>
<span hidden="">I'm also hidden</span>
<span hidden="hidden">I'm hidden too!</span>

以下将元素设置为 隐藏直到被发现 状态：

¥The following sets the element to the hidden until found state:

<span hidden="until-found">I'm hidden until found</span>

hidden 属性不得用于仅隐藏一个演示文稿中的内容。如果某些内容被标记为隐藏，则该内容将从所有演示文稿中隐藏，包括屏幕阅读器等。

¥The hidden attribute must not be used to hide content just from one presentation. If something is marked hidden, it is hidden from all presentations, including, for instance, screen readers.

隐藏元素不应与非隐藏元素链接。例如，使用 href 属性链接到标有 hidden 属性的部分是不正确的。如果内容不适用或不相关，则没有理由链接到它。

¥Hidden elements shouldn't be linked from non-hidden elements. For example, it would be incorrect to use the href attribute to link to a section marked with the hidden attribute. If the content is not applicable or relevant, then there is no reason to link to it.

但是，使用 ARIA aria-describedby 属性来引用本身隐藏的描述就可以了。虽然隐藏描述意味着它们本身没有用，但它们可以以这样的方式编写，即它们在从它们描述的元素引用的特定上下文中有用。

¥It would be fine, however, to use the ARIA aria-describedby attribute to refer to descriptions that are themselves hidden. While hiding the descriptions implies that they are not useful on their own, they could be written in such a way that they are useful in the specific context of being referenced from the element that they describe.

类似地，具有 hidden 属性的 canvas 元素可以被脚本图形引擎用作离屏缓冲区，并且表单控件可以使用其 form 属性引用隐藏的表单元素。

¥Similarly, a canvas element with the hidden attribute could be used by a scripted graphics engine as an off-screen buffer, and a form control could refer to a hidden form element using its form attribute.

作为隐藏元素的后代的元素仍然处于活动状态，这意味着脚本元素仍然可以执行并且表单元素仍然可以提交。

¥Elements that are descendants of a hidden element are still active, which means that script elements can still execute and form elements can still submit.

¥The hidden state

隐藏状态表示该元素当前与页面不相关，或者它正用于声明供页面其他部分重用的内容，并且不应直接呈现给用户。浏览器不会渲染处于隐藏状态的元素。

¥The hidden state indicates that the element is not currently relevant to the page, or that it is being used to declare content for reuse by other parts of the page and should not be directly presented to the user. The browser will not render elements that are in the hidden state.

Web 浏览器可以使用 display: none 实现隐藏状态，在这种情况下该元素将不参与页面布局。这也意味着更改处于隐藏状态的元素上的 CSS display 属性值将覆盖该状态。例如，尽管存在 hidden 属性，样式为 display: block 的元素仍将显示。

¥Web browsers may implement the hidden state using display: none, in which case the element will not participate in page layout. This also means that changing the value of the CSS display property on an element in the hidden state will override the state. For instance, elements styled display: block will be displayed despite the hidden attribute's presence.

¥The hidden until found state

在“隐藏直至找到”状态下，元素处于隐藏状态，但浏览器的 "在页面中查找" 功能或片段导航可以访问其内容。当这些功能导致滚动到隐藏直到找到子树中的元素时，浏览器将：

¥In the hidden until found state, the element is hidden but its content will be accessible to the browser's "find in page" feature or to fragment navigation. When these features cause a scroll to an element in a hidden until found subtree, the browser will:

• 在隐藏元素上触发 beforematch 事件
• 从元素中删除 hidden 属性
• 滚动到元素

这使得开发者能够折叠内容的一部分，但使其可通过片段导航进行搜索和访问。

¥This enables a developer to collapse a section of content, but make it searchable and accessible via fragment navigation.

请注意，浏览器通常使用 content-visibility: hidden 实现隐藏直到找到。这意味着与隐藏状态中的元素不同，隐藏直到找到状态中的元素将生成框，这意味着：

¥Note that browsers typically implement hidden until found using content-visibility: hidden. This means that unlike elements in the hidden state, elements in the hidden until found state will have generated boxes, meaning that:

• 该元素将参与页面布局
• 将渲染元素的边距、边框、填充和背景。

此外，该元素需要受到 布局遏制 的影响才能显示出来。这意味着，如果处于隐藏直到找到状态的元素的 display 值为 none、contents 或 inline，则在页面或片段导航中查找时不会显示该元素。

¥Also, the element needs to be affected by layout containment in order to be revealed. This means that if the element in the hidden until found state has a display value of none, contents, or inline, then the element will not be revealed by find in page or fragment navigation.

¥Examples

¥Using until-found

在这个例子中我们有：

¥In this example we have:

• 三个 <div> 元素。第一个和第三个没有隐藏，而第二个有 hidden="until-found" 和 id="until-found-box" 属性。
• 目标是 "until-found-box" 片段的链接。

隐藏直到找到的元素具有红色虚线边框和灰色背景。

¥The hidden until found element has a dotted red border and a gray background.

我们还有一些 JavaScript 监听在隐藏的直到找到的元素上触发的 beforematch 事件。事件处理程序更改框的文本内容。

¥We also have some JavaScript that listens for the beforematch event firing on the hidden until found element. The event handler changes the text content of the box.

HTML

<a href="#until-found-box">Go to hidden content</a>

<div>I'm not hidden</div>
<div id="until-found-box" hidden="until-found">Hidden until found</div>
<div>I'm not hidden</div>

<button id="reset">Reset</button>

CSS

div {
  height: 40px;
  width: 300px;
  border: 5px dashed black;
  margin: 1rem 0;
  padding: 1rem;
  font-size: 2rem;
}

div#until-found-box {
  color: red;
  border: 5px dotted red;
  background-color: lightgray;
}

#until-found-box {
  scroll-margin-top: 200px;
}

JavaScript

const untilFound = document.querySelector("#until-found-box");
untilFound.addEventListener(
  "beforematch",
  () => (untilFound.textContent = "I've been revealed!"),
);

document.querySelector("#reset").addEventListener("click", () => {
  document.location.hash = "";
  document.location.reload();
});

结果

¥Result

请注意，虽然元素的内容被隐藏，但元素仍然有一个生成的框，占据布局中的空间并呈现背景和边框。

¥Note that although the content of the element is hidden, the element still has a generated box, occupying space in the layout and with background and borders rendered.

单击 "转到隐藏内容" 按钮导航到隐藏的元素，直至找到。触发 beforematch 事件，更新文本内容，并显示元素内容。

¥Clicking the "Go to hidden content" button navigates to the hidden until found element. The beforematch event fires, the text content is updated, and the element content is displayed.

要再次运行该示例，请单击 "重置"。

¥To run the example again, click "Reset".

¥See also

• HTMLElement.hidden
• 全部 全局属性
• aria-hidden 属性
• beforematch 事件