[zh-cn]: create docs for HIDDevice (#24290)

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

files/zh-cn/web/api/hiddevice/close/index.md

@@ -0,0 +1,40 @@
+---
+title: HIDDevice：close() 方法
+slug: Web/API/HIDDevice/close
+l10n:
+  sourceCommit: 534e2c61fee576355e8a9b7036d9fa36056edb03
+---
+
+{{securecontext_header}}{{APIRef("WebHID API")}}{{SeeCompatTable}}{{AvailableInWorkers("window_and_worker_except_shared")}}
+
+{{domxref("HIDDevice")}} 接口的 **`close()`** 方法用于关闭 HID 设备的连接。
+
+## 语法
+
+```js-nolint
+close()
+```
+
+### 参数
+
+无。
+
+### 返回值
+
+一个 {{jsxref("Promise")}}，会在连接关闭时兑现为 `undefined`。
+
+## 示例
+
+在以下示例中，一旦所有数据已发送和接收，我们就关闭 HID 设备。
+
+```js
+await device.close();
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}

files/zh-cn/web/api/hiddevice/collections/index.md

@@ -0,0 +1,93 @@
+---
+title: HIDDevice：collections 属性
+slug: Web/API/HIDDevice/collections
+l10n:
+  sourceCommit: 534e2c61fee576355e8a9b7036d9fa36056edb03
+---
+
+{{securecontext_header}}{{APIRef("WebHID API")}}{{SeeCompatTable}}{{AvailableInWorkers("window_and_worker_except_shared")}}
+
+{{domxref("HIDDevice")}} 接口的 **`collections`** 只读属性返回报告格式的数组。
+
+## 值
+
+一个报告格式数组，每个条目包含以下内容：
+
+- `usagePage`
+
+  - : 一个整数，表示请求设备的 HID 用途中的用途页面组件。顶级集合的用途用于识别设备类型。
+
+    可以在 [HID 使用表](https://usb.org/document-library/hid-usage-tables-15)文档中找到标准 HID 用途值。
+
+- `usage`
+  - : 一个整数，表示此集合关联的 HID 用途中的用途 ID 组件。
+- `type`
+
+  - : 一个 8 位值，表示集合类型，描述分组条目之间的不同关系。为以下值之一：
+
+    - `0x00`
+      - : 物理（Physical）（轴组）
+    - `0x01`
+      - : 应用（Application）（鼠标、键盘）
+    - `0x02`
+      - : 逻辑（Logical）（相关数据）
+    - `0x03`
+      - : 报告（Report）
+    - `0x04`
+      - : 具名数组
+    - `0x05`
+      - : 用途开关
+    - `0x06`
+      - : 修改后的用途
+    - `0x07` 到 `0x7F`
+      - : 保留供未来使用
+    - `0x80` 到 `0xFF`
+      - : 供应商定义
+
+    有关这些类型的更多信息，请参阅[设备类定义](https://www.usb.org/document-library/device-class-definition-hid-111)文档。
+
+- `children`
+  - : 一个子集合数组，采用与顶级集合相同的格式。
+- `inputReports`
+  - : 一个 `inputReport` 项数组，表示此集合中描述的各个输入报告。
+- `outputReports`
+  - : 一个 `outputReport` 项数组，表示此集合中描述的各个输出报告。
+- `featureReports`
+  - : 一个 `featureReport` 项数组，表示此集合中描述的各个特征报告。
+
+## 示例
+
+以下示例演示如何在返回 `collections` 属性后访问各个元素。你可以在文章[连接到不常见的 HID 设备](https://developer.chrome.google.cn/docs/capabilities/hid)中看到更多示例和实时演示。
+
+```js
+for (const collection of device.collections) {
+  // 一个 HID 集合包括用途、用途页面、报告和子集合。
+  console.log(`用途：${collection.usage}`);
+  console.log(`用途页面：${collection.usagePage}`);
+
+  for (const inputReport of collection.inputReports) {
+    console.log(`输入报告：${inputReport.reportId}`);
+    // 遍历 inputReport.items
+  }
+
+  for (const outputReport of collection.outputReports) {
+    console.log(`输出报告：${outputReport.reportId}`);
+    // 遍历 outputReport.items
+  }
+
+  for (const featureReport of collection.featureReports) {
+    console.log(`特征报告：${featureReport.reportId}`);
+    // 遍历 featureReport.items
+  }
+
+  // 使用 collection.children 遍历子集合
+}
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}

files/zh-cn/web/api/hiddevice/forget/index.md

@@ -0,0 +1,60 @@
+---
+title: HIDDevice：forget() 方法
+slug: Web/API/HIDDevice/forget
+l10n:
+  sourceCommit: e4d6e3444fc0f46a2f12de882c5b12c44fb75e02
+---
+
+{{securecontext_header}}{{APIRef("WebHID API")}}{{SeeCompatTable}}{{AvailableInWorkers("window_and_worker_except_shared")}}
+
+{{domxref("HIDDevice")}} 接口的 **`forget()`** 方法会关闭 HID 设备的连接并忘记该设备。
+
+## 语法
+
+```js-nolint
+forget()
+```
+
+### 参数
+
+无。
+
+### 返回值
+
+一个 {{jsxref("Promise")}}，会在连接关闭、设备被遗忘且权限重置时兑现为 `undefined`。
+
+## 示例
+
+在以下示例中，我们将连接到一个任天堂（Nintendo）Switch 的 Joy-Con 右手柄 HID 设备，使其闪烁一次，然后断开与它的连接。
+
+```js
+async function blink() {
+  const devices = await navigator.hid.requestDevice({
+    filters: [
+      {
+        vendorId: 0x057e, // 任天堂株式会社（Nintendo Co., Ltd）
+        productId: 0x2007, // Joy-Con 右手柄
+      },
+    ],
+  });
+  const device = devices[0];
+  await device.open();
+  // 关闭
+  await device.sendFeatureReport(reportId, Uint32Array.from([0, 0]));
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  // 打开
+  await device.sendFeatureReport(reportId, Uint32Array.from([512, 0]));
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  // 最后，断开与它的连接
+  await device.forget();
+}
+blink();
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}

files/zh-cn/web/api/hiddevice/index.md

@@ -0,0 +1,92 @@
+---
+title: HIDDevice
+slug: Web/API/HIDDevice
+l10n:
+  sourceCommit: e4d6e3444fc0f46a2f12de882c5b12c44fb75e02
+---
+
+{{securecontext_header}}{{APIRef("WebHID API")}}{{SeeCompatTable}}{{AvailableInWorkers("window_and_worker_except_shared")}}
+
+[WebHID API](/zh-CN/docs/Web/API/WebHID_API) 的 **`HIDDevice`** 接口表示人机接口（HID）设备。它提供了用于访问设备信息的属性，打开和关闭的方法，以及发送和接收报告的功能。
+
+{{InheritanceDiagram}}
+
+## 实例属性
+
+_此接口也从其父接口 {{domxref("EventTarget")}} 继承属性。_
+
+- {{domxref("HIDDevice.opened")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : 返回一个 {{jsxref("boolean")}} 值，如果设备已打开连接，则为 `true`。
+- {{domxref("HIDDevice.vendorId")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : 返回 HID 设备的供应商 ID。
+- {{domxref("HIDDevice.productId")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : 返回 HID 设备的产品 ID。
+- {{domxref("HIDDevice.productName")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : 返回一个包含 HID 设备产品名称的字符串。
+- {{domxref("HIDDevice.collections")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : 返回 HID 设备的报告格式数组。
+
+### 事件
+
+- {{domxref("HIDDevice.inputreport_event", "inputreport")}} {{Experimental_Inline}}
+  - : 当设备发送报告时触发。
+
+## 实例方法
+
+_此接口也从其父接口 {{domxref("EventTarget")}} 继承方法。_
+
+- {{domxref("HIDDevice.open()")}} {{Experimental_Inline}}
+  - : 打开此 HID 设备的连接，并返回一个会在连接成功时兑现的 {{jsxref("Promise")}}。
+- {{domxref("HIDDevice.close()")}} {{Experimental_Inline}}
+  - : 关闭此 HID 设备的连接，并返回一个会在连接关闭时兑现的 {{jsxref("Promise")}}。
+- {{domxref("HIDDevice.forget()")}} {{Experimental_Inline}}
+  - : 关闭此 HID 设备的连接并重置访问权限，然后返回一个会在权限被重置时兑现的 {{jsxref("Promise")}}。
+- {{domxref("HIDDevice.sendReport()")}} {{Experimental_Inline}}
+  - : 向此 HID 设备发送输出报告，并返回一个会在报告发送成功时兑现的 {{jsxref("Promise")}}。
+- {{domxref("HIDDevice.sendFeatureReport()")}} {{Experimental_Inline}}
+  - : 向此 HID 设备发送一个特征报告，并返回一个会在报告发送成功时兑现的 {{jsxref("Promise")}}。
+- {{domxref("HIDDevice.receiveFeatureReport()")}} {{Experimental_Inline}}
+  - : 从 HID 设备接收一个特征报告，以 {{jsxref("Promise")}} 的形式兑现为 {{jsxref("DataView")}}。从而允许以类型化的方式访问此消息的内容。
+
+## 示例
+
+以下示例演示如何监听 `inputreport` 事件，该事件允许应用程序检测到 Joy-Con 右手柄设备上的哪个按钮被按下。
+
+```js
+device.addEventListener("inputreport", (event) => {
+  const { data, device, reportId } = event;
+
+  // 处理 Joy-Con 右手柄设备和特定的报告 ID
+  if (device.productId !== 0x2007 && reportId !== 0x3f) return;
+
+  const value = data.getUint8(0);
+  if (value === 0) return;
+
+  const someButtons = { 1: "A", 2: "X", 4: "B", 8: "Y" };
+  console.log(`用户按下了 ${someButtons[value]}。`);
+});
+```
+
+在以下示例中，用 `sendFeatureReport` 使设备闪烁。
+
+```js
+const reportId = 1;
+for (let i = 0; i < 10; i++) {
+  // 关闭
+  await device.sendFeatureReport(reportId, Uint32Array.from([0, 0]));
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  // 打开
+  await device.sendFeatureReport(reportId, Uint32Array.from([512, 0]));
+  await new Promise((resolve) => setTimeout(resolve, 100));
+}
+```
+
+你可以在文章[连接到不常见的 HID 设备](https://developer.chrome.google.cn/docs/capabilities/hid)中看到更多示例和实时演示。
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}

files/zh-cn/web/api/hiddevice/inputreport_event/index.md

@@ -0,0 +1,64 @@
+---
+title: HIDDevice：inputreport 事件
+slug: Web/API/HIDDevice/inputreport_event
+l10n:
+  sourceCommit: 534e2c61fee576355e8a9b7036d9fa36056edb03
+---
+
+{{securecontext_header}}{{APIRef("WebHID API")}}{{SeeCompatTable}}{{AvailableInWorkers("window_and_worker_except_shared")}}
+
+{{domxref("HIDDevice")}} 接口的 **`inputreport`** 事件在从 HID 设备接收新报告时会触发。
+
+## 语法
+
+在诸如 {{domxref("EventTarget.addEventListener", "addEventListener()")}} 之类的方法中使用事件名称，或设置事件处理器属性。
+
+```js
+addEventListener("inputreport", (event) => {});
+
+oninputreport = (event) => {};
+```
+
+## 事件类型
+
+一个 {{domxref("HIDInputReportEvent")}}。继承自 {{domxref("Event")}}。
+
+{{InheritanceDiagram("HIDInputReportEvent")}}
+
+## 事件属性
+
+_此接口也从其父接口 {{domxref("Event")}} 继承属性。_
+
+- {{domxref("HIDInputReportEvent.data")}} {{ReadOnlyInline}}
+  - : 一个 {{jsxref("DataView")}}，包含输入报告中的数据，如果 HID 接口使用报告 ID，则不包括 `reportId`。
+- {{domxref("HIDInputReportEvent.device")}} {{ReadOnlyInline}}
+  - : 表示发送输入报告的 HID 接口的 {{domxref("HIDDevice")}} 实例。
+- {{domxref("HIDInputReportEvent.reportId")}} {{ReadOnlyInline}}
+  - : 此报告的单字节标识前缀，如果 HID 接口不使用报告 ID，则为 `0`。
+
+## 示例
+
+以下示例演示如何监听 `inputreport` 事件，该事件允许应用程序检测到 Joy-Con 右手柄设备上的哪个按钮被按下。你可以在文章[连接到不常见的 HID 设备](https://developer.chrome.google.cn/docs/capabilities/hid)中看到更多示例和实时演示。
+
+```js
+device.addEventListener("inputreport", (event) => {
+  const { data, device, reportId } = event;
+
+  // 处理 Joy-Con 右手柄设备和特定的报告 ID
+  if (device.productId !== 0x2007 && reportId !== 0x3f) return;
+
+  const value = data.getUint8(0);
+  if (value === 0) return;
+
+  const someButtons = { 1: "A", 2: "X", 4: "B", 8: "Y" };
+  console.log(`用户按下了 ${someButtons[value]}。`);
+});
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}