syncfusion-winforms-tab-splitter-container

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion WinForms TabSplitterContainer

实现Syncfusion WinForms TabSplitterContainer

The TabSplitterContainer control provides a Visual Studio 2008-style tabbed split view of tab groups, enabling users to easily render different views of the same document. This control is ideal for creating code editors with preview panes, design/code split views, or any multi-view document interface.
TabSplitterContainer控件提供Visual Studio 2008风格的标签组分割视图,让用户可以轻松渲染同一文档的不同视图。该控件非常适合创建带预览窗格的代码编辑器、设计/代码分割视图,或者任何多视图文档界面。

When to Use This Skill

什么时候使用这个技能

Use this skill when the user needs to:
  • Split View Editors: Code editor with XAML/Design split view (like Visual Studio)
  • Document Multi-View: Display same document in different modes (edit vs preview)
  • Tabbed Splitter Layouts: Multiple tab groups that can be swapped or repositioned
  • Collapsible Panes: Split view with collapsible secondary pane
  • VS-Style Interfaces: Visual Studio 2008-style multi-pane editors
  • Adjustable Split Position: User can drag splitter bar to resize panes
  • Multi-Pane Applications: Applications requiring primary and secondary tab groups
  • Horizontal/Vertical Splits: Support both horizontal and vertical layout orientations
当用户需要实现以下需求时可使用本技能:
  • 分割视图编辑器: 带XAML/设计分割视图的代码编辑器(类似Visual Studio)
  • 文档多视图: 以不同模式展示同一文档(编辑模式 vs 预览模式)
  • 标签化分割布局: 支持交换或调整位置的多标签组
  • 可折叠窗格: 带可折叠次级窗格的分割视图
  • VS风格界面: Visual Studio 2008风格的多窗格编辑器
  • 可调整分割位置: 用户可拖动分割条调整窗格大小
  • 多窗格应用: 需要主标签组和次级标签组的应用
  • 水平/垂直分割: 同时支持水平和垂直布局方向

Component Overview

组件概述

TabSplitterContainer (
Syncfusion.Windows.Forms.Tools.TabSplitterContainer
) is a versatile split-view layout control supporting:
  • Primary and Secondary Pages: Two collections of tabbed pages (PrimaryPages, SecondaryPages)
  • Swap Functionality: Built-in swap button to exchange primary/secondary tab groups
  • Collapse/Expand: Built-in collapse button to hide/show secondary pane
  • Dual Orientation: Horizontal (side-by-side) or Vertical (top-bottom) layouts
  • Adjustable Splitter: Draggable splitter bar with SplitterPosition property
  • Office2016 Themes: Colorful, White, DarkGray, Black theme support
  • TabSplitterPage: Customizable pages with images, tooltips, border styles
  • Splitter Components: Swap button, collapse/expand buttons, orientation toggles
  • Design-Time Support: Visual designer integration with smart tags
Key Namespace:
Syncfusion.Windows.Forms.Tools
Assembly:
Syncfusion.Tools.Windows.dll
(and dependencies)

TabSplitterContainer (
Syncfusion.Windows.Forms.Tools.TabSplitterContainer
) 是一个功能丰富的分割视图布局控件,支持以下特性:
  • 主页面和次页面: 两套标签页集合(PrimaryPages、SecondaryPages)
  • 交换功能: 内置交换按钮,可互换主/次标签组位置
  • 折叠/展开: 内置折叠按钮,可隐藏/展示次级窗格
  • 双布局方向: 水平(并排)或垂直(上下堆叠)布局
  • 可调整分割条: 可拖动的分割条,支持通过SplitterPosition属性控制位置
  • Office2016主题: 支持多彩、白色、深灰、黑色主题
  • TabSplitterPage: 可自定义页面,支持图片、提示框、边框样式配置
  • 分割组件: 交换按钮、折叠/展开按钮、方向切换控件
  • 设计时支持: 与可视化设计器集成,支持智能标签
核心命名空间:
Syncfusion.Windows.Forms.Tools
程序集:
Syncfusion.Tools.Windows.dll
(及相关依赖)

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When to read: User needs to install, configure, or create their first TabSplitterContainer.
Topics covered:
  • Assembly deployment and NuGet package installation
  • Adding TabSplitterContainer via designer (toolbox + smart tags)
  • Adding TabSplitterContainer via code
  • Creating and adding TabSplitterPage instances
  • PrimaryPages and SecondaryPages collections
  • Basic tab page setup and configuration
  • Adding controls to tab pages
📄 阅读: references/getting-started.md
适用场景: 用户需要安装、配置或者创建第一个TabSplitterContainer时。
涵盖内容:
  • 程序集部署与NuGet包安装
  • 通过设计器添加TabSplitterContainer(工具箱+智能标签)
  • 通过代码添加TabSplitterContainer
  • 创建并添加TabSplitterPage实例
  • PrimaryPages和SecondaryPages集合说明
  • 基础标签页设置与配置
  • 向标签页添加控件

Splitter Components and Pages

分割组件与页面配置

📄 Read: references/splitter-components.md
When to read: User wants to understand swap button, collapse/expand functionality, or customize TabSplitterPage properties.
Topics covered:
  • Splitter component overview (swap, collapse/expand buttons)
  • Primary page collection (PrimaryPages property)
  • Secondary page collection (SecondaryPages property)
  • Swap button functionality (Swapped property)
  • Collapse/Expand functionality (Collapsed property)
  • TabSplitterPage customization (Text, Image, Tooltip)
  • Page properties (BorderStyle, BackgroundImage, Visible)
  • Runtime page manipulation and visibility
📄 阅读: references/splitter-components.md
适用场景: 用户想要了解交换按钮、折叠/展开功能,或者自定义TabSplitterPage属性时。
涵盖内容:
  • 分割组件概述(交换、折叠/展开按钮)
  • 主页面集合(PrimaryPages属性)
  • 次页面集合(SecondaryPages属性)
  • 交换按钮功能(Swapped属性)
  • 折叠/展开功能(Collapsed属性)
  • TabSplitterPage自定义(文本、图片、提示框)
  • 页面属性(边框样式、背景图、可见性)
  • 运行时页面操作与可见性控制

Orientation and Splitter Position

布局方向与分割条位置

📄 Read: references/orientation-and-position.md
When to read: User needs horizontal/vertical layout or wants to adjust splitter position.
Topics covered:
  • Horizontal orientation (default, side-by-side layout)
  • Vertical orientation (top-bottom layout)
  • Orientation property configuration
  • SplitterPosition property for programmatic control
  • Design-time splitter adjustment
  • Runtime splitter position changes
  • Layout considerations for different orientations
📄 阅读: references/orientation-and-position.md
适用场景: 用户需要水平/垂直布局,或者想要调整分割条位置时。
涵盖内容:
  • 水平布局(默认,并排布局)
  • 垂直布局(上下堆叠布局)
  • Orientation属性配置
  • 通过SplitterPosition属性进行程序化控制
  • 设计时分割条调整
  • 运行时分割条位置变更
  • 不同布局方向的适配注意事项

Styling and Appearance

样式与外观配置

📄 Read: references/styling-and-appearance.md
When to read: User wants Office2016 themes or custom splitter appearance.
Topics covered:
  • Visual styles overview (Default, Office2016 variants)
  • Office2016Colorful, Office2016White, Office2016DarkGray, Office2016Black
  • Style property usage
  • Customizable splitter back color (SplitterBackColor)
  • Theme consistency with application
  • Visual appearance customization
📄 阅读: references/styling-and-appearance.md
适用场景: 用户想要使用Office2016主题或者自定义分割条外观时。
涵盖内容:
  • 视觉样式概述(默认、Office2016系列)
  • Office2016多彩、Office2016白色、Office2016深灰、Office2016黑色主题
  • Style属性使用方法
  • 可自定义分割条背景色(SplitterBackColor)
  • 与应用主题保持一致性
  • 视觉外观自定义

Advanced Features

高级特性

📄 Read: references/advanced-features.md
When to read: User needs events, localization, or runtime page management.
Topics covered:
  • TabSplitterContainer events
  • Localization support and CultureInfo
  • Runtime manipulation (swap, collapse, expand programmatically)
  • Page visibility control
  • Dynamic page management (add/remove at runtime)
  • Best practices and troubleshooting
  • Performance considerations

📄 阅读: references/advanced-features.md
适用场景: 用户需要事件处理、本地化或者运行时页面管理能力时。
涵盖内容:
  • TabSplitterContainer相关事件
  • 本地化支持与CultureInfo
  • 运行时操作(程序化交换、折叠、展开)
  • 页面可见性控制
  • 动态页面管理(运行时添加/移除)
  • 最佳实践与问题排查
  • 性能注意事项

Quick Start Example

快速入门示例

Basic XAML/Design Split View

基础XAML/设计分割视图

csharp
using Syncfusion.Windows.Forms.Tools;

// Create TabSplitterContainer
TabSplitterContainer splitterContainer = new TabSplitterContainer();
splitterContainer.Dock = DockStyle.Fill;

// Create primary page (XAML view)
TabSplitterPage xamlPage = new TabSplitterPage();
xamlPage.Text = "XAML";
xamlPage.BackColor = Color.White;

// Create secondary page (Design view)
TabSplitterPage designPage = new TabSplitterPage();
designPage.Text = "Design";
designPage.BackColor = Color.White;

// Add pages to collections
splitterContainer.PrimaryPages.Add(xamlPage);
splitterContainer.SecondaryPages.Add(designPage);

// Add to form
this.Controls.Add(splitterContainer);
csharp
using Syncfusion.Windows.Forms.Tools;

// 创建TabSplitterContainer
TabSplitterContainer splitterContainer = new TabSplitterContainer();
splitterContainer.Dock = DockStyle.Fill;

// 创建主页面(XAML视图)
TabSplitterPage xamlPage = new TabSplitterPage();
xamlPage.Text = "XAML";
xamlPage.BackColor = Color.White;

// 创建次页面(设计视图)
TabSplitterPage designPage = new TabSplitterPage();
designPage.Text = "Design";
designPage.BackColor = Color.White;

// 向集合添加页面
splitterContainer.PrimaryPages.Add(xamlPage);
splitterContainer.SecondaryPages.Add(designPage);

// 添加到窗体
this.Controls.Add(splitterContainer);

Vertical Split with Office2016 Theme

带Office2016主题的垂直分割布局

csharp
// Configure vertical orientation
splitterContainer.Orientation = Orientation.Vertical;

// Apply Office2016 Colorful theme
splitterContainer.Style = TabSplitterContainerStyle.Office2016Colorful;

// Set initial splitter position (50% split)
splitterContainer.SplitterPosition = splitterContainer.Height / 2;

csharp
// 配置垂直布局方向
splitterContainer.Orientation = Orientation.Vertical;

// 应用Office2016多彩主题
splitterContainer.Style = TabSplitterContainerStyle.Office2016Colorful;

// 设置初始分割位置(50%分割)
splitterContainer.SplitterPosition = splitterContainer.Height / 2;

Common Patterns

常见使用模式

Code Editor with Preview Pane

带预览窗格的代码编辑器

csharp
// Primary: Code editor
TabSplitterPage codePage = new TabSplitterPage();
codePage.Text = "Code";
TextBox codeEditor = new TextBox { Dock = DockStyle.Fill, Multiline = true };
codePage.Controls.Add(codeEditor);

// Secondary: Preview pane
TabSplitterPage previewPage = new TabSplitterPage();
previewPage.Text = "Preview";
WebBrowser previewBrowser = new WebBrowser { Dock = DockStyle.Fill };
previewPage.Controls.Add(previewBrowser);

// Add to splitter
tabSplitterContainer1.PrimaryPages.Add(codePage);
tabSplitterContainer1.SecondaryPages.Add(previewPage);
When to use: Markdown editors, HTML editors, any code with live preview.
csharp
// 主页面:代码编辑器
TabSplitterPage codePage = new TabSplitterPage();
codePage.Text = "Code";
TextBox codeEditor = new TextBox { Dock = DockStyle.Fill, Multiline = true };
codePage.Controls.Add(codeEditor);

// 次页面:预览窗格
TabSplitterPage previewPage = new TabSplitterPage();
previewPage.Text = "Preview";
WebBrowser previewBrowser = new WebBrowser { Dock = DockStyle.Fill };
previewPage.Controls.Add(previewBrowser);

// 添加到分割控件
tabSplitterContainer1.PrimaryPages.Add(codePage);
tabSplitterContainer1.SecondaryPages.Add(previewPage);
适用场景: Markdown编辑器、HTML编辑器、任何需要实时预览的代码场景。

Multi-Tab Groups (VS-Style)

多标签组(VS风格)

csharp
// Primary group: Multiple document tabs
TabSplitterPage doc1 = new TabSplitterPage { Text = "Document1.cs" };
TabSplitterPage doc2 = new TabSplitterPage { Text = "Document2.cs" };
tabSplitterContainer1.PrimaryPages.AddRange(new[] { doc1, doc2 });

// Secondary group: Properties/Output tabs
TabSplitterPage propPage = new TabSplitterPage { Text = "Properties" };
TabSplitterPage outputPage = new TabSplitterPage { Text = "Output" };
tabSplitterContainer1.SecondaryPages.AddRange(new[] { propPage, outputPage });
When to use: IDE-style interfaces, multi-document editors.
csharp
// 主标签组:多个文档标签
TabSplitterPage doc1 = new TabSplitterPage { Text = "Document1.cs" };
TabSplitterPage doc2 = new TabSplitterPage { Text = "Document2.cs" };
tabSplitterContainer1.PrimaryPages.AddRange(new[] { doc1, doc2 });

// 次标签组:属性/输出标签
TabSplitterPage propPage = new TabSplitterPage { Text = "Properties" };
TabSplitterPage outputPage = new TabSplitterPage { Text = "Output" };
tabSplitterContainer1.SecondaryPages.AddRange(new[] { propPage, outputPage });
适用场景: IDE风格界面、多文档编辑器。

Collapsible Secondary Pane

可折叠次级窗格

csharp
// Start with secondary pane collapsed
tabSplitterContainer1.Collapsed = true;

// Toggle collapse on button click
btnToggle.Click += (s, e) => {
    tabSplitterContainer1.Collapsed = !tabSplitterContainer1.Collapsed;
};
When to use: Optional preview panes, collapsible sidebars.
csharp
// 初始状态下次级窗格折叠
tabSplitterContainer1.Collapsed = true;

// 点击按钮切换折叠状态
btnToggle.Click += (s, e) => {
    tabSplitterContainer1.Collapsed = !tabSplitterContainer1.Collapsed;
};
适用场景: 可选预览窗格、可折叠侧边栏。

Swap Tab Groups Programmatically

程序化交换标签组

csharp
// Swap primary and secondary tab groups
tabSplitterContainer1.Swapped = true;

// Toggle swap on button click
btnSwap.Click += (s, e) => {
    tabSplitterContainer1.Swapped = !tabSplitterContainer1.Swapped;
};
When to use: User preference for tab group positioning.

csharp
// 交换主、次标签组
tabSplitterContainer1.Swapped = true;

// 点击按钮切换交换状态
btnSwap.Click += (s, e) => {
    tabSplitterContainer1.Swapped = !tabSplitterContainer1.Swapped;
};
适用场景: 支持用户自定义标签组位置偏好。

Key Properties

核心属性

Core Properties

基础属性

PropertyTypeDescriptionWhen to Use
PrimaryPages
TabSplitterPageCollection
Collection of primary tab pagesAdd/manage primary pane tabs
SecondaryPages
TabSplitterPageCollection
Collection of secondary tab pagesAdd/manage secondary pane tabs
Orientation
Orientation
Horizontal or Vertical splitChange layout direction
SplitterPosition
int
Position of splitter bar (pixels)Set initial or runtime split position
Collapsed
bool
Collapse/expand secondary paneShow/hide secondary pane
Swapped
bool
Swap primary/secondary tab groupsExchange tab group positions
属性名类型描述适用场景
PrimaryPages
TabSplitterPageCollection
主标签页集合添加/管理主窗格标签
SecondaryPages
TabSplitterPageCollection
次标签页集合添加/管理次窗格标签
Orientation
Orientation
水平或垂直分割更改布局方向
SplitterPosition
int
分割条位置(像素)设置初始或运行时分割位置
Collapsed
bool
折叠/展开次级窗格展示/隐藏次级窗格
Swapped
bool
交换主/次标签组互换标签组位置

Styling Properties

样式属性

PropertyTypeDescriptionWhen to Use
Style
TabSplitterContainerStyle
Visual style (Default, Office2016*)Apply Office2016 themes
SplitterBackColor
Color
Splitter bar background colorCustom splitter appearance
属性名类型描述适用场景
Style
TabSplitterContainerStyle
视觉样式(默认、Office2016系列)应用Office2016主题
SplitterBackColor
Color
分割条背景色自定义分割条外观

TabSplitterPage Properties

TabSplitterPage属性

PropertyTypeDescriptionWhen to Use
Text
string
Tab page text/captionSet tab label
Image
Image
Tab page iconAdd icon to tab
ToolTip
string
Tab tooltip textProvide hover information
BorderStyle
BorderStyle
Page border styleAdd/remove page borders
BackgroundImage
Image
Page background imageCustom page background
Visible
bool
Page visibilityShow/hide specific pages

属性名类型描述适用场景
Text
string
标签页文本/标题设置标签显示文本
Image
Image
标签页图标为标签添加图标
ToolTip
string
标签提示文本提供悬停说明信息
BorderStyle
BorderStyle
页面边框样式添加/移除页面边框
BackgroundImage
Image
页面背景图自定义页面背景
Visible
bool
页面可见性展示/隐藏指定页面

Common Use Cases

常见使用场景

1. Code Editor with Split View

1. 带分割视图的代码编辑器

Scenario: Markdown editor with edit/preview split view.
  • Create primary page with TextBox for editing
  • Create secondary page with WebBrowser for preview
  • Use Orientation.Horizontal for side-by-side
  • Enable Collapsed to allow hiding preview
  • Read: getting-started.md, orientation-and-position.md
场景: 带编辑/预览分割视图的Markdown编辑器。
  • 创建带TextBox的主页面用于编辑
  • 创建带WebBrowser的次页面用于预览
  • 使用Orientation.Horizontal实现并排布局
  • 启用折叠功能支持隐藏预览窗格
  • 相关文档:getting-started.mdorientation-and-position.md

2. Visual Studio-Style Document Editor

2. Visual Studio风格文档编辑器

Scenario: Multi-document IDE with tab groups.
  • Add multiple TabSplitterPages to PrimaryPages (document tabs)
  • Add tool/output pages to SecondaryPages
  • Use Office2016 theme for professional appearance
  • Enable swap button for user preference
  • Read: splitter-components.md, styling-and-appearance.md
场景: 带标签组的多文档IDE。
  • 向PrimaryPages添加多个TabSplitterPage(文档标签)
  • 向SecondaryPages添加工具/输出页面
  • 使用Office2016主题打造专业外观
  • 启用交换按钮支持用户自定义布局偏好
  • 相关文档:splitter-components.mdstyling-and-appearance.md

3. Document Viewer with Thumbnails

3. 带缩略图的文档查看器

Scenario: PDF viewer with thumbnail sidebar.
  • Primary page: Main document viewer
  • Secondary page: Thumbnail panel
  • Use Orientation.Vertical for top-bottom layout
  • Set SplitterPosition to allocate more space to main view
  • Allow collapse for full-screen document view
  • Read: orientation-and-position.md, splitter-components.md
场景: 带缩略图侧边栏的PDF查看器。
  • 主页面:主文档查看器
  • 次页面:缩略图面板
  • 使用Orientation.Vertical实现上下堆叠布局
  • 设置SplitterPosition为主视图分配更多空间
  • 支持折叠功能实现全屏文档查看
  • 相关文档:orientation-and-position.mdsplitter-components.md

4. Data Entry Form with Help Pane

4. 带帮助窗格的数据录入表单

Scenario: Form with contextual help in secondary pane.
  • Primary page: Data entry form
  • Secondary page: Help/documentation panel
  • Start with Collapsed = true (hide by default)
  • Add toggle button to show/hide help
  • Read: splitter-components.md
场景: 次级窗格提供上下文帮助的表单。
  • 主页面:数据录入表单
  • 次页面:帮助/文档面板
  • 初始状态设置Collapsed = true(默认隐藏)
  • 添加切换按钮控制帮助面板展示/隐藏
  • 相关文档:splitter-components.md

5. Multi-Language Editor

5. 多语言编辑器

Scenario: Localized application with language-specific views.
  • Multiple TabSplitterPages for different languages
  • Swap functionality for language switching
  • Use localization support for tab labels
  • Read: advanced-features.md
场景: 带多语言视图的本地化应用。
  • 为不同语言创建多个TabSplitterPage
  • 使用交换功能实现语言切换
  • 使用本地化支持配置标签文本
  • 相关文档:advanced-features.md

6. Report Designer

6. 报表设计器

Scenario: Report design with code/preview split.
  • Primary: Report definition editor (XML/JSON)
  • Secondary: Report preview rendering
  • Vertical orientation for stacked layout
  • Adjustable splitter for resizing panes
  • Read: orientation-and-position.md

场景: 带代码/预览分割视图的报表设计工具。
  • 主页面:报表定义编辑器(XML/JSON)
  • 次页面:报表预览渲染
  • 垂直布局实现堆叠展示
  • 可调整分割条修改窗格大小
  • 相关文档:orientation-and-position.md

Events

事件

Common events for TabSplitterContainer:
  • Component-specific events for state changes
  • See advanced-features.md for detailed event documentation

TabSplitterContainer的常用事件:
  • 组件专属的状态变更事件
  • 详见advanced-features.md获取完整的事件说明文档

Best Practices

最佳实践

  1. Theme Consistency: Match TabSplitterContainer Style to application theme
  2. Splitter Position: Set initial SplitterPosition based on content importance
  3. Page Management: Use PrimaryPages for main content, SecondaryPages for supporting views
  4. Collapse State: Provide UI controls for users to toggle Collapsed state
  5. Orientation Choice: Use Horizontal for side-by-side, Vertical for stacked layouts
  6. Swap Functionality: Enable Swapped property for user preference customization
  7. Page Naming: Use descriptive Text property for clear tab labels
  8. Performance: Lazy-load page content to improve initial load time

  1. 主题一致性: 保持TabSplitterContainer的样式与应用主题匹配
  2. 分割条位置: 根据内容重要性设置初始分割条位置
  3. 页面管理: 主页面集合存放核心内容,次页面集合存放辅助视图
  4. 折叠状态控制: 提供UI控件让用户可以切换折叠状态
  5. 布局方向选择: 并排布局使用水平方向,堆叠布局使用垂直方向
  6. 交换功能: 启用Swapped属性支持用户自定义布局偏好
  7. 页面命名: 使用清晰的Text属性值作为标签文本,提升辨识度
  8. 性能优化: 懒加载页面内容提升初始加载速度

Related Skills

相关技能

  • SplitContainerAdv: Alternative split container without tab support
  • DockingManager: Advanced docking and layout management
  • TabControlAdv: Standalone tabbed interface control

  • SplitContainerAdv: 无标签支持的替代分割容器
  • DockingManager: 高级停靠与布局管理组件
  • TabControlAdv: 独立的标签化界面控件

See Also

参考链接