doc(DrawerService): add documentation for DrawerService (#4027)

* refactor: 移动 Icon 组件位置 * doc: 更新文档配置 * doc: 增加 DrawerService 文档 * doc: 增加抽屉服务文档 * doc: 更新文档状态
dotnetcore · Aug 11, 2024 · 54a180c · 54a180c
1 parent d1e7108
commit 54a180c
Show file tree

Hide file tree

Showing 10 changed files with 110 additions and 70 deletions.
diff --git a/src/BootstrapBlazor.Server/Components/Samples/BootstrapBlazorIcons.razor b/src/BootstrapBlazor.Server/Components/Samples/BootstrapBlazorIcons.razor
@@ -0,0 +1,29 @@
+@page "/icon"
+@inject IStringLocalizer<BootstrapBlazorIcons> Localizer
+
+<h3>@Localizer["IconsTitle"]</h3>
+
+<h4>@Localizer["IconsDescription"]</h4>
+
+<HeadContent>
+    <style>
+        .bb-icon {
+            --bb-icon-width: 24px;
+            --bb-icon-color: var(--bs-body-color);
+        }
+    </style>
+</HeadContent>
+
+<DemoBlock Title="@Localizer["FATitle"]" Introduction="@Localizer["FAIntro"]" Name="Font">
+    <BootstrapBlazorIcon Name="fa-solid fa-home"></BootstrapBlazorIcon>
+</DemoBlock>
+
+<DemoBlock Title="@Localizer["SvgTitle"]" Introduction="@Localizer["SvgIntro"]" Name="Svg">
+    <BootstrapBlazorIcon Name="config" IsSvgSprites="true" Url="./_content/BootstrapBlazor.IconPark/icon-park.svg"></BootstrapBlazorIcon>
+</DemoBlock>
+
+<DemoBlock Title="@Localizer["ImageTitle"]" Introduction="@Localizer["ImageIntro"]" Name="Image">
+    <BootstrapBlazorIcon>
+        <img src="./favicon.png" alt="img" />
+    </BootstrapBlazorIcon>
+</DemoBlock>
diff --git a/...mples/Icons/BootstrapBlazorIcons.razor.cs → ...nts/Samples/BootstrapBlazorIcons.razor.cs b/...mples/Icons/BootstrapBlazorIcons.razor.cs → ...nts/Samples/BootstrapBlazorIcons.razor.cs
@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 // Website: https://www.blazor.zone or https://argozhang.github.io/
 
-namespace BootstrapBlazor.Server.Components.Samples.Icons;
+namespace BootstrapBlazor.Server.Components.Samples;
 
 /// <summary>
 /// Icon 组件

diff --git a/src/BootstrapBlazor.Server/Components/Samples/DrawerServices.razor b/src/BootstrapBlazor.Server/Components/Samples/DrawerServices.razor
@@ -0,0 +1,54 @@
+@page "/drawer-service"
+@layout MainLayout
+@inject IStringLocalizer<DrawerServices> Localizer
+
+<h3>抽屉弹窗服务 <code>DrawerService</code></h3>
+<h4>组件库内置了抽屉弹窗服务</h4>
+
+<p class="code-label">1. 服务注入</p>
+
+<Pre>[Inject]
+[NotNull]
+private DrawerService? DrawerService { get; set; }</Pre>
+
+<p class="code-label">2. 使用服务</p>
+<p>调用 <code>DrawerService</code> 实例方法 <code>Show</code> 即可</p>
+
+<Pre>DrawerService.Show(new DrawerOption()
+{
+    ChildContent = BootstrapDynamicComponent.Create&lt;Count&gt;().Render()
+})</Pre>
+
+<p class="code-label">3. 设计思路</p>
+
+<ul class="ul-demo">
+    <li>弹窗服务仅仅负责弹出弹窗，并且提供 <code>Close</code> 关窗功能</li>
+    <li>显示内容通过 <code>DrawerOption</code> 类参数 <code>ChildContent</code> 自行指定</li>
+    <li>其他更多参数可参见 <code>DrawerOption</code> 类定义 <a href="drawer" target="_blank">[传送门]</a></li>
+</ul>
+
+<p class="code-label">4. 常见问题</p>
+
+<div>
+    <GroupBox Title="代码中如何关闭弹窗" class="mb-3">
+        <p>在使用弹窗的过程中基本都是需要根据自己的业务需求放置一些业务逻辑处理按钮的，比如放置 <b>关闭</b> <b>保存</b> <b>应用</b> 等等，这些按钮逻辑有些是需要处理业务逻辑结束后，根据业务逻辑处理结果决定是否关闭弹窗，代码关闭弹窗我们组件库内置了一下几种办法</p>
+
+        <ul class="ul-demo">
+            <li>弹窗关闭按钮 <code>DialogCloseButton</code></li>
+            <p>这个组件时专门为弹窗设计的按钮组件，此组件内置了关闭所在弹窗功能，无需任何代码</p>
+            <Pre>&lt;DialogCloseButton&gt;</Pre>
+            <p>业务逻辑可使用 <code>OnClick</code> 或者 <code>OnClickWithoutRender</code> 处理，结束后自动关闭弹窗</p>
+            <li>关闭回调方法</li>
+            <Pre class="mt-3">[CascadingParameter]
+private Func&lt;Task&gt;? OnCloseAsync { get; set; }</Pre>
+            <p>弹窗内部任何组件中均可以通过此级联参数获得一个关闭弹窗的方法，可以根据自己的业务逻辑需求自行调用关闭弹窗</p>
+            <p><b>注意：</b>级联参数定义可以随意不一定是 <code>OnCloseAsync</code> 也可以根据自己需要更改为 <code>CloseDrawerAsync</code></p>
+        </ul>
+        <ul class="ul-demo">
+            <li>关闭按钮 <code>DialogCloseButton</code></li>
+            <p>点击后直接关窗，不进行业务逻辑处理</p>
+            <li>保存按钮 <code>DialogSaveButton</code></li>
+            <p>点击后触发 <b>Table</b> 组件内置的保存逻辑，此按钮实际为 <code>submit</code> 按钮，提交表单后触发表单验证逻辑，通过数据有效性验证后调用表格组件 <code>OnSaveAsync</code> 回调方法，控制权再次转移到开发者</p>
+        </ul>
+    </GroupBox>
+</div>
diff --git a/src/BootstrapBlazor.Server/Components/Samples/DrawerServices.razor.css b/src/BootstrapBlazor.Server/Components/Samples/DrawerServices.razor.css
@@ -0,0 +1,7 @@
+::deep .legend {
+    font-weight: bolder;
+}
+
+::deep .groupbox .ul-demo > li {
+    font-weight: bolder;
+}
diff --git a/src/BootstrapBlazor.Server/Components/Samples/Icons/BootstrapBlazorIcons.razor b/src/BootstrapBlazor.Server/Components/Samples/Icons/BootstrapBlazorIcons.razor
diff --git a/src/BootstrapBlazor.Server/Components/Samples/Icons/BootstrapBlazorIcons.razor.css b/src/BootstrapBlazor.Server/Components/Samples/Icons/BootstrapBlazorIcons.razor.css
diff --git a/src/BootstrapBlazor.Server/Extensions/MenusLocalizerExtensions.cs b/src/BootstrapBlazor.Server/Extensions/MenusLocalizerExtensions.cs
@@ -163,7 +163,6 @@ void AddOtherComponent(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["Splitting"],
                     Url = "splitting"
                 },
@@ -332,7 +331,6 @@ void AddForm(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["ClockPicker"],
                     Url = "clock-picker"
                 },
@@ -364,7 +362,6 @@ void AddForm(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["ListGroup"],
                     Url = "list-group"
                 },
@@ -432,13 +429,11 @@ void AddForm(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["SelectObject"],
                     Url = "select-object"
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["SelectTable"],
                     Url = "select-table"
                 },
@@ -507,7 +502,6 @@ void AddData(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["AzureOpenAI"],
                     Url = "ai-chat"
                 },
@@ -573,13 +567,11 @@ void AddData(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["CountUp"],
                     Url = "count-up"
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["CodeEditor"],
                     Url = "code-editors"
                 },
@@ -595,7 +587,6 @@ void AddData(DemoMenuItem item)
                 },
                 new ()
                 {
-                    IsNew = true,
                     Text=Localizer["ExportPdfButton"],
                     Url = "export-pdf-button"
                 },
@@ -606,7 +597,6 @@ void AddData(DemoMenuItem item)
                 },
                 new ()
                 {
-                    IsNew = true,
                     Text=Localizer["EyeDropper"],
                     Url = "eye-dropper"
                 },
@@ -628,8 +618,7 @@ void AddData(DemoMenuItem item)
                 new()
                 {
                     Text = Localizer["Gantt"],
-                    Url = "gantt",
-                    IsNew = true
+                    Url = "gantt"
                 },
                 new()
                 {
@@ -663,7 +652,6 @@ void AddData(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["MindMap"],
                     Url = "mind-map"
                 },
@@ -679,7 +667,6 @@ void AddData(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["QueryBuilder"],
                     Url = "query-builder"
                 },
@@ -700,7 +687,6 @@ void AddData(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["Segmented"],
                     Url = "segmented"
                 },
@@ -717,8 +703,7 @@ void AddData(DemoMenuItem item)
                 new()
                 {
                     Text = Localizer["SvgEditor"],
-                    Url = "svg-editors",
-                    IsNew = true,
+                    Url = "svg-editors"
                 },
                 new()
                 {
@@ -757,19 +742,16 @@ void AddData(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["Waterfall"],
                     Url = "tutorials/waterfall"
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["WebSerial"],
                     Url = "web-serial"
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["WebSpeech"],
                     Url = "web-speech"
                 }
@@ -1119,19 +1101,16 @@ void AddNotice(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["ContextMenu"],
                     Url = "context-menu"
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["CountButton"],
                     Url = "count-button"
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["DialButton"],
                     Url = "dial-button"
                 },
@@ -1152,7 +1131,6 @@ void AddNotice(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["FlipClock"],
                     Url = "flip-clock"
                 },
@@ -1175,7 +1153,6 @@ void AddNotice(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["Marquee"],
                     Url = "marquee"
                 },
@@ -1226,7 +1203,6 @@ void AddNotice(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["SlideButton"],
                     Url = "slide-button"
                 },
@@ -1379,7 +1355,6 @@ void AddLayout(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["Stack"],
                     Url = "stack"
                 }
@@ -1422,6 +1397,11 @@ void AddServices(DemoMenuItem item)
                     Url = "connection-service"
                 },
                 new()
+                {
+                    Text = Localizer["DialogService"],
+                    Url = "dialog-service"
+                },
+                new()
                 {
                     Text = Localizer["Dispatch"],
                     Url = "dispatch"
@@ -1433,8 +1413,9 @@ void AddServices(DemoMenuItem item)
                 },
                 new()
                 {
-                    Text = Localizer["DialogService"],
-                    Url = "dialog-service"
+                    IsNew = true,
+                    Text = Localizer["DrawerService"],
+                    Url = "drawer-service"
                 },
                 new()
                 {
@@ -1488,7 +1469,6 @@ void AddServices(DemoMenuItem item)
                 },
                 new()
                 {
-                    IsNew = true,
                     Text = Localizer["ThemeProvider"],
                     Url = "theme-provider"
                 },
@@ -1527,11 +1507,13 @@ void AddIcons(DemoMenuItem item)
                 },
                 new()
                 {
+                    IsNew = true,
                     Text = Localizer["AntDesignIcon"],
                     Url = "ant-design-icon"
                 },
                 new()
                 {
+                    IsNew = true,
                     Text = Localizer["ElementIcon"],
                     Url = "element-icon"
                 },

diff --git a/src/BootstrapBlazor.Server/Locales/en-US.json b/src/BootstrapBlazor.Server/Locales/en-US.json
@@ -4726,7 +4726,8 @@
     "Icons": "Icons",
     "BootstrapIcon": "Bootstrap Icons",
     "MaterialIcon": "Material Icons",
-    "ElementIcon": "Element Icon"
+    "ElementIcon": "Element Icon",
+    "DrawerService": "DrawerService"
   },
   "BootstrapBlazor.Server.Components.Samples.Table.TablesHeader": {
     "TablesHeaderTitle": "Header grouping function",
@@ -6599,7 +6600,7 @@
     "AntDesignIconDescription": "Semantic vector graphics.",
     "CopiedTooltipText": "Copied"
   },
-  "BootstrapBlazor.Server.Components.Samples.Icons.BootstrapBlazorIcons": {
+  "BootstrapBlazor.Server.Components.Samples.BootstrapBlazorIcons": {
     "IconsTitle": "Icon",
     "IconsDescription": "Supports font icons, vector SVG icons, and Image pictures",
     "FATitle": "Font Icons",