悬浮球必须用 position: fixed 定位且 z-index ≥ 9999，禁用 display 切换而用 class 控制显隐与动效，dom 需预渲染并配合 aria-hidden/aria-expanded 提升可访问性，事件应绑定 pointerdown 并防默认行为。
悬浮球元素必须是 fixed 定位且层级足够高
如果点击按钮后悬浮球没反应，大概率是 z-index 不够或定位失效。悬浮球容器（比如一个 <div id="floating-ball">）必须用 <code>position: fixed，不能依赖父容器布局。常见错误是把它放在某个 flex 或 grid 容器里，结果被裁剪或脱离视口。
推荐基础样式：
#floating-ball {
position: fixed;
bottom: 24px;
right: 24px;
width: 60px;
height: 60px;
border-radius: 50%;
background: #3a86ff;
z-index: 9999; /* 至少高于所有业务组件 */
cursor: pointer;
}
- 避免用
z-index: 999这类模糊值，统一维护一个层级常量表（如Z_INDEX_FLOATING = 9999） - 移动端需加
touch-action: manipulation防止延迟响应 - 若页面有 iframe 或第三方 SDK（如客服浮窗），它们可能自带高
z-index，得实测覆盖
按钮触发时不要直接 toggle display，优先用 class 控制状态
用 style.display = 'none' 切换容易破坏过渡动画、丢失焦点状态，也难做渐隐/缩放等动效。正确做法是通过添加/移除 class 控制显隐和行为。
例如：
.floating-ball--hidden {
opacity: 0;
transform: scale(0.8);
pointer-events: none;
transition: all 0.2s ease;
}
.floating-ball--visible {
opacity: 1;
transform: scale(1);
pointer-events: auto;
}
- 用
pointer-events: none确保隐藏时不响应任何鼠标事件，比visibility: hidden更可靠 - 不要在 JS 中硬编码 CSS 属性，所有视觉变化交给 class + CSS 实现
- 如果悬浮球内含子菜单（如隐藏功能列表），它的显示逻辑应由主球体的 class 派生，而非独立控制
隐藏功能的 DOM 结构要提前渲染，别用 innerHTML 动态拼接
用户点击按钮后“秒出”功能，前提是 DOM 已存在。临时用 document.createElement 或 innerHTML 插入菜单节点，会带来渲染卡顿和 focus 管理问题。
- 把隐藏功能区域（如快捷操作项、调试开关）写死在悬浮球 HTML 内，初始用
aria-hidden="true"和 class 隐藏 - 用
aria-expanded同步控制可访问性状态，屏幕阅读器才能正确播报展开/收起 - 若功能项含异步内容（如最近操作记录），可用
data-loaded="false"标记，首次展开时 fetch 并缓存，后续直接 show
移动端真机上 click 事件可能不触发，改用 pointerdown
iOS Safari 和部分安卓 WebView 对 click 有 300ms 延迟或完全失效，尤其当悬浮球用了 transform 或 will-change 优化时。
- 绑定事件一律用
addEventListener('pointerdown', handler)，它兼容 touch/mouse/pen，且无延迟 - 记得在 handler 里调用
event.preventDefault()防止长按呼出菜单或选中文字 - 避免同时监听
click和pointerdown，否则可能触发两次——用pointerdown单一来源即可
复杂点在于：悬浮球如果支持拖拽移动，pointerdown 就得配合 pointermove 做手势判断，此时隐藏功能的呼出逻辑要和拖拽状态解耦，比如只在非拖拽状态下响应点击。
