Office.DevicePermission interface

Pacote:

office

Fornece métodos para um suplemento pedir permissão a um utilizador para aceder às respetivas capacidades de dispositivo. As capacidades de dispositivo de um utilizador incluem a câmara, a geolocalização e o microfone.

Comentários

Aplicações: esta API é suportada pelas seguintes aplicações do Office ao executar em browsers baseados em Chromium, como o Microsoft Edge e o Google Chrome.

• Excel Online

• Outlook na Web

• PowerPoint Online

• Word Online

Também é suportado no novo Outlook no Windows.

Conjunto de requisitos: DevicePermission 1.1

Métodos

requestPermissions(permissions)	Pede permissão a um utilizador para aceder às respetivas capacidades do dispositivo, como uma câmara ou microfone. Todas as permissões pedidas são apresentadas numa única caixa de diálogo modal para o utilizador. A caixa de diálogo inclui opções para Permitir, Permitir uma vez ou Negar as permissões pedidas. Este método devolve uma promessa. Utilize-o com suplementos do Excel, PowerPoint e Word. Se um utilizador conceder acesso a uma capacidade de dispositivo pela primeira vez, a promessa é resolvida com true. Em seguida, tem de recarregar o suplemento antes de poder executar o código que utiliza a capacidade do dispositivo. Por exemplo, pode chamar window.location.reload() para recarregar o suplemento. Se um utilizador tiver concedido anteriormente acesso a uma capacidade de dispositivo, a promessa é resolvida com false. Não precisa de recarregar o suplemento para executar o código que utiliza a capacidade do dispositivo, uma vez que a permissão já está definida. Se um utilizador negar o acesso a uma capacidade de dispositivo, a promessa é rejeitada com uma mensagem de erro "O utilizador negou o pedido de permissão".
requestPermissionsAsync(permissions, options, callback)	Pede permissão a um utilizador para aceder às respetivas capacidades do dispositivo, como uma câmara, geolocalização ou microfone. Todas as permissões pedidas são apresentadas numa única caixa de diálogo modal para o utilizador. A caixa de diálogo inclui opções para Permitir, Permitir uma vez ou Negar as permissões pedidas. Este método aceita uma função de chamada de retorno. Utilize-o com suplementos do Outlook.
requestPermissionsAsync(permissions, callback)	Pede permissão a um utilizador para aceder às respetivas capacidades do dispositivo, como uma câmara, geolocalização ou microfone. Todas as permissões pedidas são apresentadas numa única caixa de diálogo modal para o utilizador. A caixa de diálogo inclui opções para Permitir, Permitir uma vez ou Negar as permissões pedidas. Este método aceita uma função de chamada de retorno. Utilize-o com suplementos do Outlook.

Detalhes do método

requestPermissions(permissions)

Pede permissão a um utilizador para aceder às respetivas capacidades do dispositivo, como uma câmara ou microfone.

Todas as permissões pedidas são apresentadas numa única caixa de diálogo modal para o utilizador. A caixa de diálogo inclui opções para Permitir, Permitir uma vez ou Negar as permissões pedidas.

Este método devolve uma promessa. Utilize-o com suplementos do Excel, PowerPoint e Word.

Se um utilizador conceder acesso a uma capacidade de dispositivo pela primeira vez, a promessa é resolvida com true. Em seguida, tem de recarregar o suplemento antes de poder executar o código que utiliza a capacidade do dispositivo. Por exemplo, pode chamar window.location.reload() para recarregar o suplemento. Se um utilizador tiver concedido anteriormente acesso a uma capacidade de dispositivo, a promessa é resolvida com false. Não precisa de recarregar o suplemento para executar o código que utiliza a capacidade do dispositivo, uma vez que a permissão já está definida. Se um utilizador negar o acesso a uma capacidade de dispositivo, a promessa é rejeitada com uma mensagem de erro "O utilizador negou o pedido de permissão".

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

Parâmetros

permissions

Office.DevicePermissionType[]

Uma matriz de capacidades de dispositivos às quais um suplemento está a pedir acesso. Nas versões Web do Excel, PowerPoint e Word, os suplementos só podem pedir acesso à câmara e ao microfone de um utilizador. O acesso à geolocalização de um utilizador está bloqueado.

Retornos

Promise<boolean>

Comentários

Importante:

• Este método não é suportado nos suplementos do Outlook. Em alternativa, utilize o requestPermissionsAsync método .

• Se o seu suplemento utilizar o mesmo código para clientes de ambiente de trabalho do Office na Web e do Office, verifique a plataforma na qual o suplemento está a ser executado antes de chamar requestPermissions. Utilize Office.context.platform e verifique se devolve Office.PlatformType.OfficeOnline. Caso contrário, a requestPermissions chamada devolverá um erro.

• Se um utilizador selecionar Permitir na caixa de diálogo, a permissão persiste até que o suplemento seja desinstalado ou até que a cache do browser no qual o suplemento está em execução esteja desmarcada. Se um utilizador quiser alterar o acesso de um suplemento à câmara ou ao microfone, tem de desinstalar o suplemento ou limpar a cache do browser.

• Se um utilizador selecionar Permitir Uma Vez na caixa de diálogo, a permissão persiste até que o separador ou janela do browser em que o suplemento está em execução esteja fechado.

• Se um utilizador selecionar Negar na caixa de diálogo, o utilizador será novamente solicitado para obter permissões da próxima vez que o suplemento necessitar de acesso às capacidades do dispositivo do utilizador.

Exemplos

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

Pede permissão a um utilizador para aceder às respetivas capacidades do dispositivo, como uma câmara, geolocalização ou microfone.

Todas as permissões pedidas são apresentadas numa única caixa de diálogo modal para o utilizador. A caixa de diálogo inclui opções para Permitir, Permitir uma vez ou Negar as permissões pedidas.

Este método aceita uma função de chamada de retorno. Utilize-o com suplementos do Outlook.

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

Parâmetros

permissions

Office.DevicePermissionType[]

Uma matriz de capacidades de dispositivos às quais um suplemento está a pedir acesso. No Outlook na Web e no novo Outlook no Windows, um suplemento pode pedir acesso à câmara, geolocalização e microfone de um utilizador.

options

Office.AsyncContextOptions

Um literal de objeto que contém a asyncContext propriedade . Atribua qualquer objeto a que pretenda aceder na função de chamada de retorno à asyncContext propriedade .

callback

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

Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro, asyncResult, que é um Office.AsyncResult objeto. Se o utilizador conceder permissão para aceder às capacidades do dispositivo pedidas, true é devolvido na asyncResult.value propriedade . Em seguida, tem de recarregar o suplemento antes de poder executar o código que utiliza as capacidades do dispositivo. Por exemplo, pode chamar window.location.reload() para recarregar o suplemento. Se o utilizador tiver concedido anteriormente permissão para aceder às capacidades do dispositivo pedidas, false é devolvido na asyncResult.value propriedade . Não precisa de recarregar o suplemento para executar o código que utiliza a capacidade do dispositivo, uma vez que a permissão já está definida. Se um utilizador negar o acesso às capacidades do dispositivo pedidas, Office.AsyncResultStatus.Failed é devolvido na asyncResult.status propriedade .

Retornos

void

Comentários

Importante:

• Para suplementos do Excel, PowerPoint e Word, utilize o requestPermissions método .

• Se o seu suplemento utilizar o mesmo código para clientes de ambiente de trabalho do Office na Web e do Office, verifique a plataforma na qual o suplemento está a ser executado antes de chamar requestPermissionsAsync. Utilize Office.context.mailbox.diagnostics.hostName e verifique se devolve OutlookWebApp. Caso contrário, a requestPermissionsAsync chamada devolverá um erro.

• Se um utilizador selecionar Permitir na caixa de diálogo, a permissão persiste até que o suplemento seja desinstalado ou até que a cache do browser no qual o suplemento está em execução esteja desmarcada. Se um utilizador quiser alterar o acesso de um suplemento à câmara ou ao microfone, tem de desinstalar o suplemento ou limpar a cache do browser.

• Se um utilizador selecionar Permitir Uma Vez na caixa de diálogo, a permissão persiste até que o separador ou janela do browser em que o suplemento está em execução esteja fechado.

• Se um utilizador selecionar Negar na caixa de diálogo, o utilizador será novamente solicitado para obter permissões da próxima vez que o suplemento necessitar de acesso às capacidades do dispositivo do utilizador.

• Se o suplemento implementar a ativação baseada em eventos, as permissões do browser para as capacidades do dispositivo não serão herdadas e o requestPermissionsAsync método não será suportado.

requestPermissionsAsync(permissions, callback)

Pede permissão a um utilizador para aceder às respetivas capacidades do dispositivo, como uma câmara, geolocalização ou microfone.

Todas as permissões pedidas são apresentadas numa única caixa de diálogo modal para o utilizador. A caixa de diálogo inclui opções para Permitir, Permitir uma vez ou Negar as permissões pedidas.

Este método aceita uma função de chamada de retorno. Utilize-o com suplementos do Outlook.

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

Parâmetros

permissions

Office.DevicePermissionType[]

Uma matriz de capacidades de dispositivos às quais um suplemento está a pedir acesso. No Outlook na Web e no novo Outlook no Windows, um suplemento pode pedir acesso à câmara, geolocalização e microfone de um utilizador.

callback

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

Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro, asyncResult, que é um Office.AsyncResult objeto. Se o utilizador conceder permissão para aceder às capacidades do dispositivo pedidas, true é devolvido na asyncResult.value propriedade . Em seguida, tem de recarregar o suplemento antes de poder executar o código que utiliza as capacidades do dispositivo. Por exemplo, pode chamar window.location.reload() para recarregar o suplemento. Se o utilizador tiver concedido anteriormente permissão para aceder às capacidades do dispositivo pedidas, false é devolvido na asyncResult.value propriedade . Não precisa de recarregar o suplemento para executar o código que utiliza a capacidade do dispositivo, uma vez que a permissão já está definida. Se um utilizador negar o acesso às capacidades do dispositivo pedidas, Office.AsyncResultStatus.Failed é devolvido na asyncResult.status propriedade .

Retornos

void

Comentários

Importante:

• Para suplementos do Excel, PowerPoint e Word, utilize o requestPermissions método .

• Se o seu suplemento utilizar o mesmo código para clientes de ambiente de trabalho do Office na Web e do Office, verifique a plataforma na qual o suplemento está a ser executado antes de chamar requestPermissionsAsync. Utilize Office.context.mailbox.diagnostics.hostName e verifique se devolve OutlookWebApp. Caso contrário, a requestPermissionsAsync chamada devolverá um erro.

• Se um utilizador selecionar Permitir na caixa de diálogo, a permissão persiste até que o suplemento seja desinstalado ou até que a cache do browser no qual o suplemento está em execução esteja desmarcada. Se um utilizador quiser alterar o acesso de um suplemento à câmara ou ao microfone, tem de desinstalar o suplemento ou limpar a cache do browser.

• Se um utilizador selecionar Permitir Uma Vez na caixa de diálogo, a permissão persiste até que o separador ou janela do browser em que o suplemento está em execução esteja fechado.

• Se um utilizador selecionar Negar na caixa de diálogo, o utilizador será novamente solicitado para obter permissões da próxima vez que o suplemento necessitar de acesso às capacidades do dispositivo do utilizador.

• Se o suplemento implementar a ativação baseada em eventos, as permissões do browser para as capacidades do dispositivo não serão herdadas e o requestPermissionsAsync método não será suportado.

Exemplos

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