掩码标签控件

• 下载源文件和演示 - 113 KB

引言

在 .NET 2.0 中，有一个新的 MaskedTextBox 控件，允许您指定一个掩码，用于限制输入字符并使输入的文本符合特定格式。该控件的一个特点是，当 TextMaskFormat 属性设置为 ExcludePromptAndLiterals 时，您可以检索不包含字面字符的文本。未掩码文本的问题是，如果您想在文本框控件之外显示它，您需要手动将掩码字符放回其中。您可以只使用一个禁用的 MaskedTextBox 控件，但文本通常更难阅读。您可以将其设置为只读，但文本框仍可获得焦点。如果您想将该值显示为更长字符串的一部分或在消息框中显示，它也无法解决问题。因此，我创建了 MaskedLabel 控件。

该控件只是一个简单的 Label 控件，并带有几个额外的属性，允许您在设置文本时指定要应用的掩码。此外，它还有一个静态的重载 Format 方法，您可以使用它来用掩码格式化文本，以便无需实际控件实例即可在其他地方使用（例如，在消息框中格式化和显示文本）。提供的演示包含程序集、帮助文件和一个演示应用程序。有关将程序集安装到 Visual Studio .NET 工具箱的详细信息，请参阅帮助文件。您还可以提取 MaskedLabel.cs 源文件以供您自己的项目或控件库使用。

在您的项目中使用的程序集

这些类位于程序集 EWSoftware.MaskedLabelControl.dll 中。要使用这些类，请在您的项目中添加对它的引用。如果您需要，帮助文件包含如何执行此操作的详细信息。在那些使用 EWSoftware.MaskedLabelControl 命名空间中的类的代码模块中，您必须为 EWSoftware.MaskedLabelControl 命名空间添加一个 using 语句（在 VB.NET 中为 Imports）。

要使用 MaskedLabel 控件，只需将其从工具箱拖放到窗体上。还可以使用以下附加属性：

• Mask - 至少，您需要设置此属性来定义用于格式化文本的掩码。掩码可以是 MaskedTextBox 控件支持的任何内容。如果未设置掩码或文本对于掩码无效，则文本将以其未掩码的形式显示。
• Culture - 可以设置此属性来指定底层带掩码的文本提供程序使用的区域信息。如果未指定区域信息，则使用当前区域信息。
• IncludePrompt - 如果设置为 true 并且指定的文本未完全填满掩码，则格式化后的文本将显示提示字符以填充未使用的空间。如果设置为 false（默认值），则格式化后的文本仅显示其已有的内容。
• PromptChar - 如果 IncludePrompt 属性设置为 true，则可以设置此属性来指定要显示的提示字符。默认值是下划线 (_)。

一旦定义了掩码；设置控件的 Text 属性将使其显示应用了掩码的文本。读取 Text 属性将返回格式化后的文本。以下只读属性可以提供有关格式化过程的一些信息，如果您需要的话：

• MaskedTextProvider - 此属性返回一个基于控件当前设置的带掩码文本提供程序对象的克隆。
• ResultHint - 此属性返回最后一次赋给 Text 属性的结果提示。如果赋给的文本未能正确格式化，则此属性将包含有关原因的提示。正值表示成功。负值表示失败。
• HintPosition - 此属性返回最后一次赋给 Text 属性的结果提示位置。如果赋给的文本未能正确格式化，则此属性将包含第一个失败的位置。
• UnmaskedText - 顾名思义，此属性返回最后一次赋给 Text 属性的未掩码文本的副本。

静态 Format 方法允许您在控件外部格式化带掩码的文本。该方法有四种重载。最简单的重载接受格式字符串和未掩码文本。同样，掩码可以是 MaskedTextBox 控件支持的任何内容。另外三个重载接受额外的参数，用于提示字符、区域信息和结果提示信息。

// Format a value

string formattedText = MaskedLabel.Format("000-00-0000",
    "123121234");

// Show a prompt character in missing positions

string withPrompt = MaskedLabel.Format("000-00-0000",
    "12312", '_');

// Show a currency value using the French culture

string withCulture = MaskedLabel.Format("$0.00",
    "123", '\x0', new CultureInfo("fr-FR"));

// Format text and get the results

MaskedTextResultHint hint;
int pos;

string badText = MaskedLabel.Format("00/00", "123456",
                                    '\x0', null, out hint, out pos);

工作原理

MaskedTextBox 控件利用 MaskedTextProvider 来处理所有与格式相关的属性和任务。这使得在 MaskedLabel 控件等其他控件中利用相同的格式化变得非常简单。要使用它，您需要构造一个新实例，指定掩码和可选的区域信息。其他属性可用于设置提示字符和其他类似选项。要获取格式化的文本值，您需要调用其 Set 方法。此方法格式化文本并返回结果信息，例如文本是否对于掩码有效。使用带掩码文本提供程序的 ToString 方法将返回格式化后的文本。以下是 MaskedLabel 控件的 Format 方法，它说明了这一过程。

public static string Format(string mask, string text,
              char promptChar, CultureInfo culture,
              out MaskedTextResultHint hint, out int hintPosition)
{
    if(text == null)
        text = String.Empty;

    if(culture == null)
        culture = CultureInfo.CurrentCulture;

    MaskedTextProvider provider =
        new MaskedTextProvider(mask, culture);

    // Set the prompt character options

    if(promptChar != '\x0')
    {
        provider.PromptChar = promptChar;
        provider.IncludePrompt = true;
    }

    // Format and return the string

    provider.Set(text, out hintPosition, out hint);

    // Positive hint results are successful

    if(hint > 0)
        return provider.ToString();

    // Return the text as-is if it didn't fit the mask

    return text;
}

已知限制

我发现 MaskedTextProvider 有一个限制。它总是从左到右格式化文本，并在进行过程中填充位置。因此，如果掩码中包含可选字符（除了在掩码末尾），通常不会得到预期的格式化值。这用像 "990.00" 这样的格式字符串很容易说明。如果您指定文本 "123"，您将得到 "123." 而不是 "1.23"。因此，带掩码的文本提供程序在没有可选字符或可选字符仅出现在掩码末尾时效果最佳。

修订历史

• 2006年6月26日 - 初始发布。