同层播放器接入方案

最实用、最落地、前端/客户端都能直接用的「同层播放器接入方案详解」，不讲废话，全是实战要点，专门给做视频、直播、广告、小程序、H5 同层播放的人用。

---

同层播放器接入方案详解（实战版）

一、什么是「同层播放器」？

同层播放 = 视频画面能和页面 DOM 元素叠加、混合渲染，而不是默认悬浮在最上层。

为什么需要同层？

• 普通视频播放器 默认全屏层级最高，盖过所有弹窗、浮层、弹幕、按钮
• 直播/短视频/广告场景必须：
  • 弹幕盖在视频上
  • 点赞、评论、送礼浮层
  • 头像、昵称、小窗播放
• 不同平台（微信、App Webview、小程序、浏览器）默认视频行为不一样，必须统一成「同层」

---

二、同层播放器核心实现原理

1. 浏览器原生方案（现代浏览器）

核心属性：

<video
  playsinline       // 关键：行内播放（不自动全屏）
  webkit-playsinline
  x5-video-player-type="h5"
  x5-video-player-fullscreen="true"
  x5-video-orientation="portrait"
></video>

关键作用：

• playsinline：禁止自动全屏，允许和 DOM 同层
• 安卓微信/QQ/X5 内核必须加 x5-video-* 系列属性

---

三、各平台同层播放标准配置（最重要）

1. 微信浏览器 / X5 内核（安卓）

必须加：

<video
  playsinline
  webkit-playsinline
  x5-video-player-type="h5"
  x5-video-player-fullscreen="true"
  x5-video-orientation="portrait"
  preload="auto"
></video>

作用：

• 强制使用 H5 同层播放器
• 不自动横屏、不自动全屏
• DOM 可以盖在视频上

---

2. iOS 微信 / Safari

<video
  playsinline
  webkit-playsinline
  muted  // 静音才能自动播放
  loop
></video>

iOS 规则：

• 必须静音才能自动播放
• 必须 playsinline
• 手势触摸后才能取消静音播放声音

---

3. 小程序同层播放器（重点）

小程序 原生 video 自带同层，但要开启：

<video
  id="myVideo"
  src="{{url}}"
  controls="{{false}}"
  autoplay
  loop
  muted
  playsinline
  webkit-playsinline
  show-progress="false"
  show-fullscreen-btn="false"
  show-play-btn="false"
  enable-auto-rotation="false"
></video>

小程序同层关键：

• 自带 同层渲染
• 支持 cover-view / cover-image 盖在视频上
• 不支持普通 div 覆盖（必须用 cover-xxx）

---

四、同层播放器「层级覆盖」方案（实战必看）

方案 A：原生 H5 → 支持所有 DOM 覆盖（现代浏览器）

video 下层
div 上层（z-index 即可）

条件：

• 开启 playsinline
• 非全屏
• 非老旧安卓设备

方案 B：微信/安卓 X5 → 只能用「同层播放器模式」

必须开启：

x5-video-player-type="h5"

开启后：

• 支持 z-index 覆盖
• 支持弹幕、浮层、按钮

方案 C：小程序 → 只能用 cover-view

<video>
  <cover-view class="danmaku">弹幕</cover-view>
  <cover-image src="avatar.png"></cover-image>
</video>

---

五、自动播放解决方案（同层必备）

1. 自动播放通用规则

• 视频必须静音 才能自动播放
• 用户交互后（点击/触摸）可取消静音

2. 兼容代码

video.muted = true
video.play().then(() => {
  // 自动播放成功
}).catch(err => {
  // 失败：等待用户点击
})

3. 微信自动播放（wx-sdk）

document.addEventListener('WeixinJSBridgeReady', () => {
  video.play()
})

---

六、同层播放器常见问题 99% 都在这

1. 视频盖过所有弹窗 → 没开同层

解决：

playsinline
webkit-playsinline
x5-video-player-type="h5"

2. 一点播放就横屏 / 全屏

解决：

x5-video-player-fullscreen="true"
x5-video-orientation="portrait"

3. 小程序盖不住视频

解决：

• 必须用 cover-view / cover-image
• 不能用普通 div

4. 自动播放失败

解决：

• 加 muted
• 监听用户触摸事件再播放声音

5. 声音和画面不同步

• 直播流用 FLV / HLS 低延迟
• 关闭视频硬解（部分安卓）

---

七、完整可直接使用的「同层播放器模板」

<video
  id="video"
  src="xxx.mp4"
  width="100%"
  height="100%"
  poster="cover.jpg"
  preload="auto"
  autoplay
  muted
  loop
  playsinline
  webkit-playsinline
  x5-video-player-type="h5"
  x5-video-player-fullscreen="true"
  x5-video-orientation="portrait"
></video>

<!-- 上层DOM 可覆盖 -->
<div class="overlay">弹幕、按钮、头像都可以</div>