Zen.Wpf.Scroll 0.3.1

🌀 Zen.Scroll

Zen.Scroll 是一个 WPF 滚动动画库，为 ScrollViewer 及其内部包含 ScrollViewer 的控件（ListView、DataGrid、GridView 等）提供滚轮、触控板与缩放的过渡动画。启用方式为在 ScrollViewer 上设置 ScrollAnimation.IsEnabled 附加属性，不涉及模板与布局的修改。

✨ 功能特性

• 🖱️ 滚轮滚动动画 —— 基于指数衰减模型，模拟物理滑动（初速与位移成正比）

• ✋ 触控板滚动 —— 依手势像素速度实时调整缓动曲线与时长

• 🔍 缩放 —— Ctrl + 滚轮，以鼠标位置为中心缩放

• 🎚️ 可调参数 —— 滚动步长、时间常数、缩放范围以附加属性配置

• 🎛️ 启用 —— 设置 ScrollAnimation.IsEnabled 附加属性，支持 XAML 与代码

• ⚡ 高性能 —— GPU 加速的视觉层变换，减少内容布局触发

• 🧩 无缝集成 —— 基于 ScrollViewer 扩展，无需重写布局或更改模板

• 📦 轻量 —— 纯 C# 实现，无额外依赖

📦 安装

通过 NuGet 包管理器安装：

dotnet add package Zen.Wpf.Scroll

或使用 Visual Studio 的 NuGet 包管理器搜索 Zen.Wpf.Scroll 安装

🚀 快速开始

1. 单个 ScrollViewer 启用

<Window>
    <ScrollViewer ScrollAnimation.IsEnabled="True">
        
    </ScrollViewer>
</Window>

2. 全局启用（所有 ScrollViewer）

 
<Application.Resources>
    <ResourceDictionary.MergedDictionaries>
        
        <ResourceDictionary Source="/TemplateStyles.xaml" />
    </ResourceDictionary.MergedDictionaries>
</Application.Resources>

 
<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Style BasedOn="{StaticResource {x:Type ScrollViewer}}" TargetType="ScrollViewer">
        <Setter Property="ScrollAnimation.IsEnabled" Value="true" />
    </Style>

    <Style
        x:Key="{x:Static GridView.GridViewScrollViewerStyleKey}"
        BasedOn="{StaticResource {x:Static GridView.GridViewScrollViewerStyleKey}}"
        TargetType="{x:Type ScrollViewer}">
        <Setter Property="ScrollAnimation.IsEnabled" Value="true" />
    </Style>
</ResourceDictionary>

3. 代码控制

// 启用/禁用
ScrollAnimation.SetIsEnabled(myScrollViewer, true);

// 检查状态
bool enabled = ScrollAnimation.GetIsEnabled(myScrollViewer);

4. 参数调节

<Style TargetType="ScrollViewer">
    <Setter Property="ScrollAnimation.IsEnabled" Value="True" />
    <Setter Property="ScrollAnimation.ScrollDelta" Value="100" />
    <Setter Property="ScrollAnimation.ScrollDuration" Value="80" />
    <Setter Property="ScrollAnimation.MinimumScale" Value="1,1" />
    <Setter Property="ScrollAnimation.MaximumScale" Value="10,10" />
    <Setter Property="ScrollAnimation.ZoomDelta" Value="0.2" />
</Style>

超出范围的值会被就近修正，参数变更立即生效。

⚙️ 工作原理（架构概览）

分层结构

调用链：

graph TD
    A[用户滚轮 / 触控板输入] --> B{Controller 拦截输入}
    B --> G[动画开始：暂停内容布局]
    G --> C[ScrollAnimation 计算本帧增量]
    C --> D[Client 提交待应用目标]
    C --> E[等待每帧 FlushFrame 合成]
    D --> F[ MatrixTransform 内容变换 （GPU 合成） ]
    E --> F
    F --> H[动画结束：恢复布局并折算内容偏移]

性能优化策略

动画期间内容子树的布局请求会被推迟到动画结束统一处理，因此滚动过程中的元素尺寸变化不会立即生效。

📝 许可证

本项目采用 Apache License 2.0 许可证，详情请参阅 LICENSE 文件。

Enjoy smooth scrolling! 🌀