iOS端的画中画（Picture in Picture，简称PiP）自从iPadOS 9引入以来，已经逐步开放到iPhone上。当WKWebView加载一个包含视频的网页时，用户点击网页内置播放器上的画中画按钮，系统会弹出一个悬浮的小窗口继续播放视频。很多开发者反馈这个窗口有时表现为半透明、有时背景发黑，甚至与自己的App界面叠在一起显得非常突兀。这篇文章就来拆解WKWebView场景下画中画窗口的形成机制，以及我们能在多大程度上影响它的透明度和视觉效果。
WKWebView中画中画窗口是如何产生的
首先要明确一点：在WKWebView里播放网页视频时，画中画窗口并不是由你的App直接创建的，而是由WebKit框架内部的播放管线触发的。网页中的video元素如果带有playsinline以及webkit-playsinline属性，用户点击视频控件上的画中画入口后，WebKit会通过AVPictureInPictureController创建一个系统级的悬浮窗口，这个窗口运行在一个独立的进程里，归属于系统而不是你的App进程。
正因为窗口归属系统，普通开发者无法像操作UIView那样直接拿到它的layer去改alpha值或背景色。Apple对画中画窗口的视觉样式做了统一约束：深色半透明背景、圆角矩形、顶部一条细窄的返回标签栏。这些样式在不同iOS版本上略有差异，但整体基调一致。理解了这一层，就能明白为什么网上流传的诸如“修改PiP窗口透明度”的hack方案大多不可靠——你在自己进程里改不到那个窗口的属性。
不过无法直接改透明度，不等于完全无能为力。可以通过几个间接手段影响画中画启动与展示时的视觉衔接，让半透明窗口出现在你的App上时不那么难看。
控制画中画的启动条件与视觉衔接
第一个可以做的事情是控制画中画功能是否可用。WKWebView的配置项allowsPictureInPicturePlayback（在WKWebViewConfiguration中对应allowsPictureInPictureMediaPlayback）决定了网页视频能否进入画中画。如果你的App界面整体是浅色半透明风格，画中画窗口的深色半透明观感会非常突兀，此时可以考虑在特定页面关闭画中画能力：
let config = WKWebViewConfiguration() // 关闭网页视频的画中画能力 config.allowsPictureInPictureMediaPlayback = false let webView = WKWebView(frame: .zero, configuration: config)
第二个手段是状态监听。WebKit提供了WKWebViewConfiguration之外的相关回调与通知，而更通用的方式是监听AVPictureInPictureController的代理方法。如果你的App同时存在原生播放器与网页播放器，建议统一通过AVPictureInPictureControllerDelegate管理画中画的生命周期，在pictureInPictureControllerWillStartPictureInPicture回调中暂停页面上的其他动画或降低背景视图的透明度，让窗口切换的瞬间更平滑。
还有一个容易被忽略的细节：进入画中画时原视频位置会留下黑洞。可以在回调中主动把网页中原video元素的位置替换成一个占位图或提示文字，方法是向页面注入一段JavaScript：
// 在画中画开始时给原视频位置加一层半透明遮罩提示
function onPipStart() {
var v = document.querySelector('video');
if (v) {
var mask = document.createElement('div');
mask.style.cssText = 'position:absolute;inset:0;background:rgba(0,0,0,0.35);'
+ 'display:flex;align-items:center;justify-content:center;'
+ 'color:#fff;font-size:14px;';
mask.textContent = '正在以画中画模式播放';
v.parentNode.style.position = 'relative';
v.parentNode.appendChild(mask);
}
}这样处理之后，画中画窗口虽然还是系统默认的半透明深色样式，但页面本身的过渡更自然，用户感知上会好很多。
原生AVPlayer方案的透明度与遮罩自定义
如果产品对视觉要求非常高，一个更彻底的思路是绕开WKWebView的网页播放器，改用原生AVPlayerLayer加自定义控制层来播放在线视频，然后在原生层上自己实现画中画。原生方案下你可以完全掌控进入画中画前的视觉状态，例如在pictureInPictureControllerWillStartPictureInStopAnimation阶段做淡出动画：
class PlayerViewController: UIViewController, AVPictureInPictureControllerDelegate {
var pipController: AVPictureInPictureController?
func setupPiP(playerLayer: AVPlayerLayer) {
guard AVPictureInPictureController.isPictureInPictureSupported() else { return }
pipController = AVPictureInPictureController(playerLayer: playerLayer)
pipController?.delegate = self
}
// 画中画即将开始时，把播放器容器做淡出处理
func pictureInPictureControllerWillStartPictureInPicture(
_ pictureInPictureController: AVPictureInPictureController) {
UIView.animate(withDuration: 0.25) {
self.playerContainerView.alpha = 0.0
}
}
// 画中画结束，恢复容器可见性
func pictureInPictureController(
_ pictureInPictureController: AVPictureInPictureController,
restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void) {
self.playerContainerView.alpha = 1.0
completionHandler(true)
}
}需要提醒的是，即便是原生方案，画中画悬浮窗本身依然是系统渲染的，它的背景透明度和圆角依然不可定制。我们能控制的只有窗口出现前后、以及恢复播放界面时的过渡效果。有些团队为了追求“透明画中画”的观感，会自己用悬浮Window加AVPlayerLayer模拟一个可拖动的迷你播放器，这种方案确实可以完全自定义透明度、圆角甚至阴影，但要自行处理音频焦点、手势拖动、与系统多任务的冲突，成本不低，建议根据产品需求权衡。
常见问题排查与注意事项
实际开发中与画中画相关的视觉问题，很多并不是“透明度”本身，而是权限和版本导致的窗口不出现。排查时先确认设备的Audio Session类别设置正确，一般需要设置为.playback，否则后台播放和画中画会直接失效；其次确认Capabilities中开启了Background Modes的Audio选项；最后注意iPhone上画中画需要iOS 14以上，部分旧机型上窗口样式与新款设备不同。
另一个高频问题是画中画窗口出现后无法通过代码关闭。AVPictureInPictureController提供了stopPictureInPicture()方法，可以主动结束画中画并回退到内嵌播放。对于WKWebView场景，则可以通过执行JavaScript操作video元素，或者直接调用webView.pauseAllMediaPlayback()系列方法间接干预。整体来说，画中画窗口的视觉定制空间有限，把精力放在过渡动画、占位遮罩和启动条件控制上，才是收益最高的优化方向。
WKWebView画中画AVPictureInPictureController修改时间：2026-09-14 02:12:45