iPhone13 Pro（iOS17 Safari）video调用webkitEnterFullScreen无法全屏

问题背景 #

在iOS Safari环境下，调用videoRef.current.webkitEnterFullScreen()让带有playsinline和autoplay属性、通过srcObject分配媒体流的<video>元素进入全屏时无响应。已确认以下条件均满足：

• 调用前已触发loadeddata和loadedmetadata事件
• 视频处于readyState 4状态、正在播放、srcObject存在
• webkitSupportsFullscreen返回true，确认全屏功能可用
• 调用由用户点击操作直接触发

该功能在iOS16.4模拟器中正常工作，iOS17下偶尔随机生效（如刷新或返回再前进后），调用时无任何错误或控制台警告。

修复方案 #

1. 切换至标准Fullscreen API #

iOS17对标准Fullscreen API的支持更稳定，优先使用标准方法并兼容旧版本：

export async function toggleFullscreen(video: HTMLVideoElement) {
  if (!document.fullscreenElement) {
    try {
      await video.requestFullscreen();
    } catch (err) {
      // 降级处理旧iOS版本
      if ('webkitEnterFullScreen' in video) {
        (video as unknown as WebkitVideoElement).webkitEnterFullScreen();
      }
    }
  } else {
    await document.exitFullscreen();
  }
}

2. 动态控制playsinline属性 #

iOS17中playsinline属性可能与全屏触发逻辑冲突，可在触发全屏前临时移除该属性，退出后恢复：

export function toggleFullscreen(video: WebkitVideoElement) {
  const isFullscreen = useIsFullscreen.getState();
  if (!isFullscreen) {
    video.removeAttribute('playsinline');
    // 确保在同步上下文执行全屏调用
    video.webkitEnterFullScreen();
    // 退出全屏后恢复属性
    video.addEventListener('webkitfullscreenchange', () => {
      if (!document.webkitFullscreenElement) {
        video.setAttribute('playsinline', '');
      }
    }, { once: true });
  } else {
    document.webkitExitFullscreen();
  }
}

3. 严格保证调用在用户交互同步上下文内 #

iOS17对用户交互的上下文校验更严格，避免将webkitEnterFullScreen()嵌套在Promise、setTimeout等异步逻辑中，确保直接在点击事件的同步回调内执行。

4. 简化媒体流约束 #

如果使用摄像头或屏幕共享流，检查媒体约束是否存在可能干扰全屏的配置，尝试简化约束参数：

// 示例：简化摄像头流约束
const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: { ideal: 1920 }, height: { ideal: 1080 } },
  audio: true
});
video.srcObject = stream;

内容的提问来源于stack exchange，提问作者stacknoobski