<Usermedia> HTML 元素

# 介绍 HTML 元素 | 博客 | Chrome for Developers 来源：https://developer.chrome.com/blog/usermedia-html-element?hl=es-419 Mari Viana Minh Le 发布于 2026 年 6 月 29 日 在 Chrome 144 中推出 `<geolocation>` 元素（https://developer.chrome.com/blog/geolocation-html-element?hl=es-419）之后，功能元素集中的下一个控件是 HTML `<usermedia>` 元素。从 Chrome 151 开始可用，该元素标志着从通用权限请求向特定功能控件的过渡，用于访问摄像头和麦克风流。通过远离脚本触发的提示，转向声明式、用户触发的体验，`<usermedia>` 减少了样板代码，增强了安全性，并为之前拒绝访问的用户提供了顺畅的恢复路径，有效解决了长期存在的权限问题。 ## 从权限管理到功能控制 `<usermedia>` 元素是能力元素集中推出的下一个专用控件，继 `<geolocation>` 的成功引入之后。这种从原始通用 `<permission>` 元素（作为 PEPC 倡议的一部分）的转变，使浏览器能够更有效地处理不同硬件能力的复杂性和独特行为。虽然最初的提案主要关注权限状态管理（如允许或拒绝），但能力元素充当数据中介。`<geolocation>` 元素为你的网站提供位置对象，而 `<usermedia>` 管理摄像头和麦克风访问的整个流程。它捕获用户意图，管理浏览器提示，并将 `MediaStream` 对象交付给应用程序。这一变化消除了单独调用 `getUserMedia()` 的需要，简化了实现，并确保浏览器有可靠的用户意图指示器。 ## 概念验证 来自初始源试验的真实世界数据表明，由用户发起且上下文相关的权限控件显著提高了用户成功率。 - Cisco 观察到，最初拒绝权限的用户只有 **10%** 的概率通过旧版提示正确授予权限，而新元素将这一比例提升至 **65%** 以上。 - **Zoom** 报告称，借助该元素引导用户恢复，摄像头或麦克风捕获错误（如系统级拦截器）**减少了 46.9%**。 - **Google Meet** 记录到关于麦克风不工作的反馈 **减少了 17%**，并且对于最初拒绝访问的用户，权限恢复成功率 **增加了 131%**。 基于 `<geolocation>` 确立的模式，`<usermedia>` 元素解决了请求强大能力的主要挑战。媒体请求依赖于 JavaScript 的命令式调用，这些调用通常触发上下文外的提示。如果你意外阻止了你的网站，撤销该决定需要深入浏览器设置，这是一个常导致功能被放弃的“权限黑洞”。`<usermedia>` 元素通过以下方式解决这些问题： - **清晰的意图和时间点：** 由于提示仅在物理点击浏览器控制的元素后出现，它提供了可靠的意图指示器。这使得浏览器能够跳过通常导致典型脚本触发请求失败的静默自动拦截。 - **简化恢复：** 如果之前拒绝了访问，按下该元素会触发专用的恢复流程，让你能在页面上立即重新启用摄像头或麦克风，而无需浏览复杂的浏览器设置。 - **直接获取流：** 作为数据中介，该元素直接暴露媒体流。这减少了管理回调和应用中错误状态所需的样板代码。 ## 实现 集成该元素所需的样板代码比传统的 JavaScript API 少得多。遵循 `<geolocation>` 元素建立的声明式模式，你可以将 `<usermedia>` 标签添加到 HTML，并使用 `setConstraints()` 方法配置硬件需求。 ```html <usermedia id="media-ctrl"> Enable camera and microphone </usermedia> <video id="videoPreview" autoplay playsinline></video> ``` ```javascript 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>` 元素的支持： ```javascript if ('HTMLUserMediaElement' in window) { // Use modern element logic } else { // Fallback to legacy getUserMedia() API } ``` 使用此检测逻辑在 `<usermedia>` 元素内添加一个标准按钮，以触发传统的 `getUserMedia()` API： ```html <usermedia id="stream-handler"> <button id="fallback-stream-handler">Enable Camera and Mic</button> </usermedia> ``` ```javascript // Function for handling video/audio streams: function handleStream (event) { /* ... */ } if ('HTMLUserMediaElement' in window) { // In this case, we have element support: const streamHandler = document.getElementById('stream-handler'); streamHandler.addEventListener('stream', event => { handleStream(event); }); } else { // 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>` 替换为 `<usermedia>`，以确保所有针对之前 `<permission>` 元素的选择器都更新为使用 `<usermedia>` 元素。 2. **功能检测：** 将 `HTMLPermissionElement` 检查更新为 `HTMLUserMediaElement`。 ## 未来路线图 虽然 `<usermedia>` 元素处理音频和视频的联合请求，但未来能力元素的路线图包括： - `<usermedia-video>`：专门针对仅视频场景。 - `<usermedia-audio>`：专门针对仅音频场景。 你可以看到这些能力特定元素如何帮助开发者创建更直观、更可靠的媒体体验。更多信息，请参阅能力元素技术指南（https://github.com/w3c/mediacapture-extensions/blob/main/media-capture-elements-explainer.md）。 - 能力元素：`<usermedia>` 元素说明（https://github.com/w3c/mediacapture-extensions/blob/main/media-capture-elements-explainer.md） - 规范（https://w3c.github.io/mediacapture-extensions/#the-usermedia-html-element） - 介绍 HTML `<geolocation>` 元素（https://developer.chrome.com/blog/geolocation-html-element?hl=es-419）