syncfusion-winforms-banner-text-provider

实现 Syncfusion WinForms BannerTextProvider

何时使用此技能

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

• 用户需要水印/占位文本 - 在空的编辑器控件中显示提示文本
• 实现 BannerTextProvider - 为 TextBoxExt、ComboBoxAdv、CurrencyTextBox 或其他编辑器控件添加横幅文本
• 自定义横幅外观 - 设置文本颜色、字体和可见模式
• 配置文本显示模式 - 在 FocusMode（获得焦点时消失）和 EditMode（输入内容时消失）之间进行选择
• 支持多个编辑器控件 - 在各种 Syncfusion 或 Microsoft 控件中应用横幅文本
• 用户提及： 水印、占位文本、提示文本、横幅文本、BannerTextProvider、BannerTextInfo

组件概述

BannerTextProvider 是一种扩展器控件，可在编辑器控件中显示水印文本。它会在控件为空时提供视觉提示，并在用户与控件交互时自动隐藏文本。

主要功能：

• 文本模式： FocusMode 和 EditMode，用于控制横幅文本何时消失
• 自定义： 文本颜色、字体和可见性控制
• 多控件支持： 支持 14 种以上的编辑器控件（TextBoxExt、ComboBoxAdv、CurrencyTextBox 等）
• 设计器和代码支持： 可通过 Form 设计器或以编程方式添加

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和 NuGet 安装
• 通过 Form 设计器添加 BannerTextProvider
• 通过代码添加 BannerTextProvider
• 为控件指定横幅文本
• 基本的 BannerTextInfo 设置

横幅文本配置

📄 阅读： references/banner-text-configuration.md

• Text 属性和可见性控制
• 设置文本颜色（BannerTextInfo.Color）
• 自定义字体（BannerTextInfo.Font）
• Mode 属性：FocusMode 与 EditMode
• 完整配置示例

支持的控件

📄 阅读： references/supported-controls.md

• 完整的 14 种以上支持控件列表
• 控件类别（编辑器、菜单、功能区、工具栏）
• 兼容性矩阵
• 各控件类型的最佳实践
• 限制和变通方法

实用示例

📄 阅读： references/practical-examples.md

• 完整的端到端代码示例
• 基于设计器的实现步骤
• 基于代码的实现模式
• 使用不同设置的多个控件
• 在运行时动态更改横幅文本

自定义和提示

📄 阅读： references/customization-and-tips.md

• 高级样式设置技巧
• 性能优化
• 常见问题和故障排除
• 边缘情况和最佳实践
• 无障碍注意事项

快速入门示例

// 1. Create BannerTextProvider (usually in Form designer or Form_Load)
BannerTextProvider bannerTextProvider = new BannerTextProvider(this.components);

// 2. Create TextBoxExt control
TextBoxExt textBox = new TextBoxExt()
{
    Size = new System.Drawing.Size(200, 30),
    Location = new System.Drawing.Point(20, 20)
};
this.Controls.Add(textBox);

// 3. Set banner text
BannerTextInfo bannerInfo = new BannerTextInfo()
{
    Text = "Enter your name...",
    Visible = true,
    Font = new System.Drawing.Font("Verdana", 9, System.Drawing.FontStyle.Italic),
    Color = System.Drawing.Color.Gray,
    Mode = BannerTextMode.EditMode  // Disappears when user types
};

bannerTextProvider.SetBannerText(textBox, bannerInfo);

常见模式

模式 1：简单占位文本

需要在用户输入内容时消失的基本提示文本时：

bannerTextProvider.SetBannerText(textBox, 
    new BannerTextInfo("Type here...", true));

模式 2：带样式的水印（EditMode）

需要更醒目的水印，且仅在添加内容时隐藏：

var bannerInfo = new BannerTextInfo(
    Text = "Email address",
    Visible = true,
    Font = new Font("Verdana", 8.25f, FontStyle.Italic),
    Color = Color.RoyalBlue,
    Mode = BannerTextMode.EditMode
);
bannerTextProvider.SetBannerText(emailTextBox, bannerInfo);

模式 3：基于焦点的横幅（FocusMode）

需要在控件获得焦点时消失的临时提示：

var bannerInfo = new BannerTextInfo(
    Text = "Click to edit",
    Visible = true,
    Color = Color.LightGray,
    Mode = BannerTextMode.FocusMode  // Disappears on focus
);
bannerTextProvider.SetBannerText(textBox, bannerInfo);

模式 4：多控件设置

高效地为多个编辑器控件应用横幅文本：

var controls = new[] { nameTextBox, emailTextBox, phoneTextBox };
var placeholders = new[] { "Full Name", "Email Address", "Phone Number" };

for (int i = 0; i < controls.Length; i++)
{
    bannerTextProvider.SetBannerText(controls[i],
        new BannerTextInfo(placeholders[i], true));
}

关键模式说明

模式	行为	适用场景
FocusMode	控件获得焦点时，横幅文本消失	快速提示文本、临时指导
EditMode	仅当控件包含文本时，横幅文本才消失	持续显示的水印、清晰区分

注意： 为获得最佳效果，请先清除控件的默认 Text 属性，再设置横幅文本。

重要注意事项

⚠️ 清除默认文本： 设置横幅文本前，务必清除控件的 Text 属性 ⚠️ 仅支持特定控件： BannerTextProvider 适用于 14 种以上的特定控件（请参阅 supported-controls.md） ⚠️ 程序集引用： 需要 Syncfusion.Shared.Base 程序集 ⚠️ EditMode 最佳实践： 如果需要让横幅在用户输入文本前一直显示，请使用 EditMode

---

后续步骤： 从入门指南开始设置组件，然后根据具体需求参阅其他指南。