feat(IBluttooth): add Start/StopNotifications method (#4510)

* chore: 重新设计蓝牙接口定义

* refactor: 重新设计蓝牙接口

* doc: 更新文档

* refactor: 移除 Connect 属性

* doc: 更新比对逻辑

* feat: 完善 StartNotifications 方法

* feat: 增加 remove 扩展方法

* feat: 增加 StopNotifications 方法

* feat: 增加资源销毁逻辑

* refactor: 更新参数名称

* feat: 增加重复判断

* refactor: 移除日志

* refactor: 更改 ReadValue 方法返回值

* test: 更新单元测试

* test: 更新单元测试

* feat: 增加 IsNotify 属性

* test: 更新单元测试

* doc: 更新文档

Author: ArgoZhang

src/BootstrapBlazor.Server/Components/Samples/Bluetooth.razor

@@ -8,7 +8,7 @@
 <p>@((MarkupString)Localizer["BluetoothDescription"].Value)</p>
 
 <Pre>[Inject, NotNull]
-private IBluetoothService? BluetoothService { get; set; }</Pre>
+private IBluetooth? BluetoothService { get; set; }</Pre>
 
 <Tips>
     <ul class="ul-demo">
@@ -59,31 +59,37 @@ private IBluetoothService? BluetoothService { get; set; }</Pre>
             </div>
         </div>
         <div class="col-12">
-            <Button Text="@Localizer["BluetoothGetServicesText"]" Icon="fa-solid fa-microchip" IsDisabled="@(_blueDevice is not { Connected: true })" OnClick="GetServices"></Button>
+            <Button Text="@Localizer["BluetoothGetServicesText"]" Icon="fa-solid fa-server" IsDisabled="@(_blueDevice is not { Connected: true })" OnClick="GetServices"></Button>
         </div>
         <div class="col-12">
             <Select Items="ServicesList" @bind-Value="_selectedService" class="flex-fill"></Select>
         </div>
         <div class="col-12">
-            <Button Text="@Localizer["BluetoothGetCharacteristicsText"]" Icon="fa-solid fa-microchip" IsDisabled="@(_blueDevice is not { Connected: true })" OnClick="GetCharacteristics"></Button>
+            <Button Text="@Localizer["BluetoothGetCharacteristicsText"]" Icon="fa-solid fa-plug" IsDisabled="@(_blueDevice is not { Connected: true })" OnClick="GetCharacteristics"></Button>
         </div>
         <div class="col-12">
             <Select Items="CharacteristicsList" @bind-Value="_selectedCharacteristic" class="flex-fill"></Select>
         </div>
         <div class="col-12">
-            <Button Text="@Localizer["BluetoothReadValueText"]" Icon="fa-solid fa-microchip" IsDisabled="@(_blueDevice is not { Connected: true })" OnClick="ReadValue"></Button>
+            <Button Text="@Localizer["BluetoothReadValueText"]" Icon="fa-solid fa-memory" IsDisabled="@(_blueDevice is not { Connected: true })" OnClick="ReadValue"></Button>
         </div>
         <div class="col-12">
             <Textarea Value="@_readValueString" rows="3" readonly></Textarea>
         </div>
+        <div class="col-12">
+            <Button Text="@Localizer["BluetoothStartText"]" Icon="fa-solid fa-play" IsDisabled="@(_blueDevice is not { Connected: true })" OnClick="StartNotifications"></Button>
+        </div>
+        <div class="col-12">
+            <Button Text="@Localizer["BluetoothStopText"]" Icon="fa-solid fa-stop" IsDisabled="@(_blueDevice is not { Connected: true })" OnClick="StopNotifications"></Button>
+        </div>
     </div>
 </DemoBlock>
 
 <p class="code-label mt-3">1. 服务注入</p>
 
 <Pre>[Inject]
 [NotNull]
-private IBluetoothService? BluetoothService { get; set; }</Pre>
+private IBluetooth? BluetoothService { get; set; }</Pre>
 
 <p class="code-label">2. 列出蓝牙设备</p>
 <p>调用 <code>BluetoothService</code> 实例方法 <code>RequestDevice</code> 即可，通过 <code>IsSupport</code> 进行浏览器是否支持蓝牙。可以通过 <code>BluetoothRequestOptions</code> 过滤参数过滤蓝牙设备</p>
@@ -130,18 +136,28 @@ if (BluetoothService.IsSupport == false)
 
 <p><code>IBluetoothService</code> 实例属性 <code>IsSupport</code> 是表示当前浏览器是否支持蓝牙功能</p>
 
-<p><code>IBluetoothService</code> 与 <code>IBluetoothDevice</code> 所有实例方法均有返回值，可通过查看其实例属性 <code>ErrorMessage</code> 获得上一次执行的错误描述信息</p>
+<p><code>IBluetooth</code> 与 <code>IBluetoothDevice</code> 所有实例方法均有返回值，可通过查看其实例属性 <code>ErrorMessage</code> 获得上一次执行的错误描述信息</p>
 
-<p><code>IBluetoothDevice</code> 实例方法 <code>ReadValue</code> 是通用方法，通过参数指定<code>Services</code> 与 <code>Characteristics</code></p>
+<p><code>IBluetoothDevice</code> 实例方法 <code>ReadValue</code> 是通用方法，通过参数指定<code>ServiceUUID</code> 与 <code>CharacteristicUUID</code></p>
 
 <p>原生方法 <code>getDevices</code> 暂未封装，因为需要设置浏览器才能开启</p>
 
-<p>可根据自己的业务需求自定义扩展方法，内置扩展方法列表如下：</p>
+<p>可根据自己的业务需求自定义扩展方法，内置方法列表如下：</p>
 
 <ul class="ul-demo">
+    <li><code>GetDeviceInfo</code> 读取设备信息</li>
+    <li><code>GetCurrentTime</code> 读取当前时间</li>
     <li><code>GetBatteryValue</code> 读取电量方法</li>
 </ul>
 
+<p class="code-label">接口说明</p>
+<ul class="ul-demo">
+    <li><code>IBluetooth</code> 蓝牙服务（系统注入）</li>
+    <li><code>IBluetoothDevice</code> 蓝牙设备</li>
+    <li><code>IBluetoothService</code> 蓝牙设备提供的服务接口 如时间服务</li>
+    <li><code>IBluetoothCharacteristic</code> 蓝牙设备服务提供的特性接口 如时间服务的当前时间特性（还有时区特性）</li>
+</ul>
+
 <p class="code-label">相关文档</p>
 
 <ul class="ul-demo">

src/BootstrapBlazor.Server/Components/Samples/Bluetooth.razor.cs

@@ -10,10 +10,10 @@ namespace BootstrapBlazor.Server.Components.Samples;
 /// <summary>
 /// Bluetooth
 /// </summary>
-public partial class Bluetooth
+public partial class Bluetooth : IAsyncDisposable
 {
     [Inject, NotNull]
-    private IBluetoothService? BluetoothService { get; set; }
+    private IBluetooth? BluetoothService { get; set; }
 
     [Inject, NotNull]
     private ToastService? ToastService { get; set; }
@@ -30,18 +30,18 @@ public partial class Bluetooth
 
     private string? _readValueString = null;
 
-    private List<string> _services = [];
+    private List<IBluetoothService> _bluetoothServices = [];
 
-    private List<string> _characteristics = [];
+    private List<IBluetoothCharacteristic> _bluetoothCharacteristics = [];
 
     private string? _selectedService;
 
     private string? _selectedCharacteristic;
 
-    private List<SelectedItem> ServicesList => _services.Select(i => new SelectedItem(i, FormatServiceName(i))).ToList();
-
-    private List<SelectedItem> CharacteristicsList => _characteristics.Select(i => new SelectedItem(i, FormatCharacteristicsName(i))).ToList();
+    private List<SelectedItem> ServicesList => _bluetoothServices.Select(i => new SelectedItem(i.UUID.ToUpperInvariant(), FormatServiceName(i))).ToList();
 
+    private List<SelectedItem> CharacteristicsList => _bluetoothCharacteristics.Select(i => new SelectedItem(i.UUID.ToUpperInvariant(), FormatCharacteristicsName(i))).ToList();
+    
     private Dictionary<string, string> ServiceUUIDList = [];
 
     /// <summary>
@@ -58,13 +58,14 @@ protected override void OnInitialized()
         }).ToDictionary();
     }
 
-    private string FormatServiceName(string serviceName)
+    private string FormatServiceName(IBluetoothService service)
     {
-        var name = ServiceUUIDList[serviceName.ToUpperInvariant()];
-        return $"{name}({serviceName.ToUpperInvariant()})";
+        var uuId = service.UUID.ToUpperInvariant();
+        return ServiceUUIDList.TryGetValue(uuId, out var serviceName)
+            ? $"{serviceName}({uuId})" : uuId;
     }
 
-    private string FormatCharacteristicsName(string characteristicName) => characteristicName.ToUpperInvariant();
+    private string FormatCharacteristicsName(IBluetoothCharacteristic characteristic) => characteristic.UUID.ToUpperInvariant();
 
     private async Task RequestDevice()
     {
@@ -73,6 +74,10 @@ private async Task RequestDevice()
             AcceptAllDevices = true,
             OptionalServices = ["device_information", "current_time", "battery_service"]
         };
+        #if DEBUG
+        options.AcceptAllDevices = false;
+        options.Filters = [ new BluetoothFilter() { NamePrefix = "Argo" } ];
+        #endif
         _blueDevice = await BluetoothService.RequestDevice(options);
         if (BluetoothService.IsSupport == false)
         {
@@ -112,8 +117,8 @@ private async Task Disconnect()
                 _batteryValue = null;
                 _batteryValueString = null;
                 _deviceInfoList.Clear();
-                _services.Clear();
-                _characteristics.Clear();
+                _bluetoothServices.Clear();
+                _bluetoothCharacteristics.Clear();
                 _readValueString = null;
             }
         }
@@ -174,28 +179,78 @@ private async Task GetServices()
     {
         if (_blueDevice != null)
         {
-            _services = await _blueDevice.GetPrimaryServices();
+            _bluetoothServices = await _blueDevice.GetPrimaryServices();
         }
     }
 
     private async Task GetCharacteristics()
     {
         if (_blueDevice != null && !string.IsNullOrEmpty(_selectedService))
         {
-            _characteristics = await _blueDevice.GetCharacteristics(_selectedService);
+            _bluetoothCharacteristics.Clear();
+            var service = _bluetoothServices.Find(i => i.UUID.ToUpperInvariant() == _selectedService);
+            if (service != null)
+            {
+                _bluetoothCharacteristics = await service.GetCharacteristics();
+            }
         }
     }
 
     private async Task ReadValue()
     {
         _readValueString = null;
-        if (_blueDevice != null && !string.IsNullOrEmpty(_selectedService) && !string.IsNullOrEmpty(_selectedCharacteristic))
+        var characteristics = _bluetoothCharacteristics.Find(i => i.UUID.ToUpperInvariant() == _selectedCharacteristic);
+        if (characteristics != null)
         {
-            var data = await _blueDevice.ReadValue(_selectedService, _selectedCharacteristic);
+            var data = await characteristics.ReadValue();
             if (data != null)
             {
                 _readValueString = string.Join(" ", data.Select(i => Convert.ToString(i, 16).PadLeft(2, '0').ToUpperInvariant()));
             }
         }
     }
+
+    private async Task StartNotifications()
+    {
+        var characteristics = _bluetoothCharacteristics.Find(i => i.UUID.ToUpperInvariant() == _selectedCharacteristic);
+        if (characteristics != null)
+        {
+            await characteristics.StartNotifications(HandlerNotification);
+        }
+    }
+
+    private async Task StopNotifications()
+    {
+        var characteristics = _bluetoothCharacteristics.Find(i => i.UUID.ToUpperInvariant() == _selectedCharacteristic);
+        if (characteristics != null)
+        {
+            await characteristics.StopNotifications();
+        }
+    }
+
+    private Task HandlerNotification(byte[] payload) {
+        _readValueString = string.Join(" ", payload.Select(i => Convert.ToString(i, 16).PadLeft(2, '0').ToUpperInvariant()));
+        StateHasChanged();
+        return Task.CompletedTask;
+    }
+
+    private async ValueTask DisposeAsync(bool disposing) 
+    {
+        if (disposing) 
+        {
+            if (_blueDevice != null) 
+            {
+                await _blueDevice.DisposeAsync();
+            }
+        }
+    }
+
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    /// <returns></returns>
+    public async ValueTask DisposeAsync() {
+        await DisposeAsync(true);
+        GC.SuppressFinalize(this);
+    }
 }

src/BootstrapBlazor.Server/Locales/en-US.json

@@ -5892,7 +5892,7 @@
     "BluetoothDescription": "Allows websites to communicate with Bluetooth devices connected to the user's computer. For example, you can connect to a Bluetooth printer to print.",
     "BluetoothTipsLi1": "This feature is available only in secure contexts (HTTPS)",
     "BluetoothTipsLi2": "This is an experimental technology Check the <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/Bluetooth#browser_compatibility\" target=\"_blank\">Browser compatibility table</a> carefully before using this in production",
-    "BluetoothTipsTitle": "Note: The <code>IBluetoothService</code> interface instance inherits <code>IAsyncDisposable</code>. When switching routes, you need to release its resources by calling its <code>DisposeAsync</code>.",
+    "BluetoothTipsTitle": "Note: The <code>IBluetoothDevice</code> interface instance inherits <code>IAsyncDisposable</code>. When switching routes, you need to release its resources by calling its <code>DisposeAsync</code>.",
     "NotSupportBluetoothTitle": "Scan Devices",
     "NotSupportBluetoothContent": "The current browser does not support serial port operations. Please change to Edge or Chrome browser.",
     "BluetoothRequestText": "Scan",
@@ -5901,7 +5901,7 @@
     "BluetoothGetBatteryText": "Battery",
     "BluetoothGetHeartRateText": "HeartRate",
     "BaseUsageTitle": "Basic usage",
-    "BaseUsageIntro": "Request communication with Bluetooth devices through the <code>IBluetoothService</code> service",
+    "BaseUsageIntro": "Request communication with Bluetooth devices through the <code>IBluetooth</code> service",
     "BluetoothGetCurrentTimeText": "Time",
     "BluetoothDeviceInfoText": "Device Info",
     "UsageDesc": "Click the Scan button and select the phone to test in the pop-up window",

src/BootstrapBlazor.Server/Locales/zh-CN.json

@@ -5887,12 +5887,12 @@
     "OnScreenKeyboardsBasicTitle": "基础用法"
   },
   "BootstrapBlazor.Server.Components.Samples.Bluetooth": {
-    "BluetoothTitle": "IBluetoothService 蓝牙服务",
+    "BluetoothTitle": "IBluetooth 蓝牙服务",
     "BluetoothIntro": "提供了查询蓝牙可用性和请求访问设备的方法",
     "BluetoothDescription": "允许网站与连接到用户计算机的蓝牙设备进行通信。例如可以连接蓝牙打印机进行打印操作",
     "BluetoothTipsLi1": "该功能仅在部分或所有支持浏览器的安全上下文(HTTPS)中可用",
     "BluetoothTipsLi2": "这是一项实验性技术，在生产中使用之前请仔细,检查 <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/Bluetooth#browser_compatibility\" target=\"_blank\">浏览器兼容性表</a>",
-    "BluetoothTipsTitle": "注意：<code>IBluetoothService</code> 接口实例继承 <code>IAsyncDisposable</code> 路由切换时需要对其进行资源释放，调用其 <code>DisposeAsync</code> 即可",
+    "BluetoothTipsTitle": "注意：<code>IBluetoothDevice</code> 接口实例继承 <code>IAsyncDisposable</code> 路由切换时需要对其进行资源释放，调用其 <code>DisposeAsync</code> 即可",
     "NotSupportBluetoothTitle": "扫描设备",
     "NotSupportBluetoothContent": "当前浏览器不支持串口操作，请更换 Edge 或者 Chrome 浏览器",
     "BluetoothRequestText": "扫描",
@@ -5901,7 +5901,7 @@
     "BluetoothGetBatteryText": "读取电量",
     "BluetoothGetHeartRateText": "读取心率",
     "BaseUsageTitle": "基础用法",
-    "BaseUsageIntro": "通过 <code>IBluetoothService</code> 服务，请求与蓝牙设备通讯",
+    "BaseUsageIntro": "通过 <code>IBluetooth</code> 服务，请求与蓝牙设备通讯",
     "BluetoothGetCurrentTimeText": "读取时间",
     "BluetoothDeviceInfoText": "读取硬件信息",
     "UsageDesc": "点击扫描按钮，在弹窗中选中手机进行测试",

src/BootstrapBlazor/Extensions/BootstrapBlazorServiceCollectionExtensions.cs

@@ -70,7 +70,7 @@ public static IServiceCollection AddBootstrapBlazor(this IServiceCollection serv
         services.TryAddScoped<IComponentHtmlRenderer, ComponentHtmlRenderer>();
         services.TryAddScoped<IBrowserFingerService, DefaultBrowserFingerService>();
         services.TryAddScoped<ISerialService, DefaultSerialService>();
-        services.TryAddScoped<IBluetoothService, DefaultBluetoothService>();
+        services.TryAddScoped<IBluetooth, DefaultBluetooth>();
         services.AddScoped<TabItemTextOptions>();
         services.AddScoped<DialogService>();
         services.AddScoped<MaskService>();