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 (Vorschauversion) 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.
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.

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 für Office im Web- und Office-Desktopclients verwendet, überprüfen Sie die Plattform, auf der das Add-In ausgeführt wird, bevor Sie aufrufenrequestPermissions. 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 der Benutzer den Zugriff auf seine Kamera oder sein Mikrofon zulässt, muss das Add-In im Browser neu geladen werden, damit die Berechtigungen wirksam werden. Sie können beispielsweise aufrufen window.location.reload() , um Ihr Add-In erneut zu laden.

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

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

                // 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 kann ein Add-In Zugriff auf die Kamera, den Geografischen Standort 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.

Gibt zurück

void

Hinweise

Wichtig:

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

  • Wenn der Benutzer den Zugriff auf seine Kamera, seine Geolocation oder sein Mikrofon zulässt, muss das Add-In im Browser neu geladen werden, damit die Berechtigungen wirksam werden. Sie können beispielsweise aufrufen window.location.reload() , um Ihr Add-In erneut zu laden.

  • Wenn Ihr Add-In denselben Code für Office im Web- und Office-Desktopclients verwendet, überprüfen Sie die Plattform, auf der das Add-In ausgeführt wird, bevor Sie aufrufenrequestPermissionsAsync. Verwenden Sie Office.context.mailbox.Diagnose. hostName, und überprüfen Sie, ob zurückgegeben wirdOutlookWebApp. 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 kann ein Add-In Zugriff auf die Kamera, den Geografischen Standort 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.

Gibt zurück

void

Hinweise

Wichtig:

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

  • Wenn der Benutzer den Zugriff auf seine Kamera, seine Geolocation oder sein Mikrofon zulässt, muss das Add-In im Browser neu geladen werden, damit die Berechtigungen wirksam werden. Sie können beispielsweise aufrufen window.location.reload() , um Ihr Add-In erneut zu laden.

  • Wenn Ihr Add-In denselben Code für Office im Web- und Office-Desktopclients verwendet, überprüfen Sie die Plattform, auf der das Add-In ausgeführt wird, bevor Sie aufrufenrequestPermissionsAsync. Verwenden Sie Office.context.mailbox.Diagnose. hostName, und überprüfen Sie, ob zurückgegeben wirdOutlookWebApp. 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 (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.
        }
    });
}