syncfusion-winforms-xptaskbar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing XPTaskBar in Windows Forms

在Windows Forms中实现XPTaskBar

When to Use This Skill

什么时候使用本教程

Use XPTaskBar when you need to:

Create expandable task panels - Display command items or features in collapsible grouped boxes
Build Windows XP-style menus - Recreate the classic task sidebar UI pattern
Organize navigation hierarchically - Group related commands into categorized boxes
Implement interactive task lists - Allow users to expand/collapse task categories with animations
Add custom animations and events - Control expand/collapse behavior and respond to user interactions

当你需要实现以下需求时可使用XPTaskBar：

创建可展开任务面板 - 在可折叠的分组框中展示命令项或功能
构建Windows XP风格菜单 - 复刻经典任务侧边栏UI模式
分层组织导航结构 - 将相关命令分组到不同分类框中
实现交互式任务列表 - 允许用户通过动画效果展开/折叠任务分类
添加自定义动画和事件 - 控制展开/折叠行为，响应用户交互

Component Overview

组件概述

XPTaskBar is a Windows Forms control that displays command items organized within collapsible boxes, mimicking the Windows XP task sidebar. The component hierarchy includes:

XPTaskBar - Main container control that can hold multiple boxes
XPTaskBarBox - Collapsible section with header and items area
XPTaskBarItem - Individual command items displayed within a box

XPTaskBar是一款Windows Forms控件，可将命令项组织在可折叠的框中，模拟Windows XP任务侧边栏效果。组件层级结构包括：

XPTaskBar - 主容器控件，可容纳多个框
XPTaskBarBox - 可折叠区块，包含头部和条目区域
XPTaskBarItem - 展示在框中的单个命令项

Key Features

核心特性

Hierarchical layout - Organize items into categorized boxes
Collapse/expand animation - Smooth transitions with configurable animation speed
Multiple layout modes - Vertical (default) or horizontal orientation
State persistence - Remember expanded/collapsed state across sessions
Rich customization - Control colors, fonts, images, and spacing
Event-driven - Handle clicks, animations, and state changes
Child control support - Host panels and other controls within boxes

分层布局 - 将条目组织到不同分类框中
折叠/展开动画 - 过渡效果流畅，动画速度可配置
多种布局模式 - 垂直（默认）或水平布局
状态持久化 - 跨会话记忆展开/折叠状态
高度可自定义 - 可控制颜色、字体、图片和间距
事件驱动 - 可处理点击、动画和状态变更事件
支持子控件 - 可在框中嵌入面板和其他控件

Quick Start Example

快速入门示例

csharp

using Syncfusion.Windows.Forms.Tools;

// Create XPTaskBar control
XPTaskBar xpTaskBar1 = new XPTaskBar();
xpTaskBar1.Dock = DockStyle.Fill;
this.Controls.Add(xpTaskBar1);

// Create first task box
XPTaskBarBox box1 = new XPTaskBarBox();
box1.Text = "File Operations";
xpTaskBar1.Controls.Add(box1);

// Add items to the box
box1.Items.AddRange(new XPTaskBarItem[] {
    new XPTaskBarItem("New Document", System.Drawing.Color.Empty, -1, "NewDoc"),
    new XPTaskBarItem("Open File", System.Drawing.Color.Empty, -1, "OpenFile"),
    new XPTaskBarItem("Save", System.Drawing.Color.Empty, -1, "Save")
});

// Handle item clicks
box1.ItemClick += (sender, e) => {
    switch (e.XPTaskBarItem.Tag as string) {
        case "NewDoc":
            // Handle new document
            break;
        case "OpenFile":
            // Handle file open
            break;
    }
};

// Create second task box
XPTaskBarBox box2 = new XPTaskBarBox();
box2.Text = "Editing Tools";
xpTaskBar1.Controls.Add(box2);

box2.Items.AddRange(new XPTaskBarItem[] {
    new XPTaskBarItem("Cut", System.Drawing.Color.Empty, -1, "Cut"),
    new XPTaskBarItem("Copy", System.Drawing.Color.Empty, -1, "Copy"),
    new XPTaskBarItem("Paste", System.Drawing.Color.Empty, -1, "Paste")
});

csharp

using Syncfusion.Windows.Forms.Tools;

// 创建XPTaskBar控件
XPTaskBar xpTaskBar1 = new XPTaskBar();
xpTaskBar1.Dock = DockStyle.Fill;
this.Controls.Add(xpTaskBar1);

// 创建第一个任务框
XPTaskBarBox box1 = new XPTaskBarBox();
box1.Text = "文件操作";
xpTaskBar1.Controls.Add(box1);

// 向框中添加条目
box1.Items.AddRange(new XPTaskBarItem[] {
    new XPTaskBarItem("新建文档", System.Drawing.Color.Empty, -1, "NewDoc"),
    new XPTaskBarItem("打开文件", System.Drawing.Color.Empty, -1, "OpenFile"),
    new XPTaskBarItem("保存", System.Drawing.Color.Empty, -1, "Save")
});

// 处理条目点击事件
box1.ItemClick += (sender, e) => {
    switch (e.XPTaskBarItem.Tag as string) {
        case "NewDoc":
            // 处理新建文档逻辑
            break;
        case "OpenFile":
            // 处理打开文件逻辑
            break;
    }
};

// 创建第二个任务框
XPTaskBarBox box2 = new XPTaskBarBox();
box2.Text = "编辑工具";
xpTaskBar1.Controls.Add(box2);

box2.Items.AddRange(new XPTaskBarItem[] {
    new XPTaskBarItem("剪切", System.Drawing.Color.Empty, -1, "Cut"),
    new XPTaskBarItem("复制", System.Drawing.Color.Empty, -1, "Copy"),
    new XPTaskBarItem("粘贴", System.Drawing.Color.Empty, -1, "Paste")
});

Documentation Navigation Guide

文档导航指南

Read the reference documentation in the order that matches your implementation needs:

请根据你的实现需求按顺序阅读参考文档：

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly and package dependencies
Adding control via designer or code
Basic XPTaskBar, box, and item setup
Assembly references required

📄 阅读： references/getting-started.md

程序集和包依赖
通过设计器或代码添加控件
XPTaskBar、框、条目的基础设置
所需的程序集引用

Building the Structure

构建结构

📄 Read: references/box-structure.md

XPTaskBar box hierarchy and anatomy
Header customization (text, font, alignment, direction)
Collapse/expand button configuration
Integrating child panels and controls

📄 Read: references/items-and-content.md

Creating and managing XPTaskBarItems
Working with Items collection
Item properties and configuration
Hosting nested controls with PreferredChildPanelHeight

📄 阅读： references/box-structure.md

XPTaskBar框层级和结构解析
头部自定义（文本、字体、对齐方式、方向）
折叠/展开按钮配置
嵌入子面板和控件

📄 阅读： references/items-and-content.md

创建和管理XPTaskBarItem
操作Items集合
条目属性和配置
通过PreferredChildPanelHeight嵌入嵌套控件

Layout and Orientation

布局和方向

📄 Read: references/layout-orientation.md

Vertical layout mode (default)
Horizontal layout mode and column width
Switching orientations dynamically
Responsive layout behavior

📄 阅读： references/layout-orientation.md

垂直布局模式（默认）
水平布局模式和列宽
动态切换布局方向
响应式布局行为

Behavior and Interactivity

行为和交互

📄 Read: references/behavior-and-events.md

Animation configuration and timing
Collapse/expand event handling
ItemClick event with Tag-based routing
State preservation (AutoPersistStates)
Drag-and-drop support
Event examples and patterns

📄 阅读： references/behavior-and-events.md

动画配置和时间设置
折叠/展开事件处理
基于Tag路由的ItemClick事件
状态保存（AutoPersistStates）
拖拽支持
事件示例和模式

Appearance and Customization

外观和自定义

📄 Read: references/appearance-customization.md

Header color and forecolor customization
Font styling for headers
Brush customization via ProvideHeaderBackgroundBrush and ProvideItemsBackgroundBrush events
Adding images to headers and items
Tooltip configuration and display
Custom background drawing techniques

📄 阅读： references/appearance-customization.md

头部颜色和前景色自定义
头部字体样式设置
通过ProvideHeaderBackgroundBrush和ProvideItemsBackgroundBrush事件自定义画刷
为头部和条目添加图片
提示框配置和展示
自定义背景绘制技术

Spacing and Scrolling

间距和滚动

📄 Read: references/padding-spacing-scrolling.md

XPTaskBar interior padding (DockPadding, HorizontalPadding, VerticalPadding)
Box header padding (PADX, PADY)
Auto-scroll behavior
Scroll margin and minimum size configuration

📄 阅读： references/padding-spacing-scrolling.md

XPTaskBar内部边距（DockPadding、HorizontalPadding、VerticalPadding）
框头部边距（PADX、PADY）
自动滚动行为
滚动边距和最小尺寸配置

Common Patterns

常见使用模式

Pattern 1: Multi-Box Task Menu

模式1：多框任务菜单

Create a sidebar with multiple collapsible task categories:

csharp

var taskBar = new XPTaskBar { VerticalLayout = true };

// Create boxes for different task categories
foreach (var category in new[] { "File", "Edit", "View", "Help" }) {
    var box = new XPTaskBarBox { Text = category };
    taskBar.Controls.Add(box);
    // Add items to box
}

创建包含多个可折叠任务分类的侧边栏：

csharp

var taskBar = new XPTaskBar { VerticalLayout = true };

// 为不同任务分类创建框
foreach (var category in new[] { "文件", "编辑", "视图", "帮助" }) {
    var box = new XPTaskBarBox { Text = category };
    taskBar.Controls.Add(box);
    // 向框中添加条目
}

Pattern 2: Item Click Routing

模式2：条目点击路由

Use the Tag property to implement event routing:

csharp

box.ItemClick += (sender, e) => {
    var command = e.XPTaskBarItem.Tag as string;
    ExecuteCommand(command);
};

使用Tag属性实现事件路由：

csharp

box.ItemClick += (sender, e) => {
    var command = e.XPTaskBarItem.Tag as string;
    ExecuteCommand(command);
};

Pattern 3: Stateful Persistence

模式3：状态持久化

Remember user preferences across sessions:

csharp

xpTaskBar1.AutoPersistStates = true;

跨会话记忆用户偏好设置：

csharp

xpTaskBar1.AutoPersistStates = true;

Pattern 4: Animated State Changes

模式4：动画状态变更

Control animation behavior during expand/collapse:

csharp

box.AnimationDelay = 50;           // Milliseconds between frames
box.AnimationPositionsCount = 15;  // Number of animation steps
box.UseAdditionalAnimation = true; // Animate when adding/removing items

控制展开/折叠过程中的动画行为：

csharp

box.AnimationDelay = 50;           // 帧之间的间隔（毫秒）
box.AnimationPositionsCount = 15;  // 动画步数
box.UseAdditionalAnimation = true; // 添加/移除条目时播放动画

Key Configuration Properties

核心配置属性

XPTaskBar Level

XPTaskBar层级

Property	Type	Purpose
`VerticalLayout`	bool	Set true for vertical mode (default), false for horizontal
`ColWidthOnHorizontalAlignment`	int	Column width in horizontal layout mode
`HorizontalPadding`	int	Interior horizontal spacing
`VerticalPadding`	int	Interior vertical spacing
`AutoScroll`	bool	Enable automatic scrollbars when needed
`AutoPersistStates`	bool	Persist expanded/collapsed state between sessions
`AllowDrop`	bool	Enable drag-and-drop support
`MinimumSize`	Size	Minimum control dimensions

属性	类型	用途
`VerticalLayout`	bool	设为true启用垂直模式（默认），false启用水平模式
`ColWidthOnHorizontalAlignment`	int	水平布局模式下的列宽
`HorizontalPadding`	int	内部水平间距
`VerticalPadding`	int	内部垂直间距
`AutoScroll`	bool	需要时自动显示滚动条
`AutoPersistStates`	bool	跨会话持久化展开/折叠状态
`AllowDrop`	bool	启用拖拽支持
`MinimumSize`	Size	控件最小尺寸

XPTaskBarBox Level

XPTaskBarBox层级

Property	Type	Purpose
`Text`	string	Box header display text
`Collapsed`	bool	Set true to collapse, false to expand
`ShowCollapseButton`	bool	Show/hide collapse button
`ToggleByButton`	bool	Allow button to toggle state
`HeaderBackColor`	Color	Header background color
`HeaderForeColor`	Color	Header text color
`HeaderFont`	Font	Header text font
`HeaderTextAlign`	StringAlignment	Header text alignment
`AnimationDelay`	int	Delay in ms between animation frames
`AnimationPositionsCount`	int	Number of animation steps
`PreferredChildPanelHeight`	int	Height reserved for child controls
`ShowToolTip`	bool	Enable tooltips for items
`PADX`	int	Horizontal header padding
`PADY`	int	Vertical header padding

属性	类型	用途
`Text`	string	框头部展示文本
`Collapsed`	bool	设为true折叠，false展开
`ShowCollapseButton`	bool	显示/隐藏折叠按钮
`ToggleByButton`	bool	允许通过按钮切换状态
`HeaderBackColor`	Color	头部背景色
`HeaderForeColor`	Color	头部文本颜色
`HeaderFont`	Font	头部文本字体
`HeaderTextAlign`	StringAlignment	头部文本对齐方式
`AnimationDelay`	int	动画帧之间的延迟（毫秒）
`AnimationPositionsCount`	int	动画步数
`PreferredChildPanelHeight`	int	为子控件预留的高度
`ShowToolTip`	bool	启用条目提示框
`PADX`	int	头部水平内边距
`PADY`	int	头部垂直内边距

XPTaskBarItem Level

XPTaskBarItem层级

Property	Type	Purpose
`Text`	string	Item display text
`ImageIndex`	int	Index in parent box's ImageList
`ToolTipText`	string	Tooltip text on hover
`Tag`	object	Custom data for event routing

Next Step: Start with references/getting-started.md to set up your first XPTaskBar control.

属性	类型	用途
`Text`	string	条目展示文本
`ImageIndex`	int	父框ImageList中的图片索引
`ToolTipText`	string	hover时的提示文本
`Tag`	object	用于事件路由的自定义数据

下一步： 从references/getting-started.md开始配置你的第一个XPTaskBar控件。

syncfusion-winforms-xptaskbar

Original

Translation

Implementing XPTaskBar in Windows Forms

在Windows Forms中实现XPTaskBar

Table of Contents

目录

When to Use This Skill

什么时候使用本教程

Component Overview

组件概述

Key Features

核心特性

Quick Start Example

快速入门示例

Documentation Navigation Guide

文档导航指南

Getting Started

入门指南

Building the Structure

构建结构

Layout and Orientation

布局和方向

Behavior and Interactivity

行为和交互

Appearance and Customization

外观和自定义

Spacing and Scrolling

间距和滚动

Common Patterns

常见使用模式

Pattern 1: Multi-Box Task Menu

模式1：多框任务菜单

Pattern 2: Item Click Routing

模式2：条目点击路由

Pattern 3: Stateful Persistence

模式3：状态持久化

Pattern 4: Animated State Changes

模式4：动画状态变更

Key Configuration Properties

核心配置属性

XPTaskBar Level

XPTaskBar层级

XPTaskBarBox Level

XPTaskBarBox层级

XPTaskBarItem Level

XPTaskBarItem层级