Freigeben über

Office.DevicePermission interface

  • Referenz
Paket:
office

Stellt Methoden für ein Add-In bereit, um von einem Benutzer die Berechtigung für den Zugriff auf seine Gerätefunktionen anzufordern. Zu den Gerätefunktionen eines Benutzers gehören kamera, geolocation und mikrofon.

Hinweise

Anwendungen: Diese API wird von den folgenden Office-Anwendungen unterstützt, wenn sie in Chromium-basierten Browsern wie Microsoft Edge und Google Chrome ausgeführt wird.

  • Excel im Web

  • Outlook im Web

  • PowerPoint im Web

  • Word im Web

Es wird auch im neuen Outlook unter Windows unterstützt.

Anforderungssatz: DevicePermission 1.1

Methoden

requestPermissions(permissions)

Fordert die Berechtigung eines Benutzers für den Zugriff auf seine Gerätefunktionen an, z. B. eine Kamera oder ein Mikrofon.

Alle angeforderten Berechtigungen werden dem Benutzer in einem einzigen modalem Dialogfeld angezeigt. Das Dialogfeld enthält Optionen zum Zulassen, einmal zulassen oder die angeforderten Berechtigungen verweigern .

Diese Methode gibt eine Zusage zurück. Verwenden Sie es mit Excel-, PowerPoint- und Word-Add-Ins.

Wenn ein Benutzer zum ersten Mal Zugriff auf eine Gerätefunktion gewährt, wird die Zusage mit trueaufgelöst. Anschließend müssen Sie das Add-In erneut laden, bevor Sie Code ausführen können, der die Gerätefunktion verwendet. Sie können beispielsweise aufrufen window.location.reload() , um Ihr Add-In erneut zu laden. Wenn ein Benutzer zuvor Zugriff auf eine Gerätefunktion gewährt hatte, wird die Zusage mit falseaufgelöst. Sie müssen Ihr Add-In nicht erneut laden, um Code auszuführen, der die Gerätefunktion verwendet, da die Berechtigung bereits festgelegt ist. Wenn ein Benutzer den Zugriff auf eine Gerätefunktion verweigert, wird die Zusage mit der Fehlermeldung "Benutzer hat die Berechtigungsanforderung verweigert" abgelehnt.
requestPermissionsAsync(permissions, options, callback)

Fordert von einem Benutzer die Berechtigung für den Zugriff auf seine Gerätefunktionen an, z. B. eine Kamera, eine Geolocation oder ein Mikrofon.

Alle angeforderten Berechtigungen werden dem Benutzer in einem einzigen modalem Dialogfeld angezeigt. Das Dialogfeld enthält Optionen zum Zulassen, einmal zulassen oder die angeforderten Berechtigungen verweigern .

Diese Methode akzeptiert eine Rückruffunktion. Verwenden Sie es mit Outlook-Add-Ins.
requestPermissionsAsync(permissions, callback)

Fordert von einem Benutzer die Berechtigung für den Zugriff auf seine Gerätefunktionen an, z. B. eine Kamera, eine Geolocation oder ein Mikrofon.

Alle angeforderten Berechtigungen werden dem Benutzer in einem einzigen modalem Dialogfeld angezeigt. Das Dialogfeld enthält Optionen zum Zulassen, einmal zulassen oder die angeforderten Berechtigungen verweigern .

Diese Methode akzeptiert eine Rückruffunktion. Verwenden Sie es mit Outlook-Add-Ins.

Details zur Methode

requestPermissions(permissions)

Fordert die Berechtigung eines Benutzers für den Zugriff auf seine Gerätefunktionen an, z. B. eine Kamera oder ein Mikrofon.

Alle angeforderten Berechtigungen werden dem Benutzer in einem einzigen modalem Dialogfeld angezeigt. Das Dialogfeld enthält Optionen zum Zulassen, einmal zulassen oder die angeforderten Berechtigungen verweigern .

Diese Methode gibt eine Zusage zurück. Verwenden Sie es mit Excel-, PowerPoint- und Word-Add-Ins.

Wenn ein Benutzer zum ersten Mal Zugriff auf eine Gerätefunktion gewährt, wird die Zusage mit trueaufgelöst. Anschließend müssen Sie das Add-In erneut laden, bevor Sie Code ausführen können, der die Gerätefunktion verwendet. Sie können beispielsweise aufrufen window.location.reload() , um Ihr Add-In erneut zu laden. Wenn ein Benutzer zuvor Zugriff auf eine Gerätefunktion gewährt hatte, wird die Zusage mit falseaufgelöst. Sie müssen Ihr Add-In nicht erneut laden, um Code auszuführen, der die Gerätefunktion verwendet, da die Berechtigung bereits festgelegt ist. Wenn ein Benutzer den Zugriff auf eine Gerätefunktion verweigert, wird die Zusage mit der Fehlermeldung "Benutzer hat die Berechtigungsanforderung verweigert" abgelehnt.

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

Parameter

permissions

Office.DevicePermissionType[]

Ein Array von Gerätefunktionen, auf das ein Add-In Zugriff anfordert. In Webversionen von Excel, PowerPoint und Word können Add-Ins nur Zugriff auf die Kamera und das Mikrofon eines Benutzers anfordern. Der Zugriff auf die Geolocation eines Benutzers wird blockiert.

Gibt zurück

Promise<boolean>

Hinweise

Wichtig:

  • Diese Methode wird in Outlook-Add-Ins nicht unterstützt. Verwenden Sie stattdessen die requestPermissionsAsync -Methode.

  • Wenn Ihr Add-In denselben Code sowohl für Office im Web als auch für Office-Desktopclients verwendet, überprüfen Sie die Plattform, auf der das Add-In ausgeführt wird, bevor Sie aufrufen requestPermissions. Verwenden Sie Office.context.platform , und vergewissern Sie sich, dass zurückgegeben wird Office.PlatformType.OfficeOnline. Andernfalls gibt der requestPermissions Aufruf einen Fehler zurück.

  • Wenn ein Benutzer im Dialogfeld Zulassen auswählt, bleibt die Berechtigung bestehen, bis das Add-In deinstalliert wird oder bis der Cache des Browsers, in dem das Add-In ausgeführt wird, gelöscht wird. Wenn ein Benutzer den Zugriff eines Add-Ins auf seine Kamera oder sein Mikrofon ändern möchte, muss er das Add-In deinstallieren oder seinen Browsercache löschen.

  • Wenn ein Benutzer im Dialogfeld Einmal zulassen auswählt, bleibt die Berechtigung bestehen, bis die Browserregisterkarte oder das Fenster, in dem das Add-In ausgeführt wird, geschlossen wird.

  • Wenn ein Benutzer im Dialogfeld Verweigern auswählt, wird der Benutzer erneut um Berechtigungen gebeten, wenn das Add-In das nächste Mal Zugriff auf die Gerätefunktionen des Benutzers benötigt.

Beispiele

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

Fordert von einem Benutzer die Berechtigung für den Zugriff auf seine Gerätefunktionen an, z. B. eine Kamera, eine Geolocation oder ein Mikrofon.

Alle angeforderten Berechtigungen werden dem Benutzer in einem einzigen modalem Dialogfeld angezeigt. Das Dialogfeld enthält Optionen zum Zulassen, einmal zulassen oder die angeforderten Berechtigungen verweigern .

Diese Methode akzeptiert eine Rückruffunktion. Verwenden Sie es mit Outlook-Add-Ins.

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

Parameter

permissions

Office.DevicePermissionType[]

Ein Array von Gerätefunktionen, auf das ein Add-In Zugriff anfordert. In Outlook im Web und dem neuen Outlook unter Windows kann ein Add-In Zugriff auf die Kamera, geolocation und das Mikrofon eines Benutzers anfordern.

options
Office.AsyncContextOptions

Ein Objektliteral, das die asyncContext -Eigenschaft enthält. Weisen Sie der -Eigenschaft jedes Objekt zu, auf das asyncContext Sie in der Rückruffunktion zugreifen möchten.

callback

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

Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter aufgerufen, asyncResult, der ein Office.AsyncResult -Objekt ist. Wenn der Benutzer die Berechtigung für den Zugriff auf die angeforderten Gerätefunktionen erteilt, true wird in der asyncResult.value -Eigenschaft zurückgegeben. Anschließend müssen Sie das Add-In erneut laden, bevor Sie Code ausführen können, der die Gerätefunktionen verwendet. Sie können beispielsweise aufrufen window.location.reload() , um Ihr Add-In erneut zu laden. Wenn der Benutzer zuvor die Berechtigung für den Zugriff auf die angeforderten Gerätefunktionen erteilt hatte, false wird in der asyncResult.value -Eigenschaft zurückgegeben. Sie müssen Ihr Add-In nicht erneut laden, um Code auszuführen, der die Gerätefunktion verwendet, da die Berechtigung bereits festgelegt ist. Wenn ein Benutzer den Zugriff auf die angeforderten Gerätefunktionen verweigert, Office.AsyncResultStatus.Failed wird in der asyncResult.status -Eigenschaft zurückgegeben.

Gibt zurück

void

Hinweise

Wichtig:

  • Verwenden Sie für Excel-, PowerPoint- und Word-Add-Ins stattdessen die requestPermissions -Methode.

  • Wenn Ihr Add-In denselben Code sowohl für Office im Web als auch für Office-Desktopclients verwendet, überprüfen Sie die Plattform, auf der das Add-In ausgeführt wird, bevor Sie aufrufen requestPermissionsAsync. Verwenden Sie Office.context.mailbox.diagnostics.hostName , und überprüfen Sie, ob zurückgegeben wird OutlookWebApp. Andernfalls gibt der requestPermissionsAsync Aufruf einen Fehler zurück.

  • Wenn ein Benutzer im Dialogfeld Zulassen auswählt, bleibt die Berechtigung bestehen, bis das Add-In deinstalliert wird oder bis der Cache des Browsers, in dem das Add-In ausgeführt wird, gelöscht wird. Wenn ein Benutzer den Zugriff eines Add-Ins auf seine Kamera oder sein Mikrofon ändern möchte, muss er das Add-In deinstallieren oder seinen Browsercache löschen.

  • Wenn ein Benutzer im Dialogfeld Einmal zulassen auswählt, bleibt die Berechtigung bestehen, bis die Browserregisterkarte oder das Fenster, in dem das Add-In ausgeführt wird, geschlossen wird.

  • Wenn ein Benutzer im Dialogfeld Verweigern auswählt, wird der Benutzer erneut um Berechtigungen gebeten, wenn das Add-In das nächste Mal Zugriff auf die Gerätefunktionen des Benutzers benötigt.

  • Wenn Ihr Add-In die ereignisbasierte Aktivierung implementiert, werden Browserberechtigungen für Gerätefunktionen nicht geerbt, und die requestPermissionsAsync Methode wird nicht unterstützt.

requestPermissionsAsync(permissions, callback)

Fordert von einem Benutzer die Berechtigung für den Zugriff auf seine Gerätefunktionen an, z. B. eine Kamera, eine Geolocation oder ein Mikrofon.

Alle angeforderten Berechtigungen werden dem Benutzer in einem einzigen modalem Dialogfeld angezeigt. Das Dialogfeld enthält Optionen zum Zulassen, einmal zulassen oder die angeforderten Berechtigungen verweigern .

Diese Methode akzeptiert eine Rückruffunktion. Verwenden Sie es mit Outlook-Add-Ins.

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

Parameter

permissions

Office.DevicePermissionType[]

Ein Array von Gerätefunktionen, auf das ein Add-In Zugriff anfordert. In Outlook im Web und dem neuen Outlook unter Windows kann ein Add-In Zugriff auf die Kamera, geolocation und das Mikrofon eines Benutzers anfordern.

callback

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

Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter aufgerufen, asyncResult, der ein Office.AsyncResult -Objekt ist. Wenn der Benutzer die Berechtigung für den Zugriff auf die angeforderten Gerätefunktionen erteilt, true wird in der asyncResult.value -Eigenschaft zurückgegeben. Anschließend müssen Sie das Add-In erneut laden, bevor Sie Code ausführen können, der die Gerätefunktionen verwendet. Sie können beispielsweise aufrufen window.location.reload() , um Ihr Add-In erneut zu laden. Wenn der Benutzer zuvor die Berechtigung für den Zugriff auf die angeforderten Gerätefunktionen erteilt hatte, false wird in der asyncResult.value -Eigenschaft zurückgegeben. Sie müssen Ihr Add-In nicht erneut laden, um Code auszuführen, der die Gerätefunktion verwendet, da die Berechtigung bereits festgelegt ist. Wenn ein Benutzer den Zugriff auf die angeforderten Gerätefunktionen verweigert, Office.AsyncResultStatus.Failed wird in der asyncResult.status -Eigenschaft zurückgegeben.

Gibt zurück

void

Hinweise

Wichtig:

  • Verwenden Sie für Excel-, PowerPoint- und Word-Add-Ins stattdessen die requestPermissions -Methode.

  • Wenn Ihr Add-In denselben Code sowohl für Office im Web als auch für Office-Desktopclients verwendet, überprüfen Sie die Plattform, auf der das Add-In ausgeführt wird, bevor Sie aufrufen requestPermissionsAsync. Verwenden Sie Office.context.mailbox.diagnostics.hostName , und überprüfen Sie, ob zurückgegeben wird OutlookWebApp. Andernfalls gibt der requestPermissionsAsync Aufruf einen Fehler zurück.

  • Wenn ein Benutzer im Dialogfeld Zulassen auswählt, bleibt die Berechtigung bestehen, bis das Add-In deinstalliert wird oder bis der Cache des Browsers, in dem das Add-In ausgeführt wird, gelöscht wird. Wenn ein Benutzer den Zugriff eines Add-Ins auf seine Kamera oder sein Mikrofon ändern möchte, muss er das Add-In deinstallieren oder seinen Browsercache löschen.

  • Wenn ein Benutzer im Dialogfeld Einmal zulassen auswählt, bleibt die Berechtigung bestehen, bis die Browserregisterkarte oder das Fenster, in dem das Add-In ausgeführt wird, geschlossen wird.

  • Wenn ein Benutzer im Dialogfeld Verweigern auswählt, wird der Benutzer erneut um Berechtigungen gebeten, wenn das Add-In das nächste Mal Zugriff auf die Gerätefunktionen des Benutzers benötigt.

  • Wenn Ihr Add-In die ereignisbasierte Aktivierung implementiert, werden Browserberechtigungen für Gerätefunktionen nicht geerbt, und die requestPermissionsAsync Methode wird nicht unterstützt.

Beispiele

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