请求 Teams 应用的设备权限

  • 项目

可使用本机设备功能（如摄像头、麦克风和位置）丰富 Teams 应用。 本文档指导如何请求用户同意和访问本机设备权限。

注意

本机设备权限

必须请求设备权限才能访问本机设备功能。 设备权限适用于所有应用构造，例如选项卡、对话框 (TeamsJS v1.x) 中称为任务模块或消息扩展。 用户必须转到 Teams 设置中的权限页面才能管理设备权限。 通过访问设备功能，您可以在 Teams 平台上构建更丰富的体验，例如：

  • 捕获和查看图像
  • 扫描 QR 或条形码
  • 录制和共享短视频
  • 录制音频备忘录并保存以供日后使用
  • 使用用户的位置信息显示相关信息

注意

  • 在浏览器中，设备权限有所不同。 有关详细信息，请参阅浏览器设备权限。
  • Teams 支持 QR 条形码扫描仪功能，此功能仅适用于移动客户端。

访问设备权限

Microsoft Teams JavaScript 客户端库提供了 Teams 应用访问用户设备权限和构建更丰富的体验所需的工具。

虽然在 web 浏览器中一般都能访问这些功能，但必须通过更新应用清单来通知 Teams 你使用的功能。 通过此更新，可以在应用在 Teams 桌面上运行时请求权限。

管理权限

用户可以通过选择允许或拒绝特定应用的权限，在 Teams 设置中管理设备权限。

  1. 打开 Teams。

  2. 转到 “设置”“>应用权限”。

  3. 选择要为其自定义设置的应用。

  4. 选择所需设置。

    屏幕截图显示了移动应用权限。

指定权限

通过添加 devicePermissions 并指定应用中使用的以下五个属性中的哪一个来更新应用的 manifest.json：

"devicePermissions": [
    "media",
    "geolocation",
    "notifications",
    "midi",
    "openExternal"
],

每个属性都允许提示用户请求其同意：

属性 说明
媒体 允许使用摄像头、麦克风、扬声器和访问媒体库。
地理位置 返回用户位置的权限。
通知 发送用户通知的权限。
midi 从数字乐器发送和接收乐器数字接口 (MIDI) 信息的权限。
openExternal 在外部应用中打开链接的权限。

有关详细信息，请参阅 应用清单。

检查应用的权限

添加 devicePermissions 到应用清单后，请使用 HTML5 权限 API 检查权限，而不导致出现提示：

// Different query options:
navigator.permissions.query({ name: 'camera' });
navigator.permissions.query({ name: 'microphone' });
navigator.permissions.query({ name: 'geolocation' });
navigator.permissions.query({ name: 'notifications' });
navigator.permissions.query({ name: 'midi', sysex: true });

// Example:
navigator.permissions.query({name:'geolocation'}).then(function(result) {
  if (result.state == 'granted') {
    // Access granted
  } else if (result.state == 'prompt') {
    // Access has not been granted
  }
});

使用 Teams API 获取设备权限

利用适当的 HTML5 或 Teams API 显示一条提示，提示你同意访问设备权限。

重要

  • 通过 selectMedia API 启用对 camera、gallery和 microphone 的支持。 使用 captureImage API 进行单一图像捕获。
  • 通过 getLocation API 启用对 location 的支持。 必须将其 getLocation API 用于位置，因为目前 Teams 桌面上并不完全支持 HTML5 地理位置 API。

例如：

  • 若要提示用户访问其位置，必须调用 getCurrentPosition()：

    navigator.geolocation.getCurrentPosition(function (position) { /*... */ });

  • 若要提示用户在桌面或 Web 上访问其相机，必须调用 getUserMedia()：

    navigator.mediaDevices.getUserMedia({ audio: true, video: true });

  • 若要在移动设备上捕获图像，Teams 移动版在调用 captureImage()时会请求权限：

            function captureImage() {
        microsoftTeams.media.captureImage((error, files) => {
            // If there's any error, an alert shows the error message/code
            if (error) {
                if (error.message) {
                    alert(" ErrorCode: " + error.errorCode + error.message);
                } else {
                    alert(" ErrorCode: " + error.errorCode);
                }
            } else if (files) {
                image = files[0].content;
                // Adding this image string in src attr of image tag will display the image on web page.
                let imageString = "data:" + item.mimeType + ";base64," + image;
            }
        });
    }

  • 调用 requestPermission()时，通知会提示用户：

    Notification.requestPermission(function(result) { /* ... */ });

  • 若要使用相机或访问照片库，Teams 应用在调用 selectMedia()时会请求权限：

     function selectMedia() {
 microsoftTeams.media.selectMedia(mediaInput, (error, attachments) => {
     // If there's any error, an alert shows the error message/code
     if (error) {
         if (error.message) {
             alert(" ErrorCode: " + error.errorCode + error.message);
         } else {
             alert(" ErrorCode: " + error.errorCode);
         }
     } else if (attachments) {
         // creating image array which contains image string for all attached images. 
         const imageArray = attachments.map((item, index) => {
             return ("data:" + item.mimeType + ";base64," + item.preview)
         })
     }
 });
}

  • 要使用麦克风，Teams 移动版会在调用 selectMedia() 时请求权限：

     function selectMedia() {
 microsoftTeams.media.selectMedia({ maxMediaCount: 1, mediaType: microsoftTeams.media.MediaType.Audio }, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
     // If there's any error, an alert shows the error message/code
     if (error) {
         if (error.message) {
             alert(" ErrorCode: " + error.errorCode + error.message);
         } else {
             alert(" ErrorCode: " + error.errorCode);
         }
     }

     if (attachments) {
         // taking the first attachment  
         let audioResult = attachments[0];

         // setting audio string which can be used in Video tag
         let audioData = "data:" + audioResult.mimeType + ";base64," + audioResult.preview
     }
 });
 }

  • 为了提示用户在地图界面上共享位置，Teams 应用在调用 getLocation()时会请求权限：

     function getLocation() {
        location.getLocation({ allowChooseLocation: true, showMap: true }).then((location) => { 
            let currentLocation = JSON.stringify(location);
     }).catch((error) => { /*Error getting location*/ })}

下面是设备权限提示对移动设备和桌面用户显示的方式。

跨登录会话的权限行为

为每个登录会话存储设备权限。 这意味着，如果你登录到另一个 Teams 实例（例如，在另一台计算机上），则你以前会话中的设备权限不可用。 因此，必须重新访问新会话的设备权限。 它还意味着，如果你注销 Teams 或在 Teams 中切换租户，你的设备权限将从上一个登录会话中删除。

注意

同意本机设备权限时，它仅对当前登录会话有效。

代码示例

示例名称 Description Node.js 清单
设备权限 此示例演示如何使用 TeamsJS SDK 和浏览器 API 使用设备权限。 View View

后续步骤

浏览器的设备权限

另请参阅