通过

Office.DevicePermission interface

  • 参考
包:
office

为外接程序提供方法，以便向用户请求访问其设备功能的权限。 用户的设备功能包括其相机、地理位置和麦克风。

注解

应用程序：在基于Chromium的浏览器（如 Microsoft Edge 和 Google Chrome）中运行时，以下 Office 应用程序支持此 API。

  • Excel 网页版

  • Outlook 网页版

  • PowerPoint 网页版

  • Word 网页版

新 Outlook on Windows (预览版) 也支持此功能。

要求集： DevicePermission 1.1

方法

requestPermissions(permissions)

请求用户访问其设备功能（如相机或麦克风）的权限。

所有请求的权限都显示在用户的单个模式对话框中。 该对话框包括 “允许”、“ 允许一次”或 “拒绝 请求的权限”选项。

此方法返回 promise。 将其与 Excel、PowerPoint 和 Word 加载项配合使用。
requestPermissionsAsync(permissions, options, callback)

请求用户访问其设备功能（例如相机、地理位置或麦克风）的权限。

所有请求的权限都显示在用户的单个模式对话框中。 该对话框包括 “允许”、“ 允许一次”或 “拒绝 请求的权限”选项。

此方法接受回调函数。 将其与 Outlook 加载项配合使用。
requestPermissionsAsync(permissions, callback)

请求用户访问其设备功能（例如相机、地理位置或麦克风）的权限。

所有请求的权限都显示在用户的单个模式对话框中。 该对话框包括 “允许”、“ 允许一次”或 “拒绝 请求的权限”选项。

此方法接受回调函数。 将其与 Outlook 加载项配合使用。

方法详细信息

requestPermissions(permissions)

请求用户访问其设备功能（如相机或麦克风）的权限。

所有请求的权限都显示在用户的单个模式对话框中。 该对话框包括 “允许”、“ 允许一次”或 “拒绝 请求的权限”选项。

此方法返回 promise。 将其与 Excel、PowerPoint 和 Word 加载项配合使用。

requestPermissions(permissions: Office.DevicePermissionType[]): Promise<boolean>;

参数

permissions

Office.DevicePermissionType[]

外接程序请求访问的设备功能数组。 在 Excel、PowerPoint 和 Word 的 Web 版本中，加载项只能请求访问用户的相机和麦克风。 阻止访问用户的地理位置。

返回

Promise<boolean>

注解

重要说明：

  • Outlook 加载项不支持此方法。 requestPermissionsAsync 请改用 方法。

  • 如果外接程序对 Office web 版 和 Office 桌面客户端使用相同的代码，请在调用 requestPermissions之前验证运行加载项的平台。 使用 Office.context.platform 并验证它是否返回 Office.PlatformType.OfficeOnline。 否则， requestPermissions 调用将返回错误。

  • 如果用户允许访问其相机或麦克风，则必须在浏览器中重新加载加载项才能使权限生效。 例如，可以调用 window.location.reload() 以重新加载加载项。

  • 如果用户从对话框中选择 “允许” ，则权限将一直保留，直到卸载加载项或清除运行加载项的浏览器的缓存。 如果用户想要更改加载项对其相机或麦克风的访问权限，则必须卸载加载项或清除其浏览器缓存。

  • 如果用户从对话框中选择“ 允许一次 ”，则权限将一直保留，直到关闭运行加载项的浏览器选项卡或窗口。

  • 如果用户从对话框中选择 “拒绝” ，则下次加载项需要访问用户设备功能时，将再次请求该用户获取权限。

示例

// Request permission from a user to access their camera and microphone.
if (Office.context.platform === Office.PlatformType.OfficeOnline) {
    const deviceCapabilities = [
        Office.DevicePermissionType.camera,
        Office.DevicePermissionType.microphone
    ];
    Office.devicePermission
        .requestPermissions(deviceCapabilities)
        .then((isGranted) => {
            if (isGranted) {
                console.log("Permission granted.");

                // Do something when permission is granted.
            } else {
                console.log("Permission denied.");

                // Do something when permission is denied.
            }
        });
}

requestPermissionsAsync(permissions, options, callback)

请求用户访问其设备功能（例如相机、地理位置或麦克风）的权限。

所有请求的权限都显示在用户的单个模式对话框中。 该对话框包括 “允许”、“ 允许一次”或 “拒绝 请求的权限”选项。

此方法接受回调函数。 将其与 Outlook 加载项配合使用。

requestPermissionsAsync(permissions: Office.DevicePermissionType[], options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

参数

permissions

Office.DevicePermissionType[]

外接程序请求访问的设备功能数组。 在Outlook 网页版，加载项可以请求访问用户的相机、地理位置和麦克风。

options
Office.AsyncContextOptions

包含 asyncContext 属性的对象文本。 将希望在回调函数中访问的任何对象分配给 asyncContext 属性。

callback

(asyncResult: Office.AsyncResult<boolean>) => void

方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。 如果用户授予访问所请求设备功能的权限， true 则会在 属性中 asyncResult.value 返回 。

返回

void

注解

重要说明：

  • 对于 Excel、PowerPoint 和Word加载项，请改用 requestPermissions 方法。

  • 如果用户允许访问其相机、地理位置或麦克风，则必须在浏览器中重新加载加载项才能使权限生效。 例如，可以调用 window.location.reload() 以重新加载加载项。

  • 如果外接程序对 Office web 版 和 Office 桌面客户端使用相同的代码，请在调用 requestPermissionsAsync之前验证运行加载项的平台。 使用 Office.context.mailbox.诊断。hostName 并验证它是否返回 OutlookWebApp。 否则， requestPermissionsAsync 调用将返回错误。

  • 如果用户从对话框中选择 “允许” ，则权限将一直保留，直到卸载加载项或清除运行加载项的浏览器的缓存。 如果用户想要更改加载项对其相机或麦克风的访问权限，则必须卸载加载项或清除其浏览器缓存。

  • 如果用户从对话框中选择“ 允许一次 ”，则权限将一直保留，直到关闭运行加载项的浏览器选项卡或窗口。

  • 如果用户从对话框中选择 “拒绝” ，则下次加载项需要访问用户设备功能时，将再次请求该用户获取权限。

  • 如果外接程序实现 基于事件的激活，则不会继承对设备功能的浏览器权限， requestPermissionsAsync 并且不支持方法。

requestPermissionsAsync(permissions, callback)

请求用户访问其设备功能（例如相机、地理位置或麦克风）的权限。

所有请求的权限都显示在用户的单个模式对话框中。 该对话框包括 “允许”、“ 允许一次”或 “拒绝 请求的权限”选项。

此方法接受回调函数。 将其与 Outlook 加载项配合使用。

requestPermissionsAsync(permissions: Office.DevicePermissionType[], callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

参数

permissions

Office.DevicePermissionType[]

外接程序请求访问的设备功能数组。 在Outlook 网页版，加载项可以请求访问用户的相机、地理位置和麦克风。

callback

(asyncResult: Office.AsyncResult<boolean>) => void

方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。 如果用户授予访问所请求设备功能的权限， true 则会在 属性中 asyncResult.value 返回 。

返回

void

注解

重要说明：

  • 对于 Excel、PowerPoint 和Word加载项，请改用 requestPermissions 方法。

  • 如果用户允许访问其相机、地理位置或麦克风，则必须在浏览器中重新加载加载项才能使权限生效。 例如，可以调用 window.location.reload() 以重新加载加载项。

  • 如果外接程序对 Office web 版 和 Office 桌面客户端使用相同的代码，请在调用 requestPermissionsAsync之前验证运行加载项的平台。 使用 Office.context.mailbox.诊断。hostName 并验证它是否返回 OutlookWebApp。 否则， requestPermissionsAsync 调用将返回错误。

  • 如果用户从对话框中选择 “允许” ，则权限将一直保留，直到卸载加载项或清除运行加载项的浏览器的缓存。 如果用户想要更改加载项对其相机或麦克风的访问权限，则必须卸载加载项或清除其浏览器缓存。

  • 如果用户从对话框中选择“ 允许一次 ”，则权限将一直保留，直到关闭运行加载项的浏览器选项卡或窗口。

  • 如果用户从对话框中选择 “拒绝” ，则下次加载项需要访问用户设备功能时，将再次请求该用户获取权限。

  • 如果外接程序实现 基于事件的激活，则不会继承对设备功能的浏览器权限， requestPermissionsAsync 并且不支持方法。

示例

// Request permission from a user to access their camera, geolocation, and microphone.
if (Office.context.mailbox.diagnostics.hostName === "OutlookWebApp") {
    const deviceCapabilities = [
        Office.DevicePermissionType.camera,
        Office.DevicePermissionType.geolocation,
        Office.DevicePermissionType.microphone
    ];

    Office.devicePermission.requestPermissionsAsync(deviceCapabilities, (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log (asyncResult.error.message);
            return;
        }

        if (asyncResult.value) {
            console.log("Permission granted.");

            // Do something when permission is granted.
        } else {
            console.log("Permission denied.");

            // Do something when permission is denied.
        }
    });
}