选项卡应用的应用挂起

当用户离开应用时，可以暂停或终止该应用。 挂起意味着应用在后台，对用户不可见。 终止意味着应用已完全关闭并从内存中删除。 暂停应用可缩短 Teams 或其他Microsoft 365 产品中应用的后续启动时间，方法是允许将一些资源和资产保留在内存中，以便在解除冻结应用时使用。

以前，应用挂起称为缓存应用，仅在 Teams 中受支持，但现在支持扩展到其他 Microsoft 365 应用程序上运行的 Teams 应用。

在 Teams 中，以下范围和客户端支持应用挂起：

启用应用挂起

若要启用应用挂起，请执行以下步骤：

1. 调用 app.lifeCycle.registerBeforeSuspendOrTerminate 和 app.lifeCycle.registerOnResumeHandler API。 需要这些处理程序才能启用应用挂起。 有关详细信息，请参阅 TeamsJS 参考中提供的 生命周期模块 。

   处理程序 app.lifecycle.registerBeforeSuspendOrTerminate 使你有机会在应用挂起或终止之前执行某些任务，而 app.lifecycle.registerOnResumeHandler 当用户导航回你的应用时，将调用 。

   注册这两个处理程序可让应用暂停应用，但请务必了解，注册并不保证应用不会在后台终止。 应用是否终止取决于其他因素，例如可用内存。

   注意

   以前teamsCore.registerBeforeUnloadHandlerteamsCore.registerOnLoadHandler和 用于启用应用缓存，但现在已弃用。

2. 使用 contentUrl 并 entityId 传递到恢复处理程序，以路由到应用中的正确页面，并调用 notifySuccess 或 notifyFailure 通知主机应用初始化流已完成。

   • contentUrl：添加内容页 URL。
   • entityId：添加唯一标识符。

3. 释放资源并执行处理程序中 beforeSuspendOrTerminate 所需的任何清理。

下面的流程图显示了想要选择加入应用挂起的应用的首次启动， (首次启动应用时注册 resume 或 beforeSuspensionOrTerminate 处理程序) ：

以程图显示了挂起的应用的启动：

选择加入应用挂起时，当用户导航到窗口中应用的不同实例时，将重复使用用于托管嵌入应用的 iframe 或 Web 视图。 当用户离开应用时，用于托管应用的 iframe 或 Web 视图处于隐藏状态，并在用户返回应用时显示。

应用不挂起或应用从缓存中删除有多种原因。 Microsoft 365 个应用的一些一般原因包括：

• 总内存负载较高。
• 挂起的应用总数超出了最大缓存大小。 在这种情况下，将删除最早挂起的应用。
• 如果计算机的可用内存不足，应用将终止。
• 应用会暂停很长时间，而不会恢复。
• 应用无法加载，并且已终止。

在 Teams 应用中，某些原因 (此处的数字可能会) 更改：

• 如果系统内存负载较高，则会从缓存中删除该应用。
• 如果 Teams 在发送通知后 30 秒内未收到 readyToUnload 来自 TeamsJS 的信号，则 beforeUnload 应用将终止。
• 如果系统内存小于 4 GB，或者 Windows 上的可用内存小于 1 GB 或 Mac 上的 512 MB，则会禁用应用挂起。
• 侧面板是会议中应用挂起的唯一受支持的 frameContext。
• 受邀用户计数超过 20 的会议不支持应用挂起。
• 在 iOS 上，当 Teams 应用终止时，将从缓存中删除该应用。

代码示例

以下代码片段是 和 app.lifecycle.registerBeforeSuspendOrTerminateHandler API 的示例app.lifecycle.registerOnResumeHandler：

MicrosoftTeams.app.lifecycle.registerOnResumeHandler((data) => {  

   console.log("got resume call" , data.contentUrl, data.entityId);  

   // use contentUrl to route to correct page  
   // invoke notifySuccess when ready  

   app.notifySuccess();  

}); 

MicrosoftTeams.app.lifecycle.registerBeforeSuspendOrTerminateHandler(() => {  

   // dispose resources and resolve promise 

}); 

缓存应用的调试工具

可以在 Teams 中启用 Proto 任务管理器，这是一种调试工具，用于显示缓存应用的状态。 在 Teams 客户端中，选择 Windows 上的 Control+Shift+Alt+8 键或 Mac 上的 Command+Shift+Option+8 以打开 Proto 任务管理器。

“ AppCaching ”选项卡包含以下详细信息：

• 状态：显示应用的缓存或未缓存状态。
• isActive：显示缓存应用的活动或非活动状态。
• timeElapsed：显示自缓存应用以来经过的时间。
• supportsLoad：如果启用了应用缓存，则显示应用是否注册了 Load 处理程序。
• supportsBeforeUnload：如果启用了应用缓存，则显示应用是否注册了 BeforeUnload 处理程序。
• totalFrameMemory：显示应用的内存使用情况。
• totalFrameCommitMemory：显示应用的 CPU 使用率。

预缓存选项卡应用

虽然缓存可以减少应用的后续加载时间，但预缓存通过允许 Teams 预加载应用来优化应用的初始加载时间。 Teams 根据用户最近的应用使用模式和应用的缓存历史记录，在启动后或空闲时在后台预加载应用。 预加载的应用将一直缓存到用户打开应用，从而缩短加载时间。

如果启用预缓存，则应用会利用资源，并且遥测数据在处于预缓存状态时被跟踪。 若要了解如何优化应用进行预讲，请参阅 最佳做法。

为选项卡应用启用预缓存

若要为选项卡应用启用预缓存，请执行以下步骤：

1. 启用应用缓存。

2. 按如下所示更新应用清单：

   1. 将 的值 showLoadingIndicator 设置为 true。 此作可确保 Teams 等待，直到应用发送 notifySuccess ，以在预缓存期间结束应用加载序列。 有关详细信息，请参阅 showLoadingIndicator。

   2. backgroundLoadConfiguration添加 对象并定义 contentUrl。

      {
      "backgroundLoadConfiguration": {
          "tabConfiguration": {
              "contentUrl": "https://www.contoso.com/content?host=msteams&isBackgroundLoad=true"
              }
          }
      }
      

      注意

      • 不能 contentUrl 包含特定于上下文的参数，例如团队网站 URL 或线程 ID，因为 Teams 在启动期间加载应用时没有先前的上下文。
      • 必须 contentUrl 足够通用，可以在后台加载而无需任何用户交互。

      有关详细信息，请参阅 backgroundLoadConfiguration。

监视后台加载

如果你监视 属性，则可以确定 Teams 是否在没有用户交互的情况下在后台加载了应用 isBackgroundLoad 。 如果该属性的状态为 true，则表示 Teams 在后台加载了应用，并且无法与用户交互。 因此，应用不需要呈现 UI 元素，例如登录提示。

isBackgroundLoad监视应用上下文中的 属性，以优化应用，以便有效地进行预缓存加载和呈现。 有关详细信息，请参阅 isBackgroundLoad。

最佳做法

下面是应用挂起和预传的最佳做法：

• 建议实现 Web 存储或服务辅助角色功能，以在本地存储数据或 Web 视图。 此策略有助于在后续启动中更快地加载应用。

• 在启动序列中尽早注册应用挂起处理程序，例如在调用 app.initialize 后和应用发送 notifySuccess之前。 如果用户在离开应用之前 Teams 客户端未看到这些注册，则不会缓存该应用。

• 尝试在调用处理程序且应用即将挂起时 app.lifecycle.onBeforeSuspendOrTerminateHandler 减少内存占用量。 例如，发布引用、删除 eventListeners、暂停同步调用或停止网络请求。

• 除用户发起的请求外，预缓存还会增加应用流量。 确保作为 contentUrl 提供的终结点可以在一天内为每个用户处理多次后台请求。 确保进行所需的遥测调整以适应应用的后台加载。

• 确保应用在预分配状态下使用的内存小于或等于 130 MB。

常规限制

以下是应用挂起的一般限制：

• 无法保证应用会被暂停。 即使应用注册了所需的处理程序，也有可能导致应用终止的原因。

• 仅当用户离开应用时，应用才会暂停。 如果应用有多个静态选项卡，当用户在选项卡之间切换时，该选项卡不会暂停。 仍会调用处理程序 app.lifecycle.onBeforeSuspendOrTerminate。

• 挂起的应用可以在同一窗口中使用。 在弹出窗口中挂起的应用不能在“主”窗口中重复使用。

• 暂停应用时，将删除所有已注册的处理程序。 恢复应用后，需要重新注册所有处理程序（如 themeChange 或 focusEnter）。 挂起时不会向应用发送通知。 如果应用即使在暂停时也需要通知，则挂起可能不是正确的解决方案。

• 只有使用客户端路由进行页面导航的单页应用才能从应用挂起和恢复中受益。 建议在应用启动的所有上下文中使用相同的域。

• 应用在挂起时应处于睡眠状态。 当应用挂起时，不允许 SDK 请求。

• 仅当完成应用序列后，suspendOrTerminate主机应用才会调用resume处理程序。 例如，如果用户启动应用的选项卡 A，然后启动同一应用的选项卡 B，则在执行选项卡 A 上的处理程序之前suspendOrTerminate，选项卡 B 不会获得resume信号。

• 应用按窗口缓存。 应用缓存发生在每个应用 (而不是在同一窗口中) 每个选项卡。

• 介绍性部分中的 表“选项卡应用暂停”提供了有关 frameContext Teams 支持缓存的信息。 对于非 Teams 中心，仅 FrameContext.Content 缓存，这意味着 FrameContext.Task 不支持内部 Dialog 。

• 如果应用不需要应用挂起，但需要时间安全地保存状态 (则仅 beforeSuspendOrTerminate 注册处理程序，因为离开应用可能会导致应用内容突然从文档对象模型 (DOM) ) 中删除。 如果应用尚未注册 resume 事件，则流完成后，该应用将从 DOM suspendOrTerminate 中删除。

Teams 中的限制

以下是 Teams 应用中应用挂起的限制：

• 只有在完成应用序列后，suspendOrTerminateTeams 客户端才会调用resume处理程序。 例如，如果用户启动应用的选项卡 A，然后启动同一应用的选项卡 B，则在执行选项卡 A 上的处理程序之前suspendOrTerminate，选项卡 B 不会获得resume信号。

• 会议阶段或对话 (TeamsJS v1.x) 上下文中称为任务模块，因为可以在选项卡顶部打开，并且同一 iframe 或 Web 视图不能用于呈现选项卡和对话框中的内容。

• 按照本部分中的准则在 Teams 会议中将应用加入应用挂起。 对于仅在会议中的应用挂起支持，请注册 resume 或 beforeSuspendOrTerminate 处理程序（如果上下文为 sidePanel）。

疑难解答

应用未暂停？ 为什么在后续导航上不调用恢复处理程序？

• 验证是否满足系统和可用内存约束。

• 减少缓存时的内存占用量。 beforeSuspendOrTerminate使用 处理程序释放资源，例如，释放引用并删除缓存时可能不需要的事件侦听器。

代码示例

另请参阅

• 创建个人选项卡
• 创建频道选项卡或组选项卡
• 会议的“生成”选项卡