feat(Memorial): add Memorial Mode (#5584)

* style: memorial mode

* refactor: 撤销格式化

* refactor: 撤销格式化

* doc: 更改注释为英文

* feat: 增加 IsMemorialMode 参数

* style: 增加追悼样式

* doc: 更新注释

* feat: 增加 setMemorialMode 方法

* doc: 增加追悼模式实战网页

* doc: 更新文档

* doc: 移除主题菜单

* test: 增加单元测试

Author: ArgoZhang

src/BootstrapBlazor.Server/Components/Components/Header.razor

@@ -20,12 +20,12 @@
             <li class="nav-item">
                 <a class="nav-link" href="tutorials">@TutorialsText</a>
             </li>
-            @if (CultureInfo.CurrentUICulture.Name == "zh-CN")
+            @* @if (CultureInfo.CurrentUICulture.Name == "zh-CN")
             {
                 <li class="nav-item">
                     <a class="nav-link" href="https://theme.blazor.zone">主题</a>
                 </li>
-            }
+            } *@
         </ul>
     </div>
     <div class="d-flex flex-fill"></div>

src/BootstrapBlazor.Server/Components/Layout/TutorialsNavMenu.razor.cs

@@ -110,6 +110,11 @@ protected override async Task OnInitializedAsync()
             {
                 Text = Localizer["OnlineSheet"],
                 Url = "tutorials/online-sheet",
+            },
+            new()
+            {
+                Text = Localizer["MemorialMode"],
+                Url = "tutorials/memorial",
             }
         ]);
     }

src/BootstrapBlazor.Server/Components/Samples/Tutorials/Memorial.razor

@@ -0,0 +1,13 @@
+@page "/tutorials/memorial"
+
+<Button Text="切换哀悼模式" OnClick="OnToggle" class="mb-3"></Button>
+
+<p class="code-label">1. 加载 <code>Utlity</code> 工具</p>
+<Pre>var module = await JSRuntime.LoadUtility();</Pre>
+
+<p class="code-label">2. 设置哀悼模式</p>
+<Pre>await module.InvokeVoidAsync("SetMemorial", true);</Pre>
+
+<p class="code-label">3. 全站默认设置追悼模式方法</p>
+<p>更新 <code>App.razor</code> 文档内容如下</p>
+<Pre>&lt;html lang="en" data-bs-theme='dark' data-bb-theme="memorial"&gt;</Pre>

src/BootstrapBlazor.Server/Components/Samples/Tutorials/Memorial.razor.cs

@@ -0,0 +1,27 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License
+// See the LICENSE file in the project root for more information.
+// Maintainer: Argo Zhang(argo@live.ca) Website: https://www.blazor.zone
+
+using Microsoft.JSInterop;
+
+namespace BootstrapBlazor.Server.Components.Samples.Tutorials;
+
+/// <summary>
+/// 追悼模式
+/// </summary>
+public partial class Memorial
+{
+    [Inject, NotNull]
+    private IJSRuntime? JSRuntime { get; set; }
+
+    private bool _isMemorial = false;
+
+    private async Task OnToggle()
+    {
+        var module = await JSRuntime.LoadUtility();
+
+        _isMemorial = !_isMemorial;
+        await module.SetMemorialModeAsync(_isMemorial);
+    }
+}

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

@@ -22,7 +22,8 @@
     "TranslateSummary": "Translate",
     "DrawingSummary": "Drawing",
     "AdminSummary": "Admin",
-    "OnlineSheet": "UniverSheet"
+    "OnlineSheet": "UniverSheet",
+    "MemorialMode": "Memorial"
   },
   "BootstrapBlazor.Server.Components.Components.Pre": {
     "LoadingText": "Loading ...",

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

@@ -22,7 +22,8 @@
     "TranslateSummary": "翻译工具 Translate",
     "DrawingSummary": "画图 Drawing",
     "AdminSummary": "中台 Admin",
-    "OnlineSheet": "在线表格 UniverSheet"
+    "OnlineSheet": "在线表格 UniverSheet",
+    "MemorialMode": "追悼模式"
   },
   "BootstrapBlazor.Server.Components.Components.Pre": {
     "LoadingText": "正在加载 ...",

src/BootstrapBlazor/Extensions/JSModuleExtensions.cs

@@ -11,33 +11,33 @@ namespace BootstrapBlazor.Components;
 public static class JSModuleExtensions
 {
     /// <summary>
-    /// 导入 utility js 模块
+    /// Load utility js module
     /// </summary>
-    /// <param name="jsRuntime"></param>
-    /// <param name="version"></param>
-    /// <returns>A <see cref="Task"/><![CDATA[<]]><see cref="JSModule"/><![CDATA[>]]> 模块加载器</returns>
+    /// <param name="jsRuntime">The <see cref="IJSRuntime"/> instance</param>
+    /// <param name="version">The version of the module</param>
+    /// <returns>A <see cref="Task"/><![CDATA[<]]><see cref="JSModule"/><![CDATA[>]]> module loader</returns>
     public static Task<JSModule> LoadUtility(this IJSRuntime jsRuntime, string? version = null) => LoadModuleByName(jsRuntime, "utility", version);
 
     /// <summary>
-    /// 通过名称导入内置脚本模块
+    /// Load built-in script module by name
     /// </summary>
-    /// <param name="jsRuntime"></param>
-    /// <param name="moduleName"></param>
-    /// <param name="version"></param>
-    /// <returns>A <see cref="Task"/><![CDATA[<]]><see cref="JSModule"/><![CDATA[>]]> 模块加载器</returns>
+    /// <param name="jsRuntime">The <see cref="IJSRuntime"/> instance</param>
+    /// <param name="moduleName">The name of the module</param>
+    /// <param name="version">The version of the module</param>
+    /// <returns>A <see cref="Task"/><![CDATA[<]]><see cref="JSModule"/><![CDATA[>]]> module loader</returns>
     public static Task<JSModule> LoadModuleByName(this IJSRuntime jsRuntime, string moduleName, string? version = null)
     {
         var fileName = $"./_content/BootstrapBlazor/modules/{moduleName}.js";
         return LoadModule(jsRuntime, fileName, version);
     }
 
     /// <summary>
-    /// IJSRuntime 扩展方法 动态加载脚本
+    /// IJSRuntime extension method to dynamically load scripts
     /// </summary>
-    /// <param name="jsRuntime"></param>
-    /// <param name="fileName"></param>
-    /// <param name="version"></param>
-    /// <returns>A <see cref="Task"/><![CDATA[<]]><see cref="JSModule"/><![CDATA[>]]> 模块加载器</returns>
+    /// <param name="jsRuntime">The <see cref="IJSRuntime"/> instance</param>
+    /// <param name="fileName">The file name of the script</param>
+    /// <param name="version">The version of the script</param>
+    /// <returns>A <see cref="Task"/><![CDATA[<]]><see cref="JSModule"/><![CDATA[>]]> module loader</returns>
     public static async Task<JSModule> LoadModule(this IJSRuntime jsRuntime, string fileName, string? version = null)
     {
         if (!string.IsNullOrEmpty(version))
@@ -64,10 +64,10 @@ public static async Task<JSModule> LoadModule(this IJSRuntime jsRuntime, string
     }
 
     /// <summary>
-    /// 获得指定类型的加载 Module 名称
+    /// Get the module name of the specified type
     /// </summary>
-    /// <param name="type"></param>
-    /// <returns></returns>
+    /// <param name="type">The type</param>
+    /// <returns>The module name</returns>
     public static string GetTypeModuleName(this Type type)
     {
         var name = type.Name;
@@ -80,47 +80,47 @@ public static string GetTypeModuleName(this Type type)
     }
 
     /// <summary>
-    /// 在新标签页打开指定网址
+    /// Open the specified URL in a new tab
     /// </summary>
-    /// <param name="module"><see cref="JSModule"/> 实例</param>
-    /// <param name="url">打开网页地址</param>
-    /// <param name="target">默认 _blank</param>
-    /// <param name="features">默认 null</param>
+    /// <param name="module"><see cref="JSModule"/> instance</param>
+    /// <param name="url">The URL to open</param>
+    /// <param name="target">The target window, default is _blank</param>
+    /// <param name="features">The features of the new window, default is null</param>
     /// <returns>A <see cref="ValueTask"/> that represents the asynchronous invocation operation.</returns>
     public static ValueTask OpenUrl(this JSModule module, string url, string? target = "_blank", string? features = null) => module.InvokeVoidAsync("openUrl", url, target, features);
 
     /// <summary>
-    /// 动态运行js代码
+    /// Dynamically run js code
     /// </summary>
-    /// <param name="module"><see cref="JSModule"/> 实例</param>
-    /// <param name="script"></param>
+    /// <param name="module"><see cref="JSModule"/> instance</param>
+    /// <param name="script">The script to run</param>
     /// <returns>A <see cref="ValueTask"/> that represents the asynchronous invocation operation.</returns>
     public static async ValueTask Eval(this JSModule module, string script) => await module.InvokeVoidAsync("runEval", script);
 
     /// <summary>
-    /// 通过 Eval 动态运行 JavaScript 代码
+    /// Dynamically run JavaScript code via Eval
     /// </summary>
-    /// <param name="module"><see cref="JSModule"/> 实例</param>
-    /// <param name="script"></param>
+    /// <param name="module"><see cref="JSModule"/> instance</param>
+    /// <param name="script">The script to run</param>
     /// <returns>A <see cref="ValueTask"/> that represents the asynchronous invocation operation.</returns>
     public static ValueTask<TValue?> Eval<TValue>(this JSModule module, string script) => module.InvokeAsync<TValue?>("runEval", script);
 
     /// <summary>
-    /// 通过 Function 动态运行 JavaScript 代码
+    /// Dynamically run JavaScript code via Function
     /// </summary>
-    /// <param name="module"><see cref="JSModule"/> 实例</param>
-    /// <param name="script"></param>
-    /// <param name="args"></param>
+    /// <param name="module"><see cref="JSModule"/> instance</param>
+    /// <param name="script">The script to run</param>
+    /// <param name="args">The arguments to pass to the script</param>
     /// <returns>A <see cref="ValueTask"/> that represents the asynchronous invocation operation.</returns>
     public static ValueTask Function(this JSModule module, string script, params object?[]? args) => module.InvokeVoidAsync("runFunction", script, args);
 
     /// <summary>
-    /// 动态运行js代码
+    /// Dynamically run js code
     /// </summary>
-    /// <typeparam name="TValue"></typeparam>
-    /// <param name="module"><see cref="JSModule"/> 实例</param>
-    /// <param name="script"></param>
-    /// <param name="args"></param>
+    /// <typeparam name="TValue">The return type</typeparam>
+    /// <param name="module"><see cref="JSModule"/> instance</param>
+    /// <param name="script">The script to run</param>
+    /// <param name="args">The arguments to pass to the script</param>
     /// <returns>A <see cref="ValueTask"/> that represents the asynchronous invocation operation.</returns>
     public static async ValueTask<TValue?> Function<TValue>(this JSModule module, string script, params object?[]? args)
     {
@@ -133,41 +133,49 @@ public static string GetTypeModuleName(this Type type)
     }
 
     /// <summary>
-    /// 获取当前终端是否为移动设备
+    /// Check if the current terminal is a mobile device
     /// </summary>
-    /// <param name="module"><see cref="JSModule"/> 实例</param>
+    /// <param name="module"><see cref="JSModule"/> instance</param>
     /// <returns>A <see cref="ValueTask"/> that represents the asynchronous invocation operation.</returns>
     public static ValueTask<bool> IsMobile(this JSModule module) => module.InvokeAsync<bool>("isMobile");
 
     /// <summary>
-    /// 获取一个页面上不重复的元素ID
+    /// Get a unique element ID on a page
     /// </summary>
     /// <param name="module">An instance of <see cref="JSModule"/></param>
     /// <param name="prefix">A prefix of type <see cref="string"/></param>
     /// <returns>Returns a <see cref="string"/> formatted element ID</returns>
     public static ValueTask<string?> GenerateId(this JSModule module, string? prefix = null) => module.InvokeAsync<string?>("getUID", prefix);
 
     /// <summary>
-    /// 获取一个页面内指定元素 Html 字符串
+    /// Get the HTML string of a specified element on a page
     /// </summary>
     /// <param name="module">An instance of <see cref="JSModule"/></param>
-    /// <param name="id"></param>
-    /// <param name="selector"></param>
+    /// <param name="id">The ID of the element</param>
+    /// <param name="selector">The selector of the element</param>
     /// <returns>Returns a <see cref="string"/> formatted element ID</returns>
     public static ValueTask<string?> GetHtml(this JSModule module, string? id = null, string? selector = null) => module.InvokeAsync<string?>("getHtml", new { id, selector });
 
     /// <summary>
-    /// 设置主题方法
+    /// Set the theme method
     /// </summary>
     /// <param name="module">An instance of <see cref="JSModule"/></param>
-    /// <param name="themeName">theme name</param>
+    /// <param name="themeName">The name of the theme</param>
     /// <returns></returns>
     public static ValueTask SetThemeAsync(this JSModule module, string themeName) => module.InvokeVoidAsync("setTheme", themeName, true);
 
     /// <summary>
-    /// 设置主题方法
+    /// Get the theme method
     /// </summary>
     /// <param name="module">An instance of <see cref="JSModule"/></param>
     /// <returns></returns>
     public static ValueTask<string?> GetThemeAsync(this JSModule module) => module.InvokeAsync<string?>("getTheme");
+
+    /// <summary>
+    /// Set memorial mode
+    /// </summary>
+    /// <param name="module">An instance of <see cref="JSModule"/></param>
+    /// <param name="isMemorial">Whether it is memorial mode</param>
+    /// <returns></returns>
+    public static ValueTask SetMemorialModeAsync(this JSModule module, bool isMemorial) => module.InvokeVoidAsync("setMemorialMode", isMemorial);
 }