了解 Office JavaScript APIUnderstanding the Office JavaScript API

Office 加载项可使用 Office JavaScript API 来与其中在运行加载项的 Office 文档中的内容进行交互。An Office Add-in can use the Office JavaScript APIs to interact with content in the Office document where the add-in is running.

访问 Office JavaScript API 库Accessing the Office JavaScript API library

可通过 Office JS 内容交付网络 (CDN) 访问 Office JavaScript API 库:https://appsforoffice.microsoft.com/lib/1/hosted/Office.jsThe Office JavaScript API library can be accessed via the Office JS content delivery network (CDN) at: https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. 要在任何加载项的网页中使用 Office JavaScript API,必须在页面的 <head> 标记中的 <script> 标记内引用 CDN。To use Office JavaScript APIs within any of your add-in's web pages, you must reference the CDN in a <script> tag in the <head> tag of the page.

<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.jsTo use preview APIs, reference the preview version of the Office JavaScript API library on the CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js.

要详细了解如何访问 Office JavaScript API 库(包括如何获取 IntelliSense),请参阅通过 Office JavaScript API 的内容交付网络 (CDN) 引用该库For more information about accessing the Office JavaScript API library, including how to get IntelliSense, see Referencing the Office JavaScript API library from its content delivery network (CDN).

API 模型API models

Office JavaScript API 包含两种不同的模型:The Office JavaScript API includes two distinct models:

  • 应用程序特定的 API 提供了强类型对象,它可用于与特定 Office 应用程序的本机对象进行交互。Application-specific APIs provide strongly-typed objects that can be used to interact with objects that are native to a specific Office application. 例如,可使用 Excel JavaScript API 来访问工作表、区域、表格和图表等。For example, you can use the Excel JavaScript APIs to access worksheets, ranges, tables, charts, and more. 应用程序特定的 API 当前可用于以下 Office 应用程序:application-specific APIs are currently available for the following Office applications:

    此 API 模型使用的是承诺,你可用它在你发送给 Office 应用程序的每个请求中指定多个操作。This API model uses promises and allows you to specify multiple operations in each request you send to the Office application. 通过以这种方式进行批处理操作,可大幅提升网页版 Office 应用程序中的加载项的性能。Batching operations in this manner can significantly improve add-in performance in Office applications on the web. 应用程序特定的 API 是随 Office 2016 引入的,不可用于与 Office 2013 进行交互。Application-specific APIs were introduced with Office 2016 and cannot be used to interact with Office 2013.

    备注

    还有一个应用程序特定的 Visio API,但它只能在 SharePoint Online 页面中用于与已嵌入到页面中的 Visio 图表进行交互。There is also an application-specific API for Visio, but you can use it only in SharePoint Online pages to interact with Visio diagrams that have been embedded in the page. Visio 不支持 Office Web 加载项。Office web add-ins are not supported in Visio.

    请参阅使用特定于应用程序的 API 模型,了解有关此 API 模型的详细信息。See Using the application-specific API model to learn more about this API model .

  • 通用 API 可用于访问在多种类型的 Office 应用程序中都很常见的 UI、对话框和客户端设置等功能。Common APIs can be used to access features such as UI, dialogs, and client settings that are common across multiple types of Office applications. 此 API 模型使用的是回调,这样,你在发送给 Office 应用程序的每个请求中只能指定一个操作。This API model uses callbacks, which allow you to specify only one operation in each request sent to the Office application. 通用 API 是随 Office 2013 引入的,可用于与 Office 2013 或更高版本进行交互。Common APIs were introduced with Office 2013 and can be used to interact with Office 2013 or later. 要详细了解通用 API 对象模型(其中包括用于与 Outlook、PowerPoint 和 Project 交互的 API),请参阅常见 JavaScript API 对象模型For details about the Common API object model, which includes APIs for interacting with Outlook, PowerPoint, and Project, see Common JavaScript API object model.

备注

某些 Excel 自定义函数在排列了计算执行优先级的唯一运行时中运行,并且没有任务窗格。Some Excel custom functions run within a unique runtime that prioritizes execution of calculations and don't have a task pane. 这些函数将使用略有不同的编程模型,且被称为无用户界面的函数。These functions use a slightly different programming model and are called UI-less functions.

API 要求集API requirement sets

要求集是指各组已命名的 API 成员。Requirement sets are named groups of API members. 要求集可特定于 Office 应用程序,例如 ExcelApi 1.7 要求集(一组仅可在 Excel 中使用的 API),也可常用于多个应用程序,例如 DialogApi 1.1 要求集(一组可在支持对话框 API 的任何 Office 应用程序中使用的 API)。Requirement sets can be specific to Office applications, such as the ExcelApi 1.7 requirement set (a set of APIs that can only be used in Excel), or common to multiple applications, such as the DialogApi 1.1 requirement set (a set of APIs that can be used in any Office application that supports the Dialog API).

加载项可使用要求集来确定 Office 应用程序是否支持需要使用的 API 成员。Your add-in can use requirement sets to determine whether the Office application supports the API members that it needs to use. 有关详细信息,请参阅指定 Office 应用程序和 API 要求For more information about this, see Specify Office applications and API requirements.

要求集支持因 Office 应用程序、版本和平台而异。Requirement set support varies by Office application, version, and platform. 要详细了解每个 Office 应用程序支持的平台、要求集和通用 API,请参阅 Office 客户端应用程序和 Office 加载项的平台可用性For detailed information about the platforms, requirement sets, and Common APIs that each Office application supports, see Office client application and platform availability for Office Add-ins.

备注

如果你计划将加载项发布到 AppSource,并使其在 Office 体验中可用,请确保你遵守商业市场认证政策If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the Commercial marketplace certification policies.例如,加载项必须适用于支持你定义的方法的所有平台,才能通过验证(有关详细信息,请参阅第 1120.3 部分以及 Office 加载项应用程序和可用性页)。 For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 1120.3 and the Office Add-in application and availability page).

另请参阅See also