HTML5 注释本身不可见且无法直接控制，需通过 CSS 模拟、data 属性条件渲染或元素实现显隐功能。
如果您在 HTML5 文档中插入注释，但发现注释内容未按预期显示或隐藏，则可能是由于注释语法使用不当或 浏览器 渲染机制理解偏差。以下是实现 HTML5 中带注释文档的多种控制方法：
一、使用标准 HTML 注释语法并配合 CSS 控制可见性
HTML5 注释本身不会被浏览器解析为 DOM 节点，因此无法直接通过 CSS 控制其显示 / 隐藏；但可通过将注释内容迁移至可渲染元素（如 <div> 或 <code><span></span>）中，并添加特定类名来模拟注释行为，再利用 CSS 的display 或visibility属性实现显隐控制。
1、在 HTML 中用 <div class="comment hidden"> <!-- 这是原始注释内容 --> 调试用：用户登录状态未校验 </div> 包裹注释文本。
2、在 <style></style> 标签或外部 CSS 文件中定义：.comment {font-size: 0.85em; color: #666; padding: 4px; background: #f9f9f9; border-left: 3px solid #ccc;}
立即学习 “ 前端免费学习笔记（深入）”；
3、定义隐藏样式：.hidden {display: none;}或.hidden {visibility: hidden;}。
4、通过 JavaScript 动态切换 hidden 类：document.querySelector('.comment').classList.toggle('hidden');
二、利用 data 属性存储注释并条件渲染
该方法将注释内容作为自定义数据属性值嵌入到相关 HTML 元素中，在需要时通过脚本读取并插入到页面指定位置，从而实现按需显示注释内容，避免污染主结构。
1、在目标元素上添加 data-comment 属性，例如：<p data-comment=" 此处用于说明段落用途，供开发人员查阅 "> 正文内容 </p>。
2、创建一个空容器用于显示注释：<div id="comment-display" style="margin-top: 8px; font-style: italic; color: #555;"></div>。
3、编写 JavaScript 获取注释内容：const commentText = document.querySelector('p').dataset.comment;
4、将注释内容写入容器：document.getElementById('comment-display').textContent = commentText;
5、通过 点击事件 触发显示 / 隐藏：document.querySelector('p').addEventListener('click', () => {……});
三、使用 HTML5 的 <details></details> 与<summary></summary>元素封装注释
<details></details>是 HTML5 原生支持的交互式折叠组件，可将注释内容置于其中，默认隐藏，点击后展开，无需 JavaScript 即可实现基础显隐控制，语义清晰且可访问性良好。
1、在需要标注的位置插入：<details><summary><strong><font color="green">【注释】</font></strong></summary> 此处说明该模块依赖于 API v2.1，返回字段包含 user_id 和 token_expires</details>。
2、可选地添加 CSS 美化：details[open] summary::after {content: " ▲";}和summary::after {content: " ▼";}。
3、若需默认展开，直接在 <details></details> 标签中添加 open 布尔属性：<details open></details>。
4、支持键盘操作：聚焦 <summary></summary> 后按 Enter 或 Space 键可切换展开 / 收起状态。
四、通过 JavaScript 动态生成注释 DOM 节点并绑定开关逻辑
该方法完全脱离 HTML 注释语法，而是由脚本创建独立的 <aside></aside> 或<section></section>元素承载注释内容，并赋予唯一 ID 及控制按钮，适合复杂文档中多处注释集中管理。
1、在 HTML 中预留一个注释容器：<div id="annotations-container"></div>。
2、定义注释数据数组：const annotations = [{id: 'a1', target: 'header', content: '顶部导航栏需适配深色模式'}, {id: 'a2', target: 'form', content: '表单提交前必须验证邮箱格式'}];
3、遍历数组，为每个注释生成带开关按钮的 DOM：const el = document.createElement('aside'); el.innerHTML = `<button onclick="toggleAnnotation('${item.id}')"> 显示 / 隐藏注释 </button><p>${item.content}</p>`; document.getElementById('annotations-container').appendChild(el);
4、实现 toggleAnnotation 函数，通过 element.style.display 切换 'block' 与'none'。
5、为对应目标元素添加 data-annotation-id="a1" 等标识，便于点击目标时自动触发关联注释显示。
