模块  java.desktop
软件包  javax.swing.text

Class MaskFormatter

  • 实现的所有接口
    Serializable ， Cloneable 
    public class MaskFormatter
extends DefaultFormatter
    MaskFormatter用于格式化和编辑字符串。 MaskFormatter的行为通过String掩码控制，该掩码指定可以包含在Document模型中特定位置的有效字符。 可以指定以下字符： Valid characters and their descriptions Character Description # Any valid number, uses Character.isDigit. ' Escape character, used to escape any of the special formatting characters. U Any character (Character.isLetter). All lowercase letters are mapped to upper case. L Any character (Character.isLetter). All upper case letters are mapped to lower case. A Any character or number (Character.isLetter or Character.isDigit). ? Any character (Character.isLetter). * Anything. H Any hex character (0-9, a-f or A-F).

    通常，字符对应于一个字符，但在某些语言中，情况并非如此。 掩码基于每个字符，因此将调整以适合所需的字符数。

    您可以进一步限制setInvalidCharacters和setValidCharacters方法可以输入的字符。 setInvalidCharacters允许您指定哪些字符不合法。 setValidCharacters允许您指定哪些字符有效。 例如，以下代码块相当于“0xHHH”的掩码，没有无效/有效字符： 

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

    如果字符串的长度小于掩码的长度，则在最初格式化值时，可能会发生两件事。 将使用占位符字符串，或者将使用占位符字符。 优先级赋予占位符字符串。 例如： 

      MaskFormatter formatter = new MaskFormatter("###-####");
   formatter.setPlaceholderCharacter('_');
   formatter.getDisplayValue(tf, "123");

    会导致字符串'123 -____'。 如果setPlaceholder("555-1212")被调用“123-1212”会导致。 占位符String仅用于初始格式，在后续格式中仅使用占位符字符。

    如果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方法更改此setAllowsInvalid ，并将对有效编辑提交编辑（使用setCommitsOnValidEdit更改此设置）。

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

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

    从以下版本开始：
    1.4
    另请参见：
    Serialized Form

    • 构造方法详细信息

      • MaskFormatter

        public MaskFormatter()
        创建一个没有蒙版的MaskFormatter。

      • MaskFormatter

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

    • 方法详细信息

      • setMask

        public void setMask​(String mask)
             throws ParseException
        设置指示合法字符的掩码。 如果mask无效，这将抛出ParseException 。
        参数
        mask - 面具
        异常
        ParseException - 如果mask不包含有效的掩码字符

      • 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值表示应使用占位符char。
        参数
        placeholder - 格式化时使用的字符串，如果值未完全填充掩码

      • getPlaceholder

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

      • 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为假，则stringToValue将返回'4155551212' 。

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

      • getValueContainsLiteralCharacters

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

      • install

        public void install​(JFormattedTextField ftf)
        将DefaultFormatter安装到特定的JFormattedTextField 。 这将调用valueToString将当前值从JFormattedTextField转换为String。 那么这将安装Action从s getActions ，该DocumentFilter从返回getDocumentFilter和NavigationFilter从返回getNavigationFilter至JFormattedTextField 。

        如果子类希望在JFormattedTextField上安装其他侦听器，则通常只需要覆盖它。

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

        虽然这是一种公共方法，但这通常仅适用于JFormattedTextField子类。 JFormattedTextField将在值更改或其内部状态更改的适当时间调用此方法。

        重写：
        install在类 DefaultFormatter
        参数
        ftf - 要格式化的JFormattedTextField，可以为null，表示从当前JFormattedTextField卸载。