Merge pull request #274 from AuroraZiling/main

Docs update for `Hosts`
kikipoulet · Aug 16, 2024 · 4095bef · 4095bef
2 parents 4e48828 + 94a4cfe
commit 4095bef
Show file tree

Hide file tree

Showing 13 changed files with 167 additions and 20 deletions.
diff --git a/docs/docs/.vitepress/config/en.mts b/docs/docs/.vitepress/config/en.mts
@@ -92,6 +92,13 @@ export const en = defineConfig({
               { text: 'Expander', link: '/documentation/controls/data/expander' },
             ]
           },
+          {
+            text: 'Notification',
+            items: [
+              { text: 'InfoBar', link: '/documentation/controls/notification/infobar' },
+              { text: 'InfoBadge', link: '/documentation/controls/notification/infobadge' },
+            ]
+          },
           {
             text: 'System',
             items: [
@@ -101,13 +108,11 @@ export const en = defineConfig({
         ]
       },
       {
-        text: 'Notification',
+        text: 'Hosts',
         items: [
-          { text: 'Dialog', link: '/documentation/notification/dialog' },
-          { text: 'Toast', link: '/documentation/notification/toast' },
-          { text: 'MessageBox', link: '/documentation/notification/messagebox' },
-          { text: 'InfoBar', link: '/documentation/notification/infobar' },
-          { text: 'InfoBadge', link: '/documentation/notification/infobadge' },
+          { text: 'About Hosts', link: '/documentation/hosts/hosts' },
+          { text: 'Dialog', link: '/documentation/hosts/dialog' },
+          { text: 'Toast', link: '/documentation/hosts/toast' },
         ]
       },
       {

diff --git a/docs/docs/.vitepress/config/zh.mts b/docs/docs/.vitepress/config/zh.mts
@@ -92,6 +92,13 @@ export const zh = defineConfig({
               { text: 'Expander', link: '/zh/documentation/controls/data/expander' },
             ]
           },
+          {
+            text: '提醒',
+            items: [
+              { text: 'InfoBar', link: '/zh/documentation/controls/notification/infobar' },
+              { text: 'InfoBadge', link: '/zh/documentation/controls/notification/infobadge' },
+            ]
+          },
           {
             text: '系统 API',
             items: [
@@ -101,13 +108,11 @@ export const zh = defineConfig({
         ]
       },
       {
-        text: '通知',
+        text: '可选窗口控件',
         items: [
-          { text: 'Dialog', link: '/zh/documentation/notification/dialog' },
-          { text: 'Toast', link: '/zh/documentation/notification/toast' },
-          { text: 'MessageBox', link: '/zh/documentation/notification/messagebox' },
-          { text: 'InfoBar', link: '/zh/documentation/notification/infobar' },
-          { text: 'InfoBadge', link: '/zh/documentation/notification/infobadge' },
+          { text: '有关 Hosts', link: '/zh/documentation/hosts/hosts' },
+          { text: 'Dialog', link: '/zh/documentation/hosts/dialog' },
+          { text: 'Toast', link: '/zh/documentation/hosts/toast' },
         ]
       },
       {

diff --git a/...s/documentation/notification/infobadge.md → ...tation/controls/notification/infobadge.md b/...s/documentation/notification/infobadge.md → ...tation/controls/notification/infobadge.md
diff --git a/...ocs/documentation/notification/infobar.md → ...entation/controls/notification/infobar.md b/...ocs/documentation/notification/infobar.md → ...entation/controls/notification/infobar.md
diff --git a/docs/docs/documentation/hosts/toast.md b/docs/docs/documentation/hosts/toast.md
@@ -24,7 +24,9 @@ public class ExampleViewModel
 }
 ```
 
-Is is possible to set `MaxToasts` to limit the number of toasts displayed in any given host.
+It is possible to set `MaxToasts` to limit the number of toasts displayed in any given host.
+
+---
 
 If you do not wish to use MVVM, or would rather a simpler solution that "just works", then you can choose to implement it like this:
 
@@ -49,19 +51,15 @@ public class MainWindow : SukiWindow
 		ToastHost.Manager = ToastManager;
 	}
 }
-
-// and then...
-
-MainWindow.ToastManager.CreateToast()
-	.Queue();
 ```
+
 ### Usage
+
 ```cs
 MainWindow.ToastManager.CreateToast()
 	.Queue();
 ```
 
-
 ## Displaying Toasts
 
 In order to construct and therefore display toasts, a fluent style builder is provided that makes constructing toasts simple. To begin constructing a toast, it's recommended to call the extension method `.CreateToast()` on the `ISukiToastManager` instance you want it to be displayed in.
@@ -70,7 +68,7 @@ From here method calls can be chained to construct the toast as desired, most of
 
 Finally to display a toast the `.Queue()` method can be called to immediately queue the toast for display.
 
-Here is a simple example, expanding on the ViewModel above:
+Here is a simple example, expanding on the `ViewModel` above:
 
 ```cs
 public void DisplayToast()

diff --git a/...h/documentation/notification/infobadge.md → ...tation/controls/notification/infobadge.md b/...h/documentation/notification/infobadge.md → ...tation/controls/notification/infobadge.md
diff --git a/.../zh/documentation/notification/infobar.md → ...entation/controls/notification/infobar.md b/.../zh/documentation/notification/infobar.md → ...entation/controls/notification/infobar.md
diff --git a/docs/docs/zh/documentation/hosts/dialog.md b/docs/docs/zh/documentation/hosts/dialog.md
@@ -0,0 +1,5 @@
+# Dialogs
+
+SukiUI 提供了一个用于弹出对话框的[可选窗口控件](./hosts)，该控件可以很轻易地在 `SukiWindow.Hosts` 添加（这也是最推荐且能达到最佳效果的使用方法）
+
+该对话框对 MVVM 设计模式友好，同时你也可以通过 `ISukiDialogManager` 来获得给定的 `SukiDialogHost` 实例，从而显示对话框。
diff --git a/docs/docs/zh/documentation/hosts/hosts.md b/docs/docs/zh/documentation/hosts/hosts.md
@@ -0,0 +1,14 @@
+# Hosts
+
+SukiUI 在 `SukiWindow` 内提供了 `Hosts` 属性，可以在该属性内添加任意控件，而这些控件将会显示在其他所有子控件的上层（包括标题栏）
+
+```xml
+<!-- XMLNS 定义已略去 -->
+<suki:SukiWindow>
+	<suki:SukiWindow.Hosts>
+		<!-- 你的控件 -->
+	</suki:SukiWindow.Hosts>
+</suki:SukiWindow>
+```
+
+SukiUI 本身提供两个可选的窗口控件，即 [SukiDialogHost](./dialog) 和 [SukiToastHost](./toast)
diff --git a/docs/docs/zh/documentation/hosts/toast.md b/docs/docs/zh/documentation/hosts/toast.md
@@ -0,0 +1,120 @@
+# Toasts
+
+SukiUI 提供了一个用于弹出消息提醒的[可选窗口控件](./hosts)，该控件可以很轻易地在 `SukiWindow.Hosts` 添加（这也是最推荐且能达到最佳效果的使用方法）
+
+该消息提醒控件对 MVVM 设计模式友好，同时你也可以通过 `ISukiToastManager` 来获得给定的 `SukiToastHost` 实例，从而显示提示消息。
+
+以下是一些 MVVM 设计模式下使用的例子：
+
+### View
+```xml
+<!-- XMLNS 定义已略去 -->
+<suki:SukiWindow>
+	<suki:SukiWindow.Hosts>
+		<suki:SukiToastHost Manager="{Binding ToastManager}"/>
+	</suki:SukiWindow.Hosts>
+<suki:SukiWindow>
+```
+
+### ViewModel
+```cs
+public class ExampleViewModel
+{
+	public ISukiToastManager ToastManager { get; } = new();
+}
+```
+
+可以通过修改 `MaxToasts` 的值以达到限制消息弹出数量的效果
+
+---
+
+如果你并未使用 MVVM 设计模式，只是想做一些简单实现，可以参考以下方法：
+
+### AXAML
+```xml
+<!-- XMLNS 定义已略去 -->
+<suki:SukiWindow>
+	<suki:SukiWindow.Hosts>
+		<suki:SukiToastHost Name="ToastManager"/>
+	</suki:SukiWindow.Hosts>
+<suki:SukiWindow>
+```
+
+### Code-Behind
+```cs
+public class MainWindow : SukiWindow
+{
+	public static ISukiToastManager ToastManager = new SukiToastManager();
+
+	public MainWindow()
+	{
+		InitializeComponent();
+		ToastHost.Manager = ToastManager;
+	}
+}
+```
+
+### 用法
+
+```cs
+MainWindow.ToastManager.CreateToast()
+	.Queue();
+```
+
+## 显示消息提醒
+
+SukiUI 实现了一个现代的消息构造器。构造时推荐在 `ISukiToastManager` 的实例上调用 `.CreateToast()` 扩展方法
+
+构造操作的体验是链式的，且均提供了 XML 文档
+
+最后通过调用 `.Queue()` 方法来让该消息进入队列中，并立即显示消息
+
+以下是在 `ViewModel` 中的用例：
+
+```cs
+public void DisplayToast()
+{
+	ToastManager.CreateToast()
+		.WithTitle("Example Toast")
+		.WithContent("The content of an example toast can be seen here.")
+		.Queue();
+}
+```
+
+## 自动消失
+
+通常地，当消息提醒数量超过预设的最大值后，最老的消息将会立即消失以腾出空间。
+
+但是，你也可以通过调用 `.Dismiss()` 方法来设置消失的条件
+
+以下是让一个消息在3秒钟后/被点击后消失的用例：
+
+```cs
+public void DisplayToast()
+{
+	ToastManager.CreateToast()
+		.Dismiss().After(TimeSpan.FromSeconds(3))
+        .Dismiss().ByClicking()
+        .Queue();
+}
+```
+
+## 交互
+
+SukiUI 提供了两个默认的消息回调，分别是 `.OnClicked()` 和 `.OnDismissed()`
+
+同时，可以通过 `.WithActionButton()` 方法来实现更复杂的交互操作
+
+以下是一个显示3秒钟后消失，点击后和消失后会调用命令行输出，按特定按钮会触发 Action 的消息用例：
+
+```cs
+public void DisplayToast()
+{
+	ToastManager.CreateToast()
+		.Dismiss().After(TimeSpan.FromSeconds(3))
+        .OnClicked(_ => Console.WriteLine("Toast Clicked!"))
+        .OnDismissed(_ => Console.WriteLine("Toast Was Dismissed!")) 
+        .WithActionButton("Dismiss", _ => { }, true)
+        .Queue();
+}
+```
diff --git a/docs/docs/zh/documentation/notification/dialog.md b/docs/docs/zh/documentation/notification/dialog.md
diff --git a/docs/docs/zh/documentation/notification/messagebox.md b/docs/docs/zh/documentation/notification/messagebox.md
diff --git a/docs/docs/zh/documentation/notification/toast.md b/docs/docs/zh/documentation/notification/toast.md