Module java.desktop
Package javax.swing.text

Class MaskFormatter

java.lang.Object
javax.swing.JFormattedTextField.AbstractFormatter
javax.swing.text.DefaultFormatter
javax.swing.text.MaskFormatter
所有已实现的接口:
Serializable, Cloneable
public class MaskFormatter extends DefaultFormatter
MaskFormatter 用于格式化和编辑字符串。 MaskFormatter 的行为由指定在 Document 模型中特定位置可以包含的有效字符的字符串掩码控制。 可以指定以下字符：
有效字符及其描述
字符 描述
# 任何有效数字，使用 Character.isDigit。
' 转义字符，用于转义任何特殊格式字符。
U 任何字符（Character.isLetter）。 所有小写字母映射为大写字母。
L 任何字符（Character.isLetter）。 所有大写字母映射为小写字母。
A 任何字符或数字（Character.isLetter 或 Character.isDigit）。
? 任何字符（Character.isLetter）。
* 任意字符。
H 任何十六进制字符（0-9, a-f 或 A-F）。

通常字符对应一个字符，但在某些语言中并非如此。 掩码是按字符为基础的，因此将根据需要调整以适应所需的字符数。

您可以通过 setInvalidCharacters 和 setValidCharacters 方法进一步限制可以输入的字符。 setInvalidCharacters 允许您指定哪些字符是非法的。 setValidCharacters 允许您指定哪些字符是有效的。 例如，以下代码块等效于没有无效/有效字符的掩码为 '0xHHH'：

 MaskFormatter formatter = new MaskFormatter("0x***");
 formatter.setValidCharacters("0123456789abcdefABCDEF");

当最初格式化值时，如果字符串的长度小于掩码的长度，则会发生两种情况。 要么使用占位符字符串，要么使用占位符字符。 优先考虑占位符字符串。 例如：

   MaskFormatter formatter = new MaskFormatter("###-####");
   formatter.setPlaceholderCharacter('_');
   System.out.println(formatter.valueToString("123"));

将导致字符串 '123-____'。 如果调用了 setPlaceholder("555-1212")，则会导致 '123-1212'。 占位符字符串仅在初始格式上使用，在后续格式中仅使用占位符字符。

如果 MaskFormatter 配置为仅允许有效字符（setAllowsInvalid(false)），则在编辑时将根据需要跳过文字字符。 考虑具有掩码“###-####”和当前值“555-1212”的 MaskFormatter。 使用右箭头键在字段中导航将导致（| 表示插入符号的位置）：

   |555-1212
   5|55-1212
   55|5-1212
   555-|1212
   555-1|212
'-' 是一个文字（不可编辑）字符，并将被跳过。

在编辑时也会产生类似的行为。 考虑将字符串 '123-45' 和 '12345' 插入到前面示例中的 MaskFormatter 中。 两次插入将导致相同的字符串 '123-45__'。 当 MaskFormatter 处理字符位置 3（'-'）处的插入时，会发生两种情况：

  1. 如果插入的字符是'-'，则会被接受。
  2. 如果插入的字符与下一个非文字字符的掩码匹配，则会被接受到新位置。
  3. 其他任何情况都会导致无效编辑

默认情况下，MaskFormatter 不允许无效编辑，您可以使用 setAllowsInvalid 方法更改此设置，并且将在有效编辑时提交编辑（使用 setCommitsOnValidEdit 更改此设置）。

默认情况下，MaskFormatter 处于覆盖模式。 也就是说，当键入字符时，不会插入新字符，而是用新键入的字符替换当前位置的字符。 您可以通过 setOverwriteMode 方法更改此行为。

警告： 该类的序列化对象将不兼容未来的 Swing 版本。 当前的序列化支持适用于短期存储或在运行相同 Swing 版本的应用程序之间的 RMI。 从 1.4 版本开始，已将所有 JavaBeans 的长期存储支持添加到 java.beans 包中。 请参阅 XMLEncoder。

自 JDK 版本:
1.4

  • Constructor Details

    • MaskFormatter

      public MaskFormatter()
      创建一个没有掩码的 MaskFormatter。

    • MaskFormatter

      public MaskFormatter(String mask) throws ParseException
      使用指定的掩码创建一个 MaskFormatter。 如果 mask 是无效掩码，则将抛出 ParseException。
      参数:
      mask - 掩码
      抛出:
      ParseException - 如果掩码不包含有效的掩码字符

  • Method Details

    • setMask

      public void setMask(String mask) throws ParseException
      设置指定合法字符的掩码。 如果 mask 无效，则会抛出 ParseException。
      参数:
      mask - 掩码
      抛出:
      ParseException - 如果掩码不包含有效的掩码字符

    • getMask

      public String getMask()
      返回格式化掩码。
      返回:
      指定合法字符值的掩码

    • setValidCharacters

      public void setValidCharacters(String validCharacters)
      允许进一步限制可以输入的字符。 只有在掩码中指定的字符、不在 invalidCharacters 中的字符和在 validCharacters 中的字符才允许输入。 传入 null（默认值）意味着有效字符仅受掩码和无效字符的限制。
      参数:
      validCharacters - 如果非 null，则指定合法字符

    • getValidCharacters

      public String getValidCharacters()
      返回可以输入的有效字符。
      返回:
      合法字符

    • setInvalidCharacters

      public void setInvalidCharacters(String invalidCharacters)
      允许进一步限制可以输入的字符。 只有在掩码中指定的字符、不在 invalidCharacters 中的字符和在 validCharacters 中的字符才允许输入。 传入 null（默认值）意味着有效字符仅受掩码和有效字符的限制。
      参数:
      invalidCharacters - 如果非 null，则指定非法字符

    • getInvalidCharacters

      public String getInvalidCharacters()
      返回不适合输入的字符。
      返回:
      非法字符

    • setPlaceholder

      public void setPlaceholder(String placeholder)
      设置如果值未完全填充掩码时要使用的字符串。 如果为 null，则应使用占位符字符。
      参数:
      placeholder - 如果值未完全填充掩码，则在格式化时使用的字符串

    • getPlaceholder

      public String getPlaceholder()
      返回如果值未完全填充掩码时要使用的字符串。
      返回:
      如果值未完全填充掩码，则在格式化时使用的字符串

    • setPlaceholderCharacter

      public void setPlaceholderCharacter(char placeholder)
      设置要用来代替值中不存在的字符的字符，即用户必须填写它们。 默认值是空格。

      仅当未指定占位符字符串或占位符字符串未完全填充掩码时才适用此设置。

      参数:
      placeholder - 如果值未完全填充掩码，则在格式化时使用的字符

    • getPlaceholderCharacter

      public char getPlaceholderCharacter()
      返回要用来代替值中不存在的字符的字符，即用户必须填写它们。
      返回:
      如果值未完全填充掩码，则在格式化时使用的字符

    • setValueContainsLiteralCharacters

      public void setValueContainsLiteralCharacters(boolean containsLiteralChars)
      如果为 true，则返回的值和设置的值还将包含掩码中的文字字符。

      例如，如果掩码为 '(###) ###-####'，当前值为 '(415) 555-1212'，并且 valueContainsLiteralCharacters 为 true，则 stringToValue 将返回 '(415) 555-1212'。 另一方面，如果 valueContainsLiteralCharacters 为 false，则 stringToValue 将返回 '4155551212'。

      参数:
      containsLiteralChars - 用于指示是否应在 stringToValue 中返回掩码中的文字字符

    • getValueContainsLiteralCharacters

      public boolean getValueContainsLiteralCharacters()
      如果 stringToValue 应返回掩码中的文字字符，则返回 true。
      返回值:
      如果掩码中的文字字符应该在 stringToValue 中返回，则为 True

    • stringToValue

      public Object stringToValue(String value) throws ParseException
      解析文本，返回字符串值的适当对象表示。根据需要剥离文字字符并调用超类的 stringToValue 方法，因此如果您已指定值类（setValueClass），则将创建其实例。如果值与当前掩码不匹配，则会抛出 ParseException。有关文字字符处理方式的详细信息，请参考 setValueContainsLiteralCharacters(boolean)。
      覆盖:
      在类 DefaultFormatter 中的 stringToValue
      参数:
      value - 要转换的字符串
      返回值:
      文本的对象表示
      抛出:
      如果转换过程中出现错误，则抛出 ParseException
      参见:

    • valueToString

      public String valueToString(Object value) throws ParseException
      根据掩码返回对象值的字符串表示。有关文字字符处理方式的详细信息，请参考 setValueContainsLiteralCharacters(boolean)。
      覆盖:
      在类 DefaultFormatter 中的 valueToString
      参数:
      value - 要转换的值
      返回值:
      值的字符串表示
      抛出:
      如果转换过程中出现错误，则抛出 ParseException
      参见:

    • install

      public void install(JFormattedTextField ftf)
      将 DefaultFormatter 安装到特定的 JFormattedTextField 上。这将调用 valueToString 将当前值从 JFormattedTextField 转换为字符串。然后，将从 getActions 获取的 Action、从 getDocumentFilter 返回的 DocumentFilter 和从 getNavigationFilter 返回的 NavigationFilter 安装到 JFormattedTextField 上。

      子类通常只需要在需要在 JFormattedTextField 上安装额外监听器时重写此方法。

      如果将当前值转换为字符串时出现 ParseException，则将文本设置为空字符串，并将 JFormattedTextField 标记为处于无效状态。

      虽然这是一个公共方法，但通常只对 JFormattedTextField 的子类有用。JFormattedTextField 会在值更改或内部状态更改时在适当的时候调用此方法。

      覆盖:
      在类 DefaultFormatter 中的 install
      参数:
      ftf - 要为其格式化的 JFormattedTextField，可能为 null，表示从当前 JFormattedTextField 卸载。