React开发MS Office任务窗格无法保存状态至.dg文件问题

• 场景：编辑Word模板时，在「AddField」标签页添加手动字段后，需要把this.state.addedFields的数据转成JSON格式，保存为.dg扩展名的文件；点击保存按钮时得弹出对话框让用户选保存位置。

两种失败的尝试 #

尝试1：浏览器端下载代码（Word任务窗格无响应） #

const handleSave = () => {
  const { addedFields } = this.state;
  const data = JSON.stringify(addedFields);
  const filename = "document.dg";

  const blob = new Blob([data], { type: "text/plain;charset=utf-8" });
  await saveAs(blob, filename);
}

问题：这段代码在普通浏览器里能正常触发下载，但Word任务窗格处于Office沙箱中，直接调用浏览器下载行为被限制，所以没反应。

尝试2：Electron+fs模块代码（模块解析失败） #

function onSaveButtonClick() {
  // Show the save dialog
  dialog.showSaveDialog({
    defaultPath: 'untitled.dg',
    filters: [{ name: 'DG Files', extensions: ['dg'] }]
  }).then(result => {
    if (result.filePath) {
      // Write the file
      const fileContent = 'Your file contents here'; // Replace with your actual file content
      fs.writeFile(result.filePath, fileContent, 'utf-8', err => {
        if (err) {
          console.error('An error occurred while saving the file:', err);
        } else {
          console.log('The file was saved successfully!');
        }
      });
    } else {
      console.log('The user did not select a file location');
    }
  }).catch(err => {
    console.error('An error occurred while showing the save dialog:', err);
  });
}

问题：Word任务窗格基于Office JavaScript API运行，不是Electron环境，根本用不了fs和Electron的dialog模块，所以会报模块无法解析的错。

正确解决方案：用Office JavaScript API实现 #

要在Word任务窗格里实现保存功能，必须用官方提供的Office JS API，步骤如下：

1. 确保引入Office JS API #

在项目的HTML页面里添加依赖：

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>

2. 编写保存按钮的处理函数 #

async function handleSaveFields() {
  try {
    // 获取字段数据并转成格式化的JSON字符串
    const { addedFields } = this.state;
    const fileContent = JSON.stringify(addedFields, null, 2);

    // 打开Office对话框（加载独立的保存页面）
    const filePicker = await Office.context.ui.displayDialogAsync(
      'https://你的插件域名.com/save-dialog.html', // 必须是同源或信任的页面
      {
        height: 30,
        width: 50,
        displayInIframe: true,
        title: '保存DG配置文件'
      }
    );

    // 监听对话框的消息回调
    filePicker.addEventHandler(Office.EventType.DialogMessageReceived, (args) => {
      if (args.message === 'save-success') {
        filePicker.close();
        console.log('配置文件保存成功');
      } else if (args.message.startsWith('error:')) {
        console.error('保存失败:', args.message.slice(6));
        filePicker.close();
      }
    });

    // 把要保存的内容传给对话框
    filePicker.messageParent(fileContent);
  } catch (error) {
    console.error('打开保存对话框失败:', error);
  }
}

3. 创建独立的保存对话框页面（save-dialog.html） #

因为任务窗格沙箱限制，得通过一个独立页面触发浏览器下载，页面内容如下：

<!DOCTYPE html>
<html>
<head>
  <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
</head>
<body>
  <script>
    Office.initialize = () => {
      // 监听来自任务窗格的内容
      Office.context.ui.addHandlerAsync(Office.EventType.DialogMessageReceived, (args) => {
        const fileContent = args.message;
        // 创建Blob并触发下载
        const blob = new Blob([fileContent], { type: 'application/json' });
        const url = URL.createObjectURL(blob);
        const a = document.createElement('a');
        a.href = url;
        a.download = 'untitled.dg'; // 默认文件名，用户可在保存对话框修改
        document.body.appendChild(a);
        a.click();
        document.body.removeChild(a);
        URL.revokeObjectURL(url);

        // 通知任务窗格保存完成
        Office.context.ui.messageParent('save-success');
      });
    };
  </script>
</body>
</html>

核心注意点 #

• Office任务窗格的沙箱环境禁止直接调用浏览器下载或Node.js文件系统API，必须通过displayDialogAsync打开信任的子页面来实现。
• 子页面必须和任务窗格同源，或者添加到Office的信任站点列表，否则会跨域报错。
• 通过messageParent和消息监听实现任务窗格与对话框之间的数据传递。

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