Office.js开发Outlook加载项：ItemChanged事件点击链接后失效

问题背景 #

使用Office.js开发Outlook自定义加载项时，通过以下代码注册ItemChanged事件以检测邮件选择变更：

Office.context.mailbox.addHandlerAsync(Office.EventType.ItemChanged, selectedMailItemChanged);

async function selectedMailItemChanged(eventArgs){
    console.log("E-mail was selected for the first time, or the email selection has changed.");
}

该事件原本正常触发，但点击指向内部应用的自定义协议链接（如下）后，事件不再响应邮件选择变更：

<a
:href="'edient:Command=ShowEditForm&LicenceCode=XXXXXX&ControllerID=JobShipment&BusinessEntityPK=' + shipment.fetch_id"
>
 <span>Open Shipment</span>
</a>

核心原因 #

点击自定义协议链接启动外部应用时，Outlook的加载项运行上下文可能被干扰：

• 外部应用启动会触发Outlook进程的焦点切换，导致加载项的事件监听器被框架自动移除或失效
• 加载项可能进入休眠状态，原有事件绑定的内存引用被清除

解决方案 #

1. 自动重新注册事件 #

监听加载项页面的可见性变化，当用户从外部应用切回Outlook时，重新注册ItemChanged事件：

// 保存事件处理器引用，用于重复注册/移除
const itemChangedHandler = selectedMailItemChanged;

// 初始注册事件
registerItemChangedHandler();

async function registerItemChangedHandler() {
  try {
    // 先移除旧处理器，避免重复绑定
    await Office.context.mailbox.removeHandlerAsync(Office.EventType.ItemChanged, itemChangedHandler);
    // 重新注册事件
    await Office.context.mailbox.addHandlerAsync(Office.EventType.ItemChanged, itemChangedHandler);
  } catch (err) {
    console.error("事件注册失败:", err);
  }
}

async function selectedMailItemChanged(eventArgs){
    console.log("邮件选择已变更");
}

// 页面重新可见时自动注册事件
document.addEventListener('visibilitychange', () => {
  if (!document.hidden) {
    registerItemChangedHandler();
  }
});

// 加载项初始化时确保事件注册
Office.initialize = () => {
  registerItemChangedHandler();
};

2. 手动处理链接点击 #

修改链接的点击逻辑，阻止默认跳转行为后手动启动外部应用，并立即重新注册事件：

<a onclick="openShipment(event, shipment.fetch_id)">
  <span>Open Shipment</span>
</a>

<script>
async function openShipment(event, shipmentId) {
  event.preventDefault();
  // 手动启动外部应用
  window.open(`edient:Command=ShowEditForm&LicenceCode=XXXXXX&ControllerID=JobShipment&BusinessEntityPK=${shipmentId}`);
  // 立即重新注册事件
  await registerItemChangedHandler();
}
</script>

3. 检查加载项激活设置 #

在Outlook中确认加载项的激活模式：

• 进入「设置 > 加载项」，找到你的自定义加载项
• 确保未设置为「仅在使用时激活」，该模式会导致加载项在失去焦点后被挂起，事件绑定失效

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