syncfusion-wpf-gridsplitter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF GridSplitter

实现Syncfusion WPF GridSplitter控件

This skill guides you in implementing the Syncfusion® WPF GridSplitter (SfGridSplitter) control, a container control that splits available space horizontally or vertically with a movable splitter to dynamically resize visual elements.

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

When to Use This Skill

适用场景

Use this skill when you need to:

Create resizable layouts with movable splitters between panels
Implement split panels in WPF applications (horizontal or vertical)
Add collapse/expand functionality for grid sections
Enable dynamic resizing of grid rows or columns with user interaction
Configure drag behavior for splitter movement and preview
Customize splitter appearance with templates and styles
Support keyboard-based resizing with increment controls
Create multi-pane layouts with independent resizable sections

This skill covers complete GridSplitter implementation from basic setup to advanced customization.

当你需要以下功能时，可以使用本技能：

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

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

Component Overview

组件概述

SfGridSplitter is a layout control that divides available space in a Grid with an interactive splitter bar. Key capabilities:

Dynamic Resizing: Movable splitter redistributes space between grid rows/columns on demand
Orientation Support: Horizontal or vertical splitting based on grid placement
Collapse/Expand: Built-in buttons to hide/show panels interactively
Preview Mode: Optional preview of resize operation before applying
Customizable Templates: Full control over gripper, collapse buttons, and preview appearance
Keyboard Support: Resize using keyboard with configurable increment values
Merged Cell Support: Works with merged grid rows and columns

Typical Use Cases:

Master-detail views with resizable sections
Code editor with collapsible side panels
Data explorer with adjustable tree/grid split
Multi-document interfaces with resizable panes

SfGridSplitter是一个布局控件，可通过交互式拆分栏划分Grid中的可用空间。核心功能包括：

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

典型应用场景：

包含可调整区域的主从视图
带有可折叠侧边栏的代码编辑器
可调整树状视图/网格拆分的数据资源管理器
带有可调整窗格的多文档界面

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Learn the fundamentals of adding and configuring SfGridSplitter:

Assembly deployment and NuGet package installation
Adding control in XAML with namespace imports
Adding control programmatically in C#
Basic grid splitter setup in row/column layouts
Initial configuration and alignment requirements

Use this reference when: Setting up GridSplitter for the first time, adding required assemblies, or creating basic split layouts.

📄 阅读： references/getting-started.md

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

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

适用场景： 首次设置GridSplitter、添加所需程序集或创建基础拆分布局时。

Resize and Layout Operations

调整大小与布局操作

📄 Read: references/resize-and-layout.md

Master grid resizing capabilities and layout configuration:

Resizing grid rows with horizontal splitters
Resizing grid columns with vertical splitters
ResizeBehavior property (PreviousAndNext, PreviousAndCurrent, etc.)
DragIncrement and KeyboardIncrement for pixel-precise resizing
MoveSplitter() method for programmatic resizing
Working with merged columns and rows
Orientation handling and alignment strategies

Use this reference when: Configuring resize behavior, implementing programmatic resizing, working with merged cells, or fine-tuning drag/keyboard increments.

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

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

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

适用场景： 配置调整大小行为、实现程序化调整、处理合并单元格或微调拖拽/键盘增量时。

Collapse and Expand Features

折叠与展开功能

📄 Read: references/collapse-expand-features.md

Implement interactive collapse/expand functionality:

EnableCollapseButton property to show/hide buttons
Collapsing and expanding grid rows and columns
Custom collapse button templates (Up, Down, Left, Right)
UpButtonTemplate and DownButtonTemplate for horizontal splitters
LeftButtonTemplate and RightButtonTemplate for vertical splitters
User interaction patterns for panel visibility

Use this reference when: Adding collapse/expand buttons, customizing button appearance, or implementing panel hide/show features.

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

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

使用EnableCollapseButton属性显示/隐藏按钮
折叠和展开网格行与列
自定义折叠按钮模板（上、下、左、右）
水平拆分器的UpButtonTemplate和DownButtonTemplate
垂直拆分器的LeftButtonTemplate和RightButtonTemplate
面板可见性的用户交互模式

适用场景： 添加折叠/展开按钮、自定义按钮外观或实现面板隐藏/显示功能时。

Customization and Styling

自定义与样式设置

📄 Read: references/customization-styling.md

Customize visual appearance and behavior:

Background property for splitter color
HorizontalGripperTemplate for horizontal splitter gripper
VerticalGripperTemplate for vertical splitter gripper
PreviewStyle for deferred resizing preview
ShowsPreview property for preview mode
Custom drag preview UI with templates
Advanced styling scenarios and theme integration

Use this reference when: Customizing splitter appearance, creating custom gripper designs, implementing preview styles, or matching application themes.

📄 阅读： references/customization-styling.md

自定义视觉外观和行为：

使用Background属性设置拆分器颜色
水平拆分器抓手的HorizontalGripperTemplate
垂直拆分器抓手的VerticalGripperTemplate
延迟调整大小预览的PreviewStyle
使用ShowsPreview属性启用预览模式
通过模板自定义拖拽预览UI
高级样式场景和主题集成

适用场景： 自定义拆分器外观、创建自定义抓手设计、实现预览样式或匹配应用主题时。

Quick Start Example

快速入门示例

Basic Horizontal Splitter (Resizes Rows)

基础水平拆分器（调整行大小）

xml

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="*" />
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        
        <!-- Top Panel -->
        <Border Grid.Row="0" Background="LightBlue">
            <TextBlock Text="Top Panel" 
                       VerticalAlignment="Center" 
                       HorizontalAlignment="Center"/>
        </Border>
        
        <!-- Grid Splitter -->
        <syncfusion:SfGridSplitter Grid.Row="1"
                                   HorizontalAlignment="Stretch"
                                   Height="5"
                                   Background="DarkGray"
                                   ResizeBehavior="PreviousAndNext"/>
        
        <!-- Bottom Panel -->
        <Border Grid.Row="2" Background="LightGreen">
            <TextBlock Text="Bottom Panel" 
                       VerticalAlignment="Center" 
                       HorizontalAlignment="Center"/>
        </Border>
    </Grid>
</Window>

xml

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="*" />
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        
        <!-- 顶部面板 -->
        <Border Grid.Row="0" Background="LightBlue">
            <TextBlock Text="Top Panel" 
                       VerticalAlignment="Center" 
                       HorizontalAlignment="Center"/>
        </Border>
        
        <!-- 网格拆分器 -->
        <syncfusion:SfGridSplitter Grid.Row="1"
                                   HorizontalAlignment="Stretch"
                                   Height="5"
                                   Background="DarkGray"
                                   ResizeBehavior="PreviousAndNext"/>
        
        <!-- 底部面板 -->
        <Border Grid.Row="2" Background="LightGreen">
            <TextBlock Text="Bottom Panel" 
                       VerticalAlignment="Center" 
                       HorizontalAlignment="Center"/>
        </Border>
    </Grid>
</Window>

Basic Vertical Splitter (Resizes Columns)

基础垂直拆分器（调整列大小）

xml

<Grid>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*" />
        <ColumnDefinition Width="Auto" />
        <ColumnDefinition Width="*" />
    </Grid.ColumnDefinitions>
    
    <!-- Left Panel -->
    <Border Grid.Column="0" Background="LightCoral">
        <TextBlock Text="Left Panel" 
                   VerticalAlignment="Center" 
                   HorizontalAlignment="Center"/>
    </Border>
    
    <!-- Grid Splitter -->
    <syncfusion:SfGridSplitter Grid.Column="1"
                               VerticalAlignment="Stretch"
                               Width="5"
                               Background="DarkGray"
                               ResizeBehavior="PreviousAndNext"/>
    
    <!-- Right Panel -->
    <Border Grid.Column="2" Background="LightYellow">
        <TextBlock Text="Right Panel" 
                   VerticalAlignment="Center" 
                   HorizontalAlignment="Center"/>
    </Border>
</Grid>

xml

<Grid>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*" />
        <ColumnDefinition Width="Auto" />
        <ColumnDefinition Width="*" />
    </Grid.ColumnDefinitions>
    
    <!-- 左侧面板 -->
    <Border Grid.Column="0" Background="LightCoral">
        <TextBlock Text="Left Panel" 
                   VerticalAlignment="Center" 
                   HorizontalAlignment="Center"/>
    </Border>
    
    <!-- 网格拆分器 -->
    <syncfusion:SfGridSplitter Grid.Column="1"
                               VerticalAlignment="Stretch"
                               Width="5"
                               Background="DarkGray"
                               ResizeBehavior="PreviousAndNext"/>
    
    <!-- 右侧面板 -->
    <Border Grid.Column="2" Background="LightYellow">
        <TextBlock Text="Right Panel" 
                   VerticalAlignment="Center" 
                   HorizontalAlignment="Center"/>
    </Border>
</Grid>

Common Patterns

常见模式

Pattern 1: Splitter with Collapse Buttons

模式1：带折叠按钮的拆分器

Enable interactive panel collapse/expand:

xml

<syncfusion:SfGridSplitter Grid.Row="1"
                           HorizontalAlignment="Stretch"
                           Height="8"
                           EnableCollapseButton="True"
                           ResizeBehavior="PreviousAndNext"/>

When to use: Users need to temporarily hide panels to maximize workspace.

启用交互式面板折叠/展开：

xml

<syncfusion:SfGridSplitter Grid.Row="1"
                           HorizontalAlignment="Stretch"
                           Height="8"
                           EnableCollapseButton="True"
                           ResizeBehavior="PreviousAndNext"/>

适用场景： 用户需要临时隐藏面板以最大化工作空间时。

Pattern 2: Preview Mode for Deferred Resizing

模式2：延迟调整大小的预览模式

Show preview before applying resize:

xml

<syncfusion:SfGridSplitter Grid.Row="1"
                           HorizontalAlignment="Stretch"
                           ShowsPreview="True"
                           ResizeBehavior="PreviousAndNext"/>

When to use: Heavy layouts where real-time resizing may cause performance issues, or users need visual feedback before committing to resize.

在应用调整前显示预览效果：

xml

<syncfusion:SfGridSplitter Grid.Row="1"
                           HorizontalAlignment="Stretch"
                           ShowsPreview="True"
                           ResizeBehavior="PreviousAndNext"/>

适用场景： 布局较复杂，实时调整可能影响性能，或用户需要在确认调整前查看视觉反馈时。

Pattern 3: Programmatic Resizing

模式3：程序化调整大小

Control splitter position via code:

csharp

// Move splitter by 50 pixels
gridSplitter.MoveSplitter(50);

// Move splitter by -30 pixels (opposite direction)
gridSplitter.MoveSplitter(-30);

When to use: Implementing preset layouts, restoring saved positions, or animating layout changes.

通过代码控制拆分器位置：

csharp

// 将拆分器移动50像素
gridSplitter.MoveSplitter(50);

// 将拆分器反向移动30像素
gridSplitter.MoveSplitter(-30);

适用场景： 实现预设布局、恢复保存的位置或为布局变化添加动画时。

Pattern 4: Multi-Splitter Layout

模式4：多拆分器布局

Create complex resizable layouts:

xml

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition />
        <RowDefinition Height="Auto" />
        <RowDefinition />
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition />
        <ColumnDefinition Width="Auto" />
        <ColumnDefinition />
    </Grid.ColumnDefinitions>
    
    <!-- Panels in different grid positions -->
    <Border Grid.Row="0" Grid.Column="0" Background="LightBlue"/>
    <Border Grid.Row="2" Grid.Column="0" Background="LightGreen"/>
    <Border Grid.Row="0" Grid.Column="2" Grid.RowSpan="3" Background="LightYellow"/>
    
    <!-- Horizontal Splitter -->
    <syncfusion:SfGridSplitter Grid.Row="1" Grid.Column="0"
                               HorizontalAlignment="Stretch"
                               ResizeBehavior="PreviousAndNext"/>
    
    <!-- Vertical Splitter -->
    <syncfusion:SfGridSplitter Grid.RowSpan="3" Grid.Column="1"
                               VerticalAlignment="Stretch"
                               ResizeBehavior="PreviousAndNext"/>
</Grid>

When to use: Complex layouts with multiple independent resizable regions.

创建复杂的可调整大小布局：

xml

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition />
        <RowDefinition Height="Auto" />
        <RowDefinition />
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition />
        <ColumnDefinition Width="Auto" />
        <ColumnDefinition />
    </Grid.ColumnDefinitions>
    
    <!-- 不同网格位置的面板 -->
    <Border Grid.Row="0" Grid.Column="0" Background="LightBlue"/>
    <Border Grid.Row="2" Grid.Column="0" Background="LightGreen"/>
    <Border Grid.Row="0" Grid.Column="2" Grid.RowSpan="3" Background="LightYellow"/>
    
    <!-- 水平拆分器 -->
    <syncfusion:SfGridSplitter Grid.Row="1" Grid.Column="0"
                               HorizontalAlignment="Stretch"
                               ResizeBehavior="PreviousAndNext"/>
    
    <!-- 垂直拆分器 -->
    <syncfusion:SfGridSplitter Grid.RowSpan="3" Grid.Column="1"
                               VerticalAlignment="Stretch"
                               ResizeBehavior="PreviousAndNext"/>
</Grid>

适用场景： 需要多个独立可调整区域的复杂布局时。

Pattern 5: Constrained Resizing with Increments

模式5：带增量限制的调整大小

Control resize granularity:

xml

<syncfusion:SfGridSplitter DragIncrement="10"
                           KeyboardIncrement="20"
                           HorizontalAlignment="Stretch"
                           ResizeBehavior="PreviousAndNext"/>

When to use: Layouts that need to snap to specific sizes (e.g., aligning with grid cells, maintaining aspect ratios).

控制调整大小的粒度：

xml

<syncfusion:SfGridSplitter DragIncrement="10"
                           KeyboardIncrement="20"
                           HorizontalAlignment="Stretch"
                           ResizeBehavior="PreviousAndNext"/>

适用场景： 布局需要对齐到特定尺寸时（例如，与网格单元格对齐、保持宽高比）。

Key Properties

核心属性

Property	Type	Purpose	When to Use
ResizeBehavior	ResizeBehavior	Controls which rows/columns are affected by resize	Set to PreviousAndNext (most common), PreviousAndCurrent, or CurrentAndNext based on which panels should resize
EnableCollapseButton	bool	Shows/hides collapse/expand buttons	Enable when users need to temporarily hide panels
ShowsPreview	bool	Shows resize preview before applying	Enable for heavy layouts or when users need visual confirmation
DragIncrement	double	Pixel interval for mouse-based resizing	Set to constrain resize to specific increments (default: 1)
KeyboardIncrement	double	Pixel interval for keyboard-based resizing	Set for arrow key resize granularity (default: 20)
HorizontalAlignment	HorizontalAlignment	Alignment for horizontal splitters	Use Stretch for row resizing
VerticalAlignment	VerticalAlignment	Alignment for vertical splitters	Use Stretch for column resizing
Background	Brush	Splitter bar color	Customize to match application theme
Height	double	Height of horizontal splitter bar	Set explicit height (e.g., 5-10 pixels) for horizontal splitters
Width	double	Width of vertical splitter bar	Set explicit width (e.g., 5-10 pixels) for vertical splitters

属性	类型	用途	适用场景
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像素）

Common Use Cases

常见应用场景

Use Case 1: Code Editor with Collapsible Side Panel

场景1：带可折叠侧边栏的代码编辑器

Scenario: IDE-style layout with file tree, editor, and properties panel.

Solution: Vertical splitters with collapse buttons for side panels, allowing users to maximize editor space.

Key Features: EnableCollapseButton, custom button templates, programmatic restore.

场景： IDE风格布局，包含文件树、编辑器和属性面板。

解决方案： 为侧边栏添加带折叠按钮的垂直拆分器，允许用户最大化编辑器空间。

核心功能： EnableCollapseButton、自定义按钮模板、程序化恢复。

Use Case 2: Data Explorer with Adjustable Views

场景2：可调整视图的数据资源管理器

Scenario: Database tool with query editor and result grid requiring adjustable space.

Solution: Horizontal splitter between query and results with preview mode.

Key Features: ShowsPreview, ResizeBehavior, saved position restoration.

场景： 数据库工具包含查询编辑器和结果网格，需要可调整的空间分配。

解决方案： 在查询区域和结果区域之间添加带预览模式的水平拆分器。

核心功能： ShowsPreview、ResizeBehavior、保存位置恢复。

Use Case 3: Master-Detail View

场景3：主从视图

Scenario: List of items with detail panel that needs variable sizing.

Solution: Vertical or horizontal splitter based on layout orientation.

Key Features: Basic resize, DragIncrement for smooth resizing, saved preferences.

场景： 包含项目列表和详情面板的布局，详情面板需要可变大小。

解决方案： 根据布局方向添加垂直或水平拆分器。

核心功能： 基础调整大小、DragIncrement实现平滑调整、保存偏好设置。

Use Case 4: Multi-Document Interface

场景4：多文档界面

Scenario: Application with multiple resizable document views.

Solution: Grid with multiple splitters creating adjustable panes.

Key Features: Multiple splitters, merged cell support, complex layouts.

场景： 应用包含多个可调整大小的文档视图。

解决方案： 使用包含多个拆分器的Grid创建可调整的窗格。

核心功能： 多拆分器、合并单元格支持、复杂布局。

Use Case 5: Dashboard with Resizable Widgets

场景5：带可调整大小部件的仪表板

Scenario: Analytics dashboard where users adjust widget sizes.

Solution: Grid layout with splitters between widget containers.

Key Features: DragIncrement for alignment, programmatic layouts, preset configurations.

场景： 分析仪表板，用户可调整部件大小。

解决方案： 在部件容器之间添加拆分器的Grid布局。

核心功能： DragIncrement实现对齐、程序化布局、预设配置。

Implementation Checklist

实施检查清单

Troubleshooting Quick Reference

故障排除快速参考

Splitter not resizing panels?

Verify Grid.Row/Grid.Column placement
Check HorizontalAlignment/VerticalAlignment settings
Ensure ResizeBehavior is set appropriately

Collapse buttons not showing?

Set EnableCollapseButton="True"
Verify splitter has sufficient size for buttons

Preview not displaying?

Set ShowsPreview="True"
Check PreviewStyle if using custom styles

Jerky resizing?

Adjust DragIncrement for smoother movement
Consider ShowsPreview for heavy layouts

Navigate to the detailed reference files above for comprehensive implementation guidance and advanced scenarios.

拆分器无法调整面板大小？

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

折叠按钮未显示？

设置EnableCollapseButton="True"
验证拆分器有足够的空间显示按钮

预览未显示？

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

调整大小卡顿？

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

如需全面的实施指导和高级场景说明，请参考上述详细的参考文档。