<usermedia> HTML 元素简介

Mari Viana
Mari Viana
LinkedIn
Minh Le
Minh Le
LinkedIn

发布时间：2026 年 6 月 29 日

继 Chrome 144 中推出 <geolocation> 元素 之后，功能 元素套件中的下一个功能控制元素是 <usermedia> HTML 元素。 此元素自 Chrome 151 起提供，标志着从通用权限请求到有针对性的功能控制（用于访问摄像头和麦克风流）的过渡进入下一阶段。通过从脚本触发的 提示转向声明式用户激活体验，<usermedia> 减少了样板代码，提高了安全性，并为之前拒绝访问权限的用户提供了无缝恢复 路径，从而有效解决了 长期存在的权限漏洞。

从权限管理到功能控制

在成功推出 <geolocation>之后，<usermedia>元素是 功能元素套件中推出的下一个专用控制元素。这种从原始通用 <permission> 提案（PEPC 计划的一部分）的过渡，让浏览器能够更有效地处理不同硬件功能的独特 复杂性和行为。 虽然早期提案主要侧重于管理权限状态（例如允许与拒绝），但功能元素充当数据中介。

<geolocation> 元素为您的网站提供位置对象，而 <usermedia> 管理摄像头和麦克风访问的整个流程。它会捕获用户意图，管理浏览器提示，并将 MediaStream 对象传递给应用。这种转变消除了对单独 getUserMedia() 调用的需求，简化了实现，并确保浏览器拥有用户意图的可信信号。

概念验证

初始源试用中的真实数据表明，上下文内用户发起的权限控制显著提高了用户成功率。

  • Cisco 观察到，最初拒绝权限的用户使用旧版提示成功授予权限的可能性仅为 10% 左右，但使用新元素后，这一比例跃升至 65% 以上。
  • Zoom 报告称，通过使用该元素引导用户完成恢复，摄像头或麦克风捕获错误（例如系统级阻止程序）减少了 46.9% ；
  • Google Meet 发现，“麦克风无法正常工作”反馈减少了 17% ，而最初拒绝访问权限的用户成功恢复权限的比例增加了 131% 。

为什么要使用 <usermedia> 元素？

<usermedia> 元素以 <geolocation> 建立的模式为基础，解决了请求强大功能的核心挑战。媒体请求依赖于强制性 JavaScript 调用，这些调用通常会触发上下文外的提示。如果您不小心屏蔽了您的网站，则需要深入浏览浏览器设置才能撤消该决定，而这种“权限漏洞”通常会导致功能被弃用。

<usermedia> 元素通过提供以下内容来解决这些问题：

  • 明确的意图和时间安排： 由于提示仅在物理轻触浏览器控制的元素后才会显示，因此它提供了可信的意图信号。这让浏览器可以绕过自动静默屏蔽，而这些屏蔽通常会导致典型的脚本触发的请求失败。
  • 简化的恢复： 如果之前拒绝了访问权限，轻触该元素会触发一个专门的恢复流程，让您可以在页面上立即重新启用摄像头或麦克风，而无需浏览复杂的浏览器设置。
  • 直接流访问： 作为数据中介，该元素直接公开媒体流。这减少了在应用中管理回调和错误状态所需的样板代码。
功能 getUserMedia() JS API <usermedia> HTML 元素
权限提示的触发事件 强制性脚本执行 (getUserMedia) 用户点击浏览器控制的元素
浏览器角色 根据状态和启发法决定提示 充当数据中介（管理同意和流传递）
场地责任 手动调用 JavaScript API、处理回调和管理错误 监听 stream 事件并访问 stream 属性
核心目标 基本的摄像头和麦克风访问 流访问、权限管理和恢复，减少摩擦

实现

与旧版 JavaScript API 相比，集成该元素所需的样板代码要少得多。按照 <geolocation> 元素建立的声明式模式，您可以将 <usermedia> 标记添加到 HTML 中，并 使用 setConstraints() 方法配置硬件要求。

<usermedia id="media-ctrl">
  <button>Enable camera and microphone</button>
</usermedia>

const el = document.getElementById('media-ctrl');

// Specify hardware preferences before user interaction:
el.setConstraints({
    video: { width: 1280, height: 720 },
    audio: { echoCancellation: true }
});

// Handle successful stream acquisition:
el.addEventListener('stream', () => {
  videoPreview.srcObject = el.stream;
});

// Handle stream acquisition failure:
el.addEventListener('error', () => {
  console.error(`Access failed: ${el.error?.name}`);
});

// Handle prompt cancellation or dismissal:
el.addEventListener('cancel', () => {
  console.log('Permission prompt was dismissed by the user.');
});

关键属性和特性

  • stream：一个只读属性，用于在用户成功授予访问权限后提供 MediaStream 对象。
  • setConstraints()：一种方法，让开发者可以在用户互动之前更新硬件偏好设置，例如 deviceId 或分辨率。
  • error：一个只读属性，用于在请求失败或被关闭时返回 DOMException（例如 NotAllowedError）。
  • onstream：一个事件处理脚本，在媒体轨道获取后立即触发。
  • onerror：一个事件处理脚本，在流获取尝试失败时触发。
  • oncancel：一个事件处理脚本，在用户在获取期间取消或关闭权限提示时触发。

样式限制

为了确保用户信任并防止欺骗性设计模式，<usermedia> 元素与其他功能 元素一样，应用了严格的样式限制：

  • 易读性： 浏览器会检查文本和背景颜色是否有足够的对比度（至少 3:1），以确保请求始终可读。您必须将 Alpha 通道 (opacity) 设置为 1，以防止元素具有欺骗性的透明度。
  • 尺寸和间距： 浏览器会强制执行 width、height 和 font-size 的最小和最大边界。它会停用负边距或轮廓偏移，以防止元素在视觉上被遮盖。
  • 视觉完整性： 浏览器会限制扭曲效果。例如，transform 仅支持 2D 转换和比例缩放。
  • CSS 伪类： 该元素支持基于状态的样式，例如 :granted （在权限处于活动状态且流已获取后激活），以及标准互动状态（如 :hover 和 :active ）。

渐进增强和迁移策略

按照 <geolocation> 建立的设计模式，<usermedia> 元素旨在优雅地降级。不支持该元素的浏览器会将其视为 HTMLUnknownElement 并呈现其子元素。这样，您就可以为所有用户提供后备体验。

自定义后备模式

以编程方式检测 JavaScript 中对 <usermedia> 元素的支持：

if ('HTMLUserMediaElement' in window) {
  // Use modern <usermedia> element logic
} else {
  // Fallback to legacy getUserMedia() API
}

使用此检测逻辑在 <usermedia> 元素内添加一个标准按钮，以触发旧版 getUserMedia() API：

<usermedia id="stream-handler">
    <button id="fallback-stream-handler">
        Enable Camera and Mic
    </button>
</usermedia>

// Function for handling video/audio streams:
function handleStream (event) {
  /* ... */
}

if ('HTMLUserMediaElement' in window) {
  // In this case, we have <usermedia> element support:
  const streamHandler = document.getElementById('stream-handler');

  streamHandler.addEventListener('stream', event => {
    handleStream(event);
  });
} else {
  // <usermedia> element support is missing, so fall back instead:
  const fallbackStreamHandler = document.getElementById('fallback-stream-handler');

  fallbackStreamHandler.addEventListener('click', event => {
    navigator.mediaDevices.getUserMedia({video: true, audio: true}).then(handleStream);
  });
}

源试用参与者的迁移

对于在源试用期间集成了实验性通用 <permission> 元素的开发者，向 <usermedia> 的过渡旨在 尽可能减少。

  1. 标记更新： 将 <permission type="camera microphone"> 替换为 <usermedia>，以确保所有以之前的 <permission> 元素为目标的选择器都更新为改用 <usermedia> 元素 。
  2. 功能检测： 将检查从 HTMLPermissionElement 更新为 HTMLUserMediaElement

未来的路线图

虽然 <usermedia> 元素处理组合的音频和视频请求，但 未来功能元素的路线图包括：

  • <camera>：专门侧重于仅视频场景。
  • <microphone>：专门侧重于仅音频场景。

您可以看到，这些特定于功能性的元素如何帮助开发者构建更直观、更值得信赖的媒体体验。如需了解详情，请参阅 功能元素技术 指南。