如何在Word JS API中遍历RangeCollection实现查找结果循环跳转

开发者阿泽

2026-9-26

解决方案

你之前的代码不生效是因为getNext()是单个Range对象的方法，用于获取文档结构中与当前Range同级的下一个Range，并非搜索结果集合中的下一个匹配项，所以无法实现需求。我们可以通过预加载所有匹配结果、维护全局当前匹配索引的方式实现逐个跳转的需求：

定义全局变量存储匹配的Range集合、当前选中的匹配项索引、上次搜索的关键词
首次触发查找或搜索词变更时，执行搜索加载所有匹配结果存入全局变量
后续触发跳转时直接更新索引，选中对应位置的匹配项即可

完整可运行代码

// 全局变量：匹配结果集合、当前匹配索引、上次搜索关键词
let matchRanges = [];
let currentMatchIndex = -1;
let lastSearchKeyword = "";

async function scrollToNextMatch() {
  // 此处可替换为从输入框动态获取的搜索词
  const targetKeyword = "and";
  await Word.run(async (context) => {
    // 搜索词变更时重置状态重新搜索
    if (targetKeyword !== lastSearchKeyword) {
      matchRanges = [];
      currentMatchIndex = -1;
      lastSearchKeyword = targetKeyword;

      // 执行搜索并加载所有匹配项
      const searchResults = context.document.body.search(targetKeyword, {
        matchWholeWord: true,
        matchCase: false
      });
      searchResults.load("items");
      await context.sync();

      matchRanges = searchResults.items;
      if (matchRanges.length === 0) {
        console.log("未找到匹配内容");
        return;
      }
    }

    if (matchRanges.length === 0) return;
    // 计算下一个匹配索引，遍历到末尾后自动回到开头循环
    currentMatchIndex = (currentMatchIndex + 1) % matchRanges.length;
    // 选中对应匹配项，Word会自动滚动到对应位置
    matchRanges[currentMatchIndex].select();
    await context.sync();
  });
}