React Native Video 在 iOS 上 ScrollView 中控件显示异常问题解析

问题现象

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

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

这个问题在 React Native Video 6.x 版本中普遍存在，影响范围包括真实设备和模拟器。

问题根源分析

经过开发者社区的深入探讨和多次测试，确认该问题的核心原因在于 iOS 平台上 AVPlayerLayer 和 AVPlayerViewController 之间的切换机制。当 controls 属性启用时，React Native Video 内部会从 AVPlayerLayer 切换到 AVPlayerViewController 来实现原生控件，但这一转换过程破坏了原有的布局约束。

特别值得注意的是，这个问题仅在以下条件同时满足时出现：

• 运行在 iOS 平台
• 视频组件位于 ScrollView 或类似可滚动容器中
• controls 属性设置为 true
• 使用 React Native Video 6.x 版本

解决方案与变通方法

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

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. 样式设置：确保为 Video 组件设置明确的宽高样式，避免依赖自动布局
2. 性能考虑：在列表中使用视频时，注意内存管理和播放状态控制
3. 测试覆盖：在实现解决方案后，应在多种设备和iOS版本上进行全面测试
4. 更新关注：关注 React Native Video 的官方更新，该问题可能会在后续版本中修复

技术深度解析

这个问题的本质在于 iOS 原生视图层与 React Native 布局系统之间的协调问题。当启用 controls 时，AVPlayerViewController 会接管视频播放的控制权，但其视图层级没有正确继承父容器的约束条件。这与 iOS 的视图控制器呈现机制和 React Native 的布局计算方式有关。

理解这一点很重要，因为类似的布局问题在其他需要切换原生视图层级的场景中也可能出现。开发者应当注意，任何涉及原生视图控制器切换的操作都可能需要手动处理布局约束。

总结

React Native Video 在 iOS ScrollView 中的控件显示问题是一个典型的跨平台框架与原生组件集成挑战。通过理解问题的根本原因，开发者可以选择最适合自己项目的解决方案。目前社区提供的补丁方法已经验证有效，建议开发者在应用这些解决方案时充分考虑项目的具体架构和需求。