syncfusion-winforms-tooltip

实现 Syncfusion Windows Forms 工具提示

Syncfusion SfToolTip 组件为 Windows Forms 应用程序提供丰富的工具提示功能。当用户将鼠标悬停在控件上时，它会自动以弹出窗口的形式显示。它支持多个工具提示项、自定义控件、图像以及丰富的外观自定义选项。

何时使用此技能

在以下情况下使用此技能：

• 为 Windows Forms 控件添加工具提示，提供基本或高级内容
• 显示包含多个项的工具提示，展示多行信息或多个区块
• 显示气球样式的工具提示，并带有指向控件的尖角
• 自定义工具提示外观，包括颜色、边框、渐变和图像
• 在工具提示中承载自定义控件，提供丰富的交互式内容
• 以编程方式控制工具提示的显示时机和位置
• 实现上下文帮助，通过悬停显示信息面板
• 支持 RTL 布局，用于国际化应用程序
• 创建自定义绘制的工具提示，使用专门的渲染方式

组件概览

SfToolTip 组件提供：

• 多个项： 添加多个具有单独样式的工具提示项
• 自定义控件： 在工具提示项中承载任意用户控件
• 丰富的内容： 文本、图像、渐变和分隔符
• 气球样式： 显示带有方向性尖角的工具提示
• 外观： 丰富的自定义选项（颜色、字体、边框、阴影）
• 事件： 控制显示行为和自定义绘制
• 编程控制： 按需显示／隐藏工具提示

比较： 当需要支持多个项、单独自定义工具提示项或承载自定义控件时，请选择 SfToolTip 而非 SuperToolTip。SfToolTip 提供更丰富的样式和灵活性。

文档和导航指南

入门

📄 阅读： references/getting-started.md

实现基本工具提示时：

• 程序集部署和所需依赖项
• 使用简单文本设置工具提示（设计器和代码）
• 使用 ToolTipInfo 设置结构化内容的工具提示
• 以编程方式显示和隐藏工具提示
• 配置工具提示延迟时间（InitialDelay、AutoPopDelay）
• 基本气球样式设置

工具提示项和内容

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

处理工具提示内容结构时：

• 创建和配置 ToolTipItem 对象
• 向单个工具提示添加多个项
• 配置项之间的间距和内边距
• 使用 Image 或 ImageList 属性添加图像
• 设置图像对齐方式（Left、Top、Right）
• 配置图像大小和间距
• 在工具提示中承载自定义用户控件

气球样式和尖角

📄 阅读： references/balloon-style-and-beak.md

实现气球样式的工具提示时：

• 启用 ToolTipStyle.Balloon
• 了解气球样式与矩形样式的区别
• 自定义尖角背景色
• 相对于控件定位气球
• 气球样式工具提示的使用场景

外观自定义

📄 阅读： references/appearance-customization.md

自定义工具提示的视觉外观时：

• 边框颜色和粗细
• 单独设置 ToolTipItem 样式（颜色、字体、对齐方式）
• 实现渐变背景
• 自定义项之间的分隔符
• 阴影效果
• RTL（从右到左）布局支持

高级用法和事件

📄 阅读： references/advanced-usage.md

实现高级工具提示功能时：

• 以编程方式获取和设置工具提示文本／信息
• 使用 ToolTipShowing 事件有条件地显示工具提示
• 动态自定义各控件的外观
• 显示前更改工具提示位置
• 设置最小和最大宽度
• 使用 DrawToolTipItem 事件进行自定义绘制
• 取消默认渲染

快速入门

带文本的基本工具提示

using Syncfusion.Windows.Forms;

// Add SfToolTip component to form
SfToolTip sfToolTip1 = new SfToolTip();

// Set simple text tooltip
sfToolTip1.SetToolTip(this.button1, "Click to submit the form");

包含多个项的工具提示

using Syncfusion.Windows.Forms;
using Syncfusion.WinForms.Controls;

SfToolTip sfToolTip1 = new SfToolTip();

// Create ToolTipInfo with multiple items
ToolTipInfo toolTipInfo = new ToolTipInfo();

ToolTipItem item1 = new ToolTipItem();
item1.Text = "User Information";
item1.Style.Font = new Font("Arial", 10f, FontStyle.Bold);

ToolTipItem item2 = new ToolTipItem();
item2.Text = "Name: John Doe\nEmail: [email protected]";

toolTipInfo.Items.AddRange(new ToolTipItem[] { item1, item2 });
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

带图像的气球样式工具提示

SfToolTip sfToolTip1 = new SfToolTip();

ToolTipInfo toolTipInfo = new ToolTipInfo();
toolTipInfo.ToolTipStyle = ToolTipStyle.Balloon;
toolTipInfo.BeakBackColor = Color.LightSkyBlue;

ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Text = "David Carter\nPhone: +1 919.494.1974\nEmail: [email protected]";
toolTipItem.Image = Properties.Resources.UserImage;
toolTipItem.Style.ImageSize = new Size(80, 80);
toolTipItem.Style.ImageAlignment = ToolTipImageAlignment.Left;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

常见模式

模式 1：带渐变效果的富文本工具提示

ToolTipInfo toolTipInfo = new ToolTipInfo();
toolTipInfo.BorderColor = Color.DarkGray;
toolTipInfo.BorderThickness = 2;

ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Text = "Important Information";
toolTipItem.EnableGradientBackground = true;
toolTipItem.Style.GradientBrush = new BrushInfo(
    GradientStyle.Horizontal, 
    new Color[] { Color.LightBlue, Color.LightGreen }
);
toolTipItem.Style.Font = new Font("Arial", 10f, FontStyle.Bold);
toolTipItem.Style.ForeColor = Color.DarkBlue;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.control, toolTipInfo);

模式 2：条件显示工具提示

sfToolTip1.ToolTipShowing += (sender, e) =>
{
    // Customize tooltip based on control state
    if (e.Control is Button button && !button.Enabled)
    {
        e.Cancel = true; // Don't show tooltip for disabled controls
    }
    
    // Or modify appearance dynamically
    if (e.Control.Tag?.ToString() == "Warning")
    {
        e.ToolTipInfo.Items[0].Style.BackColor = Color.LightCoral;
        e.ToolTipInfo.BorderColor = Color.Red;
    }
};

模式 3：以编程方式显示工具提示

// Show tooltip at specific location
Point location = new Point(300, 200);
sfToolTip1.Show("Processing complete!", location);

// Show tooltip at cursor position with duration
ToolTipInfo info = new ToolTipInfo();
ToolTipItem item = new ToolTipItem { Text = "Operation successful!" };
info.Items.Add(item);
sfToolTip1.Show(info);

// Hide after delay
Thread.Sleep(3000);
sfToolTip1.Hide();

模式 4：工具提示中的自定义控件

// Create custom control (e.g., PictureBox with animated GIF)
PictureBox pictureBox = new PictureBox();
pictureBox.Image = Image.FromFile("loading.gif");
pictureBox.SizeMode = PictureBoxSizeMode.CenterImage;
pictureBox.Size = new Size(200, 100);

ToolTipInfo toolTipInfo = new ToolTipInfo();
ToolTipItem toolTipItem = new ToolTipItem();
toolTipItem.Control = pictureBox;

toolTipInfo.Items.Add(toolTipItem);
sfToolTip1.SetToolTipInfo(this.button1, toolTipInfo);

关键属性

SfToolTip 属性

属性	类型	说明
InitialDelay	int	工具提示显示前的延迟时间（毫秒，默认值：0）
AutoPopDelay	int	工具提示保持可见的时长（毫秒，默认值：5000）
ShadowVisible	bool	启用工具提示的阴影效果

ToolTipInfo 属性

属性	类型	说明
Items	ToolTipItemCollection	要显示的工具提示项集合
ToolTipStyle	ToolTipStyle	矩形（默认）或气球样式
BeakBackColor	Color	气球尖角的背景颜色
BorderColor	Color	工具提示的边框颜色
BorderThickness	int	边框粗细（像素）
MinWidth	int	工具提示的最小宽度
MaxWidth	int	工具提示的最大宽度
RightToLeft	RightToLeft	支持 RTL 布局

ToolTipItem 属性

属性	类型	说明
Text	string	工具提示项的文本内容
Image	Image	要在项中显示的图像
ImageList	ImageList	用于存放多个图像的 ImageList
ImageIndex	int	使用 ImageList 时的索引
Control	Control	要嵌入项中的自定义控件
EnableSeparator	bool	在项后显示分隔线
EnableGradientBackground	bool	启用渐变背景
Padding	Padding	项内容周围的间距
Style	ToolTipStyleInfo	全面的样式选项

ToolTipStyleInfo（Style）属性

属性	类型	说明
BackColor	Color	背景颜色
ForeColor	Color	文本颜色
Font	Font	文本字体
TextAlignment	ContentAlignment	文本对齐方式（MiddleLeft 等）
ImageAlignment	ToolTipImageAlignment	图像位置（Left、Top、Right）
ImageSize	Size	固定图像尺寸
ImageToTextOffset	int	图像与文本之间的间距
GradientBrush	BrushInfo	渐变配置
SeparatorColor	Color	分隔线颜色
SeparatorStyle	DashStyle	分隔线样式

常见用例

1. 表单字段帮助： 为表单控件添加说明性工具提示，解释预期输入
2. 按钮操作： 显示工具栏按钮和图标的操作说明
3. 状态信息： 显示状态栏项或指示器的详细状态
4. 用户档案： 将鼠标悬停时显示包含图像的丰富档案卡片
5. 数据验证： 在验证控件上显示验证规则或错误详情
6. 仪表板小组件： 在图表或小组件的工具提示中提供详细指标
7. 禁用的控件： 解释控件被禁用的原因，以及何时可以使用
8. 进度指示器： 将鼠标悬停时显示详细的进度信息
9. 图标托盘应用程序： 在系统托盘工具提示中显示应用程序状态
10. 多语言支持： 使用 RTL 支持显示译文或补充说明

事件

事件	说明	用例
ToolTipShowing	在工具提示显示之前触发	按控件自定义外观、有条件地取消显示、调整位置
DrawToolTipItem	在工具提示呈现期间触发	实现自定义绘制、覆盖默认外观

程序集依赖项

必需程序集：

• Syncfusion.Core.WinForms.dll 和 Syncfusion.Shared.Base

NuGet 包：

• Syncfusion.Core.WinForms

最佳实践

1. 保持工具提示简洁： 用户会快速阅读工具提示；仅提供必要信息
2. 谨慎使用气泡样式： 气泡工具提示会吸引更多注意；仅用于重要提示
3. 避免冗余： 不要在工具提示中逐字重复控件标签
4. 考虑时机： 根据内容复杂程度调整 InitialDelay 和 AutoPopDelay
5. 无障碍性： 确保工具提示文本清晰易读，并具有足够的颜色对比度
6. 性能： 对频繁悬停的控件，避免在工具提示中使用复杂的自定义控件
7. 测试 RTL 布局： 在从右向左的语言配置中验证工具提示的显示效果