Shepherd 项目中浮动 UI 选项的配置技巧

Shepherd 是一个流行的用户引导库，它基于 Floating UI（原 Popper.js）来实现元素的定位和浮动效果。在实际使用中，开发者经常需要自定义浮动 UI 的行为以满足特定需求。

浮动 UI 选项的基本配置

在 Shepherd 中，可以通过 floatingUIOptions 参数来传递 Floating UI 的配置选项。这些配置会直接传递给底层的 Floating UI 实例，让开发者能够精细控制浮动元素的行为。

const tour = useShepherdTour({
  tourOptions: {
    defaultStepOptions: {
      floatingUIOptions: {
        // 这里放置 Floating UI 配置
      }
    }
  }
});

常见配置场景

禁用祖先滚动自动更新

当页面有滚动容器时，Floating UI 默认会监听祖先元素的滚动事件并自动更新浮动元素位置。要禁用这一行为，可以这样配置：

floatingUIOptions: {
  autoUpdate: {
    ancestorScroll: false
  }
}

替代解决方案：阻止 body 滚动

在某些情况下，开发者可能发现禁用滚动自动更新并不能完全解决问题。这时可以考虑直接阻止 body 元素的滚动行为，这通常能更彻底地固定引导元素的位置。

使用 CDN 时的注意事项

对于通过 CDN 引入 Shepherd 的情况，虽然不能直接使用模块导入语法，但仍然可以通过全局对象访问 Floating UI 的功能。配置方式与模块化引入基本一致，只是需要注意全局变量的使用。

最佳实践建议

1. 优先尝试使用 floatingUIOptions 进行精细控制
2. 对于复杂场景，考虑结合 CSS 定位和滚动控制
3. 在移动端特别注意滚动行为的处理
4. 测试不同浏览器下的表现一致性

通过合理配置 Shepherd 的浮动 UI 选项，开发者可以创建出在各种环境下表现稳定的用户引导体验。