Office.DevicePermission interface

Paquet:

office

Fournit des méthodes permettant à un complément de demander à un utilisateur l’autorisation d’accéder aux fonctionnalités de son appareil. Les fonctionnalités d’appareil d’un utilisateur incluent sa caméra, sa géolocalisation et son microphone.

Remarques

Applications : cette API est prise en charge par les applications Office suivantes lorsqu’elles s’exécutent dans des navigateurs basés sur Chromium, tels que Microsoft Edge et Google Chrome.

• Excel sur le web

• Outlook sur le web

• PowerPoint sur le web

• Word sur le web

Il est également pris en charge dans la nouvelle version d’Outlook sur Windows.

Ensemble de conditions requises : DevicePermission 1.1

Méthodes

requestPermissions(permissions)	Demande à un utilisateur l’autorisation d’accéder aux fonctionnalités de son appareil, telles qu’une caméra ou un microphone. Toutes les autorisations demandées sont affichées dans une boîte de dialogue modale unique pour l’utilisateur. La boîte de dialogue inclut les options Autoriser, Autoriser une seule fois ou Refuser les autorisations demandées. Cette méthode retourne une promesse. Utilisez-la avec les compléments Excel, PowerPoint et Word. Si un utilisateur accorde l’accès à une fonctionnalité d’appareil pour la première fois, la promesse se résout avec true. Vous devez ensuite recharger le complément avant de pouvoir exécuter du code qui utilise la fonctionnalité de l’appareil. Par exemple, vous pouvez appeler window.location.reload() pour recharger votre complément. Si un utilisateur avait précédemment accordé l’accès à une fonctionnalité d’appareil, la promesse se résout avec false. Vous n’avez pas besoin de recharger votre complément pour exécuter du code qui utilise la fonctionnalité de l’appareil, car l’autorisation est déjà définie. Si un utilisateur refuse l’accès à une fonctionnalité d’appareil, la promesse est rejetée avec un message d’erreur « L’utilisateur a refusé la demande d’autorisation ».
requestPermissionsAsync(permissions, options, callback)	Demande à un utilisateur l’autorisation d’accéder aux fonctionnalités de son appareil, telles qu’une caméra, une géolocalisation ou un microphone. Toutes les autorisations demandées sont affichées dans une boîte de dialogue modale unique pour l’utilisateur. La boîte de dialogue inclut les options Autoriser, Autoriser une seule fois ou Refuser les autorisations demandées. Cette méthode accepte une fonction de rappel. Utilisez-la avec les compléments Outlook.
requestPermissionsAsync(permissions, callback)	Demande à un utilisateur l’autorisation d’accéder aux fonctionnalités de son appareil, telles qu’une caméra, une géolocalisation ou un microphone. Toutes les autorisations demandées sont affichées dans une boîte de dialogue modale unique pour l’utilisateur. La boîte de dialogue inclut les options Autoriser, Autoriser une seule fois ou Refuser les autorisations demandées. Cette méthode accepte une fonction de rappel. Utilisez-la avec les compléments Outlook.

Détails de la méthode

requestPermissions(permissions)

Demande à un utilisateur l’autorisation d’accéder aux fonctionnalités de son appareil, telles qu’une caméra ou un microphone.

Toutes les autorisations demandées sont affichées dans une boîte de dialogue modale unique pour l’utilisateur. La boîte de dialogue inclut les options Autoriser, Autoriser une seule fois ou Refuser les autorisations demandées.

Cette méthode retourne une promesse. Utilisez-la avec les compléments Excel, PowerPoint et Word.

Si un utilisateur accorde l’accès à une fonctionnalité d’appareil pour la première fois, la promesse se résout avec true. Vous devez ensuite recharger le complément avant de pouvoir exécuter du code qui utilise la fonctionnalité de l’appareil. Par exemple, vous pouvez appeler window.location.reload() pour recharger votre complément. Si un utilisateur avait précédemment accordé l’accès à une fonctionnalité d’appareil, la promesse se résout avec false. Vous n’avez pas besoin de recharger votre complément pour exécuter du code qui utilise la fonctionnalité de l’appareil, car l’autorisation est déjà définie. Si un utilisateur refuse l’accès à une fonctionnalité d’appareil, la promesse est rejetée avec un message d’erreur « L’utilisateur a refusé la demande d’autorisation ».

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

Paramètres

permissions

Office.DevicePermissionType[]

Tableau de fonctionnalités d’appareil auxquelles un complément demande l’accès. Dans les versions web d’Excel, PowerPoint et Word, les compléments peuvent uniquement demander l’accès à la caméra et au microphone d’un utilisateur. L’accès à la géolocalisation d’un utilisateur est bloqué.

Retours

Promise<boolean>

Remarques

Important:

• Cette méthode n’est pas prise en charge dans les compléments Outlook. Utilisez la méthode à la requestPermissionsAsync place.

• Si votre complément utilise le même code pour office sur le web et les clients de bureau Office, vérifiez la plateforme sur laquelle le complément s’exécute avant d’appeler requestPermissions. Utilisez Office.context.platform et vérifiez qu’il retourne Office.PlatformType.OfficeOnline. Sinon, l’appel requestPermissions renvoie une erreur.

• Si un utilisateur sélectionne Autoriser dans la boîte de dialogue, l’autorisation persiste jusqu’à ce que le complément soit désinstallé ou jusqu’à ce que le cache du navigateur sur lequel le complément s’exécute soit effacé. Si un utilisateur souhaite modifier l’accès d’un complément à sa caméra ou son microphone, il doit désinstaller le complément ou effacer le cache de son navigateur.

• Si un utilisateur sélectionne Autoriser une fois dans la boîte de dialogue, l’autorisation persiste jusqu’à ce que l’onglet ou la fenêtre du navigateur dans lequel le complément s’exécute soit fermé.

• Si un utilisateur sélectionne Refuser dans la boîte de dialogue, l’utilisateur est à nouveau invité à obtenir des autorisations la prochaine fois que le complément aura besoin d’accéder aux fonctionnalités de l’appareil de l’utilisateur.

Exemples

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

Demande à un utilisateur l’autorisation d’accéder aux fonctionnalités de son appareil, telles qu’une caméra, une géolocalisation ou un microphone.

Toutes les autorisations demandées sont affichées dans une boîte de dialogue modale unique pour l’utilisateur. La boîte de dialogue inclut les options Autoriser, Autoriser une seule fois ou Refuser les autorisations demandées.

Cette méthode accepte une fonction de rappel. Utilisez-la avec les compléments Outlook.

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

Paramètres

permissions

Office.DevicePermissionType[]

Tableau de fonctionnalités d’appareil auxquelles un complément demande l’accès. Dans Outlook sur le web et les nouveaux Outlook sur Windows, un complément peut demander l’accès à l’appareil photo, à la géolocalisation et au microphone d’un utilisateur.

options

Office.AsyncContextOptions

Littéral d’objet qui contient la asyncContext propriété . Affectez à la propriété tout objet auquel vous souhaitez accéder dans la asyncContext fonction de rappel.

callback

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

Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet . Si l’utilisateur accorde l’autorisation d’accéder aux fonctionnalités d’appareil demandées, true est retourné dans la asyncResult.value propriété . Vous devez ensuite recharger le complément avant de pouvoir exécuter du code qui utilise les fonctionnalités de l’appareil. Par exemple, vous pouvez appeler window.location.reload() pour recharger votre complément. Si l’utilisateur avait précédemment accordé l’autorisation d’accéder aux fonctionnalités d’appareil demandées, false est retourné dans la asyncResult.value propriété . Vous n’avez pas besoin de recharger votre complément pour exécuter du code qui utilise la fonctionnalité de l’appareil, car l’autorisation est déjà définie. Si un utilisateur refuse l’accès aux fonctionnalités de l’appareil demandées, Office.AsyncResultStatus.Failed est retourné dans la asyncResult.status propriété .

Retours

void

Remarques

Important:

• Pour les compléments Excel, PowerPoint et Word, utilisez plutôt la requestPermissions méthode .

• Si votre complément utilise le même code pour office sur le web et les clients de bureau Office, vérifiez la plateforme sur laquelle le complément s’exécute avant d’appeler requestPermissionsAsync. Utilisez Office.context.mailbox.diagnostics.hostName et vérifiez qu’il retourne OutlookWebApp. Sinon, l’appel requestPermissionsAsync renvoie une erreur.

• Si un utilisateur sélectionne Autoriser dans la boîte de dialogue, l’autorisation persiste jusqu’à ce que le complément soit désinstallé ou jusqu’à ce que le cache du navigateur sur lequel le complément s’exécute soit effacé. Si un utilisateur souhaite modifier l’accès d’un complément à sa caméra ou son microphone, il doit désinstaller le complément ou effacer le cache de son navigateur.

• Si un utilisateur sélectionne Autoriser une fois dans la boîte de dialogue, l’autorisation persiste jusqu’à ce que l’onglet ou la fenêtre du navigateur dans lequel le complément s’exécute soit fermé.

• Si un utilisateur sélectionne Refuser dans la boîte de dialogue, l’utilisateur est à nouveau invité à obtenir des autorisations la prochaine fois que le complément aura besoin d’accéder aux fonctionnalités de l’appareil de l’utilisateur.

• Si votre complément implémente l’activation basée sur les événements, les autorisations de navigateur sur les fonctionnalités d’appareil ne sont pas héritées et la requestPermissionsAsync méthode n’est pas prise en charge.

requestPermissionsAsync(permissions, callback)

Demande à un utilisateur l’autorisation d’accéder aux fonctionnalités de son appareil, telles qu’une caméra, une géolocalisation ou un microphone.

Toutes les autorisations demandées sont affichées dans une boîte de dialogue modale unique pour l’utilisateur. La boîte de dialogue inclut les options Autoriser, Autoriser une seule fois ou Refuser les autorisations demandées.

Cette méthode accepte une fonction de rappel. Utilisez-la avec les compléments Outlook.

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

Paramètres

permissions

Office.DevicePermissionType[]

Tableau de fonctionnalités d’appareil auxquelles un complément demande l’accès. Dans Outlook sur le web et les nouveaux Outlook sur Windows, un complément peut demander l’accès à l’appareil photo, à la géolocalisation et au microphone d’un utilisateur.

callback

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

Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet . Si l’utilisateur accorde l’autorisation d’accéder aux fonctionnalités d’appareil demandées, true est retourné dans la asyncResult.value propriété . Vous devez ensuite recharger le complément avant de pouvoir exécuter du code qui utilise les fonctionnalités de l’appareil. Par exemple, vous pouvez appeler window.location.reload() pour recharger votre complément. Si l’utilisateur avait précédemment accordé l’autorisation d’accéder aux fonctionnalités d’appareil demandées, false est retourné dans la asyncResult.value propriété . Vous n’avez pas besoin de recharger votre complément pour exécuter du code qui utilise la fonctionnalité de l’appareil, car l’autorisation est déjà définie. Si un utilisateur refuse l’accès aux fonctionnalités de l’appareil demandées, Office.AsyncResultStatus.Failed est retourné dans la asyncResult.status propriété .

Retours

void

Remarques

Important:

• Pour les compléments Excel, PowerPoint et Word, utilisez plutôt la requestPermissions méthode .

• Si votre complément utilise le même code pour office sur le web et les clients de bureau Office, vérifiez la plateforme sur laquelle le complément s’exécute avant d’appeler requestPermissionsAsync. Utilisez Office.context.mailbox.diagnostics.hostName et vérifiez qu’il retourne OutlookWebApp. Sinon, l’appel requestPermissionsAsync renvoie une erreur.

• Si un utilisateur sélectionne Autoriser dans la boîte de dialogue, l’autorisation persiste jusqu’à ce que le complément soit désinstallé ou jusqu’à ce que le cache du navigateur sur lequel le complément s’exécute soit effacé. Si un utilisateur souhaite modifier l’accès d’un complément à sa caméra ou son microphone, il doit désinstaller le complément ou effacer le cache de son navigateur.

• Si un utilisateur sélectionne Autoriser une fois dans la boîte de dialogue, l’autorisation persiste jusqu’à ce que l’onglet ou la fenêtre du navigateur dans lequel le complément s’exécute soit fermé.

• Si un utilisateur sélectionne Refuser dans la boîte de dialogue, l’utilisateur est à nouveau invité à obtenir des autorisations la prochaine fois que le complément aura besoin d’accéder aux fonctionnalités de l’appareil de l’utilisateur.

• Si votre complément implémente l’activation basée sur les événements, les autorisations de navigateur sur les fonctionnalités d’appareil ne sont pas héritées et la requestPermissionsAsync méthode n’est pas prise en charge.

Exemples

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