navigator.mediaDevices API 教程

navigator.mediaDevices API 教程

1. 什么是 navigator.mediaDevices?

navigator.mediaDevices 是现代浏览器提供的 JavaScript API，允许 Web 应用安全访问用户的媒体设备（摄像头、麦克风、屏幕等）。它是实现音视频通话、屏幕录制、拍照等功能的基石。

支持场景：

• 视频会议（如 Zoom Web）
• 在线直播
• 浏览器截图/录屏工具
• 人脸识别类应用

---

2. 核心方法详解

2.1 getUserMedia(constraints)：请求媒体权限

作用：获取摄像头或麦克风的实时数据流。

参数：constraints 指定媒体类型和质量要求。

// 示例：获取摄像头视频（默认分辨率）
const constraints = {
  video: true,  // 开启视频
  audio: {      // 可选配置音频
    sampleSize: 16, 
    echoCancellation: true
  }
};

// 调用方法
navigator.mediaDevices.getUserMedia(constraints)
  .then(stream => {
    const videoElement = document.getElementById('video');
    videoElement.srcObject = stream; // 将流绑定到 <video> 元素
  })
  .catch(error => {
    console.error('媒体访问失败:', error.name); // 处理错误（如用户拒绝）
  });

常见错误类型：

• NotAllowedError：用户拒绝授权
• NotFoundError：无匹配设备
• OverconstrainedError：配置无法满足

---

2.2 enumerateDevices()：列出所有媒体设备

注意：需先通过 getUserMedia 获取权限，否则设备名称为空（隐私保护）。

navigator.mediaDevices.enumerateDevices()
  .then(devices => {
    devices.forEach(device => {
      console.log(`${device.kind}: ${device.label} (ID: ${device.deviceId})`);
    });
  });

// 输出示例：
// videoinput: FaceTime HD Camera (ID: xyz123)
// audioinput: Built-in Microphone (ID: abc456)

设备类型 (device.kind) 包括：

• audioinput（麦克风）
• videoinput（摄像头）
• audiooutput（扬声器）

---

2.3 getDisplayMedia(constraints)：共享屏幕内容

用途：实现屏幕录制或远程协作。

// 发起屏幕共享请求
navigator.mediaDevices.getDisplayMedia({ video: true })
  .then(stream => {
    const screenVideo = document.createElement('video');
    screenVideo.srcObject = stream;
    document.body.appendChild(screenVideo);
    screenVideo.play();
  });

浏览器会弹出窗口让用户选择共享整个屏幕、某个应用窗口或单个标签页。

---

3. 安全性要求

• 必须使用 HTTPS 或 localhost：非安全环境下（如 HTTP）API 不可用。
• 用户显式授权：浏览器会弹出提示框，无法静默获取权限。

---

4. 完整示例：拍照应用

<video id="preview" autoplay></video>
<button id="capture">拍照</button>
<canvas id="canvas" hidden></canvas>

<script>
const video = document.getElementById('preview');
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');

// 启动摄像头
navigator.mediaDevices.getUserMedia({ video: { width: 1280 } })
  .then(stream => video.srcObject = stream);

// 点击拍照
document.getElementById('capture').addEventListener('click', () => {
  canvas.width = video.videoWidth;
  canvas.height = video.videoHeight;
  ctx.drawImage(video, 0, 0);

  // 获取图片数据
  const photoData = canvas.toDataURL('image/png');
  const img = new Image();
  img.src = photoData;
  document.body.appendChild(img);
});
</script>

---

5. 兼容性与最佳实践

兼容性处理

• 旧版浏览器可能需要前缀（如 navigator.webkitGetUserMedia）
• 推荐使用适配库：webrtc-adapter

设备权限检查：

// 检测设备是否存在
navigator.mediaDevices.getUserMedia({ video: true })
  .catch(error => {
    if (error.name === 'NotFoundError') {
      alert('未检测到摄像头！');
    }
  });

最佳实践

1. 按需请求权限：仅在用户操作（如点击按钮）时调用，提升信任度。

2. 释放资源：停止不再使用的流。

   stream.getTracks().forEach(track => track.stop());
   

3. 响应式布局：根据设备支持的分辨率动态调整 constraints。

---

掌握 navigator.mediaDevices 是实现现代 Web 媒体应用的必备技能。合理处理权限和设备差异，将为用户提供无缝的多媒体体验。