React Spring动画及视频自动播放在iOS上无法触发问题求助

问题核心 #

iOS 所有基于 WebKit 的浏览器（Safari、Chrome 等）有两项严格限制：

1. 媒体自动播放政策：即使视频已设置 muted、playsInline、autoPlay，仍可能因未在用户交互上下文触发而无法自动播放。
2. 非用户触发动画限制：页面加载后无用户交互的自动动画（如轮播、react-spring 动画）会被浏览器节流，仅在用户手动交互后才会正常运行。

以下是针对性的代码修改方案：

1. 主动触发视频播放 #

给视频添加 ref，在加载完成后主动调用 play()，同时捕获 iOS 限制导致的播放失败：

// 组件内新增视频 ref 数组
const videoRefs = useRef<(HTMLVideoElement | null)[]>([])

// 修改视频渲染部分
{data.map((item, index) => {
  const originalUrl = item.caseLink?.case.cloudinary.secure_url

  return (
    <animated.video
      ref={el => videoRefs.current[index] = el}
      src={originalUrl}
      autoPlay
      loop
      key={index}
      muted
      playsInline
      className="absolute w-screen h-screen top-0 left-0 object-cover"
      style={{
        ...videoSprings[index],
        transformOrigin: "center center",
        transform: videoSprings[index].scale?.to((s) => `scale(${s})`),
        opacity: videoSprings[index].opacity?.to((o) => o.toFixed(2))
      }}
      onCanPlayThrough={() => {
        // 加载完成后尝试播放，捕获 iOS 限制错误
        videoRefs.current[index]?.play().catch(err => {
          console.log("iOS 视频自动播放限制：", err)
        })
      }}
    />
  )
})}

2. 监听首次用户交互启动轮播 #

iOS 会阻止无用户交互的自动动画，需监听首次点击/触摸事件来启动轮播和动画：

// 新增状态标记是否已触发用户交互
const [userInteracted, setUserInteracted] = useState(false)

// 监听页面首次交互
useEffect(() => {
  const handleFirstInteraction = () => {
    if (!userInteracted) {
      setUserInteracted(true)
      // 启动轮播（如果还没启动）
      if (loaded.videos && loaded.content && !intervalRef.current) {
        startInterval()
      }
      // 触发所有视频播放
      videoRefs.current.forEach(video => video?.play().catch(console.log))
    }
    // 移除监听，只执行一次
    window.removeEventListener("click", handleFirstInteraction)
    window.removeEventListener("touchstart", handleFirstInteraction)
  }

  window.addEventListener("click", handleFirstInteraction)
  window.addEventListener("touchstart", handleFirstInteraction)

  return () => {
    window.removeEventListener("click", handleFirstInteraction)
    window.removeEventListener("touchstart", handleFirstInteraction)
  }
}, [userInteracted, loaded.videos, loaded.content])

// 修改轮播启动逻辑，仅在用户交互后自动启动
useEffect(() => {
  if (loaded.videos && loaded.content && userInteracted) {
    setActiveButton(0)
    startInterval()
  }

  return () => clearInterval(intervalRef.current)
}, [loaded.videos, loaded.content, userInteracted])

3. 适配触摸设备的按钮交互 #

iOS 触摸设备不支持 mouseenter/mouseleave，添加触摸事件替代：

<Link
  className="emoji eyes text-inherit text-lg md:text-2xl -top-2 mr-2 md:mr-4 overflow-hidden px-[1.25rem] py-[0.297rem] md:py-[0.625rem] border-2 border-white rounded-[100px] relative transition-all duration-300 ease-in-out hover:bg-white hover:text-black group"
  href={`/cases/${item.caseLink?.case.slug.current}`}
  onMouseEnter={() => handleMouseEnter(index)}
  onMouseLeave={handleMouseLeave}
  // 添加触摸事件适配iOS
  onTouchStart={() => handleMouseEnter(index)}
  onTouchEnd={handleMouseLeave}
>
  {/* 原有内容不变 */}
</Link>

4. 优化 react-spring 动画配置 #

调整动画配置，适配 iOS 性能限制：

const videoSprings = useSprings(
  data.length,
  data.map((item, index) => ({
    opacity: activeButton === index ? 1 : 0,
    scale: activeButton === index ? 1.1 : 1,
    config: {
      duration: DURATION,
      easing: activeButton === index ? easeInOutCubic : easeOutQuad,
      // 启用 clamp 确保动画不会超出预期范围
      clamp: true,
    } as SpringConfig
  }))
)

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