[zh-cn]: create the translation of MediaDevices.selectAudioOutput()…

… method (#21688)

Co-authored-by: A1lo <[email protected]>
Co-authored-by: skyclouds2001 <[email protected]>

files/zh-cn/web/api/htmlmediaelement/setsinkid/index.md

@@ -7,7 +7,7 @@ l10n:
 
 {{APIRef("Audio Output Devices API")}}{{securecontext_header}}
 
-{{domxref("HTMLMediaElement")}} 的 **`setSinkId()`** 方法设置要用于音频输出的设备 ID，并返回一个 {{jsxref("Promise")}}。
+{{domxref("HTMLMediaElement")}} 接口的 **`setSinkId()`** 方法设置要用于音频输出的设备 ID，并返回一个 {{jsxref("Promise")}}。
 
 只有当应用程序被允许使用指定的设备时，此方法才有效。有关更多信息，请参阅下面的[安全要求](#安全要求)。
 

files/zh-cn/web/api/htmlmediaelement/sinkid/index.md

@@ -7,7 +7,7 @@ l10n:
 
 {{APIRef("Audio Output Devices API")}}{{securecontext_header}}
 
-{{domxref("HTMLMediaElement")}} 的 **`sinkId`** 只读属性，返回一个作为播放音频输出的设备唯一 ID 的字符串。
+{{domxref("HTMLMediaElement")}} 接口的 **`sinkId`** 只读属性，返回一个作为播放音频输出的设备唯一 ID 的字符串。
 
 这个 ID 应该是从 {{domxref("MediaDevices.enumerateDevices()")}} 返回的 {{domxref("MediaDeviceInfo.deviceId")}} 值之一、`id-multimedia` 或 `id-communications`。如果正在使用用户代理的默认设备，它会返回一个空字符串。
 

files/zh-cn/web/api/mediadevices/selectaudiooutput/index.md

@@ -0,0 +1,104 @@
+---
+title: MediaDevices：selectAudioOutput() 方法
+slug: Web/API/MediaDevices/selectAudioOutput
+l10n:
+  sourceCommit: cfb7587e3e3122630ad6cbd94d834ecadbe0a746
+---
+
+{{APIRef("Audio Output Devices API")}}{{securecontext_header}}{{SeeCompatTable}}
+
+{{domxref("MediaDevices")}} 接口的 **`selectAudioOutput()`** 方法会提示用户选择一个音频输出设备，例如扬声器或耳机。如果用户选择了设备，该方法会授予用户权限，使选定的设备成为音频输出的目标。
+
+选择设备后，如果该设备可用，可以使用 {{domxref("MediaDevices.enumerateDevices()")}} 列出它，并使用 {{domxref("HTMLMediaElement.setSinkId()")}} 将其设置为音频输出目标。
+
+成功时，返回的 {{jsxref("Promise")}} 会兑现一个描述所选设备的 {{domxref("MediaDeviceInfo")}} 对象。
+
+## 语法
+
+```js-nolint
+selectAudioOutput()
+selectAudioOutput(options)
+```
+
+### 参数
+
+- `options` {{Optional_Inline}}
+
+  - : 对象，用于配置可以在用户提示中提供的设备。
+
+    - `deviceId` {{Optional_Inline}}
+
+      - : 表示单个先前公开或允许设备的 ID 的字符串。如果未设置，则会显示包含所有可用音频输出设备的提示。
+
+        该选项适用于希望存储设备 ID 以便将来会话中默认使用同一设备的应用程序。注意，方法可能会返回同一设备的新 ID，并且持久化的 ID 必须在 {{domxref("HTMLMediaElement.setSinkId","setSinkId()")}} 成功地通过 `selectAudioOutput()` 传递后才能使用。
+
+        > **备注：** 如果在先前会话中通过 `selectAudioOutput()` 向用户显示了指定的非空 ID，则用户代理可能会选择跳过提示用户的步骤。
+        > 在这种情况下，用户代理可能会简单地解析为此设备 ID，或者如果设备 ID 已更改，则解析为同一设备的新 ID。
+        > 如果先前授予了指定设备的权限，但此后被撤销，用户代理可能会显示所有允许的设备，并突出显示具有指定 ID 的设备。
+
+### 返回值
+
+{{ jsxref("Promise") }}，其会兑现一个描述用户选择的音频输出设备的 {{domxref("MediaDeviceInfo")}} 对象。
+
+### 异常
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : 如果使用 [`speaker-selection`](/zh-CN/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) [权限策略](/zh-CN/docs/Web/HTTP/Permissions_Policy)来阻止使用音频输出（此外不会显示用于选择音频输出的弹出窗口），或者用户关闭选择提示而没有选择设备时，则会返回此错误。
+- `NotFoundError` {{domxref("DOMException")}}
+  - : 如果没有可用的音频输出设备，则会返回此错误。
+- `InvalidStateError` {{domxref("DOMException")}}
+  - : 如果没有发生{{Glossary("transient activation", "瞬态激活")}}（你必须从某种 UI 事件中触发它），则会返回此错误。
+
+## 安全要求
+
+对此 API 的访问受以下约束：
+
+- 方法必须在[安全上下文](/zh-CN/docs/Web/Security/Secure_Contexts)中调用。
+- 需要[瞬态用户激活](/zh-CN/docs/Web/Security/User_activation)。
+  用户必须与页面或 UI 元素进行交互，才能使用此特性。
+- 访问可能受 [`speaker-selection`](/zh-CN/docs/Web/HTTP/Headers/Permissions-Policy/midi) HTTP [权限策略](/zh-CN/docs/Web/HTTP/Permissions_Policy)的控制。
+
+权限状态可以通过 [Permissions API](/zh-CN/docs/Web/API/Permissions_API) 的 {{domxref("Permissions.query", "navigator.permissions.query()")}} 方法进行查询（传递一个带有 `speaker-selection` 权限的权限描述符）。
+
+## 示例
+
+以下是使用 `selectAudioOutput()` 的示例，它在按钮点击时触发。它会输出所选的{{domxref("MediaDeviceInfo.deviceId", "设备 ID", "", "nocode")}} 和标签（如果可用），或者错误消息。
+
+```js
+document.querySelector("#myButton").addEventListener("click", () => {
+  if (!navigator.mediaDevices.selectAudioOutput) {
+    console.log("不支持 selectAudioOutput()。");
+    return;
+  }
+
+  // 显示提示并记录所选设备或错误
+  navigator.mediaDevices
+    .selectAudioOutput()
+    .then((device) => {
+      console.log(`${device.kind}: ${device.label} id = ${device.deviceId}`);
+    })
+    .catch((err) => {
+      console.error(`${err.name}: ${err.message}`);
+    });
+});
+```
+
+选择输出设备后，可能会产生如下输出：
+
+```bash
+audiooutput: Realtek Digital Output (Realtek(R) Audio) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- {{domxref("HTMLMediaElement.setSinkId()")}}
+- {{domxref("HTMLMediaElement.sinkId")}}
+- [WebRTC](/zh-CN/docs/Web/API/WebRTC_API) API 的介绍页面