避免在循环中使用 context.sync

注意

本文假定你已超过使用四个特定于应用程序的 Office JavaScript API(适用于 Excel、Word、OneNote 和 Visio)中至少一个的开始阶段,这些 API 使用批处理系统与 Office 文档交互。 特别是,您应该知道调用 context.sync 的作用,并且应该知道集合对象是什么。 如果你尚未处于该阶段,请从 了解 Office JavaScript API 和该文章中“特定于应用程序”下链接的文档开始。

使用 特定于应用程序的 API 模型 之一的 Office 加载项可能会出现要求代码从集合对象的每个成员读取或写入某些属性的情况。 例如,获取特定表列中每个单元格值的 Excel 加载项或突出显示文档中字符串的每个实例的 Word 加载项。 您将需要循环访问集合对象属性中的 items 成员;但是,出于性能原因,您应该避免在循环的每次迭代中调用 context.sync 。 每次调用 context.sync 都是从加载项到 Office 文档的往返。 重复的往返会影响性能,尤其是在加载项在 Office web 版中运行时,因为往返是通过 Internet 进行的。

注意

本文中的所有示例都使用 for 循环,但所述做法适用于可循环访问数组的任何循环语句,包括:

  • for
  • for of
  • while
  • do while

它们还适用于任何数组方法,该方法将函数传递并应用于数组中的项目,包括:

  • Array.every
  • Array.forEach
  • Array.filter
  • Array.find
  • Array.findIndex
  • Array.map
  • Array.reduce
  • Array.reduceRight
  • Array.some

注意

通常,最好将 have final context.sync 放在应用程序 run 函数 (Excel.run的结束“}”字符之前,例如 , Word.run等 ) 。 这是因为该 run 函数进行隐藏调用 context.sync ,这是当且仅当存在尚未同步的排队命令时,它才会执行的最后一件事。 此调用是隐藏的这一事实可能会令人困惑,因此我们通常建议您添加显式。context.sync 然而,鉴于本文是关于最小化 context.sync调用 ,添加一个完全不必要的 final context.sync实际上更加令人困惑。 因此,在本文中,如果末尾 run没有未同步的命令,我们就省略了它。

写入文档

在最简单的情况下,仅写入集合对象的成员,而不读取其属性。 例如,以下代码用黄色突出显示 Word 文档中的每个“the”实例。

await Word.run(async function (context) {
  let startTime, endTime;
  const docBody = context.document.body;

  // search() returns an array of Ranges.
  const searchResults = docBody.search('the', { matchWholeWord: true });
  searchResults.load('font');
  await context.sync();

  // Record the system time.
  startTime = performance.now();

  for (let i = 0; i < searchResults.items.length; i++) {
    searchResults.items[i].font.highlightColor = '#FFFF00';

    await context.sync(); // SYNCHRONIZE IN EACH ITERATION
  }
  
  // await context.sync(); // SYNCHRONIZE AFTER THE LOOP

  // Record the system time again then calculate how long the operation took.
  endTime = performance.now();
  console.log("The operation took: " + (endTime - startTime) + " milliseconds.");
})

在 Windows 上的 Word 中,在包含 200 个“the”实例的文档中,上述代码用了整整 1 秒钟才能完成。 但是,当循环内的行被注释掉,并且循环后的同一行被取消注释时 await context.sync(); ,该操作只用了 1/10 秒。 在以 Edge 为浏览器) 的 Word Web (中,循环内同步仅用了整整 3 秒,循环后同步仅用了 6/10 秒,大约快了五倍。 在包含 2000 个“the”实例的文档中,在 Web 上的 Word 中 (循环内同步) 80 秒,循环后同步仅用了 4 秒,大约快了 20 倍。

注意

值得问的是,如果同步并发运行,“循环内同步”版本是否会执行得更快,这可以通过简单关键字 (keyword) 地await从 .context.sync() 这将导致运行时启动同步,然后立即开始循环的下一次迭代,而无需等待同步完成。 但是,由于以下原因,这不如完全退出 context.sync 循环更好的解决方案。

  • 正如同步批处理作业中的命令排队一样,批处理作业本身在 Office 中排队,但 Office 支持队列中不超过 50 个批处理作业。 更多触发器错误。 因此,如果循环中的迭代次数超过 50 次,则可能会超出队列大小。 迭代次数越多,发生这种情况的可能性就越大。
  • “同时”并不意味着同时。 执行多个同步操作仍然比执行一个同步操作需要更长的时间。
  • 并发操作不保证以与它们开始的顺序相同的顺序完成。 在上面的示例中,突出显示单词“the”的顺序并不重要,但在某些情况下,按顺序处理集合中的项目非常重要。

使用拆分循环模式从文档中读取值

当代码在处理每个集合项时必须读取集合项的属性时,避免context.sync进入循环就变得更具挑战性。 假设代码需要迭代 Word 文档中的所有内容控件,并记录与每个控件关联的第一段文本。 你的编程本能可能会导致你循环访问控件,加载 text 每个 (第一个) 段落的属性,调用 context.sync 以使用文档中的文本填充代理段落对象,然后记录它。 示例如下。

Word.run(async (context) => {
    const contentControls = context.document.contentControls.load('items');
    await context.sync();

    for (let i = 0; i < contentControls.items.length; i++) {
      // The sync statement in this loop will degrade performance.
      const paragraph = contentControls.items[i].getRange('Whole').paragraphs.getFirst(); 
      paragraph.load('text');
      await context.sync();
      console.log(paragraph.text);
    }
});

在这种情况下,为了避免出现 a context.sync 在循环中,您应该使用我们称之为 拆分循环 模式的模式。 在对它进行正式描述之前,让我们先看看该模式的具体示例。 下面介绍如何将拆分循环模式应用于前面的代码段。 对于此代码,请注意以下事项。

  • 现在有两个循环, context.sync 它们之间,所以两个循环中都没有 context.sync 。
  • 第一个循环会循环访问集合对象中的项目并加载text属性,就像原始循环一样,但第一个循环无法记录段落文本,因为它不再包含context.synctext填充代理对象的paragraph属性。 相反,它将 paragraph 对象添加到数组中。
  • 第二个循环循环访问第一个循环创建的数组,并记录 text 每个 paragraph 项目的 。 这是可能的,因为 context.sync 两个循环之间的 填充了所有 text 属性。
Word.run(async (context) => {
    const contentControls = context.document.contentControls.load("items");
    await context.sync();

    const firstParagraphsOfCCs = [];
    for (let i = 0; i < contentControls.items.length; i++) {
      const paragraph = contentControls.items[i].getRange('Whole').paragraphs.getFirst();
      paragraph.load('text');
      firstParagraphsOfCCs.push(paragraph);
    }

    await context.sync();

    for (let i = 0; i < firstParagraphsOfCCs.length; i++) {
      console.log(firstParagraphsOfCCs[i].text);
    }
});

上面的示例建议了以下过程,用于将包含 的 context.sync 循环转换为拆分循环模式。

  1. 将循环替换为两个循环。
  2. 创建第一个循环以循环访问集合并将每个项目添加到数组中,同时加载代码需要读取的项目的任何属性。
  3. 按照第一个循环 context.sync ,使用任何加载的属性填充代理对象。
  4. 按照第二个循环的 循环访问 context.sync 第一个循环中创建的数组并读取加载的属性。

使用“相关对象”模式处理文档中的对象

让我们考虑一个更复杂的方案,在这种情况下,处理集合中的项目需要不在项目本身中的数据。 该方案设想了一个 Word 加载项,它对从包含一些样本文本的模板创建的文档进行操作。 文本中散布着以下占位符字符串的一个或多个实例:“{Coordinator}”、“{Deputy}”和“{Manager}”。 加载项将每个占位符替换为某个人的姓名。 虽然加载项的 UI 对本文并不重要,但该加载项可以有一个带有三个文本框的任务窗格,每个文本框标有其中一个占位符。 用户在每个文本框中输入名称,然后按 “替换 ”按钮。 按钮的处理程序会创建一个数组,该数组将名称映射到占位符,然后将每个占位符替换为分配的名称。

可以使用 Script Lab 工具按照此处显示的代码片段进行操作。 在 Word 中,可以加载“相关对象模式”示例,或从 GitHub 存储库导入此示例代码。

以下赋值语句在占位符和分配的名称之间创建映射数组。

const jobMapping = [
        { job: "{Coordinator}", person: "Sally" },
        { job: "{Deputy}", person: "Bob" },
        { job: "{Manager}", person: "Kim" }
    ];

以下代码演示了如何在循环中使用每个占位符为其分配的名称 context.sync 。 这对 replacePlaceholdersSlow 应于示例中的函数。

Word.run(async (context) => {
    // The context.sync calls in the loops will degrade performance.
    for (let i = 0; i < jobMapping.length; i++) {
      let options = Word.SearchOptions.newObject(context);
      options.matchWildcards = false;
      let searchResults = context.document.body.search(jobMapping[i].job, options);
      searchResults.load('items');

      await context.sync(); 

      for (let j = 0; j < searchResults.items.length; j++) {
        searchResults.items[j].insertText(jobMapping[i].person, Word.InsertLocation.replace);

        await context.sync();
      }
    }
});

在前面的代码中,有一个外部循环和一个内部循环。 它们中的每一个都包含一个 context.sync 调用。 根据本文中的第一个代码段,你可能会看到可以 context.sync 简单地在内部循环之后移动内部循环中的 。 但这仍然会让代码 context.sync (其中两个实际上) 在外部循环中。 以下代码演示如何从循环中删除 context.sync 。 它对 replacePlaceholders 应于示例中的函数。 我们稍后会讨论代码。

Word.run(async (context) => {

    const allSearchResults = [];
    for (let i = 0; i < jobMapping.length; i++) {
      let options = Word.SearchOptions.newObject(context);
      options.matchWildcards = false;
      let searchResults = context.document.body.search(jobMapping[i].job, options);
      searchResults.load('items');
      let correlatedSearchResult = {
        rangesMatchingJob: searchResults,
        personAssignedToJob: jobMapping[i].person
      }
      allSearchResults.push(correlatedSearchResult);
    }

    await context.sync()

    for (let i = 0; i < allSearchResults.length; i++) {
      let correlatedObject = allSearchResults[i];

      for (let j = 0; j < correlatedObject.rangesMatchingJob.items.length; j++) {
        let targetRange = correlatedObject.rangesMatchingJob.items[j];
        let name = correlatedObject.personAssignedToJob;
        targetRange.insertText(name, Word.InsertLocation.replace);
      }
    }

    await context.sync();
});

请注意,该代码使用拆分循环模式。

  • 上例中的外部循环已拆分为两部分。 (第二个循环有一个内部循环,这是预期的,因为代码正在循环访问一组作业 (或占位符) ,并且在该集中,它正在循环访问匹配范围。)
  • 每个主要循环之后都有一个 context.sync ,但任何循环中都没有 context.sync 。
  • 第二个主要循环循环访问第一个循环中创建的数组。

但是,在第一个循环中创建的数组 并不 像第一个循环在“ 使用拆分循环模式从文档读取值”部分中所做的那样只包含 Office 对象。 这是因为处理 Word Range 对象所需的某些信息并不在 Range 对象本身中,而是来自jobMapping数组。

因此,在第一个循环中创建的数组中的对象是具有两个属性的自定义对象。 第一个是与特定职务 (匹配的Word范围数组,即占位符字符串) 第二个是提供分配给该职位的人员姓名的字符串。 这使得最终循环易于编写和阅读,因为处理给定范围所需的所有信息都包含在包含该范围的同一自定义对象中。 应替换 correlatedObject.rangesMatchingJob.items[j] 的名称是同一对象的另一个属性:correlatedObject.personAssignedToJob。

我们将这种拆分循环模式的变体称为 相关对象 模式。 一般思路是,第一个循环创建自定义对象数组。 每个对象都有一个属性,其值是 Office 集合对象 (中的某个项目,或是此类项目) 的数组。 自定义对象具有其他属性,每个属性都提供在最终循环中处理 Office 对象所需的信息。 有关自定义关联对象具有两个以上属性的示例的链接,请参阅 这些模式的其他示例 部分。

还有一个警告:有时仅创建自定义关联对象的数组就需要多个循环。 如果您需要读取一个 Office 集合对象的每个成员的属性,只是为了收集用于处理另一个集合对象的信息,则可能会发生这种情况。 (例如,代码需要读取 Excel 表中所有列的标题,因为加载项将根据该列的标题对某些列的单元格应用数字格式。) 但是,您始终可以将 s 保留在 context.sync循环之间,而不是在循环中。 有关示例,请参阅 “这些模式的其他示例 ”部分。

这些模式的其他示例

  • 有关使用 Array.forEach 循环的 Excel 的一个非常简单的示例,请参阅此 Stack Overflow 问题的公认答案: 是否可以在 context.sync 之前将多个 context.load 排队?
  • 有关使用Array.forEach循环但不使用awaitasync/语法的 Word 的简单示例,请参阅此 Stack Overflow 问题的公认答案:使用 Office JavaScript API 使用内容控件迭代所有段落。
  • 如需高级 Word 示例,请将此 Gist 导入 Script Lab 工具。 有关使用 gist 的上下文,请参阅 Stack Overflow 问题: 替换文本后文档不同步的已接受答案。 此示例创建具有三个属性的自定义关联对象类型。 它总共使用三个循环来构造相关对象的数组,另外两个循环来进行最终处理。 混合了 for 和 Array.forEach 循环。
  • 尽管严格来说不是拆分循环或相关对象模式的示例,但有一个高级 Excel 示例演示了如何仅使用单个 context.sync. 若要试用,请打开 Script Lab 工具,然后搜索并导航到 Currency Converter 示例。

什么时候 不应 使用本文中的模式?

Excel web 版在给定context.sync调用中无法读取超过 5MB 的数据。 如果超出此限制,将引发错误。 (有关详细信息,请参阅 Office 加载项的资源限制和性能优化 的“Excel 加载项部分”。) 很少会接近此限制,但如果加载项有可能发生这种情况,则代码 不应 在单个循环中加载所有数据,而应在循环后使用 context.sync. 但是您仍然应该避免在对集合对象进行循环的每次迭代中都有 。context.sync 相反,定义集合中项目的子集,并依次循环每个子集,在循环之间使用 。context.sync 您可以使用一个外部循环来构建它,该循环迭代子集并在每个外部迭代中包含 。context.sync