Word Add-in JS RichAPI调用getText()触发GeneralException异常咨询

异常原因 #

这个GeneralException是Office 365 2308版本（内部版本16731.20948）的Word客户端与Office JS API的兼容性Bug。具体是调用getText({ IncludeHiddenText: false, IncludeTextMarkedAsDeleted: false})后执行同步时触发的内部逻辑错误，后续2501版本已修复该问题，说明微软在新版本中针对该API的参数处理逻辑做了修正。

解决途径 #

1. 升级Office JS库 #

升级Office JS到适配2501及以上Office客户端的版本可解决问题，但需注意：若加载项需要兼容旧版本Office客户端，单纯升级JS库无法在2308版本中规避异常——因为Bug根源在客户端侧而非JS库本身。

2. 实现降级 fallback 机制 #

若要兼容老版本Office，建议实现getText与getReviewedText的 fallback 逻辑：

• 优先尝试调用getText方法并捕获GeneralException异常；
• 触发异常时自动切换为getReviewedText方法替代。

代码示例（带fallback逻辑） #

await Word.run(async (context) => {
  const document = context.document;
  const body = document.body;
  const paragraphs = body.paragraphs;

  paragraphs.load({ $all: true });
  let listItems = [];
  let paragraphText = {};
  await context.sync();

  for (let i = 0; i < paragraphs.items.length; i++) {
    paragraphGUIDHash.set(paragraphs.items[i].uniqueLocalId, true);
    listItems.push(paragraphs.items[i].listItemOrNullObject);
    listItems[i].load("listString");
  }

  try {
    await context.sync();
  } catch (error) {
    console.log("Loading error for list paragraph api!!!");
  }

  // 实现fallback逻辑
  for (let i = 0; i < paragraphs.items.length; i++) {
    try {
      paragraphText[i] = paragraphs.items[i].getText({ 
        IncludeHiddenText: false, 
        IncludeTextMarkedAsDeleted: false
      });
    } catch (error) {
      // 捕获异常后切换为getReviewedText
      paragraphText[i] = paragraphs.items[i].getReviewedText();
    }
  }

  let sectionsJson = [];
  let currentSection = [];
  let sectionCount = 1;

  try {
    await context.sync();
  } catch (error) {
    console.log("Loading error for paragraph text!!!");
  }
})

补充说明 #

• getReviewedText本身返回不包含删除标记和隐藏文本的内容，和你传入参数的getText行为一致，作为降级方案完全可行；
• 若用户群体可强制升级Office版本，引导用户升级到2501及以上版本是最彻底的解决方式。

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