如何修复React-joyride滚动时Spotlight位置偏移问题？

以下是几个经过验证的可行修复方案，按优先级排序：

1. 监听滚动事件手动更新Joyride实例 #

当页面滚动时，手动触发Joyride的位置更新，确保Spotlight始终对准目标元素：

import { useRef, useEffect } from 'react';
import Joyride from 'react-joyride';

const Tour = () => {
  const joyrideRef = useRef(null);

  useEffect(() => {
    const handleScroll = () => joyrideRef.current?.update();
    
    window.addEventListener('scroll', handleScroll);
    return () => window.removeEventListener('scroll', handleScroll);
  }, []);

  const steps = [
    { target: '#your-target', content: '引导内容' }
  ];

  return (
    <Joyride
      ref={joyrideRef}
      steps={steps}
      disableScrolling={false}
    />
  );
};

2. 配置floaterProps优化定位策略 #

React-Joyride依赖react-floater处理定位，通过floaterProps调整滚动相关配置，适配你的页面结构：

<Joyride
  steps={steps}
  floaterProps={{
    scroll: {
      container: window, // 如果目标在自定义滚动容器内，替换为对应DOM节点
      behavior: 'instant',
      offset: 15
    },
    position: 'auto' // 让组件自动选择最佳位置
  }}
/>

3. 明确滚动容器上下文 #

如果目标元素位于自定义滚动容器（而非全局window）中，必须指定滚动容器的DOM节点，避免位置计算错误：

const scrollContainerRef = useRef(null);

// ...

<Joyride
  steps={steps}
  floaterProps={{
    scroll: {
      container: scrollContainerRef.current
    }
  }}
/>

// 自定义滚动容器
<div ref={scrollContainerRef} style={{ overflowY: 'auto', height: '600px' }}>
  {/* 包含目标元素的内容 */}
</div>

4. 升级到最新版本 #

旧版本的React-Joyride存在滚动定位的已知bug，升级到最新稳定版能解决大部分此类问题：

npm update react-joyride
# 或
yarn upgrade react-joyride

5. 自定义Spotlight组件（终极方案） #

如果以上方法都无效，可以替换默认的Spotlight组件，完全自主控制定位逻辑：

const CustomSpotlight = ({ targetRect, children }) => {
  return (
    <div
      style={{
        position: 'fixed',
        top: targetRect.top,
        left: targetRect.left,
        width: targetRect.width,
        height: targetRect.height,
        boxShadow: '0 0 0 9999px rgba(0,0,0,0.7)',
        borderRadius: '4px',
        zIndex: 9999
      }}
    >
      {children}
    </div>
  );
};

// 使用自定义组件
<Joyride
  steps={steps}
  spotlightComponent={CustomSpotlight}
/>

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