如何一步一步创建 Office 加载项

要是你想知道 如何创建 Office 加载项 （或者插件、扩展程序……不管你喜欢怎么称呼它们），你来对地方了。插件是集成到 Web 系统中的小型 Web 应用程序。 WordExcel、Outlook、PowerPoint、OneNote、Project 等 应用 扩展 Office 的功能，从自动化繁重任务到连接外部云服务。

在你开始疯狂编程之前，重要的是要明白这一点： Office 加载项并非简单的独立脚本。它存在于 Office 加载项平台中，由清单文件描述，并以 Web 应用程序的形式运行，使用 JavaScript API 与 Office 通信。接下来，我们将逐步讲解您需要了解的一切：创建项目的工具、内部结构、API 模型、测试和调试方法、发布方法，甚至包括如何在应用程序内部管理权限和访问权限。

Office 加载项究竟是什么？

Office 加载项基本上是 一个与 Microsoft 365 应用程序集成的 Web 应用程序 （Word、Excel、Outlook、PowerPoint、OneNote、Project 等）并扩展它们的界面和功能。您可以将其视为附加组件，可以“附加”到功能区、上下文菜单或侧边栏，以提供新功能。

恩典是 该插件使用标准网络技术运行。 它支持 HTML、CSS、JavaScript 或 TypeScript，甚至 React 等框架，并使用 Office JavaScript API 与文档或电子邮件进行通信。这使其能够读取和修改内容、显示自定义界面，并与外部服务、REST API、公司内部系统等进行通信。

Office 加载项的两个关键组成部分

每个 Office 加载项始终包含以下内容： 两个区别很大的部分这一点必须从一开始就牢记在心：

• 互补宣言它定义了配置、行为以及如何将其集成到 Office 界面中。
• 该网络应用程序即渲染任务窗格界面、对话框或内容插件的实际代码（HTML、CSS、JavaScript/TypeScript），其中包含业务逻辑。

该宣言起到了以下作用： “身份证”和使用说明书 加载项是“引擎”，而 Web 应用程序则是执行实际工作的“引擎”，它使用 Office JavaScript API 与文档或电子邮件进行通信。

补充宣言的定义是什么

Office 加载项的清单文件，通常存储为 manifest.xml 或 manifest.json 项目根部包含了 Office 需要了解的所有信息，例如您的加载项的功能、托管位置以及应如何向用户显示。

该宣言除其他内容外，还明确规定了以下内容： 关键要素应严格控制：

• 插件元数据：标识符（ID）、版本、用户显示名称、描述、默认语言环境等。
• 兼容的办公应用程序例如，该加载项是否可以在 Word、Excel、Outlook、PowerPoint、Project 或 OneNote 中使用。
• 所需权限：您需要对文档、Outlook 邮箱或其他资源进行何种级别的访问。
• 与 Office 界面集成：自定义选项卡、功能区上的按钮、添加到上下文菜单的命令以及其他用户界面元素。
• 图标和图像: 指向将在功能区、菜单和界面其他部分显示的图标的路径，并遵守插件的品牌标识。
• 插件尺寸例如，内容加载项的大小或 Outlook 加载项的首选高度。
• Outlook 中的激活规则：决定何时在电子邮件或报价中显示插件的条件（基于发件人、主题、内容等）。
• 键盘快捷键Excel 和 Word 中可用的自定义快捷键。

所有这些使 宣言对于其发展和出版都至关重要。部署插件时，实际分发的是清单文件，该文件指向托管 Web 应用程序的 URL。

该插件的Web应用程序

第二个重要组成部分是Web应用程序，也就是用户看到并与之交互的内容。该应用程序通常由以下部分组成： HTML页面、CSS样式表和JavaScript或TypeScript脚本可以使用框架构建，也可以不使用框架构建（React 是最常见的框架之一，但并非唯一框架）。

插件会从这些页面中获取信息。 Office JavaScript API 它可以读取和修改运行所在文档的内容：Excel 单元格区域、Word 段落、Outlook 邮件、PowerPoint 幻灯片、表格、图表等等。此外，作为一款 Web 应用程序，它还可以：

• 连接到外部网络服务 获取或发送数据。
• 管理用户身份验证 使用 OAuth、Azure AD 或其他提供商。
• 使用内部 REST API 你的组织。
• 实现所有必要的业务逻辑，从高级计算到复杂的自动化。

用于创建 Office 加载项的工具

Office 加载项平台提供了多种方式 创建可供开发的项目这些工具根据不同的用户画像和工作偏好量身定制。主要选项包括：Yeoman 生成器、Visual Studio、Visual Studio Code 插件开发工具包和 Microsoft 365 代理工具包。

使用 Yeoman 生成器创建插件

Yeoman 的 Office 加载项生成器允许您 创建可直接使用的 Node.js 项目 并使用 Visual Studio Code 或其他编辑器进行管理。如果您习惯于在纯 JavaScript 环境下使用命令行工具，这将是一个非常便捷的选择。

使用此生成器，您可以 创建插件 为：

• Excel
• OneNote中
• Outlook
• PowerPoint中
• 项目
• Word
• 自定义 Excel 函数

运行向导时，您可以选择是否要基于以下内容创建项目： HTML、CSS 和 JavaScript 或 TypeScript “裸机”或者一个与……相关的项目 应对同样，在 JavaScript 或 TypeScript 中也是如此。生成器负责设置整个结构、Node 依赖项和初始配置。

使用 Yeoman 的前提条件

要使用 Yeoman Office 生成器，您需要安装一些软件。 基本组件这些在 JavaScript 生态系统中很常见：

• Node.js LTS 版本它从Node.js官方网站下载，并根据您的操作系统进行安装。
• Yeoman 和 Office 加载项生成器它们通过以下命令全局安装：
  npm install -g yo generator-office
• 有效的 Microsoft 365 订阅 使用 Office，您可以在桌面版 Office 和网页版 Office 中测试加载项。

使用 Yeoman 创建一个项目

安装完所有设备后， 项目创建 非常简单。在命令行中，进入你想工作的目录，运行以下命令：

yo office

助理会问一系列问题 调整项目例如，对于 Word 的第一个任务窗格加载项，您可以这样回答：

• 选择项目类型： Office 加载项任务窗格项目
• 选择一种类型 脚本: JavaScript
• 您想给这个插件起什么名字？ 我的 Office 加载项
• 您希望支持哪些 Office 客户端应用程序？ Word

完成向导后，Yeoman 将生成所有项目文件并安装必要的 Node 模块，以便： 你会发现一个功能齐全的基本配件.

项目结构由 Yeoman 生成

使用 Yeoman 为任务看板创建的项目通常包含 结构非常相似 其中，每个部分都发挥着特定的作用：

• ./manifest.xml 或 ./manifest.json：定义 Web 应用程序的配置、权限、与接口的集成以及 URL 的清单。
• ./src/taskpane/taskpane.html：用户将看到的任务面板的 HTML 模板。
• ./src/taskpane/taskpane.css：用于塑造和设计面板的样式表。
• ./src/taskpane/taskpane.js：实现逻辑并调用 Office API 的 JavaScript 代码。

试试用 Yeoman 创建的插件

要测试该插件，只需 进入项目文件夹并运行一些命令 启动本地 Web 服务器并将加载项加载到 Office 中。

1. 进入项目根文件夹：
   cd "My Office Add-in"
2. 启动本地服务器，并在桌面版 Word 中执行以下命令进行测试：
   npm start

   此命令会启动 Web 服务器（如果尚未启动），并自动打开加载项加载的 Word。

3. 如果您想在浏览器中试用 Word 加载项，可以使用如下命令：
   npm run start -- web --document {url}

   哪里 {网址} 它是存储在 OneDrive 或 Word 文档库中的 Word 文档的地址。 SHAREPOINT 您有权访问该加载项。如果由于某种原因，该加载项无法在 Office 网页版中正确加载，您可以手动安装并手动删除本地加载的清单文件。

4. 文档上传完成后，您可以从选项卡打开任务窗格。 首页 通过单击按钮 显示任务窗格点击链接 Ejecutar 在该面板中，典型示例会将具有自身样式的“Hello, world”插入到文档中。
5. 要停止本地服务器，并在必要时卸载已加载的插件，您可以使用：
   npm stop

   如果您已手动将插件上传到本地，则需要按照特定步骤删除该类型的本地上传。

Yeoman 和 npm 的常见问题

在安装或项目执行过程中，遇到以下情况较为常见： npm 警告和错误一些常见情况包括：

• 自动步骤故障 npm安装 发电机本身运行。如果稍后 npm开始 它会报错；通常情况下，只需进入项目文件夹并手动运行以下命令即可。 npm install.
• 插件会发出关于过时或不兼容依赖项的警告，这些警告通常不会阻止插件运行，但可能会很烦人。如果您想清除这些警告，可以使用该工具。 npm 检查更新 如下：
  • 安装工具： npm i -g npm-check-updates
  • 更新 package.json 中的版本信息： ncu -u
  • 重新安装依赖项： npm install

使用 Visual Studio 创建插件

Visual Studio中 它允许您直接从 Visual Studio 创建 Office 加载项。在这种情况下，加载项项目是更大解决方案的一部分，并且也基于 HTML、CSS 和 JavaScript。

Visual Studio 允许您创建以下插件：

• Excel
• Outlook
• PowerPoint中
• Word

是的， 它不支持为 OneNote 或 Project 创建加载项。对于这些应用，您需要使用 Yeoman 生成器并按照特定的快速入门指南进行操作。

在 Visual Studio 中开发和自定义插件

当您使用 Visual Studio 创建插件项目时，环境会生成 功能有限的基础插件这只是一个简单的起点。接下来，您可以根据自己的喜好进行自定义：

• El 表现调整元数据、权限、激活规则和界面元素。
• 档案 HTML，CSS和JavaScript 影响任务窗格或对话框形状的元素。

为了充分利用它，了解以下信息非常重要 插件平台的一般概念 （开发生命周期、清单、API 模型、需求集）以及每个应用程序的具体方面：Excel、Word、Outlook 等。

从 Visual Studio 运行、调试和发布

在开发过程中，Visual Studio 会针对该插件运行测试。 本地 Web 服务器（localhost）当一切准备就绪可以投入生产时，典型的生产流程包括：

1. 发布 Web 应用程序 在服务器或托管服务（例如 Microsoft Azure）上。
2. 更新宣言 这样它就指向了应用程序托管的最终 URL。
3. 选择一种实现方法 （内部插件目录、AppSource 等）并将清单文件分发给用户。

有关如何在不同平台上进行调试以及如何解决特定问题的详细信息，请参阅文档。 在 Visual Studio 中调试 Office 加载项 以及在通用测试和调试指南中。

Visual Studio Code 的 Office 加载项开发工具包

如果你的自然环境是 Visual Studio Code，你可以安装 Office 加载项开发工具包一个扩展程序，让您在编辑器内创建、运行和调试插件项目时更加轻松。

通过此扩展，您可以 创建新的附加项目 通过引导式界面，您可以直接将示例加载到您的环境中，而无需手动设置所有配置。该扩展程序可从 Visual Studio Marketplace 下载，并通过其专属图标集成到 VS Code 活动栏中。

使用开发工具包创建一个项目

点击项目创建按钮 由扩展程序提供。如果您尚未安装，系统会提示您进行安装。

在扩展页面，您将看到项目描述，并可以选择该选项。 创建 开始生成插件。

选择 工作文件夹 项目将在文件夹选择对话框出现时创建在此处。

开发工具包将创建文件结构， 项目将在第二个 VS Code 窗口中打开。此时，建议关闭初始窗口，只在新实例中工作。

最终的项目还包含 一个基本的任务窗格插件并附有可供运行和修改的示例代码。

VS Code 项目的结构和关键文件

La 此类项目的结构 它与 Yeoman 生成的非常相似，通常你会发现：

1. 一个文件 ./manifest.xml 或 ./manifest.json 在根目录下，包含插件的配置和功能。
2. 文件 ./src/taskpane/taskpane.html 其中包含任务窗格的 HTML 代码。
3. 样式表 ./src/taskpane/taskpane.css 控制视觉设计的。
4. 剧本 ./src/taskpane/taskpane.js 使用 Office JavaScript API 代码将任务窗格连接到 Office 应用程序。

测试并停止开发工具包中的插件

要使用开发工具包从 VS Code 测试插件 只需遵循几个非常简单的步骤即可 使用扩展程序自身的活动栏：

1. 点击图标即可打开扩展程序。 Office 加载项开发工具包 在活动栏中。
2. 选择选项 Office 加载项预览 (F5)从而制备净化环境。
3. 从快速选择菜单中选择该选项 办公应用桌面版（Edge Chromium）将 {Office Application} 替换为您想要的应用程序（Word、Excel 等）。这将启动桌面应用程序，加载加载项，并附加调试器。

在此过程中，试剂盒会检查所有…… 先前的要求 并在节目中播出。 终端 如果出现问题，将提供详细信息。第一条 引导 由于需要安装必要的依赖项和证书，因此可能需要一些时间。

完成测试和调试后，这一点非常重要。 正确停止插件仅仅关闭 Office 应用并不总是能正确地使加载项注册失效。要正确操作：

1. 再次打开扩展程序 从活动栏中的图标查看。
2. 点击 停止预览 Office 加载项这会关闭 Web 服务器并清除缓存中的插件日志。
3. 最后关掉 办公应用程序窗口.

如果您发现插件无法启动或运行异常，通常这样做会有帮助。 关闭所有 Office 实例 请确保已使用扩展程序自带的选项停止之前的服务器。您也可以在官方文档中找到相关章节。 Office 加载项开发过程中的故障排除在极端情况下，您始终可以在 GitHub 上提交问题。

Microsoft 365 代理工具包

另一种现代选择是使用 Microsoft 365 代理工具包它是一套旨在创建几乎所有类型 Microsoft 365 扩展程序（包括 Office 加载项）的工具集。当您需要在 Microsoft 365 生态系统中集成更高级的逻辑或使用智能代理功能时，它尤其有用。

使用此工具，您可以 从更广泛的角度配置插件项目 （不仅限于经典 Office，而是整个 Microsoft 365 环境），利用特定的模板和向导。官方文档详细介绍了如何使用此工具包创建加载项项目，以及如何将它们与其他服务和工作流集成。

访问 Office JavaScript API

为了使您的 Web 应用程序能够与运行所在的 Office 文档或消息进行通信，您需要加载该文档或消息。 Office JavaScript 库 (office.js)该网站由微软官方 CDN 提供服务。

标准库的URL是：
https://appsforoffice.microsoft.com/lib/1/hosted/office.js

在您的插件中任何需要使用 API 的网页上，您都需要添加一个 head 标签内的 script 标签 从而：

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

从那一刻起，您将可以使用 Office 命名空间，并且您可以使用两者。 应用专用 API （例如 Excel、Word 等） 常用API 这些功能由多个应用程序共享。此外，官方文档还解释了如何启用诸如以下功能： 智能感知 在编辑器中工作会更舒适。

可用的 API 模型

Office 加载项平台提供 JavaScript 中的两种主要 API 模型它们彼此互补，但又应该明确区分开来：

• 应用专用API
• 常用 API

该 应用专用API 它们旨在与特定应用程序的原生对象进行交互。例如，借助 Excel 的 API，您可以使用强类型对象来操作工作表、区域、表格、图表和其他 Excel 元素。

此 API 模型与 承诺 并支持以下模型 批量操作这样可以将多个操作串联成一个发送到 Office 应用程序的单个请求，从而显著提升性能，尤其是在 Office 网页版中。该模型最早出现在 Office 2016 中，并已根据新的需求进行了扩展。

该 常用 API他们则更注重功能性。 多个 Office 应用程序共享例如对话框、客户端设置或用户界面的某些部分。此模型基于 回调 它不使用 Promise，而是每个请求只允许执行一个操作。它向下兼容，因为它是在 Office 2013 中引入的，例如，它被用于与 Outlook、PowerPoint 或 Project 进行基本交互。

API 需求集

在 JavaScript API 中，不同的功能组被组织成所谓的“组件”。 需求集每个集合都将一组 API 成员按名称和版本分组，使您能够非常精确地了解每个 Office 客户端中可用的功能。

例如，您可以找到如下集合：

• ExcelApi 1.7它将特定版本 Excel 中可用的特定 API 分组在一起。
• DialogApi 1.1它为多个 Office 应用程序提供通用对话框功能。

配件可以使用这些套装 在运行时检查应用程序是否支持必要的 API因此，当某些内容不可用时，它会调整自身行为或显示相应的消息。每套组件的具体兼容性因组件而异。 平台 （Windows, Mac（网页、移动端），Office 版本和应用程序本身（Word、Excel 等）。

使用 Script Lab 探索 API

如果你想在不构建整个项目的情况下尝试使用 API，你可以使用 脚本实验室这是微软商城提供的一款免费插件。

Script Lab 允许您 直接在 Excel 或 Word 等应用程序中测试代码片段。实时查看它们对文档的影响。这非常适合学习 API、验证小型逻辑或在将其集成到实际插件之前构建快速原型。

在脚本实验室中，您会发现 一个预构建示例库 您可以直接运行它，也可以将其作为您自己代码的基础。此外，官方文档还包含一些展示 Script Lab 实际运行效果的短视频，这对于了解它的所有功能非常有帮助。

展开 Office 用户界面

配饰的优势之一在于： 他们不仅仅是在“幕后”执行代码。但它们可以完全集成到 Office 界面中，添加根据您的需求量身定制的选项卡、按钮、菜单和面板。

该 最常见的形式 以下是一些扩展接口的方法：

• 插件命令 集成到功能区或上下文菜单中。
• HTML容器例如任务窗格、内容加载项和自定义对话框。

MGI 插件命令 这些命令允许您向 Office 功能区添加新的选项卡或按钮组，甚至可以展开在 Excel 中右键单击文本或对象时出现的上下文菜单。用户按下这些命令之一时，可以执行 JavaScript 代码、打开特定的任务窗格或启动对话框。

就他们而言 任务窗格、内容加载项和对话框 这些是用于显示加载项界面的 HTML 容器。内容由您在清单文件中指定的网页提供，除了常规网站的所有功能（例如身份验证、调用外部 API、数据可视化等）之外，您还可以通过这些网页使用 Office API 与文档进行交互。

Office 加载项的用户界面元素文档详细介绍了如何操作。 设计用户体验推荐使用哪些模式，以及如何充分利用每种类型的容器。

查找并使用已安装的插件

从最终用户的角度来看，一旦插件被安装或分发， 在 Office 中找到它非常容易。虽然根据具体应用情况，它也有一些细微差别。

1. 首先，你必须 登录 Office 使用相应的 Microsoft 365 帐户。为此，请打开任意 Office 应用程序，然后在右上角选择登录选项，并输入您的电子邮件地址和密码。
2. 在 Word、Excel 或 PowerPoint 桌面应用程序中，您可以转到 插入 > 我的插件 查看该应用程序的可用插件列表。
3. 盒子里面 Office 加载项您可以按名称搜索插件。如果找不到，请检查您是否已登录正确的帐户，如有必要，请点击…… 更新 刷新列表。
4. 找到配件后，只需…… 双击它 这样它就能启动并在文档中显示其界面。

这种行为，基于 将插件链接到用户帐户只要使用同一个 Microsoft 365 帐户，就可以确保加载项在不同的设备和应用程序之间始终可用。

管理其他办公套件中的插件和扩展程序

虽然我们这里主要关注的是 Office 加载项平台，但通过将其与……进行比较，了解一些背景信息会很有帮助。 其他办公套间及其扩展管理因为总体理念相似。

COM 加载项和经典 Microsoft Office 中的加载项

在 Word 2016 等桌面版本中，除了现代的基于 Web 的加载项之外，仍然存在一些问题。 COM 组件和传统加载项要管理它们，您可以前往 文件 > 选项 在附加组件部分，查看按类型分组的列表。

从列表中选择一个项目后，将显示以下内容： 详情见底部。 窗口。一个典型的例子是插件。 FoxitReader PDF 创造者该功能可在安装 Foxit Reader 时选择添加，它包含一个额外的选项卡或按钮，用于从 Word 创建和操作 PDF。

在这个窗口的底部有一个区域，叫做 管理带有下拉菜单和按钮 去... 它允许您管理特定类型的扩展程序：激活、停用或删除它们。并非所有插件都会添加可见的按钮或选项卡； 这完全取决于开发者的设计方式。.

LibreOffice Calc 中的扩展

在 LibreOffice 中，尤其是在 Calc 中，您可以从菜单管理扩展程序。 工具 > 扩展管理器您可以在这里找到已安装扩展程序的列表，并可以选择添加新扩展程序、更新现有扩展程序或卸载它们。

某些扩展程序会随附出现。 一把黄色小挂锁这表明它们是 LibreOffice 基本软件包的一部分，无法移除。要安装新组件，通常需要访问 LibreOffice 官方网站。 LibreOffice 扩展和模板托管于 https://extensions.libreoffice.org/虽然该网站主要使用英语，但大多数开发者都会用英语发布他们的扩展程序，所以不必害怕使用英语。

Google 文档中的插件

谷歌文档 它还提供了一套系统 界面内部集成了插件。 从菜单 饰品 通过文档，您可以管理已安装的程序，并在数据库中搜索新程序。 Google.

系统允许 按类别筛选，查看每个插件的安装用户数量。您可以查看评分和评论，只需点击几下即可直接安装。这个集成商店大大简化了流程，无需访问任何外部开发者网站即可找到插件。

权限和设备功能访问权限

某些插件，特别是那些基于现代网络技术的插件，可能需要 访问设备功能 例如摄像头、地理位置或麦克风。发生这种情况时，浏览器或平台本身会显示一个对话框，征求您的同意。

您通常会看到类似这样的选项： 允许、仅允许一次或拒绝:

• 如果你选择 允许该插件将能够持续访问所请求的资源，直到您卸载该插件或清除运行该插件的浏览器的缓存为止。
• 如果你选择 允许一次仅在当前会话期间授予访问权限，直到您关闭运行该插件的标签页或窗口为止。
• 如果你选择 拒绝该插件将没有访问权限，当它再次需要访问权限时，会通过另一个对话框再次请求权限。

如果您愿意 撤销您使用“允许”按钮接受的权限您需要卸载该插件或清除浏览器缓存，才能强制忘记之前的决定并重新进行设置。

Office 加载项生态系统提供 一个高度灵活的框架，可用于扩展 Word、Excel、Outlook 等软件。 使用标准的 Web 技术、Yeoman、Visual Studio 或 VS Code 开发工具包等工具，以及具有特定和通用模型的 JavaScript API（受一系列需求支持），并深入了解清单的作用、项目结构、调试选项、部署方法以及权限和设备访问的影响，就可以构建强大的解决方案，这些解决方案可以无缝集成到日常办公体验中，而不会中断用户的常规工作流程。