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 加载项配合使用。

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

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 请改用方法。
如果外接程序对 Web 上的 Office 和 Office 桌面客户端使用相同的代码，请在调用 requestPermissions之前验证运行加载项的平台。使用 Office.context.platform 并验证它是否返回 Office.PlatformType.OfficeOnline。否则， requestPermissions 调用将返回错误。
如果用户从对话框中选择 “允许” ，则权限将一直保留，直到卸载加载项或清除运行加载项的浏览器的缓存。如果用户想要更改加载项对其相机或麦克风的访问权限，则必须卸载加载项或清除其浏览器缓存。
如果用户从对话框中选择“ 允许一次 ”，则权限将一直保留，直到关闭运行加载项的浏览器选项卡或窗口。
如果用户从对话框中选择 “拒绝” ，则下次加载项需要访问用户设备功能时，将再次请求该用户获取权限。

示例

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

options: Office.AsyncContextOptions

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

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

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

void

注解

重要说明：

对于 Excel、PowerPoint 和 Word 加载项，请改用 requestPermissions 方法。
如果外接程序对 Web 上的 Office 和 Office 桌面客户端使用相同的代码，请在调用 requestPermissionsAsync之前验证运行加载项的平台。使用 Office.context.mailbox.diagnostics.hostName 并验证它是否返回 OutlookWebApp。否则， requestPermissionsAsync 调用将返回错误。
如果用户从对话框中选择 “允许” ，则权限将一直保留，直到卸载加载项或清除运行加载项的浏览器的缓存。如果用户想要更改加载项对其相机或麦克风的访问权限，则必须卸载加载项或清除其浏览器缓存。
如果用户从对话框中选择“ 允许一次 ”，则权限将一直保留，直到关闭运行加载项的浏览器选项卡或窗口。
如果用户从对话框中选择 “拒绝” ，则下次加载项需要访问用户设备功能时，将再次请求该用户获取权限。
如果外接程序实现基于事件的激活，则不会继承对设备功能的浏览器权限， requestPermissionsAsync 并且不支持方法。

requestPermissionsAsync(permissions, callback)

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

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

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

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

参数

permissions: Office.DevicePermissionType[]

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

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

void

注解

重要说明：

对于 Excel、PowerPoint 和 Word 加载项，请改用 requestPermissions 方法。
如果外接程序对 Web 上的 Office 和 Office 桌面客户端使用相同的代码，请在调用 requestPermissionsAsync之前验证运行加载项的平台。使用 Office.context.mailbox.diagnostics.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.
            }
        }
    });
}

通过

Office.DevicePermission interface

注解

方法

方法详细信息

requestPermissions(permissions)

参数

返回

注解

示例

requestPermissionsAsync(permissions, options, callback)

参数

返回

注解

requestPermissionsAsync(permissions, callback)

参数

返回

注解

示例

其他资源