开发 Office 加载项

提示

阅读本文之前,请查看 Office 加载项平台概述

所有 Office 加载项均基于 Office 加载项平台构建。 无论构建任何加载项,你都需要了解应用程序和平台可用性、Office JavaScript API 编程模式、如何在清单文件中指定加载项的设置和功能、如何设计 UI 和用户体验等重要概念。 本文档的“开发生命周期” > “开发”部分在此介绍了这类核心开发概念。 在浏览与所构建的加载项(例如 Excel)相对应的应用程序特定文档之前,请先查看此处的信息。

创建 Office 加载项

你可通过适用于 Office 加载项的 Yeoman 生成器或 Visual Studio 来创建 Office 加载项。

适用于 Office 加载项的 Yeoman 生成器

可用来创建 Node.js Office 加载项项目,而后者可通过 Visual Studio Code 或任何其他编辑器进行管理。 该生成器可创建适合下述任一应用的 Office 加载项:

  • Excel
  • OneNote
  • Outlook
  • PowerPoint
  • Project
  • Word
  • Excel 自定义函数

你可选择使用 HTML、CSS 和 JavaScript 创建该项目,也可使用 Angular 或 React 进行创建。 此外,无论选择哪种框架,都可在 JavaScript 和 Typescript 之间进行选择。 有关使用 Yeoman 生成器创建加载项的详细信息,请参阅使用 Visual Studio Code 开发 Office 加载项

Visual Studio

Visual Studio 可用于创建适用于 Excel、Outlook、Word 和 PowerPoint 的 Office 加载项。 Office 加载项项目是作为 Visual Studio 解决方案的一部分创建的,它使用 HTML、CSS 和 JavaScript。 有关使用 Visual Studio 创建加载项的详细信息,请参阅使用 Visual Studio 开发 Office 加载项

备注

虽然可使用 Visual Studio 创建 Office 加载项,但使用 Yeoman 生成器可在一定程度上明显提供更好的开发人员体验。

  • 与 Visual Studio 相比,Yeoman 生成器可为 Office 加载项项目提供更广泛的项目类型、框架和语言选项。

  • Yeoman 生成器中的项目模板的更新频率高于 Visual Studio 中的项目模板。

了解 Office 加载项的两个部分

Office 加载项由两部分组成:

  • 加载项清单(XML 文件),它定义了加载项的设置和功能。

  • Web 应用程序,它定义了加载项组件的 UI 和功能,例如任务窗格、内容加载项和对话框。

这些 Web 应用程序可使用 Office JavaScript API 来与其中正在运行加载项的 Office 文档中的内容进行交互。你的加载项还可执行 Web 应用程序通常可实现的其他操作,例如调用外部 Web 服务和简化用户身份验证等等。

定义加载项的设置和功能

Office 加载项的清单是一个 XML 文件,它定义了加载项的设置和功能。 你需配置清单来指定如下内容:

  • 描述加载项的元数据(例如 ID、版本、说明、显示名称和默认区域设置)。
  • 将在其中运行加载项的 Office 应用程序。
  • 加载项所需的权限。
  • 加载项与 Office 集成的方式,包括与加载项创建的自定义选项卡和功能区按钮等自定义 UI 的集成。
  • 加载项对品牌和命令图标使用的图像的位置。
  • 加载项的尺寸(例如内容加载项的尺寸、Outlook 加载项请求的高度)。
  • 指定何时在消息或约会上下文中激活加载项的规则(仅限 Outlook 加载项)。

有关清单的详细信息,请参阅 Office 加载项 XML 清单

与 Office 文档中的内容交互

Office 加载项可使用 Office JavaScript API 来与其中在运行加载项的 Office 文档中的内容进行交互。

访问 Office JavaScript API 库

可通过 Office JS 内容交付网络 (CDN) 访问 Office JavaScript API 库:https://appsforoffice.microsoft.com/lib/1/hosted/office.js 要在任何加载项的网页中使用 Office JavaScript API,必须在页面的 <head> 标记中的 <script> 标记内引用 CDN。

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

备注

要使用预览版 API,请参考 CDN 上的 Office JavaScript API 库预览版:https://appsforoffice.microsoft.com/lib/beta/hosted/office.js

要详细了解如何访问 Office JavaScript API 库(包括如何获取 IntelliSense),请参阅通过 Office JavaScript API 的内容交付网络 (CDN) 引用该库

API 模型

Office JavaScript API 包含两种不同的模型:

  • 应用程序特定的 API 提供了强类型对象,它可用于与特定 Office 应用程序的本机对象进行交互。 例如,可使用 Excel JavaScript API 来访问工作表、区域、表格和图表等。 应用程序特定的 API 当前可用于以下 Office 应用程序。

    此 API 模型使用的是承诺,你可用它在你发送给 Office 应用程序的每个请求中指定多个操作。 通过以这种方式进行批处理操作,可大幅提升网页版 Office 应用程序中的加载项的性能。 应用程序特定的 API 是随 Office 2016 引入的,不可用于与 Office 2013 进行交互。

    备注

    还有一个应用程序特定的 Visio API,但它只能在 SharePoint Online 页面中用于与已嵌入到页面中的 Visio 图表进行交互。 Visio 不支持 Office Web 加载项。

    请参阅 使用特定于应用程序的 API 模型,以了解有关此 API 模型的详细信息。

  • 通用 API 可用于访问在多种类型的 Office 应用程序中都很常见的 UI、对话框和客户端设置等功能。 此 API 模型使用的是回调,这样,你在发送给 Office 应用程序的每个请求中只能指定一个操作。 通用 API 是随 Office 2013 引入的,可用于与 Office 2013 或更高版本进行交互。 要详细了解通用 API 对象模型(其中包括用于与 Outlook、PowerPoint 和 Project 交互的 API),请参阅常见 JavaScript API 对象模型

备注

某些 Excel 自定义函数在排列了计算执行优先级的唯一运行时中运行,并且没有任务窗格。 这些函数将使用略有不同的编程模型,且被称为无用户界面的函数。

API 要求集

要求集 是已命名的 API 成员组。要求集可特定于 Office 应用程序,例如 ExcelApi 1.7 要求集(一组仅可在 Excel 中使用的 API),也可通用于多个应用程序,例如 DialogApi 1.1 要求集(一组可在支持对话框 API 的任何 Office 应用程序中使用的 API)。

加载项可使用要求集来确定 Office 应用程序是否支持需要使用的 API 成员。 有关详细信息,请参阅指定 Office 应用程序和 API 要求

要求集支持因 Office 应用程序、版本和平台而异。有关每个 Office 应用程序支持的平台、要求集和通用 API 的详细信息,请参阅 适用于 Office 加载项的 Office 客户端应用程序和平台可用性

使用 Script Lab 了解 API

Script Lab 是一款加载项,在 Excel 或 Word 等 Office 程序中工作时,你可用它来了解 Office JavaScript API 和运行代码片段。 该工具通过 AppSource 免费提供,随附在你的开发工具包中,在你建立希望加载项中拥有的功能原型和验证该功能时非常有用。 在 Script Lab 中,你可访问内置示例库以快速试用 API,甚至还可将示例用作你自己的代码的起点。

下面时长一分钟的视频展示了 Script Lab 的实际运行情况。

显示 Script Lab 在 Excel、Word 和 PowerPoint 中运行的短视频。

有关 Script Lab 的详细信息,请参阅使用 Script Lab 了解 Office JavaScript API

扩展 Office UI

Office 加载项可使用加载项命令和 HTML 容器(如任务窗格、内容加载项或对话框)来扩展 Office UI。

  • 加载项命令可用于向 Office 中的默认功能区添加自定义选项卡、按钮和菜单,或者扩展当用户右键单击 Office 文档中的文本或 Excel 中的对象时显示的默认上下文菜单。 当用户选择加载项命令时,他们将启动该加载项命令指定的任务,例如运行 JavaScript 代码、打开任务窗格或启动对话框。

  • 任务窗格内容加载项对话框等 HTML 容器可用于显示自定义 UI 和探索 Office 应用程序中的附加功能。 每个任务窗格、内容加载项或对话框的内容和功能派生自你指定的网页。 这些网页可使用 Office JavaScript API 来与其中正在运行加载项的 Office 文档中的内容进行交互,还可执行网页通常可实现的其他操作,例如调用外部 Web 服务和简化用户身份验证等等。

下图显示功能区中有一个加载项命令、文档右侧有一个任务窗格,且文档上方有一个对话框或内容加载项。

显示 Office 文档中的功能区内加载项命令、任务窗格、对话框/内容加载项的图表。

要详细了解如何扩展 Office UI 和设计加载项的 UX,请参阅 Office 加载项的 Office UI 元素

后续步骤

本文概述了创建 Office 加载项的不同方法、介绍了加载项扩展 Office UI 的方法,描述了 API 集,介绍了 Script Lab(一种用来于了解 Office JavaScript API 和建立加载项功能原型的宝贵工具)。现在,你了解这一介绍性信息,请考虑沿着以下学习路径继续你的 Office 加载项之旅。

创建 Office 加载项

可完成 5 分钟快速入门,快速创建适合 Excel、OneNote、Outlook、PowerPoint、Project 或 Word 的基本加载项。 如果你之前已完成快速入门,并且想要创建更复杂一些的加载项,请尝试本教程

了解详细信息

查看此文档,详细了解如何开发、测试和发布 Office 加载项。

提示

对于你构建的任何加载项,都可查看本文档的开发生命周期部分中的信息,还可查看与你要构建的加载项类型(例如 Excel)相对应的应用程序特定部分中的信息。

另请参阅