docs: 添加部分内容

docs/zh/enhanced_controls.md

@@ -107,4 +107,60 @@ TextBox 和 PasswordBox 现在可以通过 Placeholder 属性来设置占位符.
 </ws:StackPanel>
 ```
 
-![圆角裁剪示例效果](/images/borderclip-example.png)
+![圆角裁剪示例效果](/images/borderclip-example.png)
+
+## 平滑滚动
+
+如果你使用 WPF Suite 提供的 ScrollViewer, 那么对于使用鼠标的内容滚动, 会有更平滑的效果.
+
+| 附加属性 | 类型 | 描述 |
+| --- | --- | --- |
+| ScrollWithWheelDelta | bool | 通过 Wheel 事件的 delta 值决定滚动距离, 此选项用于优化触摸板滚动效果, 默认为 true |
+| EnableScrollingAnimation | bool | 启用滚动动画, 决定使用鼠标进行滚动时是否使用缓动的效果, 默认为 true, 并且此选项要求 ScrollWithWheelDelta 设为 true, 否则不起作用 |
+| ScrollingAnimationDuration | Duration | 滚动动画的时长, 默认为 250ms |
+| MouseScrollDeltaFactor | double | 当使用鼠标进行滚动时, 滚动 Delta 值的乘数. 改变此值可以变更滚动速度与方向, 默认为 1 |
+| TouchpadScrollDeltaFactor | double | 当使用触摸板进行滚动时, 滚动 Delta 值的乘数. 改变此值可以变更滚动速度与方向, 默认为 1 |
+| AlwaysHandleMouseWheelScrolling | bool | 总是处理鼠标 Wheel 事件的滚动, 当鼠标滚轮滚动时则滚动 ScrollViewer 内容. 默认为 true |
+
+{: .tip }
+> 将 AlwaysHandleMouseWheelScrolling 设置为 false 时, ScrollViewer 的滚动效果将不会应用于 TextBox 上
+
+使用示例:
+{: .fw-300}
+
+```xml
+<ws:ScrollViewer>
+    省略内容...
+</ws:ScrollViewer>
+```
+
+![ScrollViewer 示例效果](/images/scrollviewer-example.webp)
+
+## 触摸模拟
+
+原生的 WPF 是无法使用笔对 ScrollViewer 进行滚动的, 如果你想要通过笔来滚动, 可以使用 "触摸设备模拟". 通过笔来模拟一个触摸设备, 实现笔滚动.
+
+| 附加属性 | 类型 | 描述 |
+| --- | --- | --- |
+| StylusTouchDevice.Simulate | bool | 是否将笔模拟为触摸设备, 默认为 false |
+| StylusTouchDevice.MoveThreshold | double | 移动阈值, 笔在移动超过指定的距离之后, 才会将移动汇报为触摸移动, 默认为 3 |
+| MouseTouchDevice.Simulate | bool | 是否将鼠标模拟为触摸设备, 默认为 false |
+| MouseTouchDevice.MoveThreshold | double | 移动阈值, 笔在移动超过指定的距离之后, 才会将移动汇报为触摸移动, 默认为 3 |
+
+{: .tip }
+> 如果你将移动阈值设为 0, 那么你将无法通过笔来进行点击 ScrollViewer 内的控件, 因为笔总是存在抖动的, 触摸移动会进行 ScrollViewer 的滚动, 从而打断点击这一动作.
+> 
+> 所以, 根据你想要的 "精度", 适当调整 "移动阈值".
+> (很多程序对于这个都有一个较大的阈值, 例如 5px, 甚至 10px 或更多)
+
+使用示例:
+{: .fw-300}
+
+```xml
+<ws:ScrollViewer PanningMode="Both"
+                 ws:MouseTouchDevice.Simulate="True">
+    省略内容...
+</ws:ScrollViewer>
+```
+
+![模拟触摸示例效果](/images/simulatetouch-example.webp)

docs/zh/index.md

@@ -13,7 +13,7 @@ WPF Suite 为 WPF 拓展了一些基础但必备的功能, 能够极大的提升
 {: .fs-6 .fw-300 }
 
 
-[快速开始](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
+[快速开始](#快速开始){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
 [在 GitHub 上查看](https://github.com/OrgEleCho/EleCho.WpfSuite){: .btn .fs-5 .mb-4 .mb-md-0 }
 
 ---

docs/zh/transition_effects.md

@@ -0,0 +1,201 @@
+---
+title: 过渡效果
+layout: default
+nav_order: 4
+permalink: /zh/transition-effects
+parent: 中文文档
+---
+
+# 过渡效果
+{: .fs-9 }
+
+当内容切换时, 执行一个过渡效果, 例如淡入淡出, 或者滑入滑出, 能够让程序美观许多.
+{: .fs-6 .fw-300 }
+
+---
+
+下面是有关 WPF Suite 中过渡动画的介绍
+
+## IContentTransition
+
+表示一个内容过渡效果的接口
+
+定义
+{: .fw-300}
+
+```cs
+/// <summary>
+/// Content transition
+/// </summary>
+public interface IContentTransition
+{
+    /// <summary>
+    /// Run the content transition
+    /// </summary>
+    /// <param name="container">Container UIElement</param>
+    /// <param name="oldContent">Old content UIElement</param>
+    /// <param name="newContent">New content UIElement</param>
+    /// <param name="forward">This transition is forward</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns></returns>
+    public Task Run(
+        FrameworkElement container, 
+        FrameworkElement? oldContent, 
+        FrameworkElement? newContent, 
+        bool forward, 
+        CancellationToken cancellationToken);
+}
+
+```
+
+下面是一些内置的过渡效果:
+
+| 类名 | 描述 |
+| --- | --- |
+| FadeTransition | 淡入淡出效果, 通过对 Opacity 运行动画实现 |
+| SlideTransition | 滑动过渡效果, 通过设置 RenderTransform, 对 TranslateTransform 运行动画实现 |
+| RotateTransition | 旋转过渡效果, 通过设置 RenderTransform, 对 RotateTransform 运行动画实现 |
+| SlideFadeTransition | 淡入淡出与滑动过渡效果的结合 |
+| RotateFadeTransition | 淡入淡出与旋转过渡效果的结合 |
+
+## TransitioningContentControl
+
+允许使用过渡动画的 ContentControl 实现. 继承自 Control.
+
+| 属性 | 类型 | 描述 |
+| Content | object | 内容, 默认为 null |
+| ContentTemplate | DataTemplate | 内容的模板, 默认为 null |
+| ContentTemplateSelector | DataTemplateSelector | 内容的模板选择器, 默认为 null |
+| Transition | IContentTransition | 内容切换所使用的过渡效果, 默认为 null |
+| CornerRadius | CornerRadius | 圆角边缘半径 |
+
+{: .warning }
+> TransitioningContentControl 并不继承自 ContentControl
+
+使用示例
+{: .fw-300}
+
+```xml
+<ws:Button Click="Button_Click"
+           ClipToBounds="True">
+    <ws:TransitioningContentControl Name="buttonContentControl"
+                                    Content="Test">
+        <ws:TransitioningContentControl.Transition>
+            <ws:SlideFadeTransition Orientation="Vertical"/>
+        </ws:TransitioningContentControl.Transition>
+    </ws:TransitioningContentControl>
+</ws:Button>
+```
+
+```cs
+private void Button_Click(object sender, RoutedEventArgs e)
+{
+    buttonContentControl.Content = System.IO.Path.GetRandomFileName();
+}
+```
+
+![过渡演示1](/images/transition-example1.webp)
+
+更复杂的使用
+{: .fw-300}
+
+```xml
+<Grid>
+    <ws:TransitioningContentControl Content="{Binding CurrentImageSource}"
+                                    d:Content="{d:DesignInstance Type=ImageSource}"
+                                    CornerRadius="5"
+                                    ClipToBounds="True">
+        <ws:TransitioningContentControl.Transition>
+            <ws:SlideTransition Reverse="{Binding TransitionReverse}"/>
+        </ws:TransitioningContentControl.Transition>
+        <ws:TransitioningContentControl.ContentTemplate>
+            <DataTemplate>
+                <Image Height="300"
+                       Source="{Binding}"
+                       Stretch="UniformToFill"/>
+            </DataTemplate>
+        </ws:TransitioningContentControl.ContentTemplate>
+    </ws:TransitioningContentControl>
+    <ws:Button Command="{Binding GoPrevCommand}"
+               VerticalAlignment="Center"
+               HorizontalAlignment="Left"
+               Opacity=".8"
+               Content="&lt;"
+               Margin="5"
+               Padding="5">
+    </ws:Button>
+    <ws:Button Command="{Binding GoNextCommand}"
+               VerticalAlignment="Center"
+               HorizontalAlignment="Right"
+               Opacity=".8"
+               Content="&gt;"
+               Margin="5"
+               Padding="5"/>
+</Grid>
+```
+
+```cs
+[ObservableProperty]
+[NotifyPropertyChangedFor(nameof(CurrentImageSource))]
+private int _currentImageSourceIndex;
+
+[ObservableProperty]
+private bool _transitionReverse;
+
+public ObservableCollection<ImageSource> ImageSources { get; } = new()
+{
+    new BitmapImage(new Uri("pack://application:,,,/WpfTest;component/Assets/Banners/1.jpg")),
+    new BitmapImage(new Uri("pack://application:,,,/WpfTest;component/Assets/Banners/2.jpg")),
+    new BitmapImage(new Uri("pack://application:,,,/WpfTest;component/Assets/Banners/3.jpg")),
+    new BitmapImage(new Uri("pack://application:,,,/WpfTest;component/Assets/Banners/4.jpg")),
+    new BitmapImage(new Uri("pack://application:,,,/WpfTest;component/Assets/Banners/5.jpg")),
+};
+
+public ImageSource? CurrentImageSource => ImageSources[CurrentImageSourceIndex];
+
+public WelcomePage()
+{
+    InitializeComponent();
+
+    DataContext = this;
+}
+
+[RelayCommand]
+public void GoPrev()
+{
+    TransitionReverse = true;
+    var prevIndex = CurrentImageSourceIndex;
+    if (prevIndex == 0)
+        prevIndex = ImageSources.Count;
+
+    prevIndex--;
+
+    CurrentImageSourceIndex = prevIndex;
+}
+
+[RelayCommand]
+public void GoNext()
+{
+    TransitionReverse = false;
+    CurrentImageSourceIndex = (CurrentImageSourceIndex + 1) % ImageSources.Count;
+}
+```
+
+{: .tip }
+> 这里的 ObservableProperty 和 RelayCommand 是使用了 CommunityToolkit.Mvvm 自动生成可观察属性与指令
+
+![过渡演示2](/images/transition-example2.webp)
+
+## Frame
+
+WPF Suite 中提供的 Frame 控件也支持导航, 所以, 当你的程序是一个多页面程序时, 可以用过渡效果来使其更美观
+
+| 属性 | 类型 | 描述 |
+| --- | --- | ---- |
+| CornerRadius | CornerRadius | 圆角边缘半径 |
+| Transition | IContentTransition | 内容切换的过渡效果 |
+
+大致效果
+{: .fw-300}
+
+![过渡演示3](/images/transition-example3.webp)