帮助文档页需语义化结构：每个faq用带唯一id的包裹，标题用，展开用原生；搜索框与分类导航应置于内顶部，确保可访问性、seo和跨浏览器兼容。

帮助文档页不是「把文字堆进去就行」的页面，核心是让每个问题可定位、可搜索、可被屏幕阅读器读出。用错结构，用户点链接打不开具体条目，SEO 抓到内容却无法跳转，无障碍测试直接失败。

为什么不能用

套所有 FAQ 条目

常见错误是写成 <div class="faq-item"> <h3>登录失败怎么办？</h3> <p>请检查密码是否输入正确...</p> </div> —— 这会导致三个实际问题：搜索引擎无法识别这是独立问答单元；屏幕阅读器无法将标题和答案建立语义关联；JavaScript 控制展开/收起时，键盘用户 Tab 键会跳过整个区块（因为 <div> 默认不可聚焦）。<p>正确做法是每个条目必须用 <code><section></section> 包裹，并带唯一 id：

<section id="faq-login-failed"><h2>登录失败怎么办？</h2>
  <p>请检查密码是否输入正确，或尝试重置密码。</p>
</section>

• <section></section> 是语义化容器，告诉浏览器“这是一个独立的内容单元”
• id 必须唯一且有意义，方便锚点链接（如 #faq-login-failed）和 JS 操作
• 标题必须用 <h2></h2>（不是 <h3></h3> 或 <div>），否则屏幕阅读器无法建立层级关系<h3>折叠展开该用 <details>/<summary> 还是自己写 JS</summary></details> </h3> <p>原生 <code><details></details> + <summary></summary> 是最稳的选择，尤其对无障碍和 SEO 友好。但 iOS Safari 上容易卡顿或不响应，根本原因不是标签本身有问题，而是 CSS 阻断了渲染流程。

  典型踩坑点：

  • 给 <details></details> 设了 overflow: hidden 或 height: 0，覆盖了原生行为
  • 在 <summary></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></main> 内部，紧贴顶部，而非塞进 <header></header> 或 <nav></nav> 里。

  

  Wechat HTML Publisher

  直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

  下载

  错误示例：<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></p> 标签需配合 aria-expanded 和 aria-controls，否则键盘用户无法感知展开状态
  • 不要用 <ul></ul> —— 规范只允许 <p></p> 或 <pre class="brush:php;toolbar:false;"></pre> 作为答案容器

  移动端折叠失效或样式错乱的根本原因

  不是代码写得不够“炫”，而是 HTML 结构或 CSS 层级破坏了 <details></details> 的原生渲染链路。iOS Safari 尤其敏感，常见触发点有：

  • 父容器设了 transform 或 will-change，导致子元素脱离渲染上下文
  • CSS 中写了 details[open] { max-height: 500px; } 并配了 transition，但 Safari 不支持 max-height 动画（会卡住或跳变）
  • 用了 display: grid 或 flex 布局，但没处理 <summary></summary> 的默认 display: list-item，造成换行或缩进异常

  最简解法：去掉所有过渡动画，用纯显隐控制；若必须动效，改用 opacity + visibility 组合，避免碰触高度相关属性。

  复杂点往往藏在看似无关的父容器样式里——比如一个 overflow: hidden 在 <main></main> 上，就能让 iOS 下所有 <details></details> 点击无反应。调试时优先检查外层容器，而不是埋头重写 JS。