VS2022中基于React(TypeScript)升级Office加载项操作指南

一、准备工作 #

• 得确保Visual Studio 2022已经安装了Office/SharePoint开发工作负载，同时装好Node.js（推荐用LTS版本）、Yeoman和Office加载项生成器：
  • 打开终端执行命令：npm install -g yo generator-office

二、创建React(TypeScript)版加载项项目 #

1. 打开VS2022，选择「创建新项目」
2. 在搜索框输入「Office Add-in」，挑选对应Excel/Word/PowerPoint的React+TypeScript模板
3. 填写项目名称和存储路径，点击「创建」
4. 在配置窗口选择目标Office应用，确认框架为React+TypeScript，完成项目生成

三、整合原有JavaScript功能，实现新旧并行 #

1. 迁移旧代码与资源 #

• 将原有项目中的HTML、CSS、JS文件复制到新项目的public目录下，建议新建legacy文件夹专门存放这些旧文件，避免文件混乱
• 如果旧代码依赖jQuery这类第三方库，要么通过npm install安装到新项目中，要么直接在旧HTML文件里引入CDN链接

2. 修改manifest清单，新增双功能区入口 #

• 打开新项目的manifest.xml文件：
  • 新增一个自定义功能区组，添加两个按钮：一个指向原有JS任务窗格（SourceLocation设为/legacy/taskpane.html），另一个指向React任务窗格（默认的/taskpane.html）
  • 配置片段参考：

    <CustomTab id="CustomTab">
      <Group id="LegacyGroup" label="原有功能">
        <Control id="LegacyTaskPaneButton" label="打开旧版面板" type="Button">
          <Action xsi:type="ShowTaskpane">
            <SourceLocation resid="LegacyTaskpaneUrl" />
          </Action>
        </Control>
      </Group>
      <Group id="ReactGroup" label="新版功能">
        <Control id="ReactTaskPaneButton" label="打开React面板" type="Button">
          <Action xsi:type="ShowTaskpane">
            <SourceLocation resid="Taskpane.Url" />
          </Action>
        </Control>
      </Group>
      <Label resid="CustomTab.Label" />
    </CustomTab>
    

  • 在Resources节点中添加旧版面板的URL资源：

    <bt:Url id="LegacyTaskpaneUrl" DefaultValue="https://localhost:3000/legacy/taskpane.html" />
    

3. 调试环境兼容配置 #

• 调整新项目的启动设置：
  • 在VS2022中通过项目属性配置端口，确保旧版和新版面板都能正常访问
  • 运行项目后，测试两个功能区按钮，确认旧功能正常运行、React面板能正常打开

四、逐步迁移功能至React(TypeScript) #

• 每次选择一个独立的功能模块（比如某段数据处理逻辑、一个UI组件），用React+TS重写：
  • 将Office JS API调用封装为带TS类型校验的hooks或工具函数，提升代码安全性
  • 可选择替换旧面板中的对应功能，或在React面板中实现相同功能，逐步引导用户使用新版
• 迁移完成一个模块就测试一次，确保与原有功能行为完全一致
• 待所有功能迁移完成后，再删除旧代码和manifest中的旧配置

五、注意事项 #

• 旧JS代码中的全局变量，可通过window对象在React组件中访问，或封装为TS模块
• 新旧代码使用的Office JS API版本要保持一致，避免因API差异出现问题
• 调试时使用Office加载项调试工具，分别查看旧版和新版面板的控制台输出，便于定位问题

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