Shepherd 项目中 FloatingUI 自动布局功能的实现与优化

背景介绍

Shepherd 是一个流行的 JavaScript 用户引导库，用于创建产品导览和教程。在最新版本中，Shepherd 从 Popper.js 迁移到了 FloatingUI 作为其定位引擎。这一变更带来了更现代化的定位能力，但也引入了一些兼容性问题，特别是在自动布局(autoPlacement)功能方面。

问题核心

在 Shepherd 12.0.1 版本中，开发者发现无法正常使用 FloatingUI 的自动布局功能。这是因为 Shepherd 默认添加了 flip(翻转)和 shift(偏移)中间件，而 flip 与 autoPlacement 在功能上是互斥的。当开发者尝试在 floatingUIOptions.middleware 中添加 autoPlacement 时，会导致错误。

技术分析

FloatingUI 提供了两种主要的定位策略：

1. 固定位置策略：基于明确的方位(top/bottom/left/right等)
2. 自动布局策略：由系统自动选择最佳显示位置

Shepherd 原有的实现强制使用了 flip 中间件，这导致自动布局功能无法正常工作。flip 中间件的作用是当元素超出可视区域时自动翻转位置，而 autoPlacement 则是更高级的自动选择最佳位置的策略，两者在功能上存在冲突。

解决方案

经过社区讨论和代码审查，Shepherd 团队通过以下方式解决了这个问题：

1. 修改了中间件的合并顺序，确保开发者传入的配置能够覆盖默认值
2. 增加了对 'auto' 位置参数的支持
3. 当检测到使用自动布局时，自动跳过 flip 中间件的添加

实现细节

在技术实现上，主要修改了 floating-ui.js 文件中的逻辑：

1. 添加了对 'auto' 位置参数的识别
2. 优化了中间件合并策略，使开发者配置能够优先
3. 确保 autoPlacement 和 flip 不会同时被启用

升级建议

对于需要使用自动布局功能的开发者，建议：

1. 升级到包含此修复的最新版本
2. 在配置中使用 'auto' 作为位置参数
3. 直接在 floatingUIOptions.middleware 中配置 autoPlacement

总结

这次优化使得 Shepherd 能够更好地支持 FloatingUI 的全部功能，特别是自动布局这一强大特性。开发者现在可以更灵活地控制导览步骤的显示位置，让用户引导体验更加智能和自然。这也体现了 Shepherd 项目对开发者需求的积极响应和持续改进的承诺。