syncfusion-wpf-gridsplitter

实现 Syncfusion WPF GridSplitter

本技能将指导你实现 Syncfusion® WPF GridSplitter（SfGridSplitter）控件。该容器控件可通过可移动的分隔条水平或垂直划分可用空间，从而动态调整可视元素的大小。

适用场景

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

• 创建可调整大小的布局，在面板之间添加可移动的分隔条
• 在 WPF 应用程序中实现拆分面板（水平或垂直）
• 为网格区域添加折叠/展开功能
• 支持用户通过交互动态调整网格行或列的大小
• 配置分隔条的拖动行为和预览效果
• 使用模板和样式自定义分隔条外观
• 通过增量控制支持键盘调整大小
• 创建包含多个独立可调整区域的多窗格布局

本技能涵盖从基本设置到高级自定义的完整 GridSplitter 实现。

组件概述

SfGridSplitter 是一种布局控件，可通过交互式分隔条划分 Grid 中的可用空间。主要功能：

• 动态调整大小： 可移动的分隔条可按需重新分配网格行或列的空间
• 支持方向： 根据网格中的位置进行水平或垂直拆分
• 折叠/展开： 内置按钮，可交互地隐藏/显示面板
• 预览模式： 应用调整前可选预览调整大小的操作
• 可自定义模板： 全面控制拖柄、折叠按钮和预览效果的外观
• 键盘支持： 使用键盘调整大小，并可配置增量值
• 支持合并单元格： 可与合并的网格行和列配合使用

典型用例：

• 带可调整区域的主从视图
• 带可折叠侧边面板的代码编辑器
• 带可调整树形视图/网格拆分的资源管理器
• 带可调整窗格的多文档界面

文档与导航指南

入门

📄 阅读： references/getting-started.md

了解添加和配置 SfGridSplitter 的基础知识：

• 程序集部署和 NuGet 包安装
• 在 XAML 中导入命名空间并添加控件
• 在 C# 中以编程方式添加控件
• 在行/列布局中进行基本的 GridSplitter 设置
• 初始配置和对齐要求

使用此参考的时机： 首次设置 GridSplitter、添加所需程序集或创建基本拆分布局时。

调整大小和布局操作

📄 阅读： references/resize-and-layout.md

掌握网格调整大小功能和布局配置：

• 使用水平分隔条调整网格行的大小
• 使用垂直分隔条调整网格列的大小
• ResizeBehavior 属性（PreviousAndNext、PreviousAndCurrent 等）
• DragIncrement 和 KeyboardIncrement，实现像素级精确调整
• 使用 MoveSplitter() 方法以编程方式调整大小
• 使用合并的列和行
• 方向处理和对齐策略

使用此参考的时机： 配置调整大小行为、实现编程式调整大小、处理合并单元格，或微调拖动/键盘增量时。

折叠和展开功能

📄 阅读： references/collapse-expand-features.md

实现交互式折叠/展开功能：

• EnableCollapseButton 属性，用于显示/隐藏按钮
• 折叠和展开网格行与列
• 自定义折叠按钮模板（Up、Down、Left、Right）
• 用于水平分隔条的 UpButtonTemplate 和 DownButtonTemplate
• 用于垂直分隔条的 LeftButtonTemplate 和 RightButtonTemplate
• 面板显示/隐藏的用户交互模式

使用此参考的时机： 添加折叠/展开按钮、自定义按钮外观，或实现面板隐藏/显示功能时。

自定义与样式

📄 阅读： references/customization-styling.md

自定义视觉外观和行为：

• 用于设置分隔条颜色的 Background 属性
• 用于设置水平分隔条拖拽柄的 HorizontalGripperTemplate
• 用于设置垂直分隔条拖拽柄的 VerticalGripperTemplate
• 用于设置延迟调整大小预览的 PreviewStyle
• 用于启用预览模式的 ShowsPreview 属性
• 使用模板自定义拖动预览 UI
• 高级样式场景与主题集成

在以下情况下使用此参考： 自定义分隔条外观、创建自定义拖拽柄设计、实现预览样式或匹配应用主题。

快速入门

对于水平分隔条：创建包含 RowDefinitions (*, Auto, ) 的 Grid，在中间行放置 SfGridSplitter，并设置 Height="5" 和 ResizeBehavior="PreviousAndNext"。对于垂直分隔条：创建 ColumnDefinitions (, Auto, *)，并改为设置 Width。完整示例请参阅 入门指南。

常见模式

主要模式包括折叠按钮（EnableCollapseButton）、预览模式（ShowsPreview）、以编程方式调整大小（MoveSplitter）、多分隔条布局，以及使用 DragIncrement/KeyboardIncrement 限制调整大小。完整实现示例和使用场景指南请参阅参考文件。

关键属性

属性	类型	用途	使用场景
ResizeBehavior	ResizeBehavior	控制调整大小时受影响的行/列	根据需要调整大小的面板，设置为 PreviousAndNext（最常见）、PreviousAndCurrent 或 CurrentAndNext
EnableCollapseButton	bool	显示/隐藏折叠/展开按钮	用户需要临时隐藏面板时启用
ShowsPreview	bool	应用调整大小前显示预览	用于复杂布局，或用户需要视觉确认时
DragIncrement	double	基于鼠标调整大小的像素间隔	设置为指定间隔调整大小（默认值：1）
KeyboardIncrement	double	基于键盘调整大小的像素间隔	设置方向键调整大小的粒度（默认值：20）
HorizontalAlignment	HorizontalAlignment	水平分隔条的对齐方式	调整行大小时使用 Stretch
VerticalAlignment	VerticalAlignment	垂直分隔条的对齐方式	调整列大小时使用 Stretch
Background	Brush	分隔条颜色	自定义以匹配应用主题
Height	double	水平分隔条的高度	为水平分隔条设置明确的高度（例如，5-10 像素）
Width	double	垂直分隔条的宽度	为垂直分隔条设置明确的宽度（例如，5-10 像素）

常见用例

• 代码编辑器： 使用 EnableCollapseButton 和自定义按钮模板实现 IDE 风格布局及可折叠侧边面板。
• 数据浏览器： 使用 ShowsPreview 和 ResizeBehavior 构建可调整查询/结果视图的数据库工具。
• 主从视图： 使用基本调整大小功能和 DragIncrement 实现可变尺寸的列表-详情界面。
• 多文档界面： 使用多个分隔条和合并单元格支持创建多个可调整大小的文档窗格。
• 仪表板小组件： 使用 DragIncrement 和预设配置创建可调整小组件容器的分析仪表板。

故障排除快速参考

分隔条无法调整面板大小？

• 确认 Grid.Row/Grid.Column 的位置
• 检查 HorizontalAlignment/VerticalAlignment 设置
• 确保 ResizeBehavior 设置正确

未显示折叠按钮？

• 设置 EnableCollapseButton="True"
• 确认分隔条尺寸足以容纳按钮

未显示预览？

• 设置 ShowsPreview="True"
• 如果使用自定义样式，请检查 PreviewStyle

调整大小时卡顿？

• 调整 DragIncrement 以实现更平滑的移动
• 对于复杂布局，可考虑启用 ShowsPreview

请参阅上方的详细参考文件，了解全面的实现指南和高级场景。