帮助文档页需语义化结构：每个FAQ用带唯一id的<section>包裹，标题用<h2>，展开用原生<details><summary>；搜索框与分类导航应置于<main>内顶部，确保可访问性、SEO和跨浏览器兼容。
帮助文档页不是「把文字堆进去就行」的页面，核心是让每个问题可定位、可搜索、可被屏幕阅读器读出。用错结构，用户点链接打不开具体条目，SEO 抓到内容却无法跳转，无障碍测试直接失败。
为什么不能用 套所有 FAQ 条目常见错误是写成 <div class="faq-item"><h3>登录失败怎么办？</h3><p>请检查密码是否输入正确...</p></div> —— 这会导致三个实际问题：搜索引擎无法识别这是独立问答单元；屏幕阅读器无法将标题和答案建立语义关联；JavaScript 控制展开/收起时，键盘用户 Tab 键会跳过整个区块（因为 <div> 默认不可聚焦）。
正确做法是每个条目必须用 <section> 包裹，并带唯一 id：
<section id="faq-login-failed">
<h2>登录失败怎么办？</h2>
<p>请检查密码是否输入正确，或尝试重置密码。</p>
</section>
-
<section> 是语义化容器，告诉浏览器“这是一个独立的内容单元”
-
id 必须唯一且有意义，方便锚点链接（如 #faq-login-failed）和 JS 操作
- 标题必须用
<h2>（不是 <h3> 或 <div>），否则屏幕阅读器无法建立层级关系
折叠展开该用 / 还是自己写 JS
原生 <details> + <summary> 是最稳的选择，尤其对无障碍和 SEO 友好。但 iOS Safari 上容易卡顿或不响应，根本原因不是标签本身有问题，而是 CSS 阻断了渲染流程。
立即学习“前端免费学习笔记（深入）”；
典型踩坑点：
- 给
<details> 设了 overflow: hidden 或 height: 0，覆盖了原生行为
- 在
<summary> 上加了 tabindex="-1"，导致键盘用户无法聚焦
- 用 JS 监听
click 后又手动调用 open = !open，干扰了原生状态同步
推荐写法（零 JS）：
<section id="faq-login-failed">
<details>
<summary>登录失败怎么办？</summary>
<p>请检查密码是否输入正确，或尝试重置密码。</p>
</details>
</section>图标（如 ▶）必须加 aria-hidden="true"，否则屏幕阅读器会念“黑色三角形”。
搜索框和分类导航放哪里才合理
80% 的用户进帮助中心第一动作是「找」，不是「读」。所以搜索框和分类导航不是装饰，而是主内容的辅助信息，应放在 <main> 内部，紧贴顶部，而非塞进 <header> 或 <nav> 里。
错误示例：<header><input type="text"></header> —— 这会让屏幕阅读器误以为搜索框是网站全局导航的一部分。
正确结构：
<main>
<div>
<label for="help-search">搜索帮助文档</label>
<input type="search" id="help-search" name="q">
</div>
<h3>常见问题分类</h3>
<p><a href="#faq-login">登录</a></p>
<p><a href="#faq-payment">支付</a></p>
<p><a href="#faq-api">API 使用</a></p>
<!-- FAQ 列表从这里开始 -->
</main>
-
<input type="search"> 比 type="text" 更合适，部分浏览器自动提供清空按钮和历史建议
- 分类超过 5 个时，
<p> 标签需配合 aria-expanded 和 aria-controls，否则键盘用户无法感知展开状态
- 不要用
<ul> —— 规范只允许 <p> 或 <pre> 作为答案容器
移动端折叠失效或样式错乱的根本原因
不是代码写得不够“炫”，而是 HTML 结构或 CSS 层级破坏了 <details> 的原生渲染链路。iOS Safari 尤其敏感，常见触发点有：
- 父容器设了
transform 或 will-change，导致子元素脱离渲染上下文
- CSS 中写了
details[open] { max-height: 500px; } 并配了 transition，但 Safari 不支持 max-height 动画（会卡住或跳变）
- 用了
display: grid 或 flex 布局，但没处理 <summary> 的默认 display: list-item，造成换行或缩进异常
最简解法：去掉所有过渡动画，用纯显隐控制；若必须动效，改用 opacity + visibility 组合，避免碰触高度相关属性。
复杂点往往藏在看似无关的父容器样式里——比如一个 overflow: hidden 在 <main> 上，就能让 iOS 下所有 <details> 点击无反应。调试时优先检查外层容器，而不是埋头重写 JS。
常见错误是写成 <div class="faq-item"><h3>登录失败怎么办？</h3><p>请检查密码是否输入正确...</p></div> —— 这会导致三个实际问题：搜索引擎无法识别这是独立问答单元；屏幕阅读器无法将标题和答案建立语义关联；JavaScript 控制展开/收起时，键盘用户 Tab 键会跳过整个区块（因为 <div> 默认不可聚焦）。
正确做法是每个条目必须用 <section> 包裹，并带唯一 id：
<section id="faq-login-failed"> <h2>登录失败怎么办？</h2> <p>请检查密码是否输入正确，或尝试重置密码。</p> </section>
-
<section>是语义化容器，告诉浏览器“这是一个独立的内容单元” -
id必须唯一且有意义，方便锚点链接（如#faq-login-failed）和 JS 操作 - 标题必须用
<h2>（不是<h3>或<div>），否则屏幕阅读器无法建立层级关系
折叠展开该用 / 还是自己写 JS
还是自己写 JS
原生 <details> + <summary> 是最稳的选择，尤其对无障碍和 SEO 友好。但 iOS Safari 上容易卡顿或不响应，根本原因不是标签本身有问题，而是 CSS 阻断了渲染流程。
立即学习“前端免费学习笔记（深入）”；
典型踩坑点：
- 给
<details>设了overflow: hidden或height: 0，覆盖了原生行为 - 在
<summary>上加了tabindex="-1"，导致键盘用户无法聚焦 - 用 JS 监听
click后又手动调用open = !open，干扰了原生状态同步
推荐写法（零 JS）：
<section id="faq-login-failed">
<details>
<summary>登录失败怎么办？</summary>
<p>请检查密码是否输入正确，或尝试重置密码。</p>
</details>
</section>图标（如 ▶）必须加 aria-hidden="true"，否则屏幕阅读器会念“黑色三角形”。
搜索框和分类导航放哪里才合理
80% 的用户进帮助中心第一动作是「找」，不是「读」。所以搜索框和分类导航不是装饰，而是主内容的辅助信息，应放在 <main> 内部，紧贴顶部，而非塞进 <header> 或 <nav> 里。
错误示例：<header><input type="text"></header> —— 这会让屏幕阅读器误以为搜索框是网站全局导航的一部分。
正确结构：
<main>
<div>
<label for="help-search">搜索帮助文档</label>
<input type="search" id="help-search" name="q">
</div>
<h3>常见问题分类</h3>
<p><a href="#faq-login">登录</a></p>
<p><a href="#faq-payment">支付</a></p>
<p><a href="#faq-api">API 使用</a></p>
<!-- FAQ 列表从这里开始 -->
</main>-
<input type="search">比type="text"更合适，部分浏览器自动提供清空按钮和历史建议 - 分类超过 5 个时，
<p>标签需配合aria-expanded和aria-controls，否则键盘用户无法感知展开状态 - 不要用
<ul>—— 规范只允许<p>或<pre>作为答案容器
移动端折叠失效或样式错乱的根本原因
不是代码写得不够“炫”，而是 HTML 结构或 CSS 层级破坏了 <details> 的原生渲染链路。iOS Safari 尤其敏感，常见触发点有：
- 父容器设了
transform或will-change，导致子元素脱离渲染上下文 - CSS 中写了
details[open] { max-height: 500px; }并配了transition，但 Safari 不支持max-height动画（会卡住或跳变） - 用了
display: grid或flex布局，但没处理<summary>的默认display: list-item，造成换行或缩进异常
最简解法：去掉所有过渡动画，用纯显隐控制；若必须动效，改用 opacity + visibility 组合，避免碰触高度相关属性。
复杂点往往藏在看似无关的父容器样式里——比如一个 overflow: hidden 在 <main> 上，就能让 iOS 下所有 <details> 点击无反应。调试时优先检查外层容器，而不是埋头重写 JS。
