脚踏实地皮皮晨头像
004016002_WPF ScrollViewer 基类体系官方源代码级完整解析封面图

004016002_WPF ScrollViewer 基类体系官方源代码级完整解析

004016002_WPF ScrollViewer 基类体系官方源代码级完整解析

本文摘要： 本文以微软官方 .NET 8 源码为基线，系统拆解 WPF ScrollViewer 背后的七层继承体系——从 DispatcherObject 的线程模型、DependencyObject 的依赖属性系统、Visual 的渲染基础、UIElement 的输入与布局、FrameworkElement 的测量排列，到 Control 的模板机制与 ContentControl 的单内容模型；并进一步深入 ScrollContentPresenter 这一真正的滚动核心，解析其通过 RenderTransform 实现内容偏移、与 ScrollViewer 协作的完整机制。文末还提供高频问题排查速查表与自定义模板实战，帮助读者从原理层面定位滚动故障、掌握工业级定制方法。

ScrollViewer 的强大能力并非凭空而来，而是建立在 WPF 精心设计的七层继承体系之上。每一层基类都专注于解决一个特定领域的问题，最终组合成功能完整、高度可扩展的滚动容器。

本文将严格按照微软官方 .NET 8 源代码，从最顶层的 Object 开始，逐层解析每个基类的官方类定义、核心成员、设计意图，以及它们如何为 ScrollViewer 提供基础能力。

完整继承链（官方精确）

System.Object
  └── System.Windows.Threading.DispatcherObject
      └── System.Windows.DependencyObject
          └── System.Windows.Media.Visual
              └── System.Windows.UIElement
                  └── System.Windows.FrameworkElement
                      └── System.Windows.Controls.Control
                          └── System.Windows.Controls.ContentControl
                              └── System.Windows.Controls.ScrollViewer

官方源码参考

本文所有源码均以 dotnet/wpf 仓库的 .NET 8.0 标签 v8.0.0 为基线。下面列出的行号为该 tag 下的近似参考值，可能随补丁提交略有浮动；进入源码页后建议用 Ctrl+F 搜索方法名快速精确定位。

1. DispatcherObject

2. DependencyObject

3. Visual

4. UIElement

5. FrameworkElement

6. Control

7. ContentControl

8. ScrollContentPresenter

💡 提示：ScrollViewer 自身的模板部件查找逻辑位于 ScrollViewer.OnApplyTemplate()（ScrollViewer.cs 中约 L300 起），可结合第六层 Control 的模板系统对照阅读。

第一层：DispatcherObject（线程模型基础）

官方类定义

public abstract class DispatcherObject
{
    // 核心属性
    public Dispatcher Dispatcher { get; }

    // 核心方法
    public bool CheckAccess();
    public void VerifyAccess();
}

核心能力与对 ScrollViewer 的贡献

  1. WPF 线程模型的基石
    • 所有 WPF 对象都必须在创建它的 Dispatcher 线程上访问
    • CheckAccess()：检查当前线程是否可以访问该对象
    • VerifyAccess()：如果当前线程无权访问，直接抛出 InvalidOperationException
  2. 在 ScrollViewer 中的体现
    • 所有滚动操作（如 ScrollToEnd()、ScrollToVerticalOffset()）必须在 UI 线程执行
    • 相机回调、PLC 通信等后台线程更新滚动位置时，必须通过 Dispatcher.Invoke() 切换到 UI 线程

⚠️ 工业开发红线：永远不要在后台线程直接操作 ScrollViewer 的任何属性或方法否则会导致偶发崩溃和内存损坏坏。

第二层：DependencyObject（依赖属性系统基础）

官方类定义

public abstract class DependencyObject
{
    // 核心方法
    public object GetValue(DependencyProperty dp);
    public void SetValue(DependencyProperty dp, object value);
    public void ClearValue(DependencyProperty dp);
    public object ReadLocalValue(DependencyProperty dp);

    // 附加属性支持
    public static object GetValue(DependencyObject d, DependencyProperty dp);
    public static void SetValue(DependencyObject d, DependencyProperty dp, object value);
}

核心能力与对 ScrollViewer 的贡献

  1. 依赖属性系统的载体

    • 所有 WPF 控件的属性都是依赖属性，支持数据绑定、样式、动画、继承。
    • ScrollViewer 的 16 个依赖属性（如 VerticalOffset、CanContentScroll）全部由 DependencyObject 提供支持。

  2. 附加属性支持

    • 支持 ScrollViewer.VerticalScrollBarVisibility 等附加属性，可以在任何元素上设置。
    • 这是 ListBox、DataGrid 等控件能够间接控制滚动行为的基础。

  3. 在 ScrollViewer 中的体现 ```csharp#
    // ScrollViewer 所有依赖属性的定义模式
    public static readonly DependencyProperty VerticalScrollBarVisibilityProperty =
    DependencyProperty.Register(
    nameof(VerticalScrollBarVisibility),
    typeof(ScrollBarVisibility),
    typeof(ScrollViewer),
    new FrameworkPropertyMetadata(ScrollBarVisibility.Visible,
    FrameworkPropertyMetadataOptions.AffectsMeasure));

第三层：Visual（底层渲染基础）

官方类定义:

public abstract class Visual : DependencyObject
{
    // 核心属性
    protected internal Visual Parent { get; }
    public DependencyObject VisualParent { get; }

    // 核心方法
    protected virtual void OnRender(DrawingContext drawingContext);
    protected internal virtual int VisualChildrenCount { get; }
    protected internal virtual Visual GetVisualChild(int index);
    public GeneralTransform TransformToAncestor(Visual ancestor);
    public GeneralTransform TransformToDescendant(Visual descendant);
}

核心能力与对 ScrollViewer 的贡献

  1. WPF 渲染系统的基础
    • 所有可见的 WPF 对象都继承自 Visual
    • 提供底层的渲染、变换、命中测试能力
    • 管理视觉树（Visual Tree）结构
  2. 在 ScrollViewer 中的体现
    • ScrollViewer 的内容通过 ScrollContentPresenter 渲染，而 ScrollContentPresenter 继承自 Visual
    • 滚动本质上是修改 ScrollContentPresenter 的 RenderTransform 属性
    • TransformToAncestor() 和 TransformToDescendant() 用于计算滚动后的坐标转换

🔑 关键原理：ScrollViewer 本身不渲染任何内容，它只是通过 ScrollContentPresenter 来显示和移动子内容。

第四层：UIElement（输入与布局基础）### 官方类定义::

public abstract class UIElement : Visual, IInputElement
{
    // 核心依赖属性
    public static readonly DependencyProperty VisibilityProperty;
    public static readonly DependencyProperty IsEnabledProperty;
    public static readonly DependencyProperty IsHitTestVisibleProperty;
    public static readonly DependencyProperty RenderTransformProperty;
    public static readonly DependencyProperty ClipToBoundsProperty;

    // 核心事件
    public event MouseButtonEventHandler MouseDown;
    public event MouseButtonEventHandler MouseUp;
    public event MouseWheelEventHandler MouseWheel;
    public event KeyEventHandler KeyDown;
    public event KeyEventHandler KeyUp;

    // 核心方法
    public bool IsKeyboardFocusWithin { get; }
    public bool IsMouseOver { get; }
    public void InvalidateVisual();
    public bool Focus();
}

核心能力与对 ScrollViewer 的贡献

  1. 输入处理系统
    • 处理鼠标、键盘、触摸等所有输入事件
    • 提供焦点管理、命中测试能力
  2. 布局基础
    • 定义了布局的基本接口（虽然具体实现在 FrameworkElement）
    • 提供 InvalidateVisual() 方法强制重绘
  3. 在 ScrollViewer 中的体现
    • 鼠标滚轮滚动、键盘方向键滚动、触摸平移全部由 UIElement 的输入事件驱动
    • ClipToBounds 属性控制是否裁剪超出视口的内容
    • RenderTransform 属性用于实现内容的滚动偏移

🔑 关键原理：ScrollViewer 的滚动行为本质上是对输入事件的响应。当用户滚动鼠标滚轮时，UIElement 触发 MouseWheel 事件，ScrollViewer 处理该事件并更新滚动偏移量。

第五层：FrameworkElement（布局与数据绑定基础### 官方类定义rp:

public class FrameworkElement : UIElement
{
    // 核心依赖属性
    public static readonly DependencyProperty WidthProperty;
    public static readonly DependencyProperty HeightProperty;
    public static readonly DependencyProperty MarginProperty;
    public static readonly DependencyProperty HorizontalAlignmentProperty;
    public static readonly DependencyProperty VerticalAlignmentProperty;
    public static readonly DependencyProperty DataContextProperty;
    public static readonly DependencyProperty StyleProperty;

    // 核心布局方法
    protected virtual Size MeasureOverride(Size availableSize);
    protected virtual Size ArrangeOverride(Size finalSize);
    public void UpdateLayout();

    // 核心事件
    public event RoutedEventHandler Loaded;
    public event SizeChangedEventHandler SizeChanged;
}

核心能力与对 ScrollViewer 的贡献

  1. 完整的布局系统
    • 实现了 WPF 的测量（Measure）和排列（Arrange）两步布局流程
    • 提供宽度、高度、边距、对齐方式等布局属性
  2. 数据绑定与样式系统
    • DataContext 属性是 MVVM 模式的基础
    • Style 属性支持控件样式定制
  3. 在 ScrollViewer 中的体现
    • ScrollViewer 通过重写 MeasureOverride 和 ArrangeOverride 计算内容大小和视口大小
    • 当内容大小或视口大小变化时，自动更新滚动条的范围和位置
    • 支持数据绑定，如 VerticalScrollBarVisibility="{Binding IsLongContent}"

🔑 关键原理：ScrollViewer 的滚动范围是在布局阶段计算的。在 MeasureOverride 中，ScrollViewer 会测量子内容的总大小，然后与自身视口大小比较，计算出可滚动范围。

----## 第六层：Control（通用控件基础）

官方类定义:rp:

public class Control : FrameworkElement
{
    // 核心依赖属性
    public static readonly DependencyProperty BackgroundProperty;
    public static readonly DependencyProperty ForegroundProperty;
    public static readonly DependencyProperty BorderBrushProperty;
    public static readonly DependencyProperty BorderThicknessProperty;
    public static readonly DependencyProperty PaddingProperty;
    public static readonly DependencyProperty FontSizeProperty;
    public static readonly DependencyProperty FontWeightProperty;
    public static readonly DependencyProperty TemplateProperty;

    // 核心方法
    public override void OnApplyTemplate();
    protected virtual AutomationPeer OnCreateAutomationPeer();
}

核心能力与对 ScrollViewer 的贡献

  1. 通用控件属性
    • 提供所有控件通用的外观属性：背景、前景、边框、内边距、字体等
    • 统一了控件的外观定制方式
  2. 控件模板系统
    • Template 属性允许完全重写控件的外观
    • OnApplyTemplate() 方法在模板应用时调用，用于查找模板部件
  3. 在 ScrollViewer 中的体现
    • ScrollViewer 的默认外观（滚动条、背景、边框）全部由 ControlTemplate 定义
    • OnApplyTemplate() 方法中查找 PART_ScrollContentPresenter、PART_VerticalScrollBar 和 PART_HorizontalScrollBar 三个核心模板部件
    • 支持通过样式自定义滚动条的外观

⚠️ 工业开发注意：自定义 ScrollViewer 模板时，必须包含三个 PART_* 模板部件，否则滚动功能将完全失效，但不会抛出任这是 WPF 最常见的陷阱之一。坑之一。

第七层：ContentControl（单内容模型基### 官方类定义（ScrollViewer 的直接基类）arp:

[ContentProperty("Content")]
public class ContentControl : Control
{
    // 核心依赖属性
    public static readonly DependencyProperty ContentProperty;
    public static readonly DependencyProperty ContentTemplateProperty;
    public static readonly DependencyProperty ContentTemplateSelectorProperty;
    public static readonly DependencyProperty ContentStringFormatProperty;

    // 核心属性
    public object Content { get; set; }
    public DataTemplate ContentTemplate { get; set; }
    public DataTemplateSelector ContentTemplateSelector { get; set; }
    public string ContentStringFormat { get; set; }

    // 核心方法
    protected virtual void OnContentChanged(object oldContent, object newContent);
}

核心能力与对 ScrollViewer 的贡献

  1. 单内容模型
    • 定义了 WPF 中所有单内容控件的标准模式
    • 只能包含一个子元素，多元素必须用面板包裹
  2. 内容模板化
    • 支持通过 ContentTemplate 自定义内容的呈现方式
    • 支持 ContentTemplateSelector 根据数据动态选择模板
  3. 在 ScrollViewer 中的体现
    • ScrollViewer 的 Content 属性直接继承自 ContentContr - 可以将任意 UIElement赋值给ScrollViewer.Contentent
    • ScrollViewer 的内容可以通过 ContentTemplate 进行数据绑定和模板化

🔑 关键原理：ScrollViewer 本身没有内容，它只是一个滚动容器。所有显示的内容都来自 ContentControl.Content 属性，ScrollViewer 只负责将内容的一部分显示在视口中。

基类能力汇总表

基类核心能力为 ScrollViewer 提供的关键功能
DispatcherObject线程模型确保所有滚动操作在 UI 线程执行
DependencyObject依赖属性系统支持 16 个滚动相关依赖属性和数据绑定
Visual底层渲染内容渲染、坐标转换、视觉树管理
UIElement输入处理鼠标滚轮、键盘、触摸等滚动输入
FrameworkElement布局系统计算内容大小、视口大小和滚动范围
Control通用控件基础外观属性、控件模板、自动化支持
ContentControl单内容模型提供 Content 属性，承载滚动内容

ScrollViewer 常见问题排查速查表

下表汇总了工业开发中最高频的 ScrollViewer 故障现象，并将每个问题回溯到本文七层基类或 ScrollContentPresenter 的具体机制，便于从原理层面快速定位。

问题现象可能原因（对应基类机制）排查步骤解决方案
内容完全不动，视口空白或只显示空白区域自定义模板缺少 PART_ScrollContentPresenter，或名称拼写错误；Control.OnApplyTemplate() 找不到模板部件（第六层 Control 模板系统）；ContentControl.Content 未赋值（第七层 ContentControl 单内容模型）检查模板 XAML 中是否存在 x:Name="PART_ScrollContentPresenter"；运行期通过 VisualTreeHelper 确认该部件是否生成；检查 ScrollViewer.Content 是否有值补全并精确命名 PART_ScrollContentPresenter；将 Content 绑定到 ScrollViewer.Content；模板应用后重新确认内容转发逻辑
滚动条不显示或该显示时不出现VerticalScrollBarVisibility/HorizontalScrollBarVisibility 设置不当；自定义模板缺少 PART_VerticalScrollBar/PART_HorizontalScrollBar；Visibility="{TemplateBinding ComputedVerticalScrollBarVisibility}" 未绑定或绑定失败（涉及第二层 DependencyObject 依赖属性绑定）检查 VerticalScrollBarVisibility 是否为 Visible 或 Auto；确认模板中存在两个滚动条部件；确认 ComputedVerticalScrollBarVisibility、ComputedHorizontalScrollBarVisibility 绑定有效显式设置滚动条可见性为 Auto 或 Visible；在模板中补全水平与垂直滚动条部件，并正确绑定 Visibility
滚动卡顿、掉帧或滚动时 CPU 占用高CanContentScroll=true 但内容面板未正确实现 IScrollInfo，导致逻辑滚动反复测量；内容未使用虚拟化，大量元素同时渲染；RenderTransform 触发额外渲染（第三层 Visual 渲染机制与 ScrollContentPresenter 偏移机制）检查 CanContentScroll 取值；确认内容是否位于 VirtualizingStackPanel；使用性能分析器观察 MeasureOverride、ArrangeOverride 调用频率改为 CanContentScroll=false 或使用虚减少 ScrollChanged 中的耗时操作 中的重活；避免在滚动过程中修改影响布局的属性
滚动位置跳变、回弹或偶尔回到顶部直接修改 ScrollContentPresenter.RenderTransform 或 ScrollBar.Value 绕过了 ScrollViewer 滚动逻辑；后台线程通过 DispatcherObject.VerifyAccess() 失败后异常；在布局尚未完成时设置偏移量（第五层 FrameworkElement 布局时序）搜索代码中是否有直接写 RenderTransform 或 TranslateTransform；检查是否在非 UI 线程更新滚动属性；确认设置偏移量发生在 Loaded/SizeChanged 之后统一改用 ScrollToVerticalOffset()、ScrollToHorizontalOffset()；通过 Dispatcher.Invoke() 切回 UI 线程；在 Loaded 或 SizeChanged 后执行初始滚动
鼠标滚轮、键盘方向键滚动无效或方向相反UIElement.MouseWheel 事件被子元素处理掉，未路由到 ScrollViewer；CanVerticallyScroll/CanHorizontallyScroll 被置为 false；ScrollContentPresenter 未正确承接输入（第四层 UIElement 输入事件机制）确认鼠标焦点所在元素；检查 CanVerticallyScroll、CanHorizontallyScroll 值；用 Snoop 观察事件路由；确认模板中 ScrollContentPresenter 是否覆盖视口设置正确的滚动开关；为内容容器设置 Focusable=false 或处理 PreviewMouseWheel 转发；避免嵌套 ScrollViewer 截断输入
滚动范围不正确，滑块过长或过满ScrollContentPresenter 上报的 ExtentWidth/Height、ViewportWidth/Height 计算错误；FrameworkElement.MeasureOverride/ArrangeOverride 未正确测量子内容（第五层 FrameworkElement 布局系统）；CanHorizontallyScroll/CanVerticallyScroll 约束不当打印 ScrollableWidth/Height、ExtentWidth/Height、ViewportWidth/Height；检查内容元素是否被限制为无限尺寸或自动尺寸；确认 CanContentScroll 与实际内容面板是否匹配给内容设置明确的 Width/Height 或对齐约束；调整 CanHorizontallyScroll、CanVerticallyScroll；重写 MeasureOverride 时正确返回包含子项的总尺寸
程序偶发崩溃或滚动操作后 UI 无响应在后台线程直接操作 ScrollViewer 属性或方法，违反 DispatcherObject 线程模型（第一层 DispatcherObject）；依赖属性在非 UI 线程读写导致内部状态损坏检查后台任务、PLC/相机回调、异步回调中是否直接操作控件；开启调试时观察跨线程访问异常所有滚动操作通过 Dispatcher.Invoke() 或 Dispatcher.BeginInvoke() 排队到 UI 线程；后台线程仅计算数值，不触碰控件实例
–

官方设计思想总结

WPF 的控件设计完美体现了单一职责原则和分层设计思想：

  1. 每一层只做一件事：从线程模型到渲染，从输入到布局，每个基类专注于解决一个特定领域的问题
  2. 能力逐步累加：上层类继承下层类的所有能力，并添加自己的特定功能
  3. 高度可扩展：通过依赖属性、模板和虚方法，提供了丰富的扩展点
  4. 一致性：所有 WPF 控件都遵循相同的设计模式，学习一个控件就可以举一反三

对于 ScrollViewer 来说，它的核心职责只有一个：根据用户输入和内容大小，计算并应用滚动偏移量。所有其他能力（渲染、布局、输入、数据绑定）全部由这种设计使得 ScrollViewer 极其轻量、运行高效且定制性强高度可定制，能够满足从简单文本滚动到工业级工艺流程图浏览的各种------

工业开发关键业开发关键

  1. 理解底层才能解决问题：很多 ScrollViewer 的常见问题（如不滚动、卡顿、滚动范围不正确）都源于对基类能力的误解。
  2. 遵循官方设计模式：不要试图绕过基类提供的机制（如直接修改 RenderTransform 而不是通过 ScrollToVerticalOffset）。
  3. 利用基类的扩展点：通过重写基类的虚方法（如 MeasureOverride、OnContentChanged）可以实现高度定制的滚动行为。
  4. 注意线程安全：所有操作必须在 UI 这是工业系统稳定性的基础。。性模板和性能

ScrollContentPresenter：ScrollViewer 真正的滚动核心

在前面七层基类体系中提到，ScrollViewer 本身并不渲染、搬运内容，真正完成“把内容显示在视口里并产生偏移”的是 ScrollContentPresenter。它也是自定义 ControlTemplate 中必须出现的 PART_ScrollContentPresenter ### 官方类定义harp:

public sealed class ScrollContentPresenter : ContentPresenter, IScrollInfo
{
    // 核心依赖属性
    public static readonly DependencyProperty CanContentScrollProperty;
    public static readonly DependencyProperty CanHorizontallyScrollProperty;
    public static readonly DependencyProperty CanVerticallyScrollProperty;

    // 核心属性
    public bool CanContentScroll { get; set; }
    public bool CanHorizontallyScroll { get; set; }
    public bool CanVerticallyScroll { get; set; }

    // IScrollInfo 核心实现
    public double ExtentWidth { get; }
    public double ExtentHeight { get; }
    public double ViewportWidth { get; }
    public double ViewportHeight { get; }
    public double HorizontalOffset { get; }
    public double VerticalOffset { get; }
    public double ScrollableWidth { get; }
    public double ScrollableHeight { get; }

    public void LineUp();
    public void LineDown();
    public void LineLeft();
    public void LineRight();
    public void PageUp();
    public void PageDown();
    public void PageLeft();
    public void PageRight();
    public void MouseWheelUp();
    public void MouseWheelDown();
    public void MouseWheelLeft();
    public void MouseWheelRight();
    public void SetHorizontalOffset(double offset);
    public void SetVerticalOffset(double offset);

    // 内容偏移相关实现
    protected override Size MeasureOverride(Size constraint);
    protected override Size ArrangeOverride(Size arrangeSize);
    protected override void OnRender(DrawingContext drawingContext);
}

核心成员：三个滚动能力开关

ScrollContentPresenter 的三个属性决定了它是否参与对应方向的滚动计算：

  1. **`CanContentScrol控制是否启用“按项滚动 / 基于逻辑单元的滚动”。的滚动”。

    • 当内容由 StackPanel、VirtualizingStackPanel 等 IScrollInfo 面板托管时，滚动单位是“项”或“像素”，会影响偏移量计算方式。
    • false 时按物理像素滚动，true 时由内容自身的 IScrollInfo 决定滚动单元。

  2. CanHorizontallyScroll

    • 允许或禁止水平方向的滚动能力。
    • 为 false 时，ScrollContentPresenter 会把水平方向测量约束留为无穷大，使内容不产生水平可滚动范围。

  3. CanVerticallyScroll

    • 与 CanHorizontallyScroll 对称，控制垂直滚动能力。
    • 它与 ScrollViewer.VerticalScrollBarVisibility 共同决定是否计算垂直偏移量。

这三个属性不是独立的装饰属性，而是直接参与 MeasureOverride、ArrangeOverride 以及 IScrollInfo 的测量过程：测量阶段根据它们决定约束空间，排列阶段再依据最终偏移量布置内容。

如何通过 RenderTransform 实现内容偏移

ScrollContentPresenter 并不在每次滚动时重新测量、重排整棵内容树，而是先完成内容测量和排列，再把滚动偏移量转换为视觉位移：

  • 在 ArrangeOverride 或内部偏移计算中，得到纵向/横向偏移量 xOffset、yOffset。
  • 通过设置自身的 RenderTransform 或子树变换，将已排列好的内容整体向相反方向平移。
  • 视觉上表现为“内容向上移动”，实际上内容自身布局只是渲染位置平移。harp:
// 概念示意：ScrollContentPresenter 内容偏移并非官方调用代码，
// 而是表达 RenderTransform 与 Offset 之间的协作关系。
var offsetTransform = new TranslateTransform(
    -HorizontalOffset,
    -VerticalOffset);

scrollContentPresenter.RenderTransform = offsetTransform;

🔑 关键原理：WPF 的滚动不是“移动子元素坐标”，而是“在已布局内容上应用平移变换”。这样滚动过程只触发渲染更新，不需要反复执行昂贵的 Measure/Arrange 布局流程。

当 CanContentScroll=true 且内容面板实现了 IScrollInfo 时，偏移量会转换为“项索引”等逻辑滚动参数，由面板决定跳过哪些子项、渲染哪些子项；当 CanContentScroll=false 时，则直接使用像素级偏移量。

与 ScrollViewer 的协作机制

ScrollContentPresenter 和 ScrollViewer 通过 IScrollInfo 与模板部件协议协同工作：

  1. 模板部件绑定

    • ScrollViewer.OnApplyTemplate() 会查找 PART_ScrollContentPresenter。
    • 找到后，把 ScrollViewer.Content、ContentTemplate 等内容属性转发给 ScrollContentPresenter。
    • 找不到该部件时，ScrollViewer 不会抛出异常，但内容不会显示，滚动能力静默失效。

  2. 滚动范围由 Presenter 上报

    • ScrollContentPresenter 完成测量后，计算 ExtentWidth/Height、ViewportWidth/Height。
    • ScrollViewer 基于这些值得到 ScrollableWidth/Height，再交给 PART_HorizontalScrollBar、PART_VerticalScrollBar 显示范围。

  3. 滚动条与 Presenter 双向反馈

    • 用户拖动滚动条时，ScrollBar.Value 通过模板绑定更新 ScrollViewer.VerticalOffset/HorizontalOffset。
    • ScrollViewer 再调用 ScrollContentPresenter.SetVerticalOffset/SetHorizontalOffset，由后者应用平移变换和命中测试更新。
    • Presenter 自身滚动时，也会回写偏移量，让滚动条滑块位置同步。

  4. 输入事件入口

    • 鼠标滚轮、键盘方向键、触摸平移等事件由 ScrollViewer 接收。
    • 处理后会转换为 LineUp/Down、PageUp/Down、MouseWheelUp/Down 等 IScrollInfo 调用，最终落到 ScrollContentPresenter 上执行。

⚠️ 工业开发注意：自定义模板时，不仅要写 PART_ScrollContentPresenter 这个名字，还要正确绑定 CanContentScroll、CanHorizontallyScroll、CanVerticallyScroll；否则可能出现“名字写对了但始终不显示滚动条/内容不可滚动”的隐蔽问题。默认模板通常绑定 ScrollViewer 的对应属性，确保滚动行为可配置。

优化

实战：自定义 ScrollViewer 模板

下面给出一个可直接落地的 ScrollViewer 自定义 ControlTemplate。它显式声明了三个必需模板部件，并保留了滚动条与内容区域的联动关系。即使只是微调外观，也建议先保证三部件齐全，再逐步修改样式。

<ControlTemplate x:Key="CustomScrollViewerTemplate" TargetType="ScrollViewer">
    <Grid Background="{TemplateBinding Background}">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*" />
            <ColumnDefinition Width="Auto" />
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition Height="*" />
            <RowDefinition Height="Auto" />
        </Grid.RowDefinitions>

        <!--
            PART_ScrollContentPresenter：
            作用：真正承载并显示 ScrollViewer.Content 的区域，
                 滚动本质上是这个部件在通过偏移量移动内容。
            常见错误：
            1. 名字必须精确拼写为 PART_ScrollContentPresenter；
            2. 缺少它时 ScrollViewer 不会显示任何内容；
            3. CanContentScroll 不绑定会破坏“按项滚动”等逻辑。
        -->
        <ScrollContentPresenter
            x:Name="PART_ScrollContentPresenter"
            Grid.Row="0"
            Grid.Column="0"
            CanContentScroll="{TemplateBinding CanContentScroll}"
            CanHorizontallyScroll="False"
            CanVerticallyScroll="False"
            Content="{TemplateBinding Content}"
            ContentTemplate="{TemplateBinding ContentTemplate}"
            Margin="{TemplateBinding Padding}" />

        <!--
            PART_VerticalScrollBar：
            作用：垂直滚动条，负责把竖直方向的滚动量回传给 ScrollViewer，
                 同时实时反映当前视口在内容中的位置。
            常见错误：
            1. 缺少该部件会导致鼠标滚轮虽然可能仍会滚动，
               但用户完全看不到垂直滚动条；
            2. Orientation 必须为 Vertical；
            3. 没有绑定 ScrollViewer.VerticalScrollBarVisibility
               会丢失“自动隐藏”等行为。
        -->
        <ScrollBar
            x:Name="PART_VerticalScrollBar"
            Grid.Row="0"
            Grid.Column="1"
            Orientation="Vertical"
            ViewportSize="0"
            Minimum="0"
            Maximum="{TemplateBinding ScrollableHeight}"
            Value="{TemplateBinding VerticalOffset, Mode=TwoWay}"
            Visibility="{TemplateBinding ComputedVerticalScrollBarVisibility}" />

        <!--
            PART_HorizontalScrollBar：
            作用：水平滚动条，与垂直滚动条协同，负责水平方向的滚动与位置显示。
            常见错误：
            1. 行列放错会导致滚动条与内容区域重叠或溢出；
            2. Orientation 必须为 Horizontal；
            3. 忘记绑定时，横向拖动不会更新 ScrollViewer.HorizontalOffset。
        -->
        <ScrollBar
            x:Name="PART_HorizontalScrollBar"
            Grid.Row="1"
            Grid.Column="0"
            Orientation="Horizontal"
            ViewportSize="0"
            Minimum="0"
            Maximum="{TemplateBinding ScrollableWidth}"
            Value="{TemplateBinding HorizontalOffset, Mode=TwoWay}"
            Visibility="{TemplateBinding ComputedHorizontalScrollBarVisibility}" />
    </Grid>
</ControlTemplate>

使用方式：

<ScrollViewer
    Template="{StaticResource CustomScrollViewerTemplate}"
    VerticalScrollBarVisibility="Auto"
    HorizontalScrollBarVisibility="Auto">
    <!-- 这里放任意可滚动内容 -->
</ScrollViewer>

需要特别注意的是：PART 名称必须与上面的写法完全一致，且区分大小写。ScrollViewer 的 OnApplyTemplate() 内部通过固定字符串查找 PART_ScrollContentPresenter、PART_VerticalScrollBar 和 PART_HorizontalScrollBar，任何一个名字写错都会导致对应滚动能力失效，而且 WPF 不会抛出异常，只表现为“看起来没反应”，排查起来非常耗时。

方案。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/qq_39302144/article/details/168642312

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数：0
关注数：0
粉丝：0
文章：0
关注标签：0
加入于：--