在加载项中请求获取 API 使用权限

本文说明您可以在内容或任务窗格加载项清单中声明的不同权限级别，以指定加载项功能所需的 JavaScript API 访问的级别。

注意

若要了解邮件 (Outlook) 加载项的权限级别，请参阅 Outlook 权限模型。

权限模型

5 级 JavaScript API 访问权限模型为内容和任务窗格加载项的用户提供基本的隐私和安全功能。图 1 显示您可以在加载项清单中声明的 API 权限的 5 个级别。

图 1. 内容和任务窗格加载项的 5 级权限模型

这些权限指定外接程序 运行时 将允许内容或任务窗格加载项在用户插入时使用的 API 子集，然后激活 (信任) 外接程序。 若要声明内容或任务窗格加载项所需的权限级别，请在加载项清单的 Permissions 元素中指定任一权限文本值。 以下示例要求 WriteDocument 权限，仅允许可以对文档进行写入（而非阅读）的方法。

<Permissions>WriteDocument</Permissions>

作为最佳做法，应该根据最小特权原则请求权限。 也就是说，应该请求仅可访问加载项正常运行所需的 API 最小子集的权限。 例如，如果您加载项的功能只需要读取用户文档中的数据，应该请求的权限不应高于 ReadDocument 权限。

下表描述了每个权限级别启用的 JavaScript API 子集。

权限	启用的 API 子集
受限	Settings 对象的方法和 Document.getActiveViewAsync 方法。 这是内容或任务窗格加载项可以请求的最低级别权限。
ReadDocument	除了 Restricted 权限允许的 API，添加对 API 成员的访问权，这是阅读文档和管理绑定所必需的权限。 这包括对以下内容的使用： Document.getSelectedDataAsync 方法，用于获取所选文本、HTML（仅限 Word）或表格数据，但不可用于包含文档中所有数据的基础 Open Office XML (OOXML) 代码。 Document.getFileAsync 方法，用于获取文档中的所有文本，而不是文档的基础 OOXML 二进制副本。 Binding.getDataAsync 方法，用于读取文档中的绑定数据。 Bindings 对象的 addFromNamedItemAsync、addFromPromptAsync、addFromSelectionAsync 方法，用于在文档中创建绑定。 Bindings 对象的 getAllAsync、getByIdAsync 和 releaseByIdAsync 方法，用于访问和删除文档中的绑定。 Document.getFilePropertiesAsync 方法，用于访问文档文件属性，例如文档的 URL。 Document.goToByIdAsync 方法，用于导航到文档中的已命名对象和位置。 对于项目的任务窗格外接程序，ProjectDocument 对象的所有"get"方法。
ReadAllDocument	除了 受限制 和 ReadDocument 权限允许的 API 外，还允许对文档数据进行以下附加访问。 Document.getSelectedDataAsync 和 Document.getFileAsync 方法可以访问文档（文档中除了文本，还可能包含格式、链接、嵌入图片、注释、修订等）的基础 OOXML 代码。
WriteDocument	除了 受限制 权限允许的 API 外，还添加了对以下 API 成员的访问权限。 Document.setSelectedDataAsync 方法，用于在文档中写入用户所选内容。
ReadWriteDocument	除了 Restricted、ReadDocument、ReadAllDocument 和 WriteDocument 权限允许的 API，将对内容和任务窗格加载项支持的所有其他 API 的访问权包含在内，包括订阅事件的方法。 必须声明 ReadWriteDocument 权限才能访问这些额外的 API 成员： Binding.setDataAsync 方法，用于将内容写入到文档的绑定区域。 TableBinding.addRowsAsync 方法，用于将行添加到绑定表格中。 TableBinding.addColumnsAsync 方法，用于将列添加到绑定表格中。 TableBinding.deleteAllDataValuesAsync 方法，用于删除绑定表格中的所有数据。 TableBinding 对象的 setFormatsAsync、clearFormatsAsync 和 setTableOptionsAsync 方法，用于设置绑定表格中的格式和选项。 CustomXmlNode、CustomXmlPart、CustomXmlParts 和 CustomXmlPrefixMappings 对象的所有成员。 内容和任务窗格加载项支持的所有订阅事件的方法，具体来说即 Binding、CustomXmlPart、Document、ProjectDocument 和 Settings 对象的 addHandlerAsync 和 removeHandlerAsync 方法。

另请参阅

• Office 加载项的隐私和安全