Module  java.desktop
软件包  javax.swing.text

Class MaskFormatter

  • All Implemented Interfaces:
    Serializable ， Cloneable 

    public class MaskFormatter
extends DefaultFormatter
    MaskFormatter用于格式化和编辑字符串。 MaskFormatter的行为通过String mask来控制，该掩码指定了可以包含在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”。 占位符字符串仅用于初始格式，后续格式仅使用占位符字符。

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

      |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开始，对所有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 - 如果掩码不包含有效的掩码字符

      • getMask

        public String getMask​()
        返回格式化掩码。
        结果
        掩饰法定字符值。

      • setValidCharacters

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

      • getValidCharacters

        public String getValidCharacters​()
        返回可以输入的有效字符。
        结果
        法定字符

      • setInvalidCharacters

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

      • getInvalidCharacters

        public String getInvalidCharacters​()
        返回对输入无效的字符。
        结果
        非法字符

      • setPlaceholder

        public void setPlaceholder​(String placeholder)
        如果值未完全填写掩码，则设置要使用的字符串。 null值意味着应该使用占位符char。
        参数
        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为真stringToValue将返回'(415) 555-1212' 。 另一方面，如果valueContainsLiteralCharacters为假，则stringToValue将返回'4155551212' 。

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

      • getValueContainsLiteralCharacters

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

      • install

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

        子类通常只需要覆盖这个，如果他们希望在JFormattedTextField上安装其他监听JFormattedTextField 。

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

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

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