如何在Shepherd.js中为引导步骤与屏幕边缘添加内边距且不偏移箭头？

当前问题 #

我正在用Shepherd.js构建应用引导页，它底层依赖Floating UI。现在的问题是引导步骤的弹窗太靠近屏幕边缘，看起来很不精致。

当前效果示例：

我的当前配置代码：

{
  attachTo: {
    element: '#top-menu-account-settings-menu-icon',
    on: 'left',
  },
  buttons: [
    {
      action: addLocationTour.next,
      text: 'Next',
    },
  ],
  floatingUIOptions: {
    middleware: [
      offset(12), // 与高亮元素的偏移量
    ],
  },
  modalOverlayOpeningRadius: 5,
  text: 'This step is attached to the bottom of the <code>.example-css-selector</code> element.',
}

已尝试的修复方案 #

我试过在floatingUIOptions里添加shift({ padding: 16 })，这确实阻止了弹窗触碰屏幕边缘，但同时也让箭头错位了——箭头向下偏移，不再对齐图标中心。

箭头错位的效果示例：

修改后的代码：

{
  attachTo: {
    element: '#top-menu-account-settings-menu-icon',
    on: 'left',
  },
  buttons: [
    {
      action: addLocationTour.next,
      text: 'Next',
    },
  ],
  floatingUIOptions: {
    middleware: [
      offset(12), // 与高亮元素的偏移量
      shift({ padding: 16 }), // 阻止弹窗触碰屏幕边缘，但导致箭头偏移
    ],
  },
  modalOverlayOpeningRadius: 5,
  text: 'This step is attached to the bottom of the <code>.example-css-selector</code> element.',
}

我的疑问 #

怎样才能既让引导步骤不触碰屏幕边缘，又不影响箭头的对齐呢？

解决方案 #

我来给你几个亲测有效的方案：

方案一：用autoPlacement替代shift（推荐）

shift会整体偏移弹窗导致箭头错位，而autoPlacement能在弹窗靠近边缘时自动切换附着方向，同时保持箭头始终对齐目标元素中心。你只需要替换掉shift配置：

floatingUIOptions: {
  middleware: [
    offset(12),
    autoPlacement({
      padding: 16, // 设置弹窗与屏幕边缘的最小距离
      // 如果你想限制可选的附着方向，可以添加这一行
      // allowedPlacements: ['left', 'right'] // 比如只允许左右两个方向切换
    })
  ],
}

这样当弹窗快要碰到左边缘时，会自动切换到右侧（或其他允许的方向），既远离了屏幕边缘，箭头也不会错位。

方案二：给shift加偏移补偿修正箭头

如果你不想改变附着方向，只想在当前位置微调，可以给shift添加offset参数来补偿箭头的偏移量，数值需要根据你的弹窗尺寸慢慢调整：

floatingUIOptions: {
  middleware: [
    offset(12),
    shift({
      padding: 16,
      offset: -8 // 根据你的箭头偏移情况设置正负数值，直到箭头对齐中心
    })
  ],
}

方案三：用CSS直接控制弹窗边距

如果上面的Floating UI配置都不适用，还可以通过CSS给弹窗加全局外边距，同时固定箭头的定位：

.shepherd-element {
  margin: 16px !important; /* 让弹窗整体远离屏幕边缘 */
}
/* 确保箭头的定位不受弹窗边距影响 */
.shepherd-arrow:before {
  transform: none !important;
}

这个方法更直接，但要注意!important可能会覆盖Shepherd的默认样式，建议先在测试环境验证兼容性。

备注：内容来源于stack exchange，提问作者TinyTiger