React Native Video 在 iOS 上使用 ScrollView 和 controls 属性时的布局问题解析

问题现象

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

1. 视频开始播放后，视图会突然发生偏移
2. ScrollView 的起始位置发生变化，导致视频内容被部分遮挡
3. 即使用户尝试滚动，也无法完整显示视频内容
4. 问题仅在视频播放时出现，暂停时会恢复正常布局

问题复现条件

这个问题在以下环境中可以稳定复现：

• React Native Video 6.4.3 及以上版本
• iOS 平台（包括真机和模拟器）
• 使用导航头部（Navigation Header）的页面
• 视频组件放置在 ScrollView 中
• 启用了 controls 属性

技术分析

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

1. 当 controls 属性为 false 时，视频使用 AVPlayerLayer 渲染
2. 当 controls 属性为 true 时，系统会自动切换到 AVPlayerViewController
3. 这种切换过程中，布局约束没有被正确保持，导致视图位置偏移
4. 问题特别容易在包含导航头的复杂视图层级中出现

解决方案

目前社区提供了几种有效的解决方案：

1. 手动设置约束（推荐）

通过修改 RCTVideo.swift 文件，在切换为 AVPlayerViewController 时手动添加约束：

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)
        ])
    }
}

2. 使用 react-native-screens 的 ModalScreenNativeComponent

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

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

3. 临时回退方案

如果上述方案不可行，可以考虑：

• iOS 平台暂时使用 5.2.1 版本
• Android 平台使用 6.4.3 版本
• 通过平台判断分别加载不同版本的组件

最佳实践建议

1. 对于新项目，建议直接应用约束修复方案
2. 在复杂视图层级中，特别注意视频组件的父容器布局
3. 如果使用导航组件，确保正确处理了安全区域和插入值
4. 考虑使用 onLayout 事件动态调整布局作为临时解决方案

总结

React Native Video 在 iOS 上的这个布局问题主要源于底层播放器视图切换时的约束丢失。通过手动维护约束或使用替代容器组件可以有效解决问题。开发者应根据项目实际情况选择最适合的解决方案，同时关注官方仓库的更新，以便在正式修复发布后及时升级。