syncfusion-winforms-scroll-frame

实现滚动框架 (SfScrollFrame)

SfScrollFrame 控件为 Windows Forms 应用程序提供可应用主题、可自定义的滚动条。它可将现代化的样式滚动条附加到任何派生自 Microsoft 的 ScrollableControl 或 Container 的控件上，用完全可自定义的替代方案取代默认系统滚动条，并支持主题、上下文菜单和丰富的外观选项。

何时使用此技能

在以下情况下使用此技能：

• 为滚动控件附加自定义滚动条，例如 Panel、ListView、ListBox 或其他可滚动控件
• 为滚动条应用主题（Office2016、Office2019、HighContrast）
• 自定义滚动条外观（颜色、尺寸、状态）
• 处理滚动条事件和上下文菜单
• 为滚动条上下文菜单实现本地化
• 启用 UI 自动化以测试滚动条（Coded UI、QTP）
• 以编程方式控制滚动并自定义滚动速度
• 用现代替代方案取代默认 Windows 滚动条

组件概览

主要功能

• 通用附加： 适用于任何派生自 ScrollableControl 的控件（Panel、ListView、ListBox 等）
• 主题支持： 内置 Office2016、Office2019 和 HighContrast 主题
• 全面自定义： 自定义所有滚动条元素的颜色、尺寸和状态
• 上下文菜单： 支持本地化的可自定义右键菜单
• 以编程方式滚动： 通过代码控制滚动位置和速度
• UI 自动化： 支持 Coded UI 测试和 QTP/UFT 测试
• 叠加显示： 滚动条显示在默认位置上方，不会改变布局

架构

SfScrollFrame
├── Control Property (attach to target)
├── HorizontalScrollBar
│   ├── Style (ScrollBarStyleInfo)
│   ├── Value, SmallChange
│   ├── EnableMaximumArrow, EnableMinimumArrow, EnableThumb
│   └── ContextMenuShowing event
└── VerticalScrollBar
    ├── Style (ScrollBarStyleInfo)
    ├── Value, SmallChange
    ├── EnableMaximumArrow, EnableMinimumArrow, EnableThumb
    └── ContextMenuShowing event

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和所需引用
• 通过设计器附加 SfScrollFrame
• 通过代码附加 SfScrollFrame
• 使用 Value 属性以编程方式滚动
• 配置 SmallChange 以设置滚动速度
• 基本实现示例

外观与样式

📄 阅读： references/appearance-styling.md

• 使用 ScrollBarStyleInfo 自定义滚动条外观
• 箭头按钮样式（颜色、悬停、按下和禁用状态）
• 滑块样式（颜色、宽度、边框和状态）
• 禁用箭头按钮和滑块
• 内置主题支持（Office2016、Office2019、HighContrast）
• 加载并应用主题程序集
• ThemeName 属性的用法

上下文菜单自定义

📄 阅读： references/context-menu.md

• 默认上下文菜单功能
• 处理 ContextMenuShowing 事件
• 禁用默认上下文菜单
• 显示自定义上下文菜单
• 向默认上下文菜单添加项目
• ContextMenuShowingEventArgs 属性

本地化支持

📄 阅读： references/localization.md

• 本地化滚动条上下文菜单字符串
• 向应用程序添加资源文件（.resx）
• 创建特定区域性的资源
• 设置 CurrentUICulture
• 编辑默认区域性资源
• 从不同程序集/命名空间进行本地化

UI 自动化与测试

📄 阅读： references/ui-automation.md

• Microsoft UI 自动化概览
• Coded UI Test (CUIT) 支持（级别 1 和 2）
• CodedUITestBuilder 的用法
• 录制操作并添加断言
• 运行自动化测试
• QTP/UFT 测试支持

限制与约束

📄 阅读： references/limitations.md

• 适用的控件（ScrollableControl 派生控件）
• 不兼容的控件（自定义滚动条实现）
• LargeChange 属性限制
• 最佳实践与解决方法

快速入门

基本实现

using Syncfusion.WinForms.Controls;

// Create SfScrollFrame instance
SfScrollFrame sfScrollFrame1 = new SfScrollFrame();

// Create a ListView (or any ScrollableControl)
ListView listView1 = new ListView();
listView1.View = View.Details;
listView1.Columns.Add("Column 1", 150);
listView1.Columns.Add("Column 2", 150);

// Add items
for (int i = 0; i < 100; i++)
{
    listView1.Items.Add(new ListViewItem(new[] { $"Item {i}", $"Value {i}" }));
}

// Attach SfScrollFrame to ListView
sfScrollFrame1.Control = listView1;

// Add ListView to form
this.Controls.Add(listView1);

应用主题

using Syncfusion.WinForms.Controls;
using Syncfusion.WinForms.Themes;

// In Program.cs
static void Main()
{
    // Load theme assembly
    SfSkinManager.LoadAssembly(typeof(Office2016Theme).Assembly);
    
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
    Application.Run(new MainForm());
}

// In form
public MainForm()
{
    InitializeComponent();
    
    // Create and attach SfScrollFrame
    SfScrollFrame sfScrollFrame1 = new SfScrollFrame();
    sfScrollFrame1.Control = listView1;
    
    // Apply theme
    sfScrollFrame1.ThemeName = "Office2016Colorful";
}

常见模式

模式 1：为 Panel 附加自定义样式

// Create Panel with content
Panel panel1 = new Panel();
panel1.AutoScroll = true;
panel1.Size = new Size(400, 300);

// Add controls to panel
for (int i = 0; i < 50; i++)
{
    Button btn = new Button();
    btn.Text = $"Button {i}";
    btn.Location = new Point(10, i * 30);
    panel1.Controls.Add(btn);
}

// Attach SfScrollFrame
SfScrollFrame sfScrollFrame1 = new SfScrollFrame();
sfScrollFrame1.Control = panel1;

// Customize vertical scrollbar appearance
sfScrollFrame1.VerticalScrollBar.Style.ScrollBarBackColor = Color.LightGray;
sfScrollFrame1.VerticalScrollBar.Style.ThumbColor = Color.Gray;
sfScrollFrame1.VerticalScrollBar.Style.ThumbHoverColor = Color.Black;
sfScrollFrame1.VerticalScrollBar.Style.ThumbPressedColor = Color.Blue;
sfScrollFrame1.VerticalScrollBar.Style.ThumbWidth = 10;

this.Controls.Add(panel1);

模式 2：以编程方式滚动并控制速度

// Attach SfScrollFrame
sfScrollFrame1.Control = listView1;

// Configure scroll speed
sfScrollFrame1.HorizontalScrollBar.SmallChange = 10;
sfScrollFrame1.VerticalScrollBar.SmallChange = 20;

// Scroll to specific position
Button scrollButton = new Button();
scrollButton.Text = "Scroll to Middle";
scrollButton.Click += (s, e) =>
{
    // Get maximum scroll value
    int maxValue = sfScrollFrame1.VerticalScrollBar.Maximum;
    
    // Scroll to middle
    sfScrollFrame1.VerticalScrollBar.Value = maxValue / 2;
};

模式 3：自定义上下文菜单

sfScrollFrame1.Control = listView1;

// Handle ContextMenuShowing event for vertical scrollbar
sfScrollFrame1.VerticalScrollBar.ContextMenuShowing += (sender, e) =>
{
    // Add custom menu item to default menu
    ToolStripMenuItem customItem = new ToolStripMenuItem("Show Current Position");

    customItem.Click += (s, ev) =>
    {
        int position = sfScrollFrame1.VerticalScrollBar.Value;
        MessageBox.Show($"Current scroll position: {position}");
    });

    e.ContextMenu.Items.Add(customItem);
};

模式 4：使用自定义颜色的禁用箭头按钮

sfScrollFrame1.Control = panel1;

// Disable minimum arrows (top/left)
sfScrollFrame1.VerticalScrollBar.EnableMinimumArrow = false;
sfScrollFrame1.HorizontalScrollBar.EnableMinimumArrow = false;

// Set disabled button colors
sfScrollFrame1.VerticalScrollBar.Style.ArrowButtonDisabledBackColor = Color.Silver;
sfScrollFrame1.VerticalScrollBar.Style.ArrowButtonDisabledForeColor = Color.Gray;

sfScrollFrame1.HorizontalScrollBar.Style.ArrowButtonDisabledBackColor = Color.Silver;
sfScrollFrame1.HorizontalScrollBar.Style.ArrowButtonDisabledForeColor = Color.Gray;

关键属性

SfScrollFrame 属性

属性	类型	描述
Control	Control	滚动条所附加到的控件（必须是 ScrollableControl）
HorizontalScrollBar	ScrollBarBase	访问水平滚动条配置
VerticalScrollBar	ScrollBarBase	访问垂直滚动条配置
ThemeName	string	要应用的主题（Office2016Colorful、Office2016White 等）

ScrollBar 属性

属性	类型	描述
Value	int	当前滚动位置
SmallChange	int	点击箭头按钮时的滚动量
EnableMaximumArrow	bool	启用/禁用底部/右侧箭头按钮
EnableMinimumArrow	bool	启用/禁用顶部/左侧箭头按钮
EnableThumb	bool	启用/禁用滚动条滑块
Style	ScrollBarStyleInfo	外观自定义设置

ScrollBarStyleInfo 属性

属性	类型	描述
ScrollBarBackColor	Color	滚动条轨道的背景颜色
ThumbColor	Color	滑块的常规状态颜色
ThumbHoverColor	Color	鼠标悬停时滑块的颜色
ThumbPressedColor	Color	点击时滑块的颜色
ThumbWidth	int	滑块的宽度/高度（最大值：滚动条尺寸）
ThumbBorderColor	Color	滑块的边框颜色
ArrowButtonBackColor	Color	箭头按钮的常规状态背景色
ArrowButtonForeColor	Color	箭头图标的常规状态颜色
ArrowButtonHoverBackColor	Color	悬停时箭头按钮的背景色
ArrowButtonPressedBackColor	Color	点击时箭头按钮的背景色
ArrowButtonDisabledBackColor	Color	禁用时箭头按钮的背景色
ArrowButtonBorderColor	Color	箭头按钮的边框颜色

常见用例

用例 1：带自定义滚动条的增强型 ListView

场景： 将 ListView 的默认滚动条替换为应用主题并自定义的滚动条。

实现：

// Setup ListView
ListView listView = new ListView { View = View.Details, Size = new Size(400, 300) };
listView.Columns.Add("Name", 150);
listView.Columns.Add("Value", 150);

// Attach themed scrollbar
SfScrollFrame scrollFrame = new SfScrollFrame();
scrollFrame.Control = listView;
scrollFrame.ThemeName = "Office2019Colorful";

// Customize thumb width
scrollFrame.VerticalScrollBar.Style.ThumbWidth = 8;
scrollFrame.HorizontalScrollBar.Style.ThumbWidth = 8;

用例 2：支持快速滚动的面板

场景： 包含许多控件并提高滚动速度的面板。

实现：

// Setup Panel
Panel panel = new Panel { AutoScroll = true, Size = new Size(500, 400) };

// Attach scrollbar with fast scrolling
SfScrollFrame scrollFrame = new SfScrollFrame();
scrollFrame.Control = panel;
scrollFrame.VerticalScrollBar.SmallChange = 30;   // Faster vertical scroll
scrollFrame.HorizontalScrollBar.SmallChange = 30; // Faster horizontal scroll

用例 3：本地化应用程序

场景： 带有本地化滚动条菜单的多语言应用程序。

实现：

// Set culture before InitializeComponent
System.Threading.Thread.CurrentThread.CurrentUICulture = 
    new System.Globalization.CultureInfo("de-DE");

InitializeComponent();

// SfScrollFrame automatically uses localized context menu strings
// if corresponding .resx files exist

用例 4：禁用滚动条交互

场景： 仅供显示的可滚动内容（无法拖动滑块）。

实现：

SfScrollFrame scrollFrame = new SfScrollFrame();
scrollFrame.Control = listView;

// Disable thumb dragging (scrolling only via arrows/wheel)
scrollFrame.VerticalScrollBar.EnableThumb = false;
scrollFrame.HorizontalScrollBar.EnableThumb = false;

// Set disabled thumb color
scrollFrame.VerticalScrollBar.Style.ThumbDisabledColor = Color.LightGray;
scrollFrame.HorizontalScrollBar.Style.ThumbDisabledColor = Color.LightGray;

故障排除

问题：滚动条未显示

解决方案：

• 确认目标控件派生自 ScrollableControl
• 检查内容是否超出控件尺寸（仅在需要时显示滚动条）
• 确保 Panel 控件的 AutoScroll 属性为 true

问题：主题未生效

解决方案：

• 在运行应用程序之前，于 Program.cs 中加载主题程序集
• 检查 ThemeName 的拼写和大小写
• 确认项目中已引用主题程序集

问题：上下文菜单未显示

解决方案：

• 直接右键单击滚动条轨道或滑块
• 确认 ContextMenuShowing 事件未取消菜单显示
• 检查控件是否处于焦点状态

问题：SmallChange 未按预期工作

解决方案：

• SmallChange 会影响箭头按钮点击，不会影响鼠标滚轮滚动
• 鼠标滚轮滚动由所附加的控件控制
• 使用较大的值（10-30）以获得明显的速度变化

最佳实践

1. 尽早附加： 在窗体构造函数中调用 InitializeComponent() 后设置 Control 属性
2. 只加载一次主题： 在 Program.cs 中加载主题程序集，而不是在每个窗体中加载
3. 样式保持一致： 在应用程序的所有 SfScrollFrame 实例中应用相同的主题
4. 调整 SmallChange： 测试不同的值（10-50），以找到最佳滚动速度
5. 处理事件： 订阅 ContextMenuShowing，以自定义菜单行为
6. 测试兼容性： 部署前验证 SfScrollFrame 是否能与目标控件正常配合使用
7. 设置本地化： 在开发早期添加资源文件，以支持多语言应用
8. 性能： 避免在运行时过度更改样式属性