React/Gatsby项目接入Schedule Engine Widget及点击事件实现方案

问题场景 #

• 技术栈：基于 React、Gatsby、Sanity 搭建客户站点，处于边学边练阶段
• 接入目标：实现官方提供的点击按钮唤起预约控件功能
• 官方提供的接入参考代码：
  1. 全局引入脚本：

  <script data-api-key="替换为Schedule Engine分配的API Key" data-defer="true" id="se-widget-embed" src="https://embed.scheduleengine.net/schedule-engine-v3.js"></script>
  

  2. 原生唤起按钮示例：

  <button class="se-widget-button" type="button" onclick="ScheduleEngine.show()">Book Now!</button>
  

• 故障表现：将原生onclick改写为React的onClick绑定ScheduleEngine.show()时，页面抛出错误。

报错核心原因 #

1. 第三方脚本配置了data-defer="true"延迟加载，React组件完成渲染、事件绑定时，全局ScheduleEngine对象可能还未初始化完成，直接调用会报变量不存在。
2. JSX内的事件回调运行在ES模块作用域，而非浏览器全局作用域，直接写ScheduleEngine会被识别为当前模块内的未定义变量，不会自动读取window下的全局属性。

分步实现方案 #

1. 全局注入第三方脚本 #

Gatsby项目推荐使用官方内置的Script组件（v4及以上版本支持）在全局布局中注入脚本，不要直接硬改静态html文件：

// 在共享布局组件（如src/components/layout.js）中引入
import { Script } from "gatsby"

const Layout = ({ children }) => {
  return (
    <>
      {/* 站点原有全局导航、主体内容等逻辑 */}
      {children}
      <Script
        id="se-widget-embed"
        src="https://embed.scheduleengine.net/schedule-engine-v3.js"
        data-api-key="替换为你的实际API Key"
        data-defer="true"
      />
    </>
  )
}

如果使用低于v4的Gatsby版本，可以通过react-helmet组件将上述脚本标签包裹后放入head区域。

2. 编写兼容的React点击事件 #

不要直接在onClick里调用ScheduleEngine.show()，显式从window对象读取第三方实例，同时增加加载状态判断，避免脚本未加载完成时点击报错：

const BookNowButton = () => {
  const handleOpenWidget = () => {
    // 实例已存在时直接唤起
    if (window.ScheduleEngine?.show) {
      window.ScheduleEngine.show()
      return
    }
    // 实例未加载完成时，轮询等待加载后再唤起
    const timer = setInterval(() => {
      if (window.ScheduleEngine?.show) {
        window.ScheduleEngine.show()
        clearInterval(timer)
      }
    }, 120)
  }

  return (
    <button
      className="se-widget-button"
      type="button"
      onClick={handleOpenWidget}
    >
      Book Now!
    </button>
  )
}

export default BookNowButton

3. TypeScript 类型补充（可选） #

如果项目使用TypeScript，会提示window对象上不存在ScheduleEngine属性，在项目全局类型声明文件（如src/global.d.ts）中添加如下声明即可：

declare global {
  interface Window {
    ScheduleEngine: {
      show: () => void
    }
  }
}

export {}

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