syncfusion-winforms-xptaskbar

在 Windows Forms 中实现 XPTaskBar

目录

• 何时使用此技能
• 组件概览
• 快速入门示例
• 文档导航指南
• 常见模式
• 关键配置属性

何时使用此技能

在以下情况下使用 XPTaskBar：

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

组件概览

XPTaskBar 是一个 Windows Forms 控件，可在可折叠的框中显示按组组织的命令项，模拟 Windows XP 任务侧边栏。组件层级包括：

• XPTaskBar - 可容纳多个框的主容器控件
• XPTaskBarBox - 带有标题和项目区域的可折叠分区
• XPTaskBarItem - 显示在框内的单个命令项

主要功能

• 层级布局 - 将项目归入不同类别的框中
• 折叠/展开动画 - 提供平滑过渡效果，并可配置动画速度
• 多种布局模式 - 垂直（默认）或水平方向
• 状态持久化 - 在不同会话间记住展开/折叠状态
• 丰富的自定义选项 - 控制颜色、字体、图像和间距
• 事件驱动 - 处理点击、动画和状态更改
• 子控件支持 - 在框中承载面板和其他控件

快速入门示例

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

文档导航指南

根据实现需求，按相应顺序阅读参考文档：

入门

📄 阅读： references/getting-started.md

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

构建结构

📄 阅读： references/box-structure.md

• XPTaskBar 框的层级结构和组成
• 标题自定义（文本、字体、对齐方式、方向）
• 折叠/展开按钮配置
• 集成子面板和控件

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

• 创建和管理 XPTaskBarItems
• 使用 Items 集合
• 项目属性和配置
• 使用 PreferredChildPanelHeight 承载嵌套控件

布局和方向

📄 阅读： references/layout-orientation.md

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

行为和交互

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

• 动画配置和计时
• 折叠/展开事件处理
• 使用 Tag 路由的 ItemClick 事件
• 状态保留（AutoPersistStates）
• 拖放支持
• 事件示例和模式

外观和自定义

📄 阅读： references/appearance-customization.md

• 标题颜色和前景色自定义
• 标题字体样式
• 通过 ProvideHeaderBackgroundBrush 和 ProvideItemsBackgroundBrush 事件自定义画刷
• 为标题和项目添加图像
• 工具提示配置和显示
• 自定义背景绘制技巧

间距和滚动

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

• XPTaskBar 内部填充（DockPadding、HorizontalPadding、VerticalPadding）
• Box 标题填充（PADX、PADY）
• 自动滚动行为
• 滚动边距和最小尺寸配置

常见模式

模式 1：多 Box 任务菜单

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

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
}

模式 2：项目点击路由

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

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

模式 3：有状态持久化

在不同会话之间记住用户偏好：

xpTaskBar1.AutoPersistStates = true;

模式 4：动画状态更改

控制展开/折叠时的动画行为：

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

关键配置属性

XPTaskBar 级别

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

XPTaskBarBox 级别

属性	类型	用途
Text	string	Box 标题显示文本
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 级别

属性	类型	用途
Text	string	项目显示文本
ImageIndex	int	在父 Box 的 ImageList 中的索引
ToolTipText	string	悬停时显示的工具提示文本
Tag	object	用于事件路由的自定义数据

---

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