如何在 Vimeo 全屏视频上精准叠加 HTML 测验层_技术教程

本文详解如何在 vimeo 视频（含原生全屏模式）上稳定显示 html 测验浮层，通过脱离 iframe 限制、劫持全屏容器、动态调整 z-index 与定位策略，解决原生全屏下 overlay 消失的核心问题。

在嵌入 Vimeo 视频时，为实现“视频播放中弹出测验题”的交互效果（如教育类课程），开发者常将

直接置于 .boiteVideo 容器内，并用 position: absolute + 高 z-index 实现覆盖。该方案在常规尺寸下完全可行，但一旦触发 Vimeo 原生全屏（点击右下角全屏按钮或调用 requestFullscreen()），问题立即暴露：自定义 overlay 消失不见。

根本原因在于：Vimeo 全屏并非简单放大 iframe，而是将整个 .boiteVideo（或其父级）提升至顶层，并在其内部重建 UI 结构（如 .vp-video-wrapper、.vp-player-ui-overlays）。此时，你原本位于 iframe 同级的 #affiche 元素，因未被纳入 Vimeo 全屏渲染树，会被浏览器视为“非全屏上下文内容”，自动降级隐藏或脱离视口层级。

✅ 正确解法是：主动接管全屏行为，确保 overlay 始终与视频容器同级且处于全屏作用域内。

✅ 推荐实现步骤

禁用 Vimeo 默认全屏按钮（可选但推荐）
在 Vimeo iframe 的 src 中添加参数 &controls=0&fullscreen=0，避免用户误触原生全屏导致 overlay 脱离。
使用自定义全屏入口
不依赖 Vimeo 内部逻辑，而是由 JS 主动对 .boiteVideo 容器调用全屏 API：

$("#btnFullScreen").click(function() {
  const container = document.querySelector(".boiteVideo");
  if (container.requestFullscreen) {
    container.requestFullscreen();
  } else if (container.webkitRequestFullscreen) {
    container.webkitRequestFullscreen();
  } else if (container.msRequestFullscreen) {
    container.msRequestFullscreen();
  }
});

确保 overlay 始终在全屏容器内且层级最高
#affiche 必须是 .boiteVideo 的直接子元素（如示例结构所示），并采用以下 CSS 策略：

.boiteVideo {
  position: relative; /* 关键：为绝对定位子元素提供参照 */
  width: 100%;
  height: 100%;
}

.boiteVideo iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  border: none;
}

#affiche {
  position: absolute;
  top: 200px;
  left: 200px;
  z-index: 2147483647; /* 使用最大安全整数，高于 Vimeo 所有已知 UI 层级 */
  pointer-events: auto; /* 确保按钮/输入框可交互 */
}

⚠️ 注意：不要尝试 $("#affiche").appendTo($("iframe")) —— iframe 是沙箱环境，无法向其 DOM 内注入外部元素；且 Vimeo 会重写其内部结构，强行注入将被清空或引发跨域错误。

监听全屏状态变化（增强鲁棒性）
可选地监听 fullscreenchange 事件，动态调整 overlay 样式（如适配不同屏幕比例）：

document.addEventListener("fullscreenchange", () => {
  if (document.fullscreenElement === document.querySelector(".boiteVideo")) {
    // 进入全屏：可扩大字体、居中定位等
    $("#affiche").css({ "font-size": "1.4em", "left": "50%", "top": "40%", "transform": "translateX(-50%)" });
  } else {
    // 退出全屏：恢复默认样式
    $("#affiche").attr("style", "");
  }
});

✅ 总结关键原则

容器即上下文：全屏操作必须作用于包含 video 和 overlay 的共同父容器（.boiteVideo），而非仅 iframe；
层级即生命线：z-index 必须显著高于 Vimeo 内部所有已知 UI 类（实测 2147483647 安全）；
定位需相对容器：#affiche 的 position: absolute 必须基于 position: relative 的 .boiteVideo；
拒绝 iframe 注入：所有 overlay 元素必须位于 iframe 外部、同级 DOM 中。

遵循以上方案，即可在 Vimeo 全屏与非全屏状态下，均稳定、精准、可交互地展示 HTML 测验层，为视频教学场景提供专业级用户体验。