在 Visual Studio 中将 Office 加载项项目转换为使用 TypeScript

项目
08/09/2024

可以使用 Visual Studio 中的 Office 加载项模板，创建使用 JavaScript 的加载项，再将加载项项目转换为使用 TypeScript。本文介绍了 Excel 加载项的此转换过程。可以按照相同的过程操作，在 Visual Studio 中将其他类型的 Office 外接程序项目从 JavaScript 转换为 TypeScript。

先决条件

安装了 Office/SharePoint 开发工作负载的 Visual Studio 2022 或更高版本

提示

如果之前已安装 Visual Studio，请使用 Visual Studio 安装程序，以确保安装 Office/SharePoint 开发 工作负载。如果尚未安装此工作负载，请使用 Visual Studio 安装程序进行安装。
Excel 2016 或更高版本。

创建加载项项目

注意

如果已有现有项目，请跳过此部分。

在 Visual Studio 中，选择“新建项目”。如果 Visual Studio 开发环境已打开，可以通过在菜单栏上选择“ 文件 > 新建 > 项目 ”来创建新项目。
使用搜索框，输入“加载项”。选择“Excel Web 加载项”，然后选择“下一步”。
对项目命名，然后选择“创建”。
在“创建 Office 加载项”对话框窗口中，选择“将新功能添加到 Excel”，再选择“完成”以创建项目。
此时，Visual Studio 创建解决方案，且它的两个项目显示在“解决方案资源管理器”中。 Home.html 文件将在 Visual Studio 中打开。

将加载项项目转换为使用 TypeScript

添加 Nuget 包

通过选择“工具>”“Nuget 包管理器”“管理解决方案的 Nuget 包”打开“Nuget 包管理器>”
选择“ 浏览 ”选项卡。搜索并选择“ Microsoft.TypeScript.MSBuild”。将此包安装到 ASP.NET Web 项目，或更新它（如果已安装）。 ASP.NET Web 项目具有项目名称，末尾追加了文本 Web 。这将确保项目在生成运行时将转译为 JavaScript。

注意

在 TypeScript 项目中，可以混合使用 TypeScript 和 JavaScript 文件，项目都可以进行编译。这是因为 TypeScript 是键入的 JavaScript 超集，可以编译 JavaScript。

创建 TypeScript 配置文件

在 “解决方案资源管理器”中，右键单击“ (”或选择并按住) ASP.NET Web 项目，然后选择“ 添加新>项”。 ASP.NET Web 项目具有项目名称，末尾追加了文本 Web 。
在 “添加新项 ”对话框中，搜索并选择“ TypeScript JSON 配置文件”。选择“ 添加 ”以创建 tsconfig.json 文件。

将 tsconfig.json 文件更新为同时包含节 include ，如以下 JSON 所示。

{
  "compilerOptions": {
    "noImplicitAny": false,
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5"
  },
  "exclude": [
    "node_modules",
    "wwwroot"
  ],
  "include": [
    "scripts/**/*",
    "**/*"
  ]
}

保存文件。有关 tsconfig.json 设置的详细信息，请参阅什么是tsconfig.json？

创建 npm 配置文件

在 “解决方案资源管理器”中，右键单击“ (”或选择并按住) ASP.NET Web 项目，然后选择“ 添加新>项”。 ASP.NET Web 项目具有项目名称，末尾追加了文本 Web 。
在 “添加新项 ”对话框中，搜索 npm 配置文件。选择“ 添加” 以创建 package.json 文件。

更新 package.json 文件以 @types/jquery 在节中包含 devDependencies 包，如以下 JSON 所示。

{
  "version": "1.0.0",
  "name": "asp.net",
  "private": true,
  "devDependencies": {
    "@types/jquery": "^3.5.30"
  }
}

保存文件。
选择具有项目名称的 ASP.NET Web 项目，并将文本 Web 追加到末尾。在 “npm ”部分下，将 “打开项目时还原” 和 “保存时还原 ”设置为“True”。

更新 JavaScript 文件

将 JavaScript 文件 (.js) 更改为 TypeScript 文件， (.ts) 。然后，对它们进行必要的更改以编译。本部分演练新项目中的默认文件。

查找 Home.js 文件，并将其重命名为 Home.ts。
找到 ./Functions/FunctionFile.js 文件，再将其重命名为 FunctionFile.ts。
找到 ./Scripts/MessageBanner.js 文件，再将其重命名为 MessageBanner.ts。
在 Home.ts中，找到该行 Office.initialize = function (reason) { ，并在其后面立即添加一行，以填充全局 window.Promise，如下所示。
```
Office.initialize = function (reason) {
    // Add the following line.
    (window as any).Promise = OfficeExtension.Promise;
    ...
```
在 ./Scripts/MessageBanner.ts 中，找到行 _onResize(null); 并将其替换为以下内容：
```
_onResize();
```

Visual Studio 生成的 JavaScript 文件不包含任何 TypeScript 语法。应考虑更新它们。例如，以下代码演示如何将参数更新为 showNotification 以包含字符串类型。

 function showNotification(header: string, content: string) {
        $("#notification-header").text(header);
        $("#notification-body").text(content);
        messageBanner.showBanner();
        messageBanner.toggleExpansion();
    }

运行转换后的外接程序项目

在 Visual Studio 中，按 F5 或选择“ 开始 ”按钮启动 Excel，并在功能区上显示“ 显示任务窗格 加载项”按钮。加载项本地托管在 IIS 上。
在 Excel 中，选择“ 开始 ”选项卡，然后选择功能区上的“ 显示任务窗格 ”按钮以打开加载项任务窗格。
在工作表中，选择九个包含数字的单元格。
按任务窗格上的“突出显示”按钮，以突出显示选定范围内所含数字最大的单元格。

通过