React Native Video 在 iOS 上 ScrollView 中 controls 属性导致布局异常问题分析

问题现象描述

在 React Native Video 6.x 版本中，iOS 平台上存在一个特殊的布局问题。当 Video 组件被放置在 ScrollView 中，并且启用了 controls 属性时，视频播放过程中会出现布局异常。具体表现为：

1. 视频开始播放后，视图会突然被"切断"，ScrollView 的起始位置发生变化
2. 视频内容无法完整显示，即使尝试滚动也无法恢复
3. 问题仅在视频播放时出现，暂停后布局会恢复正常
4. 该问题在 iOS 17.2 及以上版本中尤为明显

问题复现条件

要复现这个问题，需要满足以下几个条件：

1. 使用 React Native Video 6.x 版本（6.4.3 至 6.9.1 均受影响）
2. 在 iOS 平台（包括模拟器和真机）
3. Video 组件被放置在 ScrollView 中
4. 启用了 controls 属性
5. 使用了导航头部（Navigation Header）

技术原因分析

经过社区开发者深入分析，发现问题根源在于 iOS 平台上 AVPlayerLayer 和 AVPlayerViewController 的切换机制：

1. 当 controls 属性为 false 时，Video 组件使用 AVPlayerLayer 进行渲染
2. 当 controls 属性为 true 时，Video 组件会切换到 AVPlayerViewController
3. 这种切换过程中，布局约束没有被正确保持
4. 特别是在 ScrollView 和导航头部共存的复杂布局中，系统自动布局系统会出现计算错误

解决方案

目前社区提供了几种可行的解决方案：

1. 临时解决方案（推荐）

使用 react-native-screens 中的 ModalScreenNativeComponent 包裹 Video 组件：

import ModalScreenNativeComponent from "react-native-screens/src/fabric/ModalScreenNativeComponent";

<ModalScreenNativeComponent>
  <Video
    controls={true}
    source={{uri: props?.source}}
    style={{aspectRatio: 16/9}}
    resizeMode={"contain"}
  />
</ModalScreenNativeComponent>

2. 补丁解决方案

对于熟悉原生开发的用户，可以手动修改 RCTVideo.swift 文件，添加布局约束：

if _controls {
    self.removePlayerLayer()
    self.usePlayerViewController()
    
    if let playerViewController = _playerViewController, let playerView = playerViewController.view {
        playerView.translatesAutoresizingMaskIntoConstraints = false
        self.addSubview(playerView)
        
        NSLayoutConstraint.activate([
            playerView.leadingAnchor.constraint(equalTo: self.leadingAnchor),
            playerView.trailingAnchor.constraint(equalTo: self.trailingAnchor),
            playerView.topAnchor.constraint(equalTo: self.topAnchor),
            playerView.bottomAnchor.constraint(equalTo: self.bottomAnchor)
        ])
    }
}

3. 版本回退方案

如果以上方案不可行，可以考虑暂时回退到 5.2.1 版本，该版本不存在此问题。

最佳实践建议

1. 对于新项目，建议等待官方修复版本发布
2. 对于现有项目，优先考虑使用 ModalScreenNativeComponent 解决方案
3. 如果必须使用原生解决方案，确保在 podfile 中正确锁定 react-native-video 版本
4. 在复杂布局中，特别注意视频组件的父容器约束

问题影响范围

该问题主要影响以下场景：

1. 长页面中包含多个视频的项目
2. 社交媒体类应用中的视频流
3. 教育类应用中的课程视频列表
4. 任何需要在可滚动视图中嵌入可控制视频的场景

总结

React Native Video 在 iOS 平台上的这个布局问题虽然特定，但对用户体验影响较大。通过理解问题本质和现有解决方案，开发者可以根据项目需求选择最适合的应对策略。随着社区持续关注，预计官方将在未来版本中提供更完善的修复方案。