Known · 元数据驱动的 .NET 全栈框架

说明

基于浏览器 WebUSB 规范封装的 USB 通信组件：点击“连接 USB 设备”后由 navigator.usb.requestDevice 弹出系统设备选择框，可按 VendorId / ProductId（厂商 / 产品 ID）或 ClassCode（接口类码，如 0x03=HID、0x02=CDC）过滤，都不设置则走 acceptAllDevices；选中后组件 open() 并自动选择一个配置，枚举配置 / 接口 / 端点三级树（可折叠展开、可在多个配置间切换）。每个 IN 端点提供读取（transferIn），值同时给出十六进制与尽力而为的 UTF-8 文本预览；OUT 端点提供按十六进制写出（transferOut，忽略空格 / 逗号 / 连字符 / 0x 前缀）。首次传输前对所在接口按需 claimInterface，可手动“释放接口”；面板底部还能手动下发控制传输（controlTransferIn / controlTransferOut，指定 bRequest / wValue / wIndex / 长度与写出数据）。对外经 OnConnected / OnDisconnected / OnData / OnError 事件驱动，或用 ConnectAsync / ReadAsync / WriteAsync / SelectConfigurationAsync / DisconnectAsync 等公开方法编程式操作；设备与描述符树以 UsbDeviceInfo（含 UsbConfiguration / UsbInterface / UsbEndpoint）呈现，一次传输以 UsbData 携带原始字节、十六进制 / UTF-8 表示与方向。平台限制：WebUSB 仅 Chrome / Edge / WebView2 提供，且必须处于安全上下文（HTTPS 或 localhost）、由用户手势发起 requestDevice；设备须已被浏览器接管（Windows 上通常需 WinUSB / .libusb 驱动，若已被系统驱动占用需先解绑），传输为按端点的原始字节、无消息帧界，需自行按协议组包 / 拆包；在 Blazor Server 中往返延迟通常使瞬时用户授权过期，因此推荐在 Blazor WASM 或桌面宿主里使用。

常见能力：

requestDevice 弹出系统设备选择框，可按厂商 / 产品 ID 或接口类码过滤
打开后自动选择配置并枚举配置 / 接口 / 端点树（可折叠展开、可切配置）
IN 端点读取，值同时给出十六进制与 UTF-8 文本预览
OUT 端点按十六进制写出（忽略空格 / 逗号 / 0x 前缀）
传输前自动 claimInterface，可手动释放接口、切换当前配置
支持手动控制传输 controlTransferIn / Out（bRequest / wValue / wIndex / 长度）
OnConnected / OnDisconnected / OnData / OnError 事件 + 公开方法双驱动
能力检测与安全上下文提示；不支持时给出明确原因

用法

<Usb Name="USB 通信" VendorId="0x2341" ReadLength="64"
     OnConnected="OnConnected" OnData="OnData" OnError="OnError" />

@code {
    // VendorId / ProductId 或 ClassCode 用于收窄设备选择框；都不设则 acceptAllDevices。
    void OnConnected(UsbDeviceInfo d) =>
        Console.WriteLine($"已连接 {d.Display}，{d.Configurations.Count} 配置");
    void OnData(UsbData u) =>
        Console.WriteLine($"{u.Direction} EP{u.EndpointNumber} {u.Hex} | {u.Text}");
    void OnError(string m) => Console.WriteLine("错误：" + m);
}

@* 也可拿到实例编程式读 / 写 / 控制传输 / 断开 *@
<Usb @ref="_usb" />
<Button Text="读 EP1" OnClick="@(() => _usb.ReadAsync(0, 1))" />

API 参数

参数	类型	默认值	说明
`AllowAll`	`bool`	`true`	当未设任何过滤条件时，是否接受全部设备（acceptAllDevices）。
`ClassCode`	`int`	`0`	接口类码过滤（如 0x03=HID）；仅在未设 VendorId 时生效。
`ConnectText`	`string`	`"连接 USB 设备"`	连接按钮文案（内部已本地化，作为翻译键）。
`MaxLog`	`int`	`200`	日志最多保留行数，超出丢弃最旧。
`Name`	`string`	`"USB 设备"`	面板标题。
`OnConnected`	`EventCallback<UsbDeviceInfo>`	—	事件连接成功（含设备与描述符树）。
`OnData`	`EventCallback<UsbData>`	—	事件发生一次数据传输（读入 / 写出 / 控制）。
`OnDisconnected`	`EventCallback`	—	事件连接断开（主动关闭或拔线）。
`OnError`	`EventCallback<string>`	—	事件发生错误，参数为错误说明。
`ProductId`	`int`	`0`	产品 ID 过滤（配合 VendorId）。
`ReadLength`	`int`	`64`	默认读取长度（字节）；面板内可即时改。
`ShowLog`	`bool`	`true`	是否显示传输日志。
`VendorId`	`int`	`0`	厂商 ID 过滤（0 表示不按厂商过滤）。
`Visible`	`bool`	`true`	取得或设置组件是否可见，默认为false。
`VisibleChanged`	`EventCallback<bool>`	—	事件取得或设置组件可见性变化时的回调事件。
`Class`	`string`	`null`	取得或设置组件的CSS类名，用于自定义样式。
`Disabled`	`bool`	`false`	取得或设置组件是否禁用，默认为false。
`Style`	`string`	`null`	取得或设置组件的内联样式，用于自定义样式。

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