syncfusion-winforms-tabcontrol

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Tab Controls (TabControlAdv)

实现标签控件 (TabControlAdv)

The TabControlAdv is an advanced Windows Forms tab control that enables organizing visual content in a compact, tabbed interface. It extends the standard TabControl with extensive appearance customization, navigation features, editing capabilities, and styling options.

TabControlAdv是一款高级Windows Forms标签控件，可用于在紧凑的标签式界面中组织可视化内容。它在标准TabControl的基础上扩展了丰富的外观自定义、导航功能、编辑能力和样式选项。

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Implement tabbed interfaces in Windows Forms applications
Add TabControlAdv with multiple TabPageAdv items
Customize tab appearance, colors, fonts, or styles
Enable tab editing, drag-and-drop, or close buttons
Configure tab navigation with TabPrimitives
Handle tab events (selection, closing, editing, etc.)
Apply Office, Metro, or Visual Studio themes to tabs
Implement scrolling, tooltips, or multi-line tabs
Persist tab state (order, active page) across sessions

当你需要完成以下需求时可使用本技能：

在Windows Forms应用中实现标签式界面
添加包含多个TabPageAdv项的TabControlAdv
自定义标签的外观、颜色、字体或样式
启用标签编辑、拖放或关闭按钮功能
通过TabPrimitives配置标签导航能力
处理标签事件（选中、关闭、编辑等）
为标签应用Office、Metro或Visual Studio主题
实现滚动、提示框或多行标签
跨会话持久化标签状态（顺序、激活页面）

Component Overview

组件概述

TabControlAdv provides:

Tab Alignment: Top, Bottom, Left, Right positioning
Navigation Support: TabPrimitives for first/last/next/previous navigation
Editing Support: Runtime tab header text editing
Icons Support: Images in tab headers
Drag and Drop: Rearrange tabs via drag-and-drop
Close Buttons: Individual or global close buttons for tabs
ToolTips: Standard and SuperToolTips for tabs
Styling: 15+ built-in themes (2D, 3D, Metro, Office, VS styles)
Serialization: Save and load tab states
Scrolling: Smooth scrolling when tabs overflow

TabControlAdv 提供以下能力：

标签对齐：支持顶部、底部、左侧、右侧定位
导航支持：通过TabPrimitives实现首页/末页/下一页/上一页导航
编辑支持：运行时可编辑标签头部文本
图标支持：标签头部可添加图片
拖放能力：可通过拖放重新排列标签顺序
关闭按钮：支持单个标签或全局关闭按钮配置
提示框：支持标准提示框和SuperToolTips自定义提示
样式能力：内置15+种主题（2D、3D、Metro、Office、VS风格）
序列化能力：支持保存和加载标签状态
滚动能力：标签溢出时支持平滑滚动

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门教程

📄 Read: references/getting-started.md

Assembly deployment and NuGet packages
Adding TabControlAdv through designer
Adding control manually in code
Creating and adding tabs (TabPageAdv)
Adding controls to tab pages
Basic tab placement configuration

📄 阅读： references/getting-started.md

程序集部署与NuGet包引入
通过设计器添加TabControlAdv
通过代码手动添加控件
创建并添加标签（TabPageAdv）
为标签页添加控件
基础标签位置配置

Alignment and Layout

对齐与布局

📄 Read: references/alignment-layout.md

Tab alignment (Top, Bottom, Left, Right)
Text alignment within tabs
Multi-line tab support
RTL (Right-to-Left) support
Rotating tabs and text
TabGap spacing

📄 阅读： references/alignment-layout.md

标签对齐（顶部、底部、左侧、右侧）
标签内文本对齐
多行标签支持
RTL（从右到左）布局支持
标签与文本旋转
标签间距配置

Appearance and Customization

外观与自定义

📄 Read: references/appearance-customization.md

Background colors and images
Active and inactive tab colors
Font and forecolor settings
Border styles and colors
Tab styles (2D, 3D, Metro, Office themes)
SizeMode options (Normal, Fixed, ShrinkToFit, FillToRight)

📄 阅读： references/appearance-customization.md

背景色与背景图配置
激活态/非激活态标签颜色设置
字体与前景色配置
边框样式与颜色设置
标签样式（2D、3D、Metro、Office主题）
尺寸模式选项（Normal、Fixed、ShrinkToFit、FillToRight）

Interactive Features

交互功能

📄 Read: references/interactive-features.md

Close button settings
Tooltip and SuperTooltip support
Scroll buttons and scrollbars
Middle-click to close tabs
Auto-scroll configuration

📄 阅读： references/interactive-features.md

关闭按钮配置
提示框与SuperTooltip支持
滚动按钮与滚动条配置
中键点击关闭标签
自动滚动配置

Tab Navigation

标签导航

📄 Read: references/tab-navigation.md

TabPrimitives overview
Navigation control types (FirstTab, LastTab, NextTab, PreviousTab, etc.)
DropDown and Close primitives
Custom primitives
Creating TabPrimitives programmatically

📄 阅读： references/tab-navigation.md

TabPrimitives概述
导航控件类型（FirstTab、LastTab、NextTab、PreviousTab等）
DropDown与关闭原语
自定义原语
编程方式创建TabPrimitives

Customization and Editing

自定义与编辑

📄 Read: references/customization-editing.md

Renaming tab headers at runtime (LabelEdit)
Drag-and-drop tab reordering (UserMoveTabs)
Padding and spacing
Tab page border styles
Animated GIF images in tabs
Preventing specific tabs from moving

📄 阅读： references/customization-editing.md

运行时重命名标签头部（LabelEdit）
拖放重排标签（UserMoveTabs）
内边距与间距配置
标签页边框样式
标签内GIF动图支持
禁止特定标签移动

Serialization

序列化

📄 Read: references/serialization.md

PersistTabState property
Automatic tab state persistence
Saving tab order and active page

📄 阅读： references/serialization.md

PersistTabState属性使用
标签状态自动持久化
保存标签顺序与激活页面

Events and Event Handling

事件与事件处理

📄 Read: references/events.md

Edit events (BeforeEdit, AfterEdit)
Selection events (SelectedIndexChanging, SelectedIndexChanged)
Tab primitive click events
DrawItem for custom rendering
Tab page events (Closed, Closing)
Other events (Paint, BackgroundImageChanged, etc.)

📄 阅读： references/events.md

编辑事件（BeforeEdit、AfterEdit）
选中事件（SelectedIndexChanging、SelectedIndexChanged）
标签原语点击事件
自定义渲染的DrawItem事件
标签页事件（Closed、Closing）
其他事件（Paint、BackgroundImageChanged等）

Quick Start Example

快速入门示例

Basic Implementation

基础实现

csharp

using Syncfusion.Windows.Forms.Tools;

// Create TabControlAdv
TabControlAdv tabControlAdv1 = new TabControlAdv();
tabControlAdv1.Size = new Size(400, 300);

// Create and add tab pages
TabPageAdv tabPage1 = new TabPageAdv();
tabPage1.Text = "Home";
tabPage1.ImageIndex = 0; // Optional icon

TabPageAdv tabPage2 = new TabPageAdv();
tabPage2.Text = "Settings";

tabControlAdv1.TabPages.Add(tabPage1);
tabControlAdv1.TabPages.Add(tabPage2);

// Add to form
this.Controls.Add(tabControlAdv1);

csharp

using Syncfusion.Windows.Forms.Tools;

// Create TabControlAdv
TabControlAdv tabControlAdv1 = new TabControlAdv();
tabControlAdv1.Size = new Size(400, 300);

// Create and add tab pages
TabPageAdv tabPage1 = new TabPageAdv();
tabPage1.Text = "Home";
tabPage1.ImageIndex = 0; // Optional icon

TabPageAdv tabPage2 = new TabPageAdv();
tabPage2.Text = "Settings";

tabControlAdv1.TabPages.Add(tabPage1);
tabControlAdv1.TabPages.Add(tabPage2);

// Add to form
this.Controls.Add(tabControlAdv1);

With Styling and Features

带样式与功能的实现

csharp

// Apply Office 2016 theme
tabControlAdv1.TabStyle = typeof(TabRendererOffice2016Colorful);

// Enable features
tabControlAdv1.ShowTabCloseButton = true;
tabControlAdv1.UserMoveTabs = true;
tabControlAdv1.LabelEdit = true;
tabControlAdv1.ShowToolTips = true;

// Customize appearance
tabControlAdv1.ActiveTabColor = Color.FromArgb(255, 255, 255);
tabControlAdv1.InactiveTabColor = Color.FromArgb(240, 240, 240);
tabControlAdv1.ActiveTabFont = new Font("Segoe UI", 9F, FontStyle.Bold);

csharp

// Apply Office 2016 theme
tabControlAdv1.TabStyle = typeof(TabRendererOffice2016Colorful);

// Enable features
tabControlAdv1.ShowTabCloseButton = true;
tabControlAdv1.UserMoveTabs = true;
tabControlAdv1.LabelEdit = true;
tabControlAdv1.ShowToolTips = true;

// Customize appearance
tabControlAdv1.ActiveTabColor = Color.FromArgb(255, 255, 255);
tabControlAdv1.InactiveTabColor = Color.FromArgb(240, 240, 240);
tabControlAdv1.ActiveTabFont = new Font("Segoe UI", 9F, FontStyle.Bold);

Common Patterns

常用实现模式

Pattern 1: Tabbed Document Interface

模式1：标签式文档界面

csharp

// Create tab control for documents
TabControlAdv documentTabs = new TabControlAdv();
documentTabs.Dock = DockStyle.Fill;
documentTabs.ShowTabCloseButton = true;
documentTabs.ShowCloseButtonForActiveTabOnly = true;

// Add document tabs dynamically
void AddDocumentTab(string title, Control content)
{
    TabPageAdv docTab = new TabPageAdv();
    docTab.Text = title;
    docTab.Controls.Add(content);
    content.Dock = DockStyle.Fill;
    documentTabs.TabPages.Add(docTab);
    documentTabs.SelectedTab = docTab;
}

// Handle tab closing
documentTabs.SelectedTab.Closing += (sender, e) =>
{
    var result = MessageBox.Show("Save changes?", "Close", 
        MessageBoxButtons.YesNoCancel);
    if (result == DialogResult.Cancel)
        e.Cancel = true;
};

csharp

// Create tab control for documents
TabControlAdv documentTabs = new TabControlAdv();
documentTabs.Dock = DockStyle.Fill;
documentTabs.ShowTabCloseButton = true;
documentTabs.ShowCloseButtonForActiveTabOnly = true;

// Add document tabs dynamically
void AddDocumentTab(string title, Control content)
{
    TabPageAdv docTab = new TabPageAdv();
    docTab.Text = title;
    docTab.Controls.Add(content);
    content.Dock = DockStyle.Fill;
    documentTabs.TabPages.Add(docTab);
    documentTabs.SelectedTab = docTab;
}

// Handle tab closing
documentTabs.SelectedTab.Closing += (sender, e) =>
{
    var result = MessageBox.Show("Save changes?", "Close", 
        MessageBoxButtons.YesNoCancel);
    if (result == DialogResult.Cancel)
        e.Cancel = true;
};

Pattern 2: Navigation Tabs with Icons

模式2：带图标的导航标签

csharp

// Setup image list
ImageList tabImages = new ImageList();
tabImages.Images.Add("home", Properties.Resources.HomeIcon);
tabImages.Images.Add("settings", Properties.Resources.SettingsIcon);
tabControlAdv1.ImageList = tabImages;

// Create tabs with icons
TabPageAdv homeTab = new TabPageAdv();
homeTab.Text = "Home";
homeTab.ImageIndex = 0;

TabPageAdv settingsTab = new TabPageAdv();
settingsTab.Text = "Settings";
settingsTab.ImageIndex = 1;

// Configure alignment
tabControlAdv1.ImageAlignmentR = RelativeImageAlignment.LeftOfText;

csharp

// Setup image list
ImageList tabImages = new ImageList();
tabImages.Images.Add("home", Properties.Resources.HomeIcon);
tabImages.Images.Add("settings", Properties.Resources.SettingsIcon);
tabControlAdv1.ImageList = tabImages;

// Create tabs with icons
TabPageAdv homeTab = new TabPageAdv();
homeTab.Text = "Home";
homeTab.ImageIndex = 0;

TabPageAdv settingsTab = new TabPageAdv();
settingsTab.Text = "Settings";
settingsTab.ImageIndex = 1;

// Configure alignment
tabControlAdv1.ImageAlignmentR = RelativeImageAlignment.LeftOfText;

Pattern 3: Tab Navigation Controls

模式3：标签导航控件

csharp

// Enable navigation primitives
tabControlAdv1.TabPrimitivesHost.Visible = true;

// Add navigation buttons
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.FirstTab, null, Color.Empty, true, 1, "First"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.PreviousTab, null, Color.Empty, true, 1, "Previous"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.NextTab, null, Color.Empty, true, 1, "Next"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.LastTab, null, Color.Empty, true, 1, "Last"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.DropDown, null, Color.Empty, true, 1, "DropDown"));

csharp

// Enable navigation primitives
tabControlAdv1.TabPrimitivesHost.Visible = true;

// Add navigation buttons
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.FirstTab, null, Color.Empty, true, 1, "First"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.PreviousTab, null, Color.Empty, true, 1, "Previous"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.NextTab, null, Color.Empty, true, 1, "Next"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.LastTab, null, Color.Empty, true, 1, "Last"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.DropDown, null, Color.Empty, true, 1, "DropDown"));

Pattern 4: Handling Tab Selection

模式4：标签选中处理

csharp

// Prevent selection of specific tab
tabControlAdv1.SelectedIndexChanging += (sender, e) =>
{
    if (e.NewSelectedIndex == 2) // Prevent selecting 3rd tab
    {
        e.Cancel = true;
        MessageBox.Show("This tab is disabled");
    }
};

// React to selection changes
tabControlAdv1.SelectedIndexChanged += (sender, e) =>
{
    var selectedTab = tabControlAdv1.SelectedTab;
    Console.WriteLine($"Selected tab: {selectedTab.Text}");
    // Load content for selected tab
};

csharp

// Prevent selection of specific tab
tabControlAdv1.SelectedIndexChanging += (sender, e) =>
{
    if (e.NewSelectedIndex == 2) // Prevent selecting 3rd tab
    {
        e.Cancel = true;
        MessageBox.Show("This tab is disabled");
    }
};

// React to selection changes
tabControlAdv1.SelectedIndexChanged += (sender, e) =>
{
    var selectedTab = tabControlAdv1.SelectedTab;
    Console.WriteLine($"Selected tab: {selectedTab.Text}");
    // Load content for selected tab
};

Key Properties

核心属性

Core Properties

基础属性

Property	Type	Description
`TabPages`	Collection	Collection of TabPageAdv items
`SelectedIndex`	int	Index of currently selected tab
`SelectedTab`	TabPageAdv	Currently selected tab page
`Alignment`	TabAlignment	Tab position (Top, Bottom, Left, Right)
`Multiline`	bool	Allow tabs in multiple rows

属性	类型	描述
`TabPages`	Collection	TabPageAdv项的集合
`SelectedIndex`	int	当前选中标签的索引
`SelectedTab`	TabPageAdv	当前激活的标签页
`Alignment`	TabAlignment	标签位置（顶部、底部、左侧、右侧）
`Multiline`	bool	是否允许多行展示标签

Appearance Properties

外观属性

Property	Type	Description
`TabStyle`	Type	Theme renderer (2D, 3D, Metro, Office, VS styles)
`ActiveTabColor`	Color	Background color of active tab
`InactiveTabColor`	Color	Background color of inactive tabs
`ActiveTabFont`	Font	Font for active tab text
`SizeMode`	TabSizeMode	Tab sizing mode

属性	类型	描述
`TabStyle`	Type	主题渲染器（2D、3D、Metro、Office、VS风格）
`ActiveTabColor`	Color	激活态标签的背景色
`InactiveTabColor`	Color	非激活态标签的背景色
`ActiveTabFont`	Font	激活态标签文本的字体
`SizeMode`	TabSizeMode	标签尺寸模式

Feature Properties

功能属性

Property	Type	Description
`ShowTabCloseButton`	bool	Show close button on tabs
`UserMoveTabs`	bool	Enable drag-drop tab reordering
`LabelEdit`	bool	Enable runtime tab text editing
`ShowToolTips`	bool	Enable tooltips on tabs
`ShowScroll`	bool	Show scroll buttons when tabs overflow

属性	类型	描述
`ShowTabCloseButton`	bool	是否在标签上展示关闭按钮
`UserMoveTabs`	bool	是否启用拖放重排标签功能
`LabelEdit`	bool	是否启用运行时标签文本编辑
`ShowToolTips`	bool	是否启用标签提示框
`ShowScroll`	bool	标签溢出时是否展示滚动按钮

Navigation Properties

导航属性

Property	Type	Description
`TabPrimitivesHost`	TabPrimitivesHost	Container for navigation buttons
`SwitchPagesForDialogKeys`	bool	Enable Ctrl+Tab navigation

属性	类型	描述
`TabPrimitivesHost`	TabPrimitivesHost	导航按钮的容器
`SwitchPagesForDialogKeys`	bool	是否启用Ctrl+Tab导航

Common Use Cases

常见使用场景

Use Case 1: Application Settings Dialog

场景1：应用设置对话框

Create a tabbed settings dialog with categories like "General", "Appearance", "Advanced":

Use
```
Alignment = TabAlignment.Left
```
for vertical tabs
Apply consistent styling with
```
TabStyle
```
Add icons to tabs with
```
ImageList
```

创建带有「通用」「外观」「高级」等分类的标签式设置对话框：

使用
```
Alignment = TabAlignment.Left
```
实现垂直标签
通过
```
TabStyle
```
应用统一的样式
通过
```
ImageList
```
为标签添加图标

Use Case 2: Multi-Document Editor

场景2：多文档编辑器

Build a document editor with closeable tabs:

Enable
```
ShowTabCloseButton = true
```
Handle
```
Closing
```
event to prompt for unsaved changes
Use
```
UserMoveTabs = true
```
for reordering

构建支持可关闭标签的文档编辑器：

启用
```
ShowTabCloseButton = true
```
处理
```
Closing
```
事件提示用户保存未修改的内容
开启
```
UserMoveTabs = true
```
支持标签重排

Use Case 3: Wizard Interface

场景3：向导界面

Create a step-by-step wizard with disabled tab selection:

Use
```
SelectedIndexChanging
```
to control navigation
Apply custom colors to indicate progress
Show/hide tabs based on wizard flow

创建支持禁用标签选中的分步向导：

使用
```
SelectedIndexChanging
```
控制导航流程
应用自定义颜色标识进度
根据向导流程显示/隐藏对应标签

Use Case 4: Dashboard with Sections

场景4：分板块控制面板

Organize dashboard content into sections:

Use
```
Multiline = true
```
for many tabs
Apply
```
SizeMode.FillToRight
```
for uniform tab widths
Enable
```
ShowScroll
```
for overflow handling

将控制面板内容按板块组织展示：

开启
```
Multiline = true
```
适配大量标签
应用
```
SizeMode.FillToRight
```
实现统一的标签宽度
启用
```
ShowScroll
```
处理标签溢出

Assembly References

程序集引用

Required assemblies:

```
Syncfusion.Shared.Base.dll
```
```
Syncfusion.Shared.Windows.dll
```
```
Syncfusion.Tools.Base.dll
```
```
Syncfusion.Tools.Windows.dll
```

For Grid controls in tabs, also add:

```
Syncfusion.Grid.Base.dll
```
```
Syncfusion.Grid.Windows.dll
```

所需程序集：

```
Syncfusion.Shared.Base.dll
```
```
Syncfusion.Shared.Windows.dll
```
```
Syncfusion.Tools.Base.dll
```
```
Syncfusion.Tools.Windows.dll
```

如果标签内使用Grid控件，还需添加：

```
Syncfusion.Grid.Base.dll
```
```
Syncfusion.Grid.Windows.dll
```