WinForm TextBox 水印文字实现方法

江屿

发布时间：2026-10-14| 5人浏览过

原创

本文展示如何利用 Windows API 消息机制，在 C# WinForm 应用程序的 TextBox 控件中轻松实现水印文字（Placeholder）功能。该方法通过扩展方法封装底层调用，代码简洁且无需引入第三方库。

实现原理与准备

WinForm 原生 TextBox 控件本身不支持直接设置水印文字，但可以通过向窗口句柄发送 EM_SETCUEBANNER 消息来实现此效果。这依赖于 user32.dll 中的 SendMessage 函数。我们将创建一个静态辅助类，将这一过程封装为易用性更高的扩展方法。

关键步骤：封装 TextBox 工具类

第1步：定义命名空间与引用

创建一个新的静态类文件，命名为 TextBoxToolV2.cs（或类似名称），并引入必要的命名空间：

using System;
using System.Runtime.InteropServices;
using System.Windows.Forms;

namespace WinFormUtilHelpV2
{
    // 后续代码将放在此处
}

第2步：声明 Windows API 消息常量与 P/Invoke 签名

定义用于设置水印消息的消息ID常数，并使用 DllImport 导入 user32.dll 的 SendMessage 函数。注意使用 [MarshalAs(UnmanagedType.LPWStr)] 确保字符串正确处理。

private const int EM_SETCUEBANNER = 0x1501;

[DllImport("user32.dll", CharSet = CharSet.Auto)]
private static extern Int32 SendMessage(
    IntPtr hWnd,
    int msg,
    int wParam,
    [MarshalAs(UnmanagedType.LPWStr)] string lParam);

第3步：编写设置与清除水印的扩展方法

为 TextBox 添加两个扩展方法：SetWatermark 用于设置显示文本，ClearWatermark 用于移除水印。

public static class TextBoxToolV2
{
    /// <summary>
    /// 为TextBox设置水印文字
    /// </summary>
    public static void SetWatermark(this TextBox textBox, string watermark)
    {
        SendMessage(textBox.Handle, EM_SETCUEBANNER, 0, watermark);
    }

    /// <summary>
    /// 清除水印文字
    /// </summary>
    public static void ClearWatermark(this TextBox textBox)
    {
        SendMessage(textBox.Handle, EM_SETCUEBANNER, 0, string.Empty);
    }
}

测试应用效果

在主窗体代码中调用上述扩展方法，即可看到效果。以下是一个简单的测试表单加载示例：

public partial class MainForm : Form
{
    public MainForm()
    {
        InitializeComponent();
    }

    private void MainForm_Load(object sender, EventArgs e)
    {
        // 设置水印
        textBox1.SetWatermark("请输入用户名称....");
        textBox2.SetWatermark("请输入用户密码....");
    }

    private void btnReset_Click(object sender, EventArgs e)
    {
        // 清除水印（例如点击重置按钮时）
        textBox1.ClearWatermark();
        textBox2.ClearWatermark();
    }
}

运行程序后，TextBox 将在无焦点或内容为空时显示灰色提示文字。