本文详解如何修复模态框（modal）头部 tooltip 文字溢出、遮挡内容及定位错位的问题，通过合理设置 `z-index`、`position: fixed` 和容器层级关系，使 tooltip 稳定悬浮于模态框上方右侧，同时保留悬停动画与语义化结构。

在构建带说明性提示的模态框时，一个常见却易被忽视的问题是：Tooltip 内容因父容器 overflow: hidden、z-index 层级不足或定位方式不当，导致文字被裁剪、与模态框重叠，甚至完全不可见。如原始代码中，.tooltip:after 使用 position: absolute，但其父元素 .name-large 缺乏 position: relative，且整个模态框容器 .top 未设置足够高的堆叠上下文，致使 Tooltip 浮层被压制在模态框内部，视觉上“嵌入”而非“悬浮”。

✅ 正确解决方案：三层定位 + 强制堆叠上下文

核心在于分离 Tooltip 的渲染上下文，使其脱离模态框的局部定位流：

1. 为 Tooltip 提示框设置 position: fixed
   这是关键一步——避免受父级 overflow: hidden 或 transform（如 .expand .to-contents 的 scale()）影响。同时配合 z-index: 10000000 确保最高优先级：

.tooltip:after {
  content: attr(data-tooltip);
  background: #2c5424;
  width: 250px;
  height: 95px;
  font-size: 10px;
  padding: 10px;
  border-radius: 5px;
  letter-spacing: 1px;
  position: fixed; /* 关键：脱离文档流 */
  z-index: 10000000; /* 确保覆盖所有模态框元素 */
  top: auto;
  bottom: auto;
  left: auto;
  right: auto;
}

2. 动态计算 Tooltip 位置（推荐 JS 辅助）
   虽然纯 CSS 可用 left/top 静态偏移，但为适配不同屏幕和模态框位置，建议用 JavaScript 动态定位。以下为轻量级实现：

  ?

document.querySelectorAll('.tooltip').forEach(el => {
  const anim = el.closest('#anim');
  if (!anim) return;

  el.addEventListener('mouseenter', () => {
    const rect = anim.getBoundingClientRect();
    const tooltip = el.nextElementSibling || el.parentNode.querySelector('.tooltip:after');
    // 实际中需创建伪元素对应的真实 DOM（见下方说明）
  });
});

⚠️ 注意：CSS 伪元素 ::after 无法直接通过 JS 获取 getBoundingClientRect()。更健壮的做法是改用真实 元素替代伪元素（见下文优化版）。

3. 使用真实 DOM 元素替代伪元素（推荐生产环境）
   伪元素定位受限且调试困难。升级方案如下：

  ?
  
    This feature will allow you to assign your available pool...
  

.tooltip-trigger {
  position: relative;
  display: inline-block;
}
.tooltip-icon {
  background: #2c5424;
  color: white;
  border-radius: 50%;
  width: 22px;
  height: 22px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 14px;
  cursor: pointer;
}
.tooltip-popup {
  position: fixed;
  background: #2c5424;
  color: white;
  padding: 10px 12px;
  border-radius: 4px;
  font-size: 12px;
  max-width: 280px;
  line-height: 1.4;
  z-index: 10000000;
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
  animation: fadeIn 0.2s ease;
}
@keyframes fadeIn {
  from { opacity: 0; transform: translateY(-5px); }
  to { opacity: 1; transform: translateY(0); }
}

// 悬停显示逻辑（无依赖）
document.querySelectorAll('.tooltip-trigger').forEach(trigger => {
  const popup = trigger.querySelector('.tooltip-popup');
  const icon = trigger.querySelector('.tooltip-icon');

  icon.addEventListener('mouseenter', () => {
    const rect = icon.getBoundingClientRect();
    popup.style.display = 'block';
    popup.style.left = `${rect.right + 8}px`;
    popup.style.top = `${rect.top + window.scrollY}px`;
  });

  icon.addEventListener('mouseleave', () => {
    popup.style.display = 'none';
  });
});

? 关键注意事项

• 避免 transform 父容器截断固定定位：CSS transform（如 scale(), translate()）会创建新的包含块（containing block），使 position: fixed 相对于该变换元素而非视口。务必确保 Tooltip 的最近 transform 祖先不干扰其定位。
• z-index 必须配合 position 生效：仅设置 z-index 而无 position: relative/absolute/fixed 无效。
• 移动端兼容性：添加 @media (hover: hover) 区分悬停设备，对触摸设备改用点击触发。
• 可访问性：为 .tooltip-icon 添加 aria-label，并确保 Tooltip 内容可通过键盘聚焦（tabindex="0" + focus 事件）。

✅ 总结

修复 Tooltip 定位异常的本质，是明确其渲染上下文：
? 用 position: fixed 脱离局部布局流；
? 用高 z-index 确保视觉层级；
? 用 JS 动态计算位置保障响应式鲁棒性；
? 用真实 DOM 替代伪元素提升可维护性与可访问性。

遵循以上原则，即可让 Tooltip 始终优雅悬浮于模态框右上方，清晰传达信息，不遮挡、不溢出、不闪烁。