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

说明

基于浏览器 Web Bluetooth 规范封装的 BLE 通信组件：点击“扫描并连接”后由 navigator.bluetooth.requestDevice 弹出系统设备选择框，连上 GATT 即自动枚举浏览器授权可见的主服务与特征，逐条提供读取、按十六进制写入（特征支持时走免应答写）与订阅 / 取消通知，并把值与事件写入日志。设备过滤默认走 Services（按服务 UUID 过滤，只列提供这些服务的外设），也可用 NamePrefixes 按名前缀过滤、或用 AllowAllDevices 列出视野内任意设备；由于浏览器隐私限制，连接后默认只能访问广播里的过滤服务，需要读写其它服务时须用 OptionalServices 预先授权。对外可经 OnConnected / OnDisconnected / OnValueChanged / OnError 事件驱动，或用 ConnectAsync / ReadAsync / WriteAsync / SubscribeAsync 等公开方法编程式操作；特征值以字节与十六进制 / UTF-8 文本呈现。平台限制：Web 蓝牙仅 Chrome / Edge / WebView2 提供，且必须处于安全上下文（HTTPS 或 localhost）、由用户手势发起 requestDevice；在 Blazor Server 中往返延迟通常使瞬时用户授权过期，因此推荐在 Blazor WASM 或桌面宿主里使用，真机联调需要一个可广播的 BLE 外设。

常见能力：

扫描并连接：requestDevice 弹出系统设备选择框
默认按服务 UUID 过滤，可选 NamePrefixes 或 AcceptAllDevices
连接后自动枚举授权可见的服务与特征（可折叠展开）
单特征读取，值同时给出十六进制与 UTF-8 文本
按十六进制写入，特征支持时自动走免应答写
订阅 / 取消通知，值变化实时上抛并记入日志
OnConnected / OnDisconnected / OnValueChanged / OnError 事件 + 公开方法双驱动
能力检测与安全上下文提示；不支持时给出明确原因

用法

<Bluetooth Name="BLE 通信" Services="@svcs" OptionalServices="@svcs"
           OnConnected="OnConnected" OnValueChanged="OnValue" OnError="OnError" />

@code {
    // 只列提供这些服务的设备；standard 别名或完整 128 位 UUID 均可。
    string[] svcs = { "heart_rate", "device_information" };

    void OnConnected(BleDeviceInfo d) =>
        Console.WriteLine($"{d.Display} 共 {d.Services.Count} 个服务");
    void OnValue(BleValue v) =>
        Console.WriteLine($"{v.CharacteristicUuid} = {v.Hex}");
    void OnError(string m) => Console.WriteLine("错误：" + m);
}

@* 也可拿到实例编程式读写 / 订阅 *@
<Bluetooth @ref="_ble" AllowAllDevices="true" />
<Button Text="写入 0x01" OnClick="@(() => _ble.WriteAsync(svc, ch, new byte[] { 0x01 }))" />

API 参数

参数	类型	默认值	说明
`AllowAllDevices`	`bool`	`false`	为真时使用 acceptAllDevices，列出视野内任意 BLE 外设（演示友好，真实场景易被无关设备淹没）。
`ConnectText`	`string`	`"扫描并连接"`	连接按钮文案（内部已本地化，作为翻译键）。
`MaxLog`	`int`	`60`	日志最多保留条数，超出丢弃最旧。
`Name`	`string`	`"蓝牙设备"`	面板标题；同时用于状态可访问性描述。默认“蓝牙设备”。
`NamePrefixes`	`String[]`	`null`	按设备名前缀过滤（与 Services 可并存，浏览器合并为候选）。
`OnConnected`	`EventCallback<BleDeviceInfo>`	—	事件连接成功（含已发现的主服务清单）。
`OnDisconnected`	`EventCallback`	—	事件连接断开（含设备掉线、主动断开）。
`OnError`	`EventCallback<string>`	—	事件发生错误，参数为错误说明。
`OnValueChanged`	`EventCallback<BleValue>`	—	事件读到或被推送一个特征值。
`OptionalServices`	`String[]`	`null`	连接后才允许发现 / 读写的额外服务（浏览器出于隐私默认只暴露广播里的过滤服务）。
`Services`	`String[]`	`null`	requestDevice 过滤服务（GATT UUID 或标准别名如 heart_rate）；非空则只列提供这些服务的设备（推荐）。
`ShowLog`	`bool`	`true`	是否显示值 / 事件日志区。
`Visible`	`bool`	`true`	取得或设置组件是否可见，默认为false。
`VisibleChanged`	`EventCallback<bool>`	—	事件取得或设置组件可见性变化时的回调事件。
`Class`	`string`	`null`	取得或设置组件的CSS类名，用于自定义样式。
`Disabled`	`bool`	`false`	取得或设置组件是否禁用，默认为false。
`Style`	`string`	`null`	取得或设置组件的内联样式，用于自定义样式。

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