在加载项中请求获取 API 使用权限Requesting permissions for API use in add-ins

本文说明您可以在内容或任务窗格加载项清单中声明的不同权限级别,以指定加载项功能所需的 JavaScript API 访问的级别。This article describes the different permission levels that you can declare in your content or task pane add-in's manifest to specify the level of JavaScript API access your add-in requires for its features.

权限模型Permissions model

5 级 JavaScript API 访问权限模型为内容和任务窗格加载项的用户提供基本的隐私和安全功能。图 1 显示您可以在加载项清单中声明的 API 权限的 5 个级别。A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your content and task pane add-ins. Figure 1 shows the five levels of API permissions you can declare in your add-in's manifest.

图 1:内容和任务窗格加载项的 5 级权限模型Figure 1. The five-level permission model for content and task pane add-ins

任务窗格应用程序的权限级别

这些权限指定加载项运行时在用户插入然后激活(信任)加载项时允许内容或任务窗格加载项使用的 API 子集。若要声明内容或任务窗格加载项所需的权限级别,请在加载项清单的 Permissions 元素中指定任一权限文本值。以下示例要求 WriteDocument 权限,仅允许可以对文档进行写入(而非阅读)的方法。These permissions specify the subset of the API that the add-in runtime will allow your content or task pane add-in to use when a user inserts, and then activates (trusts) your add-in. To declare the permission level your content or task pane add-in requires, specify one of the permission text values in the Permissions element of your add-in's manifest. The following example requests the WriteDocument permission, which will allow only methods that can write to (but not read) the document.

<Permissions>WriteDocument</Permissions>

作为最佳做法,应该根据 最小特权 原则请求权限。也就是说,应该请求仅可访问加载项正常运行所需的 API 最小子集的权限。例如,如果您加载项的功能只需要读取用户文档中的数据,应该请求的权限不应高于 ReadDocument 权限。As a best practice, you should request permissions based on the principle of least privilege. That is, you should request permission to access only the minimum subset of the API that your add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the ReadDocument permission.

下表描述了每个权限级别启用的 JavaScript API 子集。The following table describes the subset of the JavaScript API that is enabled by each permission level.

权限Permission 启用的 API 子集Enabled subset of the API
受限Restricted Settings 对象的方法和 Document.getActiveViewAsync 方法。这是内容或任务窗格加载项可以请求的最低级别权限。The methods of the Settings object, and the Document.getActiveViewAsync method.This is the minimum permission level that can be requested by a content or task pane add-in.
ReadDocumentReadDocument 除了受限制权限允许的 api,添加对 api 成员的访问权限,以读取文档和管理绑定。这包括使用:In addition to the API allowed by the Restricted permission, adds access to the API members necessary to read the document and manage bindings.This includes the use of:
Document.getSelectedDataAsync 方法,用于获取所选文本、HTML(仅限 Word)或表格数据,但不可用于包含文档中所有数据的基础 Open Office XML (OOXML) 代码。The Document.getSelectedDataAsync method to get the selected text, HTML (Word only), or tabular data, but not the underlying Open Office XML (OOXML) code that contains all of the data in the document.

  • Document.getFileAsync 方法,用于获取文档中的所有文本,而不是文档的基础 OOXML 二进制副本。The Document.getFileAsync method to get all of the text in the document, but not the underlying OOXML binary copy of the document.

  • Binding.getDataAsync 方法,用于读取文档中的绑定数据。The Binding.getDataAsync method for reading bound data in the document.

  • Bindings 对象的 addFromNamedItemAsyncaddFromPromptAsyncaddFromSelectionAsync 方法,用于在文档中创建绑定。The addFromNamedItemAsync, addFromPromptAsync, addFromSelectionAsync methods of the Bindings object for creating bindings in the document.

  • Bindings 对象的 getAllAsyncgetByIdAsyncreleaseByIdAsync 方法,用于访问和删除文档中的绑定。The getAllAsync, getByIdAsync, and releaseByIdAsync methods of the Bindings object for accessing and removing bindings in the document.

  • Document.getFilePropertiesAsync 方法,用于访问文档文件属性,例如文档的 URL。The Document.getFilePropertiesAsync method to access document file properties, such as the URL of the document.

  • Document.goToByIdAsync 方法,用于导航到文档中的已命名对象和位置。The Document.goToByIdAsync method to navigate to named objects and locations in the document.

  • 对于项目的任务窗格外接程序,ProjectDocument 对象的所有"get"方法。For task pane add-ins for Project, all of the "get" methods of the ProjectDocument object.

  • ReadAllDocumentReadAllDocument 除了受限制ReadDocument权限允许的 API 之外,还允许以下对文档数据的额外访问权限:In addition to the API allowed by the Restricted and ReadDocument permissions, allows the following additional access to document data:
    • Document.getSelectedDataAsyncDocument.getFileAsync 方法可以访问文档(文档中除了文本,还可能包含格式、链接、嵌入图片、注释、修订等)的基础 OOXML 代码。The Document.getSelectedDataAsync and Document.getFileAsync methods can access the underlying OOXML code of the document (which in addition to the text may include formatting, links, embedded graphics, comments, revisions, and so forth).

    WriteDocumentWriteDocument 除了受限制权限允许的 API,添加对以下 API 成员的访问权限:In addition to the API allowed by the Restricted permission, adds access to the following API members:
    ReadWriteDocumentReadWriteDocument 除了受限制ReadDocument需要使用 readalldocumentWriteDocument权限允许的 api 之外,还包括对内容和任务窗格外接程序支持的所有其他 api (包括用于订阅事件的方法)的访问权限。必须声明ReadWriteDocument权限才能访问这些附加 API 成员:In addition to the API allowed by the Restricted, ReadDocument, ReadAllDocument, and WriteDocument permissions, includes access to all remaining API supported by content and task pane add-ins, including methods for subscribing to events.You must declare the ReadWriteDocument permission to access these additional API members:

    另请参阅See also