Hid

说明

基于浏览器 WebHID 规范封装的人机接口设备通信组件：点击“连接 HID 设备”后由 navigator.hid.requestDevice 弹出系统设备选择框，须给出非空过滤条件（WebHID 没有 acceptAllDevices 开关）——可按 VendorId / ProductId（厂商 / 产品 ID）收窄，或按 UsagePage（用法页，如 0x01=Generic Desktop、0x0C=Consumer、0xFF00=厂商自定义）配合 Usage 过滤；未设过滤时组件退回复用 getDevices() 里已授权的首台设备。选中后组件 open() 并枚举其 collections（用法页 / 用法）与 input / output / feature 三类报告描述符（报告号与长度，兼容 device.reports 与 collections[].reports 两种暴露形态并做了回退）；随后设备每次 oninputreport 上报都由组件实时接住，面板顶部展示最近一份输入报告的报告号、十六进制与尽力而为的文本预览。收发区支持输出报告（sendReport）与特性报告（sendFeatureReport / receiveFeatureReport），负载按十六进制输入（忽略空格 / 逗号 / 连字符 / 0x 前缀），还可“撤销授权”（forget）清除浏览器对该设备的记住许可。对外经 OnConnected / OnDisconnected / OnData / OnError 事件驱动，或用 RequestAsync / WriteAsync / SendFeatureAsync / ReceiveFeatureAsync / CloseAsync / ForgetAsync 等公开方法编程式操作；设备以 HidDeviceInfo（含 HidCollection 与各报告号列表）呈现，一次收发以 HidData 携带报告号、方向、原始字节与十六进制 / UTF-8 表示。连接与拔线监听走 navigator.hid.addEventListener 并按 deviceId 过滤，多个 Hid 实例可安全共存。平台限制：WebHID 仅 Chrome / Edge / Opera 等 Chromium 内核提供，须处于安全上下文（HTTPS 或 localhost）、由用户手势发起 requestDevice；与 Web NFC（仅 Android）不同，HID 在桌面浏览器上通常可直接联调真实 USB HID 外设。报告是无消息边界的字节流，一次上报的语义依设备报告描述符而定；reportId 为 0 时约定负载首字节即报告号；在 Blazor Server 中往返延迟通常使瞬时授权过期，因此推荐在 Blazor WASM 或桌面宿主里使用。

常见能力：

• requestDevice 弹出系统设备选择框，按 VID:PID 或用法页（Usage Page / Usage）过滤（须非空过滤）
• 打开后枚举集合（用法页 / 用法）与 输入 / 输出 / 特性 三类报告描述符
• 实时接收 oninputreport 上报，展示报告号、十六进制与文本预览
• 输出报告 sendReport、特性报告 sendFeatureReport / receiveFeatureReport，负载按十六进制收发
• 可撤销浏览器授权（forget），关闭连接
• OnConnected / OnDisconnected / OnData / OnError 事件 + 公开方法双驱动
• 连接 / 拔线用 addEventListener 按 deviceId 过滤，多实例可共存；兼容两种报告描述符暴露形态
• 能力检测与安全上下文提示；不支持时给出明确原因

用法

<Hid Name="HID 通信" UsagePage="0x01"
    OnConnected="OnConnected" OnData="OnData" OnError="OnError" />

@code {
    // 按用法页（Generic Desktop）或 VendorId/ProductId 收窄选择框；requestDevice 须给出非空过滤。
    void OnConnected(HidDeviceInfo d) =>
        Console.WriteLine($"{d.Display} 共 {d.Collections.Count} 集合 · {d.Inputs.Count} 输入报告");
    void OnData(HidData h) =>
        Console.WriteLine($"{h.Direction} R{h.ReportId} {h.Hex} | {h.Text}");
    void OnError(string m) => Console.WriteLine("错误：" + m);
}

@* 也可拿到实例编程式下发输出 / 特性报告、读取特性报告、撤销授权 *@
<Hid @ref="_hid" VendorId="0x054C" ProductId="0x0CE6" />
<Button Text="下发输出" OnClick="@(() => _hid.WriteAsync(1, new byte[] { 0x00, 0x01 }))" />
<Button Text="读特性" OnClick="@(() => _hid.ReceiveFeatureAsync(0xF0))" />
<Button Text="撤销授权" OnClick="@(() => _hid.ForgetAsync())" />

API 参数

所有组件均继承 BaseComponent，除上表参数外还支持 Class、Style、Disabled、Visible。