Outlook安卓App加载项通知显示及addAsync接口异常咨询

安卓端基于校验规则展示加载项通知的实现方案 #

• 先明确客户端支持边界：Outlook 安卓端对原生通知接口的支持存在版本门槛，仅16.0.13127及以上版本开放了邮件页内联通知的渲染容器，更低版本无对应承载位，直接调用原生接口不会有任何展示。
• 高版本原生适配方案：
  调用接口前先通过Office.context.requirements.isSetSupported('Mailbox', '1.10')做能力检测，确认支持后再调用原生接口，通知类型必须选择PersistentMessage（安卓端不支持悬浮类通知样式），图标参数必须传入16*16像素png格式的base64编码值，传入外链或本地路径都会导致通知渲染失败。
• 全版本兼容方案：
  不满足原生接口支持条件时，直接在加载项自身的运行容器（任务面板、内嵌命令面板）顶部注入固定定位的自定义通知条DOM，按照预设校验规则触发展示即可，样式、交互完全可控，不受客户端版本限制，是目前安卓端适配成本最低、兼容性最高的方案。

Office.context.mailbox.item.notificationMessages.addAsync安卓端不生效的解决建议 #

• 前置能力校验缺失是最常见诱因：低版本Outlook安卓端没有实现该接口，调用后不会抛出明确错误，只会静默失败，必须在调用前先执行能力检测，不支持时直接走自定义通知逻辑，不要直接调用接口。
• 严格对齐安卓端入参要求，安卓端对参数的校验规则比桌面端、iOS端更严格，不符合要求的参数会直接触发静默失败：
  • 通知ID长度不能超过32位，不能包含特殊字符
  • 通知文本message长度不能超过150字，超长会被直接拦截
  • 通知类型仅支持Office.MailboxEnums.ItemNotificationMessageType.PersistentMessage，传入其他类型均无法展示
  • 图标icon字段必须传入标准base64编码的png资源，不支持外链、相对路径资源
• 调整调用时机：必须等Office.initialize回调执行完成、且当前邮件项的自定义属性/正文等资源加载完成后再调用接口，初始化未完成时调用会因为item对象未就绪导致失败，参考正确调用示例：

Office.initialize = () => {
  Office.context.mailbox.item.loadCustomPropertiesAsync((loadResult) => {
    if (loadResult.status === Office.AsyncResultStatus.Succeeded) {
      // 先执行业务校验逻辑，再调用通知接口
      Office.context.mailbox.item.notificationMessages.addAsync(
        "validation_tip",
        {
          type: Office.MailboxEnums.ItemNotificationMessageType.PersistentMessage,
          message: "当前邮件缺少必填审批标识，请补充后再发送",
          icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH5gMVESkqQfK6fAAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAUSURBVDjLY2AYBaNgFIyCUTAKRsEAAH+gAAEv/Q0fAAAAAElFTkSuQmCC"
        },
        (result) => {
          if (result.status !== Office.AsyncResultStatus.Succeeded) {
            // 原生接口调用失败时兜底走自定义通知逻辑
            renderCustomNotice("当前邮件缺少必填审批标识，请补充后再发送")
          }
        }
      )
    }
  })
}

• 兜底方案：如果完成以上调整后接口仍无法正常展示，直接放弃原生通知接口，统一使用加载项内部自定义通知条实现，该方案可覆盖所有安卓端Outlook版本，不会因为客户端版本差异、灰度策略导致通知失效。

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