doc: 更新文档

ArgoZhang · ArgoZhang · commit 5c89f411dbf6 · 2024-10-19T11:21:45.000+08:00
diff --git a/src/BootstrapBlazor.Server/Components/Samples/WebSerials.razor b/src/BootstrapBlazor.Server/Components/Samples/WebSerials.razor
@@ -71,8 +71,55 @@ private ISerialService? SerialService { get; set; }</Pre>
     </GroupBox>
 </DemoBlock>
 
+<p class="code-label mt-3">1. 服务注入</p>
 
-<AttributeTable Items="@GetAttributes()" />
+<Pre>[Inject]
+[NotNull]
+private ISerialService? SerialService { get; set; }</Pre>
+
+<p class="code-label">2. 申请串口权限</p>
+<p>调用 <code>SerialService</code> 实例方法 <code>GetPort</code> 即可，通过 <code>IsSupport</code> 进行浏览器是否支持判断</p>
+
+<Pre>_serialPort = await SerialService.GetPort();
+if (SerialService.IsSupport == false)
+{
+    await ToastService.Error(Localizer["NotSupportSerialTitle"], Localizer["NotSupportSerialContent"]);
+}</Pre>
+
+<p class="code-label">3. 打开串口</p>
 
-<AttributeTable Title="@Localizer["WebSerialOptionsText"]" Items="@GetWebSerialOptionsAttributes()" />
+<ul class="ul-demo">
+    <li>如果需要读取数据，请先设置 <code>ISerialPort</code> 实例 <code>DataReceive</code> 参数</li>
+    <li>调用 <code>ISerialPort</code> 实例方法 <code>Open</code> 打开串口，可通过参数设置 <code>波特率</code> 等信息</li>
+</ul>
 
+<Pre>private async Task OpenPort()
+{
+    if (_serialPort != null)
+    {
+        _serialPort.DataReceive = async data =>
+        {
+            _messages.Add(new ConsoleMessageItem()
+            {
+                IsHtml = true,
+                Message = $"{DateTime.Now}: --> Text: {Encoding.ASCII.GetString(data)} HEX: {Convert.ToHexString(data)}"
+            });
+            await InvokeAsync(StateHasChanged);
+        };
+        await _serialPort.Open(_serialOptions);
+    }
+}</Pre>
+
+<p class="code-label">4. 关闭串口</p>
+
+<p>调用 <code>ISerialPort</code> 实例方法 <code>Close</code> 关闭串口，请注意路由切换时，请调用其 <code>DisposeAsync</code> 方法释放资源</p>
+
+<Pre>private async Task ClosePort()
+{
+    if (_serialPort != null)
+    {
+        await _serialPort.Close();
+    }
+}</Pre>
+
+<AttributeTable Items="@GetAttributes()" />
diff --git a/src/BootstrapBlazor.Server/Components/Samples/WebSerials.razor.cs b/src/BootstrapBlazor.Server/Components/Samples/WebSerials.razor.cs
@@ -9,19 +9,14 @@ namespace BootstrapBlazor.Server.Components.Samples;
 /// <summary>
 /// WebSerials 组件
 /// </summary>
-public partial class WebSerials : IDisposable
+public partial class WebSerials : IAsyncDisposable
 {
     private string _sendData = "";
     private int _sendInterval = 1000;
     private bool _appendCRLF;
     private bool _isHEX;
     private bool _isLoop;
-    private ConsoleMessageCollection _messages = new(8);
-
-    private string? _message;
-    private string? _statusMessage;
-    private string? _errorMessage;
-    private readonly WebSerialOptions options = new() { BaudRate = 115200, AutoGetSignals = true };
+    private readonly ConsoleMessageCollection _messages = new(8);
 
     private readonly List<SelectedItem> _baudRateList =
     [
@@ -45,21 +40,15 @@ public partial class WebSerials : IDisposable
 
     private readonly List<SelectedItem> _stopBits = [new("1", "1"), new("2", "2")];
 
-    private bool Flag { get; set; }
-
-    private bool IsConnected { get; set; }
-
-    /// <summary>
-    /// 收到的信号数据
-    /// </summary>
-    public WebSerialSignals Signals { get; set; } = new WebSerialSignals();
-
     [Inject, NotNull]
     private ISerialService? SerialService { get; set; }
 
+    [Inject, NotNull]
+    private ToastService? ToastService { get; set; }
+
     private ISerialPort? _serialPort;
 
-    private SerialOptions _serialOptions = new();
+    private readonly SerialOptions _serialOptions = new();
 
     private bool CheckOpen => _serialPort is not { IsOpen: false };
 
@@ -68,6 +57,10 @@ public partial class WebSerials : IDisposable
     private async Task GetPort()
     {
         _serialPort = await SerialService.GetPort();
+        if (SerialService.IsSupport == false)
+        {
+            await ToastService.Error(Localizer["NotSupportSerialTitle"], Localizer["NotSupportSerialContent"]);
+        }
     }
 
     private async Task OpenPort()
@@ -84,6 +77,11 @@ private async Task OpenPort()
                 await InvokeAsync(StateHasChanged);
             };
             await _serialPort.Open(_serialOptions);
+
+            if (_serialPort.IsOpen == false)
+            {
+                await ToastService.Error(Localizer["OpenPortSerialTitle"], Localizer["OpenPortSerialContent"]);
+            }
         }
     }
 
@@ -151,60 +149,6 @@ private static byte[] ConvertToHex(string data)
         return [.. ret];
     }
 
-    private Task OnSignals(WebSerialSignals? signals)
-    {
-        if (signals is null) return Task.CompletedTask;
-
-        Signals = signals;
-
-        if (!options.AutoGetSignals)
-        {
-            // 仅在不自动获取信号时才显示
-            _message = $"{DateTime.Now:hh:mm:ss} 收到信号数据: {Environment.NewLine}" +
-                            $"RING:  {signals.RING}{Environment.NewLine}" +
-                            $"DSR:   {signals.DSR}{Environment.NewLine}" +
-                            $"CTS:   {signals.CTS}{Environment.NewLine}" +
-                            $"DCD:   {signals.DCD}{Environment.NewLine}" +
-                            $"{_message}{Environment.NewLine}";
-        }
-
-        StateHasChanged();
-        return Task.CompletedTask;
-    }
-
-    private Task OnConnect(bool flag)
-    {
-        IsConnected = flag;
-        if (flag)
-        {
-            _message = null;
-            _statusMessage = null;
-            _errorMessage = null;
-        }
-        StateHasChanged();
-        return Task.CompletedTask;
-    }
-
-    private Task OnLog(string message)
-    {
-        _statusMessage = message;
-        StateHasChanged();
-        return Task.CompletedTask;
-    }
-
-    private Task OnError(string message)
-    {
-        _errorMessage = message;
-        StateHasChanged();
-        return Task.CompletedTask;
-    }
-
-    private void OnApply()
-    {
-        //options.BaudRate = SelectedBaudRate;
-        //Flag = !Flag;
-    }
-
     /// <summary>
     /// 获得属性方法
     /// </summary>
@@ -292,151 +236,26 @@ private static AttributeItem[] GetAttributes() =>
         }
     ];
 
-    /// <summary>s
-    /// 获得WebSerialOptions属性方法
-    /// </summary>
-    /// <returns></returns>
-    private static AttributeItem[] GetWebSerialOptionsAttributes() =>
-    [
-        new()
-        {
-            Name = "BaudRate",
-            Description = "波特率",
-            Type = "int",
-            ValueList = "-",
-            DefaultValue = "9600"
-        },
-        new()
-        {
-            Name = "DataBits",
-            Description = "数据位",
-            Type = "int",
-            ValueList = "7|8",
-            DefaultValue = "8"
-        },
-        new()
-        {
-            Name = "StopBits",
-            Description = "停止位",
-            Type = "int",
-            ValueList = "1|2",
-            DefaultValue = "1"
-        },
-        new()
-        {
-            Name = "ParityType",
-            Description = "流控制",
-            Type = "WebSerialFlowControlType",
-            ValueList = "none|even|odd",
-            DefaultValue = "none"
-        },
-        new()
-        {
-            Name = "BufferSize",
-            Description = "读写缓冲区",
-            Type = "int",
-            ValueList = "-",
-            DefaultValue = "255"
-        },
-        new()
-        {
-            Name = "FlowControlType",
-            Description = "校验",
-            Type = "WebSerialParityType",
-            ValueList = "none|hardware",
-            DefaultValue = "none"
-        },
-        new()
-        {
-            Name =nameof(WebSerialOptions.InputWithHex),
-            Description = "HEX发送",
-            Type =  "bool",
-            ValueList = "-",
-            DefaultValue = "false"
-        },
-        new()
-        {
-            Name =nameof(WebSerialOptions.OutputInHex),
-            Description = "HEX接收",
-            Type =  "bool",
-            ValueList = "-",
-            DefaultValue ="false"
-        },
-        new()
-        {
-            Name =nameof(WebSerialOptions.AutoConnect),
-            Description = "自动连接设备",
-            Type =  "bool",
-            ValueList = "-",
-            DefaultValue ="true"
-        },
-        new()
-        {
-            Name =nameof(WebSerialOptions.AutoFrameBreakType),
-            Description = "自动断帧方式",
-            Type =  "AutoFrameBreakType",
-            ValueList = "-",
-            DefaultValue ="Character"
-        },
-        new(){
-            Name =nameof(WebSerialOptions.FrameBreakChar),
-            Description = "断帧字符",
-            Type =  "string",
-            ValueList = "-",
-            DefaultValue ="\\n"
-        },
-        new()
-        {
-            Name = nameof(WebSerialOptions.ConnectBtnTitle),
-            Description = "获得/设置 连接按钮文本",
-            Type = "string",
-            ValueList = "",
-            DefaultValue = "连接"
-        },
-        new()
-        {
-            Name = nameof(WebSerialOptions.DisconnectBtnTitle),
-            Description = "获得/设置 断开连接按钮文本",
-            Type = "string",
-            ValueList = "",
-            DefaultValue = "连接"
-        },
-        new()
-        {
-            Name = nameof(WebSerialOptions.WriteBtnTitle),
-            Description = "获得/设置 写入按钮文本",
-            Type = "string",
-            ValueList = "",
-            DefaultValue = "写入"
-        },
-        new()
-        {
-            Name = nameof(WebSerialOptions.AutoGetSignals),
-            Description = "获得/设置 自动检查状态",
-            Type = "bool",
-            ValueList = "-",
-            DefaultValue ="false"
-        }
-    ];
-
-    private void Dispose(bool disposing)
+    private async ValueTask DisposeAsync(bool disposing)
     {
         if (disposing)
-        {
             if (_loopSendTokenSource != null)
             {
                 _loopSendTokenSource.Cancel();
                 _loopSendTokenSource = null;
             }
+        if (_serialPort != null)
+        {
+            await _serialPort.DisposeAsync();
         }
     }
 
     /// <summary>
     /// <inheritdoc/>
     /// </summary>
-    public void Dispose()
+    public async ValueTask DisposeAsync()
     {
-        Dispose(true);
+        await DisposeAsync(true);
         GC.SuppressFinalize(this);
     }
 }
diff --git a/src/BootstrapBlazor.Server/Locales/en-US.json b/src/BootstrapBlazor.Server/Locales/en-US.json
@@ -6319,7 +6319,11 @@
     "LoopIntervalText": "Interval(ms)",
     "WebSerialTipsLi1": "This feature is available only in secure contexts (HTTPS)",
     "WebSerialTipsLi2": "This is an experimental technology Check the <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/SerialPort#browser_compatibility\" target=\"_blank\">Browser compatibility table</a> carefully before using this in production",
-    "WebSerialTipsTitle": ""
+    "WebSerialTipsTitle": "Note: The <code>ISerialPort</code> interface instance inherits <code>IAsyncDisposable</code>. When switching routes, you need to release its resources by calling its <code>DisposeAsync</code>",
+    "NotSupportSerialTitle": "Get Port",
+    "NotSupportSerialContent": "The current browser does not support serial port operations. Please change to Edge or Chrome browser.",
+    "OpenPortSerialTitle": "Open Port",
+    "OpenPortSerialContent": "Failed to open the serial port"
   },
   "BootstrapBlazor.Server.Components.Samples.MindMaps": {
     "MindMapTitle": "Mind Map",
diff --git a/src/BootstrapBlazor.Server/Locales/zh-CN.json b/src/BootstrapBlazor.Server/Locales/zh-CN.json
@@ -6319,7 +6319,11 @@
     "LoopIntervalText": "发送间隔(ms)",
     "WebSerialTipsLi1": "该功能仅在部分或所有支持浏览器的安全上下文(HTTPS)中可用",
     "WebSerialTipsLi2": "这是一项实验性技术，在生产中使用之前请仔细,检查 <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/SerialPort#browser_compatibility\" target=\"_blank\">浏览器兼容性表</a>",
-    "WebSerialTipsTitle": ""
+    "WebSerialTipsTitle": "注意：<code>ISerialPort</code> 接口实例继承 <code>IAsyncDisposable</code> 路由切换时需要对其进行资源释放，调用其 <code>DisposeAsync</code> 即可",
+    "NotSupportSerialTitle": "申请串口权限",
+    "NotSupportSerialContent": "当前浏览器不支持串口操作，请更换 Edge 或者 Chrome 浏览器",
+    "OpenPortSerialTitle": "打开串口操作",
+    "OpenPortSerialContent": "打开串口失败"
   },
   "BootstrapBlazor.Server.Components.Samples.MindMaps": {
     "MindMapTitle": "Mind Map 思维导图",
