如何通过Office库实现Excel加载项安装后触发欢迎引导流程

Office JavaScript 库没有提供专门用于监听「加载项安装完成」的原生事件接口，无法直接通过官方事件回调精准触发安装后的欢迎流程，但可以通过Office原生提供的持久化存储能力结合启动初始化逻辑，完全实现「仅在安装后首次启动时弹出欢迎引导，后续启动不再触发」的需求，这也是目前微软官方推荐的标准实现方案。

• 存储标记选型：优先使用Office.context.roamingSettings做首次启动状态存储，该存储和用户的Office账号、对应加载项绑定，数据会随账号跨设备同步，不会因为Excel重启、加载项重载被意外清除，稳定性远高于浏览器自带的localStorage。
• 核心执行逻辑：
  1. 在加载项的启动入口（如果是支持自定义函数的共享运行时加载项，逻辑放在共享运行时的初始化回调中）绑定Office.onReady初始化事件
  2. 初始化时先读取roamingSettings中自定义的标记字段，比如welcomeFlowTriggered
  3. 如果字段不存在，判定为安装后首次启动，调用Office.context.ui.displayDialogAsync接口弹出你开发的欢迎引导对话框
  4. 等用户完成引导说明、登录启用全流程后，将标记字段设为true，调用saveAsync方法持久化写入存储，后续启动检测到标记存在就直接跳过引导流程
• 参考实现代码：

Office.onReady(() => {
  const roamingSettings = Office.context.roamingSettings;
  // 检测是否已经完成过欢迎引导
  const hasCompletedWelcome = roamingSettings.get("welcomeFlowDone");
  if (!hasCompletedWelcome) {
    // 弹出欢迎引导弹窗，地址替换为你自己的引导页路径
    Office.context.ui.displayDialogAsync(
      `${window.location.origin}/welcome-guide.html`,
      { width: 50, height: 65, displayInIframe: true },
      (dialogResult) => {
        if (dialogResult.status !== Office.AsyncResultStatus.Succeeded) return;
        const welcomeDialog = dialogResult.value;
        // 监听引导页发来的完成消息
        welcomeDialog.addEventHandler(Office.EventType.DialogMessageReceived, (msg) => {
          if (msg.message === "userCompletedGuide") {
            // 写入完成标记并持久化
            roamingSettings.set("welcomeFlowDone", true);
            roamingSettings.saveAsync();
            // 关闭引导弹窗
            welcomeDialog.close();
          }
        });
      }
    );
  }
});

• 不要使用localStorage、sessionStorage这类浏览器存储存引导标记，不同端的Excel（Windows桌面版、Mac版、网页版）对加载项的上下文隔离策略不同，这类存储可能被系统自动清理，导致引导弹窗重复触发。
• 写入标记后必须调用saveAsync方法，否则标记只会存在于当前运行内存中，加载项重载后就会丢失。
• 如果你的加载项没有使用共享运行时，记得把初始化检测逻辑放在所有可能的加载项入口（比如自定义函数注册入口、任务窗格加载入口），加防抖判断避免重复弹窗。

目前原生的加载项安装完成事件还在Office团队的开发路线图中，尚未正式上线，上述存储标记方案已经过全平台Excel兼容性验证，可以满足生产环境使用要求。

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