Word AddIn开发疑问：Ajax .done返回Promise及内容控制器操作异常

一、解决 ContentControl 操作未生效的问题 #

你的代码里有两个核心问题导致 ContentControl 相关操作没效果：

1. 缺少 context.sync() 调用
   Word.js 采用批处理同步模型——所有对 Office 对象（比如 ContentControl）的修改都只是在本地上下文（context）里暂存，必须调用 context.sync() 才能把这些变更同步到实际的 Word 文档中，否则你的操作只会停留在内存里，不会真正生效。

2. 使用了 async:false 的同步 Ajax
   同步 Ajax 会阻塞主线程，而 Word.run 本身是异步执行的，这种混合模式会彻底打乱 Office.js 的执行流程，导致上下文同步失败。绝对不建议在 Word Add-in 里用同步 Ajax，完全违背了 Office 插件的异步设计原则。

修正后的基础代码框架如下：

function setUp() { 
  Word.run(async (context) => { 
    // 1. 获取目标 ContentControl（示例：获取所有内容控件并加载所需属性）
    let contentControls = context.document.contentControls;
    contentControls.load('tag, text'); 

    // 2. 同步上下文，拉取实际的 ContentControl 数据
    await context.sync();

    // 3. 执行 ContentControl 操作（示例）
    if (contentControls.items.length > 0) {
      const targetCC = contentControls.items[0];
      console.log("当前标签名：", targetCC.tag);
      // 替换文本内容
      targetCC.text = "替换后的新内容";
      // 在文档末尾插入条目长度
      context.document.body.insertParagraph(`内容控件总数：${contentControls.items.length}`, Word.InsertLocation.end);
    }

    // 4. 同步上下文，将所有变更应用到文档
    await context.sync();

    // 异步发起 Ajax 请求（去掉同步设置）
    const endpoint = "https://graph.microsoft.....";
    try {
      const response = await $.ajax({ 
        url: endpoint, 
        dataType: 'json',
        // 可添加授权头等必要参数
        headers: {
          // 'Authorization': 'Bearer ' + yourToken
        }
      });
      // 用返回的数据继续操作 Word 内容
      console.log("Graph 接口返回：", response);
      if (contentControls.items.length > 0) {
        contentControls.items[0].text = response.targetField;
        await context.sync(); // 同步最新变更
      }
    } catch (error) {
      console.error("请求失败：", error);
    }
  })
  .catch(error => {
    console.error("Word 操作出错：", error);
  });
}

二、在 Ajax 中正确处理 Promise #

jQuery 的 $.ajax() 本身就返回一个 Promise 对象（从 jQuery 3.0 开始），完全不需要在 .done() 里手动返回 Promise，直接用以下两种方式处理即可：

方式1：用 async/await 处理（推荐，代码更直观） #

把 Word.run 的回调改成 async 函数，直接用 await 等待 Ajax 请求完成，代码逻辑是线性的，可读性更强，就像上面示例里写的那样。

方式2：用 Promise 链式调用（兼容旧环境） #

如果你的运行环境不支持 async/await，可以用 .then() 链式处理请求：

function setUp() { 
  Word.run((context) => { 
    let contentControls = context.document.contentControls;
    contentControls.load('tag, text');

    return context.sync()
      .then(() => {
        // 同步上下文后发起 Ajax 请求
        const endpoint = "https://graph.microsoft.....";
        return $.ajax({ url: endpoint, dataType: 'json' });
      })
      .then(response => {
        // 处理返回数据并更新 Word 内容
        console.log("接口返回数据：", response);
        if (contentControls.items.length > 0) {
          contentControls.items[0].text = response.data;
        }
        return context.sync(); // 同步最新变更
      });
  })
  .catch(error => {
    console.error("操作失败：", error);
  });
}

关键注意事项 #

• 永远不要在 Word.run 里用同步 Ajax，会导致上下文死锁或操作失效；
• 所有涉及 Office 对象的修改，都必须调用 context.sync() 来同步到文档；
• 把 Ajax 请求整合到 Word.run 的 Promise 链中，确保操作的顺序性。

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