btn-top--hidden 是唯一合法写法，因 BEM 规范强制修饰符用双连字符 -- 分隔，否则会被误判为新 Block 或被工具链忽略，且无法被 JS 安全控制和 DevTools 语义识别。
返回顶部按钮的状态必须用 btn-top--hidden、btn-top--visible、btn-top--animating 这类修饰符，不能写成 btn-top-hidden 或 btn-top_hidden——否则它就不是 BEM 修饰符，而是个普通类名，JS 控制、构建工具识别、DevTools 调试都会出问题。
为什么 btn-top--hidden 是唯一合法写法？
BEM 规范强制修饰符（Modifier）必须用双连字符 -- 与块名分隔。写成 btn-top-hidden 会被解析为一个新 Block；btn-top_hidden 中的下划线在 BEM 里无语义，CSS 工具链（如 postcss-bem-linter）会报错或忽略。只有 btn-top--hidden 明确表达“这是 btn-top 块的 hidden 状态”，且能被 element.classList.toggle('btn-top--hidden', shouldHide) 安全控制。
常见错误现象：
-
btn-top-hidden在 Sass 中无法被@extend %btn-top-modifier统一收口 - 构建时 css-loader 若开启
localIdentName，可能把btn-top-hidden当作局部类误删 - DevTools 里看不到该类和
btn-top的语义关联，调试时得翻 HTML 才能确认上下文
btn-top--visible 和 btn-top--hidden 必须正交，不能嵌套
返回顶部按钮常需根据滚动位置动态切换显隐，这两个状态是互斥布尔值，应由 JS 单独控制，不依赖顺序或组合逻辑：
立即学习“前端免费学习笔记（深入）”；
- 正确：
el.classList.toggle('btn-top--visible', isVisible)+el.classList.toggle('btn-top--hidden', !isVisible) - 错误：
btn-top--visible--hidden—— BEM 不允许修饰符嵌套，这会被当成新 Block 名，且 JS 无法原子化切换 - 错误：
btn-top--hidden仅靠display: none隐藏 —— 缺少aria-hidden="true"和pointer-events: none，影响可访问性和点击穿透
性能提示：隐藏态建议用 visibility: hidden; opacity: 0; 配合 transition，避免 display: none 触发重排；显隐切换应节流至 requestAnimationFrame，防止滚动中高频重绘。
加载中或过渡动画要用 btn-top--animating 单独修饰
返回顶部操作常伴随 scrollTo 动画，此时按钮需反馈“正在执行”，但这个状态和显隐无关，必须独立声明：
-
btn-top--animating应作用于整个按钮，而非子元素（如btn-top__icon），否则动画中断后图标可能残留旋转 - 多个状态共存时（如
btn-top--visible btn-top--animating），CSS 必须显式覆盖组合效果：.btn-top--visible.btn-top--animating { opacity: 0.8; } - 禁止用
btn-top__icon--animating替代 —— 图标只是载体，状态属于按钮整体；若需图标动画差异化，应在btn-top--animating下用currentColor或 CSS 变量控制 - 动画结束回调里必须手动移除
btn-top--animating，不能依赖 CSSanimationend事件监听——滚动行为可能被用户中断，需 JS 主动清理
容易被忽略的边界点
返回顶部按钮常被塞进固定定位容器（如 footer-fixed），这时 btn-top--hidden 的 transform: translateY(100%) 可能受父容器 overflow: hidden 截断；更稳妥的做法是用 inset: auto 0 0 auto 配合 visibility 控制。另外，SSR 渲染时服务端无法判断滚动位置，初始状态必须设为 btn-top--hidden，再由客户端 JS 根据 window.scrollY 补充 btn-top--visible —— 否则首屏闪动或状态错乱。
