syncfusion-winforms-tab-splitter-container

实现 Syncfusion WinForms TabSplitterContainer

TabSplitterContainer 控件提供 Visual Studio 2008 风格的选项卡式分屏视图，可显示多个选项卡组，让用户轻松查看同一文档的不同视图。该控件非常适合用于创建带预览窗格的代码编辑器、设计视图与代码视图分屏，或任何多视图文档界面。

何时使用此技能

在用户需要以下功能时使用此技能：

• 分屏编辑器： 带 XAML／设计视图分屏的代码编辑器（类似 Visual Studio）
• 文档多视图： 以不同模式显示同一文档（编辑与预览）
• 选项卡式分隔布局： 可互换或重新定位的多个选项卡组
• 可折叠窗格： 带可折叠次级窗格的分屏视图
• VS 风格界面： Visual Studio 2008 风格的多窗格编辑器
• 可调整分隔位置： 用户可拖动分隔栏来调整窗格大小
• 多窗格应用程序： 需要主选项卡组和次选项卡组的应用程序
• 水平／垂直分屏： 支持水平和垂直布局方向

组件概述

TabSplitterContainer（Syncfusion.Windows.Forms.Tools.TabSplitterContainer）是一种灵活的分屏布局控件，支持：

• 主页面和次级页面： 两组选项卡页面集合（PrimaryPages、SecondaryPages）
• 互换功能： 内置互换按钮，可交换主选项卡组和次选项卡组
• 折叠／展开： 内置折叠按钮，可隐藏／显示次级窗格
• 双向布局： 水平（并排）或垂直（上下）布局
• 可调整分隔条： 可拖动的分隔栏，带有 SplitterPosition 属性
• Office2016 主题： 支持 Colorful、White、DarkGray、Black 主题
• TabSplitterPage： 可自定义页面，支持图像、工具提示和边框样式
• 分隔栏组件： 互换按钮、折叠／展开按钮、方向切换按钮
• 设计时支持： 集成可视化设计器和智能标记

关键命名空间： Syncfusion.Windows.Forms.Tools

程序集： Syncfusion.Tools.Windows.dll（及其依赖项）

---

文档和导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 用户需要安装、配置或创建第一个 TabSplitterContainer。

涵盖主题：

• 程序集部署和 NuGet 包安装
• 通过设计器（工具箱和智能标记）添加 TabSplitterContainer
• 通过代码添加 TabSplitterContainer
• 创建并添加 TabSplitterPage 实例
• PrimaryPages 和 SecondaryPages 集合
• 基本选项卡页面的设置和配置
• 向选项卡页面添加控件

分隔栏组件和页面

📄 阅读： references/splitter-components.md

阅读时机： 用户想了解互换按钮、折叠／展开功能，或自定义 TabSplitterPage 属性。

涵盖主题：

• 分隔栏组件概述（互换、折叠／展开按钮）
• 主页面集合（PrimaryPages 属性）
• 次级页面集合（SecondaryPages 属性）
• 互换按钮功能（Swapped 属性）
• 折叠／展开功能（Collapsed 属性）
• TabSplitterPage 自定义（Text、Image、Tooltip）
• 页面属性（BorderStyle、BackgroundImage、Visible）
• 运行时页面操作和可见性

方向和分隔位置

📄 阅读： references/orientation-and-position.md

阅读时机： 用户需要水平／垂直布局，或想调整分隔位置。

涵盖主题：

• 水平方向（默认，并排布局）
• 垂直方向（上下布局）
• Orientation 属性配置
• 通过 SplitterPosition 属性进行编程控制
• 设计时调整分隔位置
• 运行时更改分隔位置
• 不同方向下的布局注意事项

样式与外观

📄 阅读： references/styling-and-appearance.md

阅读时机： 用户需要 Office2016 主题或自定义分隔条外观时。

涵盖主题：

• 视觉样式概览（Default、Office2016 变体）
• Office2016Colorful、Office2016White、Office2016DarkGray、Office2016Black
• Style 属性的用法
• 可自定义的分隔条背景色（SplitterBackColor）
• 与应用程序保持主题一致
• 自定义视觉外观

高级功能

📄 阅读： references/advanced-features.md

阅读时机： 用户需要事件、本地化或运行时页面管理时。

涵盖主题：

• TabSplitterContainer 事件
• 本地化支持和 CultureInfo
• 运行时操作（以编程方式交换、折叠、展开）
• 页面可见性控制
• 动态页面管理（运行时添加/移除）
• 最佳实践和故障排除
• 性能注意事项

---

快速入门示例

基本 XAML/设计视图

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);

使用 Office2016 主题的垂直拆分视图

// 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;

---

常见模式

带预览窗格的代码编辑器

// 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);

适用场景： Markdown 编辑器、HTML 编辑器，以及任何带实时预览的代码编辑器。

多标签组（VS 风格）

// 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 });

适用场景： IDE 风格界面、多文档编辑器。

可折叠的辅助窗格

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

// Toggle collapse on button click
btnToggle.Click += (s, e) => {
    tabSplitterContainer1.Collapsed = !tabSplitterContainer1.Collapsed;
};

适用场景： 可选预览窗格、可折叠侧边栏。

以编程方式交换标签组

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

// Toggle swap on button click
btnSwap.Click += (s, e) => {
    tabSplitterContainer1.Swapped = !tabSplitterContainer1.Swapped;
};

适用场景： 用户希望自定义标签组的位置。

---

关键属性

核心属性

属性	类型	描述	适用场景
PrimaryPages	TabSplitterPageCollection	主标签页集合	添加/管理主窗格标签页
SecondaryPages	TabSplitterPageCollection	辅助标签页集合	添加/管理辅助窗格标签页
Orientation	Orientation	水平或垂直拆分	更改布局方向
SplitterPosition	int	分隔条位置（像素）	设置初始或运行时的拆分位置
Collapsed	bool	折叠/展开辅助窗格	显示/隐藏辅助窗格
Swapped	bool	交换主/辅助标签组	交换标签组位置

样式属性

属性	类型	描述	适用场景
Style	TabSplitterContainerStyle	视觉样式（Default、Office2016*）	应用 Office2016 主题
SplitterBackColor	Color	分隔条背景色	自定义分隔条外观

TabSplitterPage 属性

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

---

常见用例

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

场景： Markdown 编辑器的编辑/预览拆分视图。

• 创建主页面，并在其中放置用于编辑的 TextBox
• 创建辅助页面，并在其中放置用于预览的 WebBrowser
• 使用 Orientation.Horizontal 实现并排布局
• 启用 Collapsed，以便隐藏预览
• 阅读：getting-started.md、orientation-and-position.md

2. Visual Studio 风格的文档编辑器

场景： 带有选项卡组的多文档 IDE。

• 将多个 TabSplitterPages 添加到 PrimaryPages（文档选项卡）
• 将工具/输出页面添加到 SecondaryPages
• 使用 Office2016 主题，呈现专业外观
• 启用交换按钮，满足用户偏好
• 阅读：splitter-components.md、styling-and-appearance.md

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

场景： 带有缩略图侧边栏的 PDF 查看器。

• 主页面：主文档查看器
• 次要页面：缩略图面板
• 使用 Orientation.Vertical 实现上下布局
• 设置 SplitterPosition，为主视图分配更多空间
• 允许折叠，以便全屏查看文档
• 阅读：orientation-and-position.md、splitter-components.md

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

场景： 在次要窗格中显示上下文相关帮助的表单。

• 主页面：数据录入表单
• 次要页面：帮助/文档面板
• 初始设置 Collapsed = true（默认隐藏）
• 添加切换按钮以显示/隐藏帮助
• 阅读：splitter-components.md

5. 多语言编辑器

场景： 带有特定语言视图的本地化应用程序。

• 使用多个 TabSplitterPages 显示不同语言
• 使用交换功能切换语言
• 使用本地化支持设置选项卡标签
• 阅读：advanced-features.md

6. 报告设计器

场景： 将代码与预览拆分显示的报告设计。

• 主页面：报告定义编辑器（XML/JSON）
• 次要页面：报告预览渲染
• 使用垂直方向实现堆叠布局
• 使用可调整的拆分器调整窗格大小
• 阅读：orientation-and-position.md

---

事件

TabSplitterContainer 的常见事件：

• 用于状态更改的组件专属事件
• 详细的事件文档请参阅 advanced-features.md

---

最佳实践

1. 主题一致性： 让 TabSplitterContainer Style 与应用程序主题保持一致
2. 拆分器位置： 根据内容的重要性设置初始 SplitterPosition
3. 页面管理： 使用 PrimaryPages 显示主要内容，使用 SecondaryPages 显示辅助视图
4. 折叠状态： 提供 UI 控件，供用户切换 Collapsed 状态
5. 方向选择： 并排布局使用 Horizontal，堆叠布局使用 Vertical
6. 交换功能： 启用 Swapped 属性，以便根据用户偏好进行自定义
7. 页面命名： 使用描述性的 Text 属性，设置清晰的选项卡标签
8. 性能： 延迟加载页面内容，缩短初始加载时间

---

另请参阅

• Syncfusion TabSplitterContainer 文档
• TabSplitterContainer API 参考
• TabSplitterPage API 参考