HTML `＜details＞` 元素实战：用纯标签实现按需展开的附加详情

文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载details是 HTML 原生的手风琴标签无需任何 JavaScript 即可让用户主动选择展开页面中的附加信息。本文以本仓库 html/disclose-additional-details.md 记录的技巧为核心讲解其结构规则、默认/展开两种状态下的表现、无 JS 展开与open属性强制展开的差异并结合仓库中的 React 可受控实现给出可直接运行的完整示例。核心结构details必须嵌套summarydetails允许你在页面中放置一段默认折叠、用户点击后展开的内容。它的使用规则非常简单但有两条必须遵守的硬性要求details内部必须嵌套一个summary标签summary之外、details之内的其他任何内容都会作为展开后才显示的详情部分。这两者的职责划分如下summary折叠状态下唯一可见的部分相当于整块的标题或提示语点击它即可切换展开/折叠details内summary以外的内容展开状态下才披露的正文可以包含任意 HTML 元素——段落、列表、表格、代码块甚至嵌套的另一个details。details summary点击这里展开/summary p这里是展开后才显示的详情内容。/p /details浏览器默认会在summary左侧渲染一个三角指示符细节展开指示器告知用户这是一个可交互的折叠块。页面加载时的默认表现先折叠后披露理解details的关键在于它的两种状态折叠状态页面加载后你只能看到summary的文本和旁边的三角符号展开状态用户点击summary后整个details块内的所有内容包括那些p标签一次性全部披露出来。这一按需披露的特性非常适合 FAQ、帮助提示、阅读说明、进阶配置等场景——默认不打扰用户需要时一键展开。纯 HTML 示例在页面中加入一段可折叠说明下面是一个最直接的纯 HTML 用法用于在页面上放置一段用户主动点击才可见的附加说明details summary什么是这个工具/summary p这是一段默认隐藏的说明文字只有用户点击摘要后才会显示。/p ul li支持列表/li li支持任意 HTML 元素/li /ul /details页面加载时仅显示 什么是这个工具 及三角符号点击后整块内容披露。这一过程完全不需要 JavaScript是details相比手写 JS 折叠组件最大的优势。React/JSX 中的写法className 与组件化封装在 React/JSX 中details与普通标签一样可直接使用属性写法遵循 JSX 规则样式类名用className而不是 HTML 中的class。原文档中作者曾在 Ruby Operator Lookup 页面上加入过这样一个details块details classNamept-2 pb-6 summaryWhat is this thing?/summary p classNamepl-3 pt-2 text-gray-700 text-sm Ruby is an expressive, versatile, and flexible dynamic programming language. That means there are all kinds of syntax features, operators, and symbols we can encounter that might look unfamiliar and are hard to look up. Ruby Operator Lookup is a directory of all these language features. /p p classNamepl-3 pt-2 text-gray-700 text-sm Use the search bar to narrow down the results. Then click on a button for the operator or symbol you want to explore further. /p /details上述className是 Tailwind 工具类本仓库另有 tailwind 目录 记录相关用法pt-2 pb-6控制上下内边距pl-3让正文相对摘要缩进text-gray-700 text-sm设置正文颜色与字号。用 Tailwind 排版后的效果是摘要在上、正文在其下方缩进披露整体视觉层次清晰。在 React 中如果想统一封装可以把这段 JSX 提取成组件参考仓库中 react/details-tags-are-a-controllable-component.md 记录的受控组件写法import React, { useState } from react; export default function Details({ summary, children, onToggle }) { const [open, setOpen] useState(false); return ( details open{open} onToggle{() { setOpen((prev) !prev); onToggle(); }} summary{summary}/summary {children} /details ); }高级用法open属性与onToggle事件details除了默认折叠、点击展开的默认行为外还支持两个重要的进阶特性1.open属性默认展开details的open是一个布尔属性加上它之后页面加载时该块就处于展开状态用户仍然可以点击摘要将其再次折叠details open summary默认展开的说明/summary p这段内容在页面加载时就已披露。/p /details在 React 中open属性可以与状态联动把原生标签变成可受控的组件如上节封装所示从而在业务逻辑里精确控制展开/折叠。2.onToggle事件监听展开状态变化每次用户切换展开/折叠状态时浏览器都会触发toggle事件。在 React 中可以通过onToggle捕获该事件用于埋点统计、联动展开其他区域、或按状态更新 UI。需要注意open与toggle配合是 React 中常见的受控折叠面板实现方式而纯 HTML 场景下details完全自管理状态无需任何脚本。实战要点与注意事项无需 JS纯details/summary即可实现折叠展开任何框架均可直接使用摘要必填缺少summary时浏览器会默认渲染一个空摘要Details结构不完整内容任意披露区域可容纳段落、列表、表格、图片、表单等任意 HTML甚至可以嵌套details实现多层折叠默认折叠除非显式加open属性否则页面加载时内容是隐藏的——这正是按需披露的语义所在无障碍友好details由浏览器原生管理焦点与 ARIA 语义与手写 JS 折叠方案相比更易维护。赞分享文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载相关推荐Paperclip数据分析从AI代理活动中挖掘业务价值Paperclip数据分析从AI代理活动中挖掘业务价值 在当今数字化时代企业越来越依赖AI代理来自动化和优化各种业务流程。Paperclip作为一款开源的A人工智能AI 应用AI Agent多智能体Agent 编排Agent 工作流MCP 服务后端前端htmx 懒加载实战利用 hx-triggerload 实现页面元素按需加载htmx 懒加载实战利用 hx triggerload 实现页面元素按需加载 导读 本文基于 htmx 官方示例 lazy load.md https:前端Web框架30 Seconds of Code HTML 实战用 details 元素实现零 JavaScript 的手风琴折叠内容30 Seconds of Code HTML 实战用 details 元素实现零 JavaScript 的手风琴折叠内容 本文基于 30 Seconds教程文档上一篇arizeai/phoenix-otel 完整解析Phoenix Node.js 追踪 SDK 的版本演进、端点解析与实战配置指南下一篇Divinity Mod Manager终极神界原罪2模组管理解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考