Partager via

Office.DevicePermission interface

  • Référence
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 (préversion).

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.
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.

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 les clients de bureau Office sur le Web et 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 l’utilisateur autorise l’accès à sa caméra ou à son microphone, le complément doit être rechargé dans le navigateur pour que les autorisations prennent effet. Par exemple, vous pouvez appeler window.location.reload() pour recharger votre complément.

  • 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.");

                // Do something when permission is granted.
            } else {
                console.log("Permission denied.");

                // 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, un complément peut demander l’accès à la caméra, à 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é .

Retours

void

Remarques

Important:

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

  • Si l’utilisateur autorise l’accès à sa caméra, à sa géolocalisation ou à son microphone, le complément doit être rechargé dans le navigateur pour que les autorisations prennent effet. Par exemple, vous pouvez appeler window.location.reload() pour recharger votre complément.

  • Si votre complément utilise le même code pour les clients de bureau Office sur le Web et 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, un complément peut demander l’accès à la caméra, à 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é .

Retours

void

Remarques

Important:

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

  • Si l’utilisateur autorise l’accès à sa caméra, à sa géolocalisation ou à son microphone, le complément doit être rechargé dans le navigateur pour que les autorisations prennent effet. Par exemple, vous pouvez appeler window.location.reload() pour recharger votre complément.

  • Si votre complément utilise le même code pour les clients de bureau Office sur le Web et 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 (asyncResult.error.message);
            return;
        }

        if (asyncResult.value) {
            console.log("Permission granted.");

            // Do something when permission is granted.
        } else {
            console.log("Permission denied.");

            // Do something when permission is denied.
        }
    });
}