Office.DevicePermission interface

为加载项提供请求用户权限以访问其设备功能的方法。用户的设备功能包括相机、地理位置和麦克风。

注解

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

Excel 网页版
Outlook 网页版
PowerPoint 网页版
Word 网页版

Windows 上的新 Outlook 也支持此功能。

要求集： DevicePermission 1.1

方法

requestPermissions(permissions)

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

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

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

如果用户首次授予对设备功能的访问权限，则承诺将以解决。true 然后，必须重新加载加载项，然后才能运行使用设备功能的代码。例如，可以调用 window.location.reload() 来重新加载加载项。如果用户以前已授予对设备功能的访问权限，则承诺将以解决。false 无需重新加载加载项即可运行使用设备功能的代码，因为已设置权限。如果用户拒绝访问设备功能，承诺将被拒绝，并显示“用户已拒绝权限请求”错误消息。

requestPermissionsAsync(permissions, options, callback)

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

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

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

requestPermissionsAsync(permissions, callback)

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

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

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

requestPermissions(permissions)

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

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

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

如果用户首次授予对设备功能的访问权限，则承诺将以解决。true 然后，必须重新加载加载项，然后才能运行使用设备功能的代码。例如，可以调用 window.location.reload() 来重新加载加载项。如果用户以前已授予对设备功能的访问权限，则承诺将以解决。false 无需重新加载加载项即可运行使用设备功能的代码，因为已设置权限。如果用户拒绝访问设备功能，承诺将被拒绝，并显示“用户已拒绝权限请求”错误消息。

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

参数

permissions: Office.DevicePermissionType[]

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

返回

Promise<boolean>

注解

重要说明：

Outlook 加载项不支持此方法。请改用该 requestPermissionsAsync 方法。
如果加载项对 Office web 版和 Office 桌面客户端使用相同的代码，请先验证正在哪个平台上运行加载项，然后再调用requestPermissions。使用 Office.context.platform 并验证它是否返回 Office.PlatformType.OfficeOnline. 否则， requestPermissions 调用将返回错误。
如果用户从对话框中选择 “允许 ”，则该权限将一直保留，直到卸载该加载项或清除运行该加载项的浏览器的缓存为止。如果用户想要更改加载项对其相机或麦克风的访问权限，则必须卸载该加载项或清除其浏览器缓存。
如果用户从对话框中选择 “允许一次 ”，则该权限将一直保留，直到运行加载项的浏览器选项卡或窗口关闭。
如果用户从对话框中选择“ 拒绝 ”，则在下次加载项需要访问用户的设备功能时，将再次请求用户提供权限。
Excel、PowerPoint 和 Word 不支持访问用户的地理位置。它仅在使用该requestPermissionsAsync方法的 Outlook 网页版和新的 Outlook on Windows 中受支持。

示例

// 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.");
                // Reload your add-in before you run code that uses the device capabilities.
                location.reload();
            } else {
                console.log("Permission has been previously granted and is already set in the iframe.");

                // Since permission has been previously granted, you don't need to reload your add-in.

                // Do something with the device capabilities.
            }
        })
        .catch((error) => {
            console.log("Permission denied.");
            console.error(error);

            // 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 网页版和 Windows 上的新版 Outlook 中，加载项可以请求访问用户的相机、地理位置和麦克风。

options: Office.AsyncContextOptions

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

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

当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。如果用户授予访问请求的设备功能的权限， true 则会在属性中 asyncResult.value 返回。然后，必须先重新加载加载项，然后才能运行使用设备功能的代码。例如，可以调用 window.location.reload() 来重新加载加载项。如果用户以前已授予访问请求的设备功能的权限， false 则在属性中 asyncResult.value 返回。无需重新加载加载项即可运行使用设备功能的代码，因为已设置权限。如果用户拒绝访问请求的设备功能， Office.AsyncResultStatus.Failed 则会在属性中 asyncResult.status 返回。

返回

void

注解

重要说明：

对于 Excel、PowerPoint 和 Word 加载项，请改用该requestPermissions方法。
如果加载项对 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 网页版和 Windows 上的新版 Outlook 中，加载项可以请求访问用户的相机、地理位置和麦克风。

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

当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。如果用户授予访问请求的设备功能的权限， true 则会在属性中 asyncResult.value 返回。然后，必须先重新加载加载项，然后才能运行使用设备功能的代码。例如，可以调用 window.location.reload() 来重新加载加载项。如果用户以前已授予访问请求的设备功能的权限， false 则在属性中 asyncResult.value 返回。无需重新加载加载项即可运行使用设备功能的代码，因为已设置权限。如果用户拒绝访问请求的设备功能， Office.AsyncResultStatus.Failed 则会在属性中 asyncResult.status 返回。

返回

void

注解

重要说明：

对于 Excel、PowerPoint 和 Word 加载项，请改用该requestPermissions方法。
如果加载项对 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("Permission denied.");

            // Do something when permission is denied.
        } else {
            if (asyncResult.value) {
                console.log("Permission granted.");
                // Reload your add-in before you run code that uses the device capabilities.
                location.reload();
            } else {
                console.log("Permission has been previously granted and is already set in the iframe.");
                
                // Since permission has been previously granted, you don't need to reload your add-in.

                // Do something with the device capabilities.
            }
        }
    });
}

注解

方法

方法详细信息

requestPermissions(permissions)

参数

返回

注解

示例

requestPermissionsAsync(permissions, options, callback)

参数

返回

注解

requestPermissionsAsync(permissions, callback)

参数

返回

注解

示例

反馈