Compartir a través de

Office.DevicePermission interface

  • Referencia
Paquete:
office

Proporciona métodos para que un complemento solicite permiso a un usuario para acceder a sus funcionalidades de dispositivo. Las funcionalidades de dispositivo de un usuario incluyen su cámara, geolocalización y micrófono.

Comentarios

Aplicaciones: esta API es compatible con las siguientes aplicaciones de Office cuando se ejecutan en exploradores basados en Chromium, como Microsoft Edge y Google Chrome.

  • Excel en la web

  • Outlook en la Web

  • PowerPoint en la web

  • Word en la web

También se admite en el nuevo Outlook en Windows (versión preliminar).

Conjunto de requisitos: DevicePermission 1.1

Métodos

requestPermissions(permissions)

Solicita permiso a un usuario para acceder a sus funcionalidades de dispositivo, como una cámara o un micrófono.

Todos los permisos solicitados se muestran en un único cuadro de diálogo modal al usuario. El cuadro de diálogo incluye opciones para Permitir, Permitir una vez o Denegar los permisos solicitados.

Este método devuelve una promesa. Úselo con complementos de Excel, PowerPoint y Word.

Si un usuario concede acceso a una funcionalidad de dispositivo por primera vez, la promesa se resuelve con true. A continuación, debe volver a cargar el complemento para poder ejecutar código que use la funcionalidad del dispositivo. Por ejemplo, puede llamar window.location.reload() a para volver a cargar el complemento. Si un usuario había concedido previamente acceso a una funcionalidad de dispositivo, la promesa se resuelve con false. No es necesario volver a cargar el complemento para ejecutar código que use la funcionalidad del dispositivo, ya que el permiso ya está establecido. Si un usuario deniega el acceso a una funcionalidad de dispositivo, la promesa se rechaza con un mensaje de error "Usuario denegado la solicitud de permiso".
requestPermissionsAsync(permissions, options, callback)

Solicita permiso a un usuario para acceder a sus funcionalidades de dispositivo, como una cámara, una geolocalización o un micrófono.

Todos los permisos solicitados se muestran en un único cuadro de diálogo modal al usuario. El cuadro de diálogo incluye opciones para Permitir, Permitir una vez o Denegar los permisos solicitados.

Este método acepta una función de devolución de llamada. Úselo con complementos de Outlook.
requestPermissionsAsync(permissions, callback)

Solicita permiso a un usuario para acceder a sus funcionalidades de dispositivo, como una cámara, una geolocalización o un micrófono.

Todos los permisos solicitados se muestran en un único cuadro de diálogo modal al usuario. El cuadro de diálogo incluye opciones para Permitir, Permitir una vez o Denegar los permisos solicitados.

Este método acepta una función de devolución de llamada. Úselo con complementos de Outlook.

Detalles del método

requestPermissions(permissions)

Solicita permiso a un usuario para acceder a sus funcionalidades de dispositivo, como una cámara o un micrófono.

Todos los permisos solicitados se muestran en un único cuadro de diálogo modal al usuario. El cuadro de diálogo incluye opciones para Permitir, Permitir una vez o Denegar los permisos solicitados.

Este método devuelve una promesa. Úselo con complementos de Excel, PowerPoint y Word.

Si un usuario concede acceso a una funcionalidad de dispositivo por primera vez, la promesa se resuelve con true. A continuación, debe volver a cargar el complemento para poder ejecutar código que use la funcionalidad del dispositivo. Por ejemplo, puede llamar window.location.reload() a para volver a cargar el complemento. Si un usuario había concedido previamente acceso a una funcionalidad de dispositivo, la promesa se resuelve con false. No es necesario volver a cargar el complemento para ejecutar código que use la funcionalidad del dispositivo, ya que el permiso ya está establecido. Si un usuario deniega el acceso a una funcionalidad de dispositivo, la promesa se rechaza con un mensaje de error "Usuario denegado la solicitud de permiso".

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

Parámetros

permissions

Office.DevicePermissionType[]

Matriz de funcionalidades de dispositivo a las que un complemento solicita acceso. En las versiones web de Excel, PowerPoint y Word, los complementos solo pueden solicitar acceso a la cámara y al micrófono de un usuario. Se bloquea el acceso a la geolocalización de un usuario.

Devoluciones

Promise<boolean>

Comentarios

Importante:

  • Este método no se admite en complementos de Outlook. En su lugar, use el requestPermissionsAsync método .

  • Si el complemento usa el mismo código para office en la web y los clientes de escritorio de Office, compruebe la plataforma en la que se ejecuta el complemento antes de llamar a requestPermissions. Use Office.context.platform y compruebe que devuelve Office.PlatformType.OfficeOnline. De lo contrario, la requestPermissions llamada devolverá un error.

  • Si un usuario selecciona Permitir en el cuadro de diálogo, el permiso se conserva hasta que se desinstala el complemento o hasta que se borra la memoria caché del explorador en el que se ejecuta el complemento. Si un usuario quiere cambiar el acceso de un complemento a su cámara o micrófono, debe desinstalar el complemento o borrar la memoria caché del explorador.

  • Si un usuario selecciona Permitir una vez en el cuadro de diálogo, el permiso persiste hasta que se cierra la pestaña del explorador o la ventana en la que se ejecuta el complemento.

  • Si un usuario selecciona Denegar en el cuadro de diálogo, el usuario volverá a solicitar permisos la próxima vez que el complemento requiera acceso a las funcionalidades del dispositivo del usuario.

Ejemplos

// 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)

Solicita permiso a un usuario para acceder a sus funcionalidades de dispositivo, como una cámara, una geolocalización o un micrófono.

Todos los permisos solicitados se muestran en un único cuadro de diálogo modal al usuario. El cuadro de diálogo incluye opciones para Permitir, Permitir una vez o Denegar los permisos solicitados.

Este método acepta una función de devolución de llamada. Úselo con complementos de Outlook.

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

Parámetros

permissions

Office.DevicePermissionType[]

Matriz de funcionalidades de dispositivo a las que un complemento solicita acceso. En Outlook en la web, un complemento puede solicitar acceso a la cámara, la geolocalización y el micrófono de un usuario.

options
Office.AsyncContextOptions

Literal de objeto que contiene la asyncContext propiedad . Asigne a la propiedad cualquier objeto al que desee tener acceso en la función de devolución de asyncContext llamada.

callback

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

Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto . Si el usuario concede permiso para acceder a las funcionalidades de dispositivo solicitadas, true se devuelve en la asyncResult.value propiedad . A continuación, debe volver a cargar el complemento para poder ejecutar código que use las funcionalidades del dispositivo. Por ejemplo, puede llamar window.location.reload() a para volver a cargar el complemento. Si el usuario había concedido previamente permiso para acceder a las funcionalidades de dispositivo solicitadas, false se devuelve en la asyncResult.value propiedad . No es necesario volver a cargar el complemento para ejecutar código que use la funcionalidad del dispositivo, ya que el permiso ya está establecido. Si un usuario deniega el acceso a las funcionalidades de dispositivo solicitadas, Office.AsyncResultStatus.Failed se devuelve en la asyncResult.status propiedad .

Devoluciones

void

Comentarios

Importante:

  • Para los complementos de Excel, PowerPoint y Word, use el requestPermissions método en su lugar.

  • Si el complemento usa el mismo código para office en la web y los clientes de escritorio de Office, compruebe la plataforma en la que se ejecuta el complemento antes de llamar a requestPermissionsAsync. Use Office.context.mailbox.diagnostics.hostName y compruebe que devuelve OutlookWebApp. De lo contrario, la requestPermissionsAsync llamada devolverá un error.

  • Si un usuario selecciona Permitir en el cuadro de diálogo, el permiso se conserva hasta que se desinstala el complemento o hasta que se borra la memoria caché del explorador en el que se ejecuta el complemento. Si un usuario quiere cambiar el acceso de un complemento a su cámara o micrófono, debe desinstalar el complemento o borrar la memoria caché del explorador.

  • Si un usuario selecciona Permitir una vez en el cuadro de diálogo, el permiso persiste hasta que se cierra la pestaña del explorador o la ventana en la que se ejecuta el complemento.

  • Si un usuario selecciona Denegar en el cuadro de diálogo, el usuario volverá a solicitar permisos la próxima vez que el complemento requiera acceso a las funcionalidades del dispositivo del usuario.

  • Si el complemento implementa la activación basada en eventos, los permisos del explorador para las funcionalidades del dispositivo no se heredan y no se admite el requestPermissionsAsync método .

requestPermissionsAsync(permissions, callback)

Solicita permiso a un usuario para acceder a sus funcionalidades de dispositivo, como una cámara, una geolocalización o un micrófono.

Todos los permisos solicitados se muestran en un único cuadro de diálogo modal al usuario. El cuadro de diálogo incluye opciones para Permitir, Permitir una vez o Denegar los permisos solicitados.

Este método acepta una función de devolución de llamada. Úselo con complementos de Outlook.

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

Parámetros

permissions

Office.DevicePermissionType[]

Matriz de funcionalidades de dispositivo a las que un complemento solicita acceso. En Outlook en la web, un complemento puede solicitar acceso a la cámara, la geolocalización y el micrófono de un usuario.

callback

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

Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto . Si el usuario concede permiso para acceder a las funcionalidades de dispositivo solicitadas, true se devuelve en la asyncResult.value propiedad . A continuación, debe volver a cargar el complemento para poder ejecutar código que use las funcionalidades del dispositivo. Por ejemplo, puede llamar window.location.reload() a para volver a cargar el complemento. Si el usuario había concedido previamente permiso para acceder a las funcionalidades de dispositivo solicitadas, false se devuelve en la asyncResult.value propiedad . No es necesario volver a cargar el complemento para ejecutar código que use la funcionalidad del dispositivo, ya que el permiso ya está establecido. Si un usuario deniega el acceso a las funcionalidades de dispositivo solicitadas, Office.AsyncResultStatus.Failed se devuelve en la asyncResult.status propiedad .

Devoluciones

void

Comentarios

Importante:

  • Para los complementos de Excel, PowerPoint y Word, use el requestPermissions método en su lugar.

  • Si el complemento usa el mismo código para office en la web y los clientes de escritorio de Office, compruebe la plataforma en la que se ejecuta el complemento antes de llamar a requestPermissionsAsync. Use Office.context.mailbox.diagnostics.hostName y compruebe que devuelve OutlookWebApp. De lo contrario, la requestPermissionsAsync llamada devolverá un error.

  • Si un usuario selecciona Permitir en el cuadro de diálogo, el permiso se conserva hasta que se desinstala el complemento o hasta que se borra la memoria caché del explorador en el que se ejecuta el complemento. Si un usuario quiere cambiar el acceso de un complemento a su cámara o micrófono, debe desinstalar el complemento o borrar la memoria caché del explorador.

  • Si un usuario selecciona Permitir una vez en el cuadro de diálogo, el permiso persiste hasta que se cierra la pestaña del explorador o la ventana en la que se ejecuta el complemento.

  • Si un usuario selecciona Denegar en el cuadro de diálogo, el usuario volverá a solicitar permisos la próxima vez que el complemento requiera acceso a las funcionalidades del dispositivo del usuario.

  • Si el complemento implementa la activación basada en eventos, los permisos del explorador para las funcionalidades del dispositivo no se heredan y no se admite el requestPermissionsAsync método .

Ejemplos

// 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.
            }
        }
    });
}