选项卡应用的应用缓存

应用缓存允许将一些资源和资产保留在内存中，以便在解除冻结应用时使用，从而缩短 Teams 中应用的后续启动时间。

以下各项支持应用缓存：

启用应用缓存

若要启用应用缓存，请执行以下步骤：

1. 调用 teamsCore.registerBeforeUnloadHandler 和 teamsCore.registerOnLoadHandler API。

2. 使用 contentUrl 并 entityId 传递到加载处理程序，以路由到应用中的正确页面，并调用 notifySuccess 或 notifyFailure 通知 Teams 客户端应用初始化流已完成。

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

3. 释放资源并执行处理程序中 beforeUnload 所需的任何清理，然后调用 readyToUnload 回调以通知 Teams 客户端应用卸载流已完成。

下面是想要选择加入应用缓存的应用的首次启动的流程图， (在首次启动应用时注册 load 或 beforeUnload) ：

下面是启动缓存应用的流程图：

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

应用无法缓存或从缓存中删除应用的原因有多种，其中一些原因 (此处的数字可能会) 更改：

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

代码示例

以下代码片段是 和 teamsCore.registerBeforeUnloadHandler API 的示例teamsCore.registerOnLoadHandler：

microsoftTeams.teamsCore.registerOnLoadHandler((data) => {
    console.log("got load from TEAMS", data.contentUrl, data.entityId);
    // use contentUrl to route to correct page 
    // invoke notifySuccess when ready  
    app.notifySuccess();
});
microsoftTeams.teamsCore.registerBeforeUnloadHandler((readyToUnload) => {
    // dispose resources and then invoke readyToUnload
    readyToUnload();
    return true;
});

缓存应用的调试工具

可以在 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 视图。 这有助于在后续启动中更快地加载应用。

• beforeUnload在调用 app.initialize 后和应用发送 notifySuccess之前注册 和 onLoad 处理程序。 如果用户在离开应用之前 Teams 客户端未看到这些注册，则不会缓存该应用。

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

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

限制

下面是应用缓存的限制：

• 使用客户端路由进行页面导航的单页应用可以从应用缓存中受益。 建议在应用启动的所有上下文中使用相同的域。

• 应用需要在加载处理程序中重新注册 、 focusEnter等事件themeChange。 Teams 客户端在缓存后不会向应用发送任何通知。 如果你的应用即使在缓存时也需要通知，则缓存可能不是正确的解决方案。

• Teams 客户端仅在完成应用序列后unload调用 loadHandler 。 例如，如果用户启动应用的选项卡 A，然后启动同一应用的选项卡 B，则在选项卡 A 调用 readyToUnload 回调之前，选项卡 B 不会获取加载信号。

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

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

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

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

• 当缓存 (使用最少的计算或网络资源并将 SDK 请求) 最小化时，应用应进入睡眠状态。 缓存应用时，允许所有寄存器处理程序和以下 SDK 请求：

  • initialize
  • notifyappLoaded
  • notifySuccess
  • notifyFailure
  • notifyExpectedFailure
  • getContext
  • getAuthToken
  • readyToUnload
  • getConfig/getSettings

疑难解答

未缓存应用？ 为什么在后续导航上不调用负载处理程序？

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

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

代码示例

另请参阅

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