Office.DevicePermission interface

Пакет:

office

Предоставляет методы для надстройки, чтобы запросить у пользователя разрешение на доступ к возможностям устройства. К возможностям устройства пользователя относятся камера, географическое расположение и микрофон.

Комментарии

Приложения. Этот API поддерживается следующими приложениями Office при запуске в браузерах на основе Chromium, таких как Microsoft Edge и Google Chrome.

• Excel в Интернете

• Outlook в Интернете

• PowerPoint в Интернете

• Word в Интернете

Он также поддерживается в новом Outlook для Windows (предварительная версия).

Набор обязательных требований: DevicePermission 1.1

Методы

requestPermissions(permissions)	Запрашивает у пользователя разрешение на доступ к возможностям устройства, таким как камера или микрофон. Все запрошенные разрешения отображаются для пользователя в одном модальном диалоговом окне. Диалоговое окно содержит параметры Разрешить, Разрешить один раз или Запретить запрошенные разрешения. Этот метод возвращает обещание. Используйте его с надстройками Excel, PowerPoint и Word. Если пользователь впервые предоставляет доступ к возможности устройства, обещание разрешается с trueпомощью . Затем необходимо перезагрузить надстройку, прежде чем выполнять код, использующий возможность устройства. Например, можно вызвать для window.location.reload() перезагрузки надстройки. Если пользователь ранее предоставлял доступ к возможности устройства, обещание разрешается с falseпомощью . Вам не нужно перезагружать надстройку для выполнения кода, использующего возможность устройства, так как разрешение уже задано. Если пользователь запрещает доступ к возможности устройства, обещание отклоняет сообщение об ошибке "Пользователь отказал в запросе разрешения".
requestPermissionsAsync(permissions, options, callback)	Запрашивает у пользователя разрешение на доступ к возможностям устройства, таким как камера, географическое расположение или микрофон. Все запрошенные разрешения отображаются для пользователя в одном модальном диалоговом окне. Диалоговое окно содержит параметры Разрешить, Разрешить один раз или Запретить запрошенные разрешения. Этот метод принимает функцию обратного вызова. Используйте его с надстройками Outlook.
requestPermissionsAsync(permissions, callback)	Запрашивает у пользователя разрешение на доступ к возможностям устройства, таким как камера, географическое расположение или микрофон. Все запрошенные разрешения отображаются для пользователя в одном модальном диалоговом окне. Диалоговое окно содержит параметры Разрешить, Разрешить один раз или Запретить запрошенные разрешения. Этот метод принимает функцию обратного вызова. Используйте его с надстройками Outlook.

Сведения о методе

requestPermissions(permissions)

Запрашивает у пользователя разрешение на доступ к возможностям устройства, таким как камера или микрофон.

Все запрошенные разрешения отображаются для пользователя в одном модальном диалоговом окне. Диалоговое окно содержит параметры Разрешить, Разрешить один раз или Запретить запрошенные разрешения.

Этот метод возвращает обещание. Используйте его с надстройками Excel, PowerPoint и Word.

Если пользователь впервые предоставляет доступ к возможности устройства, обещание разрешается с trueпомощью . Затем необходимо перезагрузить надстройку, прежде чем выполнять код, использующий возможность устройства. Например, можно вызвать для window.location.reload() перезагрузки надстройки. Если пользователь ранее предоставлял доступ к возможности устройства, обещание разрешается с falseпомощью . Вам не нужно перезагружать надстройку для выполнения кода, использующего возможность устройства, так как разрешение уже задано. Если пользователь запрещает доступ к возможности устройства, обещание отклоняет сообщение об ошибке "Пользователь отказал в запросе разрешения".

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

Параметры

permissions

Office.DevicePermissionType[]

Массив возможностей устройств, к которым надстройка запрашивает доступ. В веб-версиях Excel, PowerPoint и Word надстройки могут запрашивать доступ только к камере и микрофону пользователя. Доступ к географическому расположению пользователя блокируется.

Возвращаемое значение

Promise<boolean>

Комментарии

Важно!

• Этот метод не поддерживается в надстройках Outlook. Вместо этого используйте requestPermissionsAsync метод .

• Если надстройка использует один и тот же код как для office в Интернете, так и для классических клиентов Office, проверьте платформу, на которой выполняется надстройка, перед вызовом requestPermissions. Используйте Office.context.platform и убедитесь, что возвращается Office.PlatformType.OfficeOnline. В противном requestPermissions случае вызов вернет ошибку.

• Если пользователь выбирает Разрешить в диалоговом окне, разрешение сохраняется до удаления надстройки или до тех пор, пока не будет очищен кэш браузера, в котором выполняется надстройка. Если пользователь хочет изменить доступ надстройки к камере или микрофону, он должен удалить надстройку или очистить кэш браузера.

• Если пользователь выбирает Разрешить один раз в диалоговом окне, разрешение сохраняется до тех пор, пока вкладка или окно браузера, в котором выполняется надстройка, не будут закрыты.

• Если пользователь выберет Запретить в диалоговом окне, он снова запросит разрешения, когда надстройке в следующий раз потребуется доступ к возможностям устройства пользователя.

Примеры

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

Запрашивает у пользователя разрешение на доступ к возможностям устройства, таким как камера, географическое расположение или микрофон.

Все запрошенные разрешения отображаются для пользователя в одном модальном диалоговом окне. Диалоговое окно содержит параметры Разрешить, Разрешить один раз или Запретить запрошенные разрешения.

Этот метод принимает функцию обратного вызова. Используйте его с надстройками Outlook.

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

Параметры

permissions

Office.DevicePermissionType[]

Массив возможностей устройств, к которым надстройка запрашивает доступ. В Outlook в Интернете надстройка может запрашивать доступ к камере пользователя, географическому расположению и микрофону.

options

Office.AsyncContextOptions

Литерал объекта, содержащий asyncContext свойство . Назначьте свойству любой объект, к которому вы хотите получить доступ в функции обратного asyncContext вызова.

callback

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

После завершения метода функция, переданная в callback параметре, вызывается с одним параметром Office.AsyncResult , asyncResultкоторый является объектом . Если пользователь предоставляет разрешение на доступ к запрошенным возможностям устройства, true возвращается в свойстве asyncResult.value . Затем необходимо перезагрузить надстройку, прежде чем выполнять код, использующий возможности устройства. Например, можно вызвать для window.location.reload() перезагрузки надстройки. Если пользователь ранее предоставил разрешение на доступ к запрошенным возможностям устройства, false возвращается в свойстве asyncResult.value . Вам не нужно перезагружать надстройку для выполнения кода, использующего возможность устройства, так как разрешение уже задано. Если пользователь запрещает доступ к запрошенным возможностям устройства, Office.AsyncResultStatus.Failed возвращается в свойстве asyncResult.status .

Возвращаемое значение

void

Комментарии

Важно!

• Для надстроек Excel, PowerPoint и Word используйте requestPermissions метод .

• Если надстройка использует один и тот же код как для office в Интернете, так и для классических клиентов Office, проверьте платформу, на которой выполняется надстройка, перед вызовом requestPermissionsAsync. Используйте Office.context.mailbox.diagnostics.hostName и убедитесь, что возвращается OutlookWebApp. В противном requestPermissionsAsync случае вызов вернет ошибку.

• Если пользователь выбирает Разрешить в диалоговом окне, разрешение сохраняется до удаления надстройки или до тех пор, пока не будет очищен кэш браузера, в котором выполняется надстройка. Если пользователь хочет изменить доступ надстройки к камере или микрофону, он должен удалить надстройку или очистить кэш браузера.

• Если пользователь выбирает Разрешить один раз в диалоговом окне, разрешение сохраняется до тех пор, пока вкладка или окно браузера, в котором выполняется надстройка, не будут закрыты.

• Если пользователь выберет Запретить в диалоговом окне, он снова запросит разрешения, когда надстройке в следующий раз потребуется доступ к возможностям устройства пользователя.

• Если надстройка реализует активацию на основе событий, разрешения браузера на возможности устройства не наследуются и requestPermissionsAsync метод не поддерживается.

requestPermissionsAsync(permissions, callback)

Запрашивает у пользователя разрешение на доступ к возможностям устройства, таким как камера, географическое расположение или микрофон.

Все запрошенные разрешения отображаются для пользователя в одном модальном диалоговом окне. Диалоговое окно содержит параметры Разрешить, Разрешить один раз или Запретить запрошенные разрешения.

Этот метод принимает функцию обратного вызова. Используйте его с надстройками Outlook.

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

Параметры

permissions

Office.DevicePermissionType[]

Массив возможностей устройств, к которым надстройка запрашивает доступ. В Outlook в Интернете надстройка может запрашивать доступ к камере пользователя, географическому расположению и микрофону.

callback

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

После завершения метода функция, переданная в callback параметре, вызывается с одним параметром Office.AsyncResult , asyncResultкоторый является объектом . Если пользователь предоставляет разрешение на доступ к запрошенным возможностям устройства, true возвращается в свойстве asyncResult.value . Затем необходимо перезагрузить надстройку, прежде чем выполнять код, использующий возможности устройства. Например, можно вызвать для window.location.reload() перезагрузки надстройки. Если пользователь ранее предоставил разрешение на доступ к запрошенным возможностям устройства, false возвращается в свойстве asyncResult.value . Вам не нужно перезагружать надстройку для выполнения кода, использующего возможность устройства, так как разрешение уже задано. Если пользователь запрещает доступ к запрошенным возможностям устройства, Office.AsyncResultStatus.Failed возвращается в свойстве asyncResult.status .

Возвращаемое значение

void

Комментарии

Важно!

• Для надстроек Excel, PowerPoint и Word используйте requestPermissions метод .

• Если надстройка использует один и тот же код как для office в Интернете, так и для классических клиентов Office, проверьте платформу, на которой выполняется надстройка, перед вызовом requestPermissionsAsync. Используйте Office.context.mailbox.diagnostics.hostName и убедитесь, что возвращается OutlookWebApp. В противном requestPermissionsAsync случае вызов вернет ошибку.

• Если пользователь выбирает Разрешить в диалоговом окне, разрешение сохраняется до удаления надстройки или до тех пор, пока не будет очищен кэш браузера, в котором выполняется надстройка. Если пользователь хочет изменить доступ надстройки к камере или микрофону, он должен удалить надстройку или очистить кэш браузера.

• Если пользователь выбирает Разрешить один раз в диалоговом окне, разрешение сохраняется до тех пор, пока вкладка или окно браузера, в котором выполняется надстройка, не будут закрыты.

• Если пользователь выберет Запретить в диалоговом окне, он снова запросит разрешения, когда надстройке в следующий раз потребуется доступ к возможностям устройства пользователя.

• Если надстройка реализует активацию на основе событий, разрешения браузера на возможности устройства не наследуются и requestPermissionsAsync метод не поддерживается.

Примеры

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