syncfusion-winforms-banner-text-provider

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WinForms BannerTextProvider

实现 Syncfusion WinForms BannerTextProvider

When to Use This Skill

何时使用本指南

Use this skill when:

User needs watermark/placeholder text - Displaying hint text in empty editor controls
Implementing BannerTextProvider - Adding banner text to TextBoxExt, ComboBoxAdv, CurrencyTextBox, or other editor controls
Customizing banner appearance - Setting text color, font, visibility modes
Configuring text display modes - Choosing between FocusMode (disappear on focus) or EditMode (disappear on input)
Supporting multiple editor controls - Applying banner text across various Syncfusion or Microsoft controls
User mentions: watermark, placeholder text, hint text, banner text, BannerTextProvider, BannerTextInfo

在以下场景中使用本指南：

用户需要水印/占位符文本 - 在空白的编辑器控件中展示提示文本
实现 BannerTextProvider - 为 TextBoxExt、ComboBoxAdv、CurrencyTextBox 或其他编辑器控件添加横幅文本
自定义横幅外观 - 设置文本颜色、字体、可见性模式
配置文本展示模式 - 选择 FocusMode（获得焦点时消失）或 EditMode（输入内容时消失）
支持多编辑器控件 - 为各类 Syncfusion 或微软控件应用横幅文本
用户提及关键词： watermark、placeholder text、hint text、banner text、BannerTextProvider、BannerTextInfo

Component Overview

组件概述

The BannerTextProvider is an extender control that displays watermark text in editor controls. It provides visual hints when controls are empty and automatically hides the text when users interact with the control.

Key Features:

Text Modes: FocusMode and EditMode for controlling when banner text disappears
Customization: Text color, font, and visibility control
Multi-Control Support: Works with 14+ editor controls (TextBoxExt, ComboBoxAdv, CurrencyTextBox, etc.)
Designer & Code Support: Add via Form designer or programmatically

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

核心特性：

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

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly deployment and NuGet installation
Adding BannerTextProvider via Form Designer
Adding BannerTextProvider via Code
Assigning banner text to controls
Basic BannerTextInfo setup

📄 阅读： references/getting-started.md

程序集部署与NuGet安装
通过窗体设计器添加 BannerTextProvider
通过代码添加 BannerTextProvider
为控件分配横幅文本
基础 BannerTextInfo 配置

Banner Text Configuration

横幅文本配置

📄 Read: references/banner-text-configuration.md

Text property and visibility control
Setting text color (BannerTextInfo.Color)
Customizing font (BannerTextInfo.Font)
Mode property: FocusMode vs EditMode
Complete configuration examples

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

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

Supported Controls

支持的控件

📄 Read: references/supported-controls.md

Complete list of 14+ supported controls
Control categories (Editors, Menu, Ribbon, Toolbar)
Compatibility matrix
Best practices per control type
Limitations and workarounds

📄 阅读： references/supported-controls.md

14种以上支持控件的完整列表
控件分类（编辑器、菜单、Ribbon、工具栏）
兼容性矩阵
各控件类型的最佳实践
局限性与解决方案

Practical Examples

实践示例

📄 Read: references/practical-examples.md

Complete end-to-end code examples
Designer-based implementation walkthrough
Code-based implementation patterns
Multiple controls with different settings
Dynamic banner text changes at runtime

📄 阅读： references/practical-examples.md

完整的端到端代码示例
基于设计器的实现教程
基于代码的实现模式
不同配置的多控件设置
运行时动态修改横幅文本

Customization and Tips

自定义与技巧

📄 Read: references/customization-and-tips.md

Advanced styling techniques
Performance optimization
Common pitfalls and troubleshooting
Edge cases and best practices
Accessibility considerations

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

高级样式技巧
性能优化
常见陷阱与问题排查
边缘场景与最佳实践
无障碍适配考虑

Quick Start Example

快速入门示例

csharp

// 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);

csharp

// 1. 创建 BannerTextProvider（通常在窗体设计器或 Form_Load 事件中创建）
BannerTextProvider bannerTextProvider = new BannerTextProvider(this.components);

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

// 3. 设置横幅文本
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  // 用户输入时消失
};

bannerTextProvider.SetBannerText(textBox, bannerInfo);

Common Patterns

常见使用模式

Pattern 1: Simple Placeholder Text

模式1：简单占位符文本

When you need basic hint text that disappears on user input:

csharp

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

当你需要基础的提示文本，在用户输入时消失：

csharp

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

Pattern 2: Styled Watermark (EditMode)

模式2：样式化水印（EditMode）

For a more prominent watermark that only hides when content is added:

csharp

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

用于更醒目的水印，仅在控件有内容时隐藏：

csharp

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

Pattern 3: Focus-Based Banner (FocusMode)

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

For temporary hints that disappear when control receives focus:

csharp

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

用于临时提示，在控件获得焦点时消失：

csharp

var bannerInfo = new BannerTextInfo(
    Text = "Click to edit",
    Visible = true,
    Color = Color.LightGray,
    Mode = BannerTextMode.FocusMode  // 获得焦点时消失
);
bannerTextProvider.SetBannerText(textBox, bannerInfo);

Pattern 4: Multi-Control Setup

模式4：多控件批量设置

Apply banner text to multiple editor controls efficiently:

csharp

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

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

csharp

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

Key Modes Explained

核心模式说明

Mode	Behavior	Best For
FocusMode	Banner text disappears when control receives focus	Quick hint text, temporary guidance
EditMode	Banner text disappears only when control contains text	Persistent watermarks, clear differentiation

Note: Clear the control's default Text property before setting banner text for optimal results.

模式	行为	适用场景
FocusMode	控件获得焦点时横幅文本消失	快速提示文本、临时引导
EditMode	仅当控件有输入内容时横幅文本消失	持久化水印、清晰区分空控件与有内容控件

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

Important Considerations

重要注意事项

⚠️ Clear default text: Always clear the

Text

property of the control before setting banner text ⚠️ Supported controls only: BannerTextProvider works with 14+ specific controls (see supported-controls.md) ⚠️ Assembly reference: Requires

Syncfusion.Shared.Base

assembly ⚠️ EditMode best practice: Use EditMode when you need the banner to persist until the user enters text

Next steps: Start with Getting Started to set up the component, then refer to other guides based on your specific needs.

⚠️ 清空默认文本： 设置横幅文本前请始终先清空控件的

Text

属性 ⚠️ 仅支持指定控件： BannerTextProvider 仅适配14种以上的特定控件（参考 supported-controls.md） ⚠️ 程序集引用要求： 需要引入

Syncfusion.Shared.Base

程序集 ⚠️ EditMode最佳实践： 当你需要横幅文本在用户输入内容前一直展示时，请使用EditMode

后续步骤： 先阅读入门指南完成组件配置，再根据你的具体需求参考其他指南。